文档先行

先写文档是在降噪

很多项目不是写不出来，而是边写边变。

今天要做 API 网关，明天加图片模型，后天接视频任务，最后连接口边界都说不清。

文档先行的目的不是做形式，而是把不同层次的问题分开：

• 需求是什么。
• 技术怎么选。
• 接口怎么暴露。
• 开发怎么拆。

一条简单的流水线就够用。

PRD.md -> TECH.md -> API.md -> FLOW.md -> PLAN.md -> TEST.md -> DEPLOY.md

每份文档只回答自己的问题。PRD 不写实现细节，TECH 不改业务目标，PLAN 不重新定义架构。这样讨论时不会混在一起。

每一步都要能审阅

文档只写给自己看，容易变成备忘录。真正有用的文档，应该能被审阅。

flowchart LR
    A[PRD 审目标] --> B[TECH 审方案]
    B --> C[API 审契约]
    C --> D[PLAN 审执行]

• PRD 审目标：产品解决什么问题，哪些算 MVP，哪些先不做。
• TECH 审方案：为什么选这个框架，为什么这样部署，风险在哪。
• API 审契约：字段名、错误码、状态流转、兼容策略是否明确。
• PLAN 审执行：每个里程碑能否独立验证，测试文件放哪，完成标准是什么。

文档先行不是多写几页字，而是在每个阶段设置一次刹车。

这次刹车很重要。它让」我以为你要的是这个」尽早暴露，而不是等代码写完才发现方向错了。

计划要拆到可验证

好的计划不是任务清单，而是验证清单。

「接入模型」太大，不好验收。」新增 POST /v1/generate，支持文本输入，非法参数返回 INVALID_PARAMETER「就清楚得多。

每个里程碑要满足三个条件：

1. 输入明确。
2. 输出明确。
3. 有测试或命令可以验证。

M1: 完成模型列表 API
验证: GET /models 返回 id、capability、input、output、stream、parameters

M2: 完成任务创建 API
验证: POST /v1/generate 返回 task_id 和 processing 状态

M3: 完成任务查询 API
验证: GET /v1/tasks/{task_id} 返回最终 output 或标准错误码

拆到这个粒度，开发不容易跑偏。中途换人，也能从文档接住上下文。

文档不是一次性产物

文档先行不等于写完就冻结。项目推进后，真实问题会出现：

• 某个模型不支持字段。
• 某个部署环境限制运行时。
• 某个接口要兼容旧客户端。

这些变化要回写到对应文档。参数变化写 API，架构变化写 TECH，执行顺序写 PLAN。

不要只改代码。代码说明系统现在怎么运行，文档说明为什么变成这样。

长期看，文档先行保护的是协作成本。它让需求、技术、测试、部署都有共同参照物。项目越多人参与，这个参照物越值钱。