最佳实践

规范

声明式写，不要叙述式。 用 contract:、invariant:、test:、failure: 这样的章节，不要编号步骤或散文。智能体读得快，跟随精确的声明。

仅关闭影响实现的决策。 在移交 plan 前，解决：契约、数据形状、失败模式、测试标准。把哲学争论和"锦上添花"留在 deferred 或 Working notes。

按路径引用代码，永不粘贴。 规范是关于要构建什么的决策，不是怎样构建的演走。

任务是 30-60 分钟 原子化到智能体能推理它们。太大了你失去可见性；太小了失去速度。

Acceptance 可执行。 每个任务的验收条件必须是 CI/人类能验证的东西：测试名、命令或脚本。不模糊，不好高骛远。

标记 [parallel] 仅当真正独立。 共享状态、错误处理或未闭合的契约 → 任务不并行。过度标记导致破坏的合并。

每个 RED-GREEN-refactor 循环一次提交。 把你的思考推进历史。后来调试时有帮助。

每个循环后同步文档。 就在提交前。如果你等待，你会忘记你改了什么和为什么。

用描述性分支名。 feat/oauth-github，不是 feature1。当你有多个 worktree 时帮你导航。

当 ≥3 个里程碑时用 roadmap。 不要试着一次性计划他们。plan 仅当前的，随着你学习更新 stub。

清晰标记当前里程碑。 ← 现在详细计划 在 M1 上信号意图。在计划 M2 前，ship 后移动标记。

期望在 M1 后修改里程碑。 第一个里程碑教你剩下的会花费多少。那是要点。

隔离优先，假设其次。 缩小到最小重现。删除代码直到症状消失。仅然后问"为什么"。

每次改一个变量。 并行很诱人但让很难知道哪个改变修复了它。

测试契约，不是实现。 如果契约说"成功时返回 200"，就测试这。不是"调用 X 函数"或"从数据库 Y 读取"。

无内部的 mock。 Mock 外部边界：HTTP、DB、文件系统。Mock 你自己的代码仅当真实版本很慢或非确定性。

如果假设实质改变，停止并重新探索。 不要强行通过如果你在解决的问题不再是问题了。在探索笔记中标记出尝试后得到的原因和经验。

如果里程碑目标移位 ≥50%，回到设计。 不要扩展计划。承认新方向并重启。

Living docs 是事实，staging docs 是草稿。 ship 后，规范移到 living docs。代码中的测试和注释与两者保持当前。

README 是第一个规范。 如果它不匹配代码，PR 失败评审。同样规则适用于所有公共契约。