Design（设计）

Gate： 用户批准规范前，无代码。

逐轮提问直到知道要构建什么。提议 2-3 种方案与权衡；推荐一个。然后写规范。

规范 = 决策列表

规范回答此变更的待决问题。典型的有：

• 契约 / 接口？
• 数据形状？
• 失败模式？
• 超出范围？
• 什么测试证明它？
• 架构？

惯例地写规范。

无问题 → 无章节。如果 Risks / Non-goals 为空就不填。

用声明，不用叙述：

contract:  <接口>
invariant: <什么必须成立>
test:      <怎么知道它行>
deferred:  <现在不决>

按路径引用代码；永不粘贴它。

移交前，仅关闭影响实现的决策：契约、数据、失败、测试。未解决的 Working notes 变成决策、deferred，或问题。

两层，一文件：docs/staging/specs/YYYY-MM-DD-<topic>.md

• 顶部：决策、契约、不变量（永久）。
• ## Working notes：草稿、待决问题（ship 时删除）。

Roadmap（范围跨 ≥3 个里程碑时）

大到无法一次性计划所有工作时，加 ## Roadmap 到规范：

## Roadmap
- [ ] M1: <一句话目标>  ← 现在详细计划
- [ ] M2: <一句话目标>  ← stub
- [ ] M3: <一句话目标>  ← stub

标记是必须的。M1 ← 现在详细计划；其他都是 ← stub。Stub 是意图不是承诺；展开前更新。

Gate

docs/staging/specs/YYYY-MM-DD-<topic>.md 必须存在于磁盘且用户确认。

两种可能的出口之一：

• → design：方向是要解决的问题，→ plan 详细任务。
• → archive：方向是知识产物（逆向工程发现、协议规范），直接存档。