为 AI 开发项目保留决策与实施历史

可以得到什么

把每次变更的 proposal、spec、design、tasks 实施结果、验收记录归档下来。后续 Agent 在新会话中打开项目时，能从归档里找回当时为什么这么做、改了哪些文件、哪些验收已经通过，避免重复造决策或推翻已有方案。

适合哪些情况

• 长期维护、跨多轮 Agent 会话的项目。
• 多人协作、需要在不同成员间同步决策的项目。
• 复杂改动（涉及架构权衡）需要保留追溯线索。
• 监管或合规要求保留"为什么这么做"的项目。

需要准备什么

• 仓库或文档系统中固定的归档目录。
• 每次变更的 proposal、spec、design、tasks 文档。
• 实施结果与验收记录（测试输出、code review 摘要）。

常见做法

1. 在项目内固定一个 archive/ 或 changes/ 目录，约定命名（如按时间或按 feature）。
2. 变更完成后，把 proposal、spec、design、tasks 与最终实施差异、验收结果一起归档。
3. 在归档中保留"为什么这样决策"的说明，而不是只保留"做了什么"。
4. 在 CLAUDE.md 项目级指令文件（Claude Code 项目宪法） 等项目级指令中指引 Agent 在新会话中先读归档再动手。
5. 与 memory bank（用文件体系恢复 coding agent 跨会话上下文） 等"用文件体系恢复上下文"的方法结合使用。

真实案例与教程

• OpenSpec-practise：示范 archive 阶段与目录结构。
• 规格驱动开发（Spec-driven development）配合 AI 助手：完整方法描述。

限制和检查点

• 归档本身有维护成本，需要在每次变更末尾执行。
• 归档内容必须真实反映实施差异，不能只复制 proposal 充数。
• 跨多个项目或跨仓库时，归档需要约定统一目录与索引。
• 归档文件中也可能含敏感信息（决策理由、负责人），注意访问控制。

相关任务

• 把模糊需求整理成可验收的规格
• 让 coding agent 按任务清单逐项推进

来源

来源：OpenSpec-practise，作者 ForceInjection。