图文

SDD 研发框架:我更推荐 OpenSpec

手绘 Agent 翻阅现行规范,旁边是本次变更便签。
文章目录4 节

上一篇聊了为什么要把需求和决策留在项目里。这次具体说说,拿到一个要改的功能,我会让 Agent 先读什么,什么时候开始写代码。上一篇《AI 研发:我为什么推荐大家使用 SDD》

从手头这次改动写起

OpenSpec 是一套规范驱动开发(SDD)工具。它把功能现在应该怎么工作、这次准备改什么,分开写进仓库里的 Markdown 文件。

在已有项目里,我喜欢从手头要改的功能写起。评审时看这次要动哪几条,下次再改它,上回定好的规则就有地方查。OpenSpec 已有项目指南

同一份需求向下分出自建流程、Spec Kit 和 OpenSpec 三种做法。

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

OpenSpec 里都放些什么?

openspec/specs/ui/spec.md 记现行约定,openspec/changes/add-dark-mode/ 里的另一份 spec.md 记本次增量,openspec/changes/archive/ 存历史变更。

图里节选了 OpenSpec v2.1.0 官方暗色模式示例的目录。它用的是默认的 spec-driven 工作流,其他工作流需要哪些文件,要看项目的配置。OpenSpec 变更目录结构

  1. 现行规范。 先查相关功能已经定好的规则,弄清这次要保留哪些行为。
  2. 本次变更。 提案写原因和范围,另一份同名的 spec.md 只写这次要改的要求。设计记技术取舍,任务清单列实施步骤,按改动大小写到够用。OpenSpec 增量规范说明
  3. 历史归档。 要查一次已完成的改动,按日期和变更名找回当时的材料。

我怎么用 OpenSpec

Agent 的四步是 explore 探索、propose 提案、apply 实现、archive 归档。人先审提案,实现后验结果,通过才归档。

我通常按这五步做。指令在编码助手的对话框里输入,下面沿用官方示例的拼写,不同助手的写法会有差别。各助手的调用方式

  1. 看现状。 输入 /openspec-explore,告诉 Agent 想改什么,让它读相关规范、实现和测试。代码和规范对不上,先确认预期。
  2. 审提案。 范围清楚后,用 /openspec-propose add-dark-mode 起草这次变更。我会确认这次改到哪里、哪些旧行为要兼容、验收时应该看到什么。
  3. 改代码。 我审过提案,再用 /openspec-apply-change 让 Agent 实现并跑测试。哪一步要扩大范围、遇到要求冲突,或要做高风险操作,都先停下来问我。
  4. 验收。 官方示例要求记住用户选的主题,我会切到暗色,关掉再打开,看选择是否保留。实际结果对不上,就让 Agent 修正后重测。OpenSpec 暗色模式示例
  5. 同步、归档。 我验收通过、同意收尾后,再用 /openspec-archive-change。让 Agent 核对增量,尚未同步的按提示合入现行规范,检查无误后完成归档。

改完了,为什么还要归档?

单独同步只更新现行规范,变更还在进行中的列表里。归档会把做完的那一份移走,按日期留下当时的提案和设计。OpenSpec 归档说明

手把已完成的一份变更送入历史归档,进行中托盘仍有其他材料。

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

打开原图

订阅更新,继续阅读新的实践记录

最近发布