产品设计准则

本目录回答"用户看到什么" — 功能规格、业务规则、schema 设计理由、AI prompt 设计。

这页是 Retaintive 团队以后做产品 / 系统 / AI workflow 设计时的默认工作方式。

核心原则:

先定义系统真实对象
再定义 API 和状态变化
最后才写 prompt

不要一上来问 AI “prompt 应该怎么写”。Prompt 只是系统的一层。真正长期稳定的东西是 schema、API、state transition、database transaction 和 audit trail。

一句话原则

AI 应该帮我们理解语义,不应该成为系统状态的 source of truth。

系统的 source of truth 应该是:

层	负责什么
Schema	系统有哪些稳定对象、字段、关系和约束
API	前端、内部服务、第三方系统、CLI、AI agent 怎么读写这些对象
State machine	一个对象能从什么状态变到什么状态,谁能改,什么情况下能改
Database transaction	真正落库时如何保证一致性、幂等、并发安全和审计
Prompt / AI	理解文本、语义、意图和模糊场景,输出 proposal

核心架构模式: Code as Guardrail, AI as Judgment

以后所有 AI workflow 默认按这个模式设计：

AI proposes structured action
Code validates policy / state / idempotency
Code executes database mutation
System records audit trail

也可以理解成：AI 做 judgment，code 做 authority。

职责	默认归属	原因
语义理解、意图分类、内容总结	AI	需要处理自然语言和模糊语义
action proposal 和 evidence	AI structured output	AI 可以建议做什么，但必须 typed
enum validation、权限、DNC、store isolation	Code / Policy Guard	不能被 prompt injection 或模型不稳定影响
lifecycle transition、idempotency、transaction	Code	必须 deterministic、可审计、可重放
audit trail / timeline	Code	系统必须知道谁提议、谁执行、为什么执行或拒绝

所以 prompt output 不应该是“最终事实”，而应该是一个 typed proposal。真正改变 contacts / tasks / contact_timeline / calls / messages / leads 的动作，必须经过代码层的 schema validation、policy guard 和 transaction。

推荐顺序

1. Schema-first: 先定义业务对象

先问:

这个系统里真正稳定的 business objects 是什么?
哪些是 source of truth?
哪些只是 projection / view / cache / audit feed?
哪些字段表达当前状态,哪些字段表达历史事件?

Task 领域的 selected Target：

Task           = 一件需要解决到底的客户机会、问题或目标
Next Action    = 当前已经采用的下一步计划
Activity       = 实际发生的处理记录
Business Progress = 已发生、但尚未构成最终 Outcome 的业务进展
Outcome        = Task 最后怎么样、为什么结束、证据是什么

Task V3 已是选定的产品与领域 Target。术语和目标边界以 Task V3 Product / Domain Contract 为准；merge、deployment、TEST acceptance 与 PROD readiness 分开看 Task V3 Rollout 状态快照。Target 不表示代码已部署、通过 TEST 或向 PROD 开放；当前 schema、config 与 runtime 行为仍须从 live evidence 复核。

Task V2+ 工程审计与实施基线保留为历史审计和兼容背景，不再是当前实施路线。

工程实现上,Schema-first 还意味着 schema 要尽量是机器可读 contract,例如 Drizzle schema、OpenAPI spec、GraphQL SDL、Zod / JSON Schema。它不只是文档描述,还应该能驱动类型、校验、mock、测试或 SDK。

不要把所有东西都塞进一个字段。比如:

Next Action       = 当前计划做什么
AI Suggestion     = AI 建议做什么，但尚未采用
Activity          = 实际发生了一通电话 / 一条 SMS / 线下工作
Task Outcome      = 整件客户事项最终如何结束
Funnel Projection = 现有 evidence 显示 Lead 走到哪里

这些不是同一个概念。

2. API-first: 再定义别人怎么读写

设计时要假设未来不只有当前前端会用这套数据。还可能有:

internal services
dashboard
OAuth API
CLI
third-party integrations
customer-owned AI agent
Codex / Claude Code 这类 agent

所以 API 返回必须是机器可读的 typed objects,不要要求调用方解析 prompt 文本或 timeline JSON。

问设计时,应该问:

GET 一个对象时,外部调用方能不能一眼看懂当前状态?
它能不能看到最近发生了什么?
它能不能知道下一步应该做什么?
它能不能区分 progress 和 final outcome?
它能不能安全地提交一次 update / close / progress event?

目标 API 应该像这样分层（不是当前 live endpoint 清单）：

GET /tasks/:taskId
POST /tasks/:taskId/activities
POST /tasks/:taskId/activity-and-next-action
POST /tasks/:taskId/next-action
POST /tasks/:taskId/close
POST /tasks/:taskId/reopen
GET /contacts/:contactId/timeline
GET /contacts/:contactId/tasks

如果 API 会被多个消费者使用,需要有 versioning strategy。比如 v3 API 不能随意 breaking change;如果对象语义要大改,应该新版本或兼容字段过渡。

3. State-machine-first: 先定状态变化规则

在 prompt 之前,先定义代码层允许哪些状态变化。

问:

object 有哪些 lifecycle status?
哪些操作会改变 lifecycle?
哪些操作只是追加 progress?
什么情况下允许 close?
什么情况下必须 no-op?
人和 AI 同时操作时谁赢?
DNC、wrong number、跨门店隔离这些硬规则在哪里执行?

例子:

Task.status = open | closed

record_activity:
  append Activity; Task does not silently close
  optionally update adopted Next Action atomically

change_next_action:
  replace current plan; append audit event
  do not move Task deadline implicitly

close_task:
  open Task -> closed Task + typed Outcome + evidence

避免用多个 boolean flag 表达状态。isOpen + isClosed + isAttempted + isResolved 这类设计会产生大量不可能组合。优先使用明确 enum lifecycle 和显式 transition。

代码层必须负责:

代码层职责	为什么不能交给 prompt
enum validation	prompt 可能输出不存在的值
store guard	prompt 不能保证跨门店隔离
idempotency	prompt 不知道这次请求是不是重复
concurrency	prompt 不能处理人和 AI 同时写同一个 task
transaction	prompt 不能保证多表同时成功或失败
DNC hard stop	DNC 是硬约束,不能靠模型自由判断
audit trail	系统必须能回放是谁在什么时候改了什么

4. Prompt-last: 最后才设计 AI 输入输出

Prompt 的职责不是直接改变数据库。Prompt 应该在 schema/API/state machine 允许的动作空间里输出 proposal。

Prompt 可以做:

理解 transcript / SMS / notes
判断客户意图
判断 Task kind 和合理的 Next Action
判断 evidence 是否可能满足 Task Outcome contract
生成 suggested actions
给出 evidence 和 confidence

Prompt 不应该做:

invent taskId
绕过 allowed enum
决定 transaction 是否成功
直接改 database state
把 Activity outcome 当 Task Outcome
忽略 store / DNC / idempotency / concurrency guard

AI action output 必须是 structured output,不要让 free text 决定系统动作。优先用 Zod / JSON Schema / OpenAPI schema 约束可选 action、enum 和字段。低置信度时不要自动写库,而是 no_op、needs_review 或进入人工确认流程。

目标 prompt output 应是 proposal，而不是 database row。示意：

{
  "taskProposals": [
    {
      "action": "record_activity",
      "taskId": "task_123",
      "activity": {
        "channel": "phone",
        "action": "call_completed",
        "outcome": "connected",
        "conversationDisposition": "follow_up_agreed"
      },
      "nextAction": {
        "text": "Call Friday afternoon",
        "reasonCode": "customer_requested"
      },
      "evidenceRefs": ["call:store-scoped-id"]
    },
    {
      "action": "propose_close",
      "taskId": "task_123",
      "resultCode": "booked",
      "closureReasonCode": "goal_achieved",
      "verificationType": "communication_explicit",
      "evidenceRefs": ["message:store-scoped-id"]
    }
  ]
}

代码收到 proposal 后再决定是否执行。

Engineering Guardrails

这些不是额外流程,而是防止 AI 系统变脆的底线。

Guardrail	准则
Machine-readable contract	关键 schema 不只写 prose,要尽量落到 Drizzle / OpenAPI / Zod / JSON Schema 等可校验形式
Schema drift check	docs、DB schema、API response、TypeScript types、prompt output schema 必须持续对齐;需要 contract tests 或 schema checks 防 drift
API versioning	多消费者 API 要有版本策略,避免无意 breaking change
Explicit state machine	用 enum + transition 表达状态,避免 boolean flag explosion
Structured AI output	AI 只能输出结构化 proposal;free text 只能当 evidence/note,不能当 action contract
Low-confidence fallback	低置信度不自动 commit;默认 no-op、needs_review 或人工确认
Blast radius limit	AI 出错时影响范围要小:单个对象、单个 store、单次 transaction,并可审计/回滚

问 AI 的标准方式

以后让 AI 帮忙做系统设计时,请直接复制下面这段作为开头:

请不要先设计 prompt。

请先帮我定义:
1. 这个系统的核心 business objects 是什么?
2. 每个 object 的 source of truth 是哪里?
3. 每个 object 的 lifecycle / state transition 是什么?
4. 外部 API 应该如何读写这些 object?
5. 哪些判断必须由代码 deterministic 执行?
6. 哪些判断需要 AI 做 semantic proposal?
7. Prompt 的 input/output schema 应该如何从 API/schema 反推?
8. 这个设计如何处理 idempotency、concurrency、audit、fallback?
9. 人和 AI 同时操作时,谁是 authority,系统怎么记录 override?
10. 这个设计如何让未来 CLI、OAuth API、第三方系统和 AI agent 也能读懂?

判断一个 AI 方案是否靠谱

一个好的 AI 系统设计应该能回答:

问题	合格答案应该包含
数据对象是什么?	清楚区分 source of truth、projection、audit
API 怎么长?	读写路径明确,外部调用方不用猜
状态怎么变?	lifecycle、progress、outcome 分清楚
AI 输出什么?	proposal,不是直接 mutation
代码执行什么?	validation、state transition、transaction、guardrail
失败怎么办?	parse fail、timeout、low confidence、race condition 都有 fallback
怎么审计?	谁在什么时候基于什么 evidence 改了什么
未来 agent 怎么接?	API typed,对象稳定,不用解析 prompt 文本

如果一个方案只讲:

我们改一下 prompt,让 AI 更聪明地判断

那通常还不够。它还没有进入真正的系统设计。

Retaintive 的默认设计口径

Retaintive 是 AI-native product,但不是 prompt-only product。

我们的默认架构应该是:

Code controls the world state.
AI proposes semantic interpretation.
Database stores source of truth.
API exposes typed objects.
Timeline records audit and display history.

中文表达:

代码控制系统状态。
AI 提出语义判断。
数据库保存事实。
API 暴露稳定对象。
Timeline 记录审计和展示历史。

这就是以后做产品设计、prompt 设计、schema 设计、API 设计时的默认准则。

#产品设计准则

#一句话原则

#核心架构模式: Code as Guardrail, AI as Judgment

#推荐顺序

#1. Schema-first: 先定义业务对象

#2. API-first: 再定义别人怎么读写

#3. State-machine-first: 先定状态变化规则

#4. Prompt-last: 最后才设计 AI 输入输出

#Engineering Guardrails

#问 AI 的标准方式

#判断一个 AI 方案是否靠谱

#Retaintive 的默认设计口径