上一篇聊了为什么要把需求和决策留在项目里。这次具体说说,拿到一个要改的功能,我会让 Agent 先读什么,什么时候开始写代码。上一篇《AI 研发:我为什么推荐大家使用 SDD》
从手头这次改动写起
OpenSpec 是一套规范驱动开发(SDD)工具。它把功能现在应该怎么工作、这次准备改什么,分开写进仓库里的 Markdown 文件。
在已有项目里,我喜欢从手头要改的功能写起。评审时看这次要动哪几条,下次再改它,上回定好的规则就有地方查。OpenSpec 已有项目指南

Spec Kit 也适合已有项目。要改一项功能,可以修订原来的规范,也可以新建一份,交付后由团队决定怎么保留和维护。Spec Kit 规范演进指南
OpenSpec 里都放些什么?

图里节选了 OpenSpec v2.1.0 官方暗色模式示例的目录。它用的是默认的 spec-driven 工作流,其他工作流需要哪些文件,要看项目的配置。OpenSpec 变更目录结构
- 现行规范。 先查相关功能已经定好的规则,弄清这次要保留哪些行为。
- 本次变更。 提案写原因和范围,另一份同名的
spec.md只写这次要改的要求。设计记技术取舍,任务清单列实施步骤,按改动大小写到够用。OpenSpec 增量规范说明 - 历史归档。 要查一次已完成的改动,按日期和变更名找回当时的材料。
我怎么用 OpenSpec

我通常按这五步做。指令在编码助手的对话框里输入,下面沿用官方示例的拼写,不同助手的写法会有差别。各助手的调用方式
- 看现状。 输入
/openspec-explore,告诉 Agent 想改什么,让它读相关规范、实现和测试。代码和规范对不上,先确认预期。 - 审提案。 范围清楚后,用
/openspec-propose add-dark-mode起草这次变更。我会确认这次改到哪里、哪些旧行为要兼容、验收时应该看到什么。 - 改代码。 我审过提案,再用
/openspec-apply-change让 Agent 实现并跑测试。哪一步要扩大范围、遇到要求冲突,或要做高风险操作,都先停下来问我。 - 验收。 官方示例要求记住用户选的主题,我会切到暗色,关掉再打开,看选择是否保留。实际结果对不上,就让 Agent 修正后重测。OpenSpec 暗色模式示例
- 同步、归档。 我验收通过、同意收尾后,再用
/openspec-archive-change。让 Agent 核对增量,尚未同步的按提示合入现行规范,检查无误后完成归档。
改完了,为什么还要归档?
单独同步只更新现行规范,变更还在进行中的列表里。归档会把做完的那一份移走,按日期留下当时的提案和设计。OpenSpec 归档说明

下次改同一块代码,我会让接手的 Agent 先读相关的现行规范,对照实现和测试,看哪些规则要沿用。想知道当时为什么这样定,再翻那次归档。
