文档先行

先写文档是在降噪

很多项目不是写不出来，而是边写边变。今天觉得要做 API 网关，明天加上图片模型，后天又接视频任务，最后连接口边界都说不清。

文档先行的目的不是做形式，而是把不同层次的问题分开：需求是什么，技术怎么选，接口怎么暴露，开发怎么拆。

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

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

每份文档只回答自己的问题。PRD 不写实现细节，TECH 不改业务目标，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。不要只改代码。代码说明系统现在怎么运行，文档说明为什么变成这样。

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