★ FEATURED ARTICLE 一、引言用 AI agent 写代码最常见的失败模式是「上来就改代码」没有可评审的计划、没有行为契约、实现过程不可控、做完之后系统「应当做什么」无人说得清。围绕这个问题社区演化出了几套不同的方法论。本文分两部分拆解OpenSpec的 6 个工作流技能——各自的功能、适用场景、解决的核心问题回答一个自然的问题OpenSpec 是不是只盯着小任务而 BMAD 的 plan 和 Superpowers 的 plan 才是产品级大功能设计结论是方向对一半两处判断需要修正。二、OpenSpecchange 驱动的规格生命周期2.1 核心模型OpenSpec 的一句话模型每个功能或修复都是一个「change变更」。一个变更携带四件规划工件proposal.md做什么 为什么、specs/capability/spec.md行为增量 deltaSHALL / WHEN-THEN 格式、design.md怎么做、tasks.md实现步骤清单实现进度tasks.md里的勾选状态- [ ]→- [x]规格增量delta specs 最终通过 sync 合入主规格openspec/specs/后者是「系统当前状态」的持久契约。所有工作流建立在openspecCLIv1.8.0之上openspec new change脚手架变更、openspec status --json查询工件依赖状态、openspec instructions artifact获取每个工件的模板与规则、openspec validate --specs校验规格。2.2 生命周期总览发现设计问题explore探索想法 · 只读propose生成四件规划工件update修订并对齐工件apply逐项实现 tasks.md · 唯一写代码syncdelta 合入主规格archive→ changes/archive/2.3 六个技能逐一解析技能生命周期阶段功能作用典型场景主要解决什么问题explore/openspec-explore① 探索思考只读的思考伙伴读代码库、问澄清性问题、挑战假设、比较选项、画图可按要求创建 OpenSpec 工件但绝不写应用代码模糊想法变更前提前调研现有架构实现中卡住想找人讨论想法没想清就动代码导致返工——把「半个想法」变成「清晰的问题定义 方向」propose/openspec-propose② 规划·立项用 CLI 脚手架创建变更一步生成四件规划工件只规划绝不碰项目代码方向明确后想正式立项、产出可评审的变更评审通过前不让 AI 动手写码AI 编码容易「上来就改代码」且无评审留痕——强制先规划后实现工件可评审、可修改update/openspec-update② 规划·修订修订变更的既有工件并保持它们双向一致只改已存在文件不建新工件不改代码每处修改先与用户确认计划写完出现新决策「设计改用 X」实现中发现设计问题想对工件做一致性审查计划与现状脱节比没有计划更危险——让「单一事实源」始终最新避免代码与计划背离apply/openspec-apply③ 实现唯一写代码的技能先读全部上下文工件按 tasks.md 逐项做代码改动完成一项勾一项遇歧义、遇设计问题会暂停并给选项工件齐备且评审通过后开始实现实现可中断、可续做重复调用继续剩余任务大改动的 vibe 式实现不可控、难验收——把实现变成可见的清单N/M 进度每次改动限定在任务范围内sync/openspec-sync④ 规格同步agent 驱动的智能合并把变更的 delta specsADDED / MODIFIED / REMOVED / RENAMED合入主规格是合并而非覆盖支持退役 capability完成后openspec validate --specs验证不归档变更想让主规格随功能落地即时刷新只想同步部分 capability希望主规格始终反映系统「现状」主规格腐化新需求不同步后续变更就会基于过时信息做规划——让主规格保持活着的系统契约archive/openspec-archive⑤ 归档·终结检查工件与任务完成度存在 delta specs 时先提示同步内联执行 sync 工作流并复核主规格确实已更新然后把变更目录移入changes/archive/YYYY-MM-DD-变更名/变更已完整实现并验证正式收尾迭代结束清理 changes 目录完成变更堆积导致 list 杂乱混淆——给变更一个带日期时间线的正式终点且保证归档前主规格已更新三条边界规则explore/propose/update永远不碰项目代码只创建和修订规划工件apply是唯一写代码的技能。sync是「合并而非覆盖」只应用 delta 里点名的四类操作主规格中 delta 未提及的内容原样保留。archive是终点验证主规格同步通过后才移动变更目录防止「归档了但规格没更新」。2.4 一次完整变更的典型路径以「给系统加用户认证」为例/openspec-explore— 先把想法聊透读现有 auth 相关代码、比较 JWT vs session、画数据流图/openspec-propose add-user-auth— 把共识固化成四件套交给人或 agent评审/openspec-apply add-user-auth— 按 tasks.md 逐项实现中途发现设计漏洞时用/openspec-update add-user-auth先修计划再回来继续全部任务勾选后/openspec-archive add-user-auth— 它会自动提示把 delta spec 同步进主规格确认后再归档。补充sync与archive的区别在于——sync 只更新主规格、不归档变更保持活动状态适合「主规格必须时刻反映现状」的团队archive 是终结操作归档前会强制走一次同步评估。所以多数场景走到 archive 就够了sync 是提前量。explore则是「姿态」而非流程没有强制产出随时可以滑向「帮我开个变更」也可以在实现中卡住时回来当思考伙伴。三、OpenSpec vs Superpowers vs BMAD3.1 问题与初步判断一个自然的直觉是OpenSpec 解决的是具体功能或 bug 修复着眼于小任务而 BMAD 的 plan 和 Superpowers 的 plan 是产品级大功能的设计与计划。这个判断对一半两处需要修正✅对BMAD 的 plan 确实是产品级——PRD 是中心必需工件由 PM / Architect / PO 等人格化 agent 做需求、架构、epic 拆分工作流强制经过 Create PRD → Create Architecture → Create Epics Stories → Check Implementation Readiness → Sprint Planning → Create Story → Dev Story步骤不可跳过。⚠️修正 1OpenSpec 不限于小任务。它的单元是 change一次行为增量可以是 bug、也可以是跨模块大功能唯一约束是「一个连贯的决策单元」它真正的边界是不做产品发现为什么做、给谁做、市场价值。⚠️修正 2Superpowers 的 plan 不是产品级。它是单功能的详细可执行实现计划writing-plans会拆到2–5 分钟一步含代码与测试粒度其实是三者里最细的。3.2 三框架对比维度OpenSpecSuperpowersobraBMAD Method定位change 驱动的规格生命周期specs 即事实源工程过程纪律 详细执行计划产品到代码的全链路多 agent 敏捷流核心工件proposal / delta specSHALL·WHEN-THEN/ design / tasks 四件套brainstorming 设计 plan 文件细到 2–5 分钟步骤含代码与测试PRD、架构、epics、stories、sprint 状态工件性质持久每次变更 sync 进主规格archive 留带日期的时间线一次性执行中消耗用完即弃项目文档保留但不是活着的系统规格粒度与规模change 一次行为增量bug 到跨模块大功能皆可须为连贯决策单元单仓库单功能plan 拆成三者中最细的步骤产品 → epic → storystory 是开发单元做产品发现吗不做有限brainstorming 是工程需求澄清非市场/用户研究做PM/PO 人格、PRD、验收标准维护活系统规格是——三者中唯一否否架构是一次性文档实现指导方式tasks.md 粗粒度清单agent 有实现自由度极细步骤指令 TDD 检查点 subagent 执行story dev agentsprint 计划检查实现就绪度核心价值规格治理行为始终有契约可审计、可追溯过程纪律TDD、验证、检查点压制 AI 漂移角色分工多 persona 模拟敏捷团队适合大项目3.3 真正的区分轴三层模型三者不在同一个维度上竞争「大与小」而是管理系统的不同层执行层 · 现在怎么实现Superpowersplan · 2–5 分钟步骤OpenSpectasks.md · 粗粒度清单BMADstory dev · sprint planning规格层 · 系统应当做什么行为契约OpenSpecspecs delta · 持久活规格产品层 · 为什么做 / 做什么BMADPRD → 架构 → epics → stories三者的「聪明」落在不同地方OpenSpec 的聪明在规格本身SHALL/WHEN-THEN 行为契约是单一事实源代码必须服从规格且规格随每次变更持续同步、永不腐化。它管的是「系统应当做什么」这一层——感觉它「着眼于具体功能」是因为输出天然是行为级的但它并不限制 change 的规模上限。Superpowers 的聪明在过程纪律brainstorming苏格拉底式澄清→writing-plans拆到 2–5 分钟一步、带代码和测试→executing-plans分批执行、检查点确认 TDD subagent 执行。plan 是「怎么把这一个功能可靠地做出来」的执行剧本做完即弃——不维护系统级规格也不关心产品战略。BMAD 的聪明在角色分工PM、Architect、PO、Dev、QA 多 persona 协作PRD 为中心工件epic → story 分解sprint 计划做实现就绪检查。它是唯一从「为什么做」开始的那一个。一句话版本框架回答的问题BMAD做什么产品、怎么分解产品 → epic → storyOpenSpec系统应当做什么、怎么合法地改它行为契约 变更治理Superpowers眼前这个功能怎么一步步做出来不翻车执行剧本 过程纪律3.4 组合建议互补而非竞争0→1 新产品BMAD 出 PRD 架构 epics → 每个 epic/story 落地时需要持久行为契约的用 OpenSpec change 实现需要细颗粒执行计划 TDD 纪律的用 Superpowers。成熟系统、规格治理优先合规、多团队、长生命周期以 OpenSpec 为中心迭代增量全部走 change不必引入另外两套。单功能快速迭代内部工具、脚本、side project只用 Superpowers 的 brainstorm → plan → execute最轻此时 OpenSpec 的规格开销是净成本。一个细节OpenSpec 之所以「感觉小」是因为它强制 change 保持连贯一个决策单元、一次可评审的 delta大工作会被拆成多个 change——这个哲学与 BMAD 的 epic→story 分解同构只是 OpenSpec 没有内建的「epic / 产品」上层结构。需要产品级分解时要自己补文档或引入 BMAD。四、让 OpenSpec 支持严格 TDD可选机制4.1 先修正一个心智模型openspec-apply 技能本身没有内置「单元测试 E2E」步骤——apply 期间观察到的测试工作来自 tasks.md 里的任务项propose 按项目规则生成 agent 逐项执行。因此「让 apply 支持严格 TDD」的正确做法不是给 apply 加开关而是把 TDD 写进任务清单propose 侧——TDD 步骤变成可勾选的任务把 TDD 写进执行契约apply 侧——每次 apply 会话都遵守可选加CI 硬闸门OpenSpec 之外——唯一真正的「强制」手段。4.2 四层机制从软到硬层级机制作用点约束力1 · 软openspec/config.yaml的 context 写 TDD 协议所有 apply 会话prompt 级必需输入每次 apply 开头必读prompt 级agent 应遵循但 CLI 不验证是否真跑了测试2 · 结构rules.tasks写 TDD 拆分规则propose 生成的 tasks.md结构性每个功能必须拆成红-绿-重构步骤进度可见3 · 原生可选自定义 schema如 spec-driven-tddTDD 指令与模板写进 schema按 change 开启openspec new change name --schema spec-driven-tddOpenSpec 原生最强大默认 schema 保持轻量按变更开 TDD4 · 硬闸门CI / pre-commit / 分支保护OpenSpec 之外唯一真正的严格测试不过不让合并为什么 TDD 与 apply 天然契合不需要任何额外机制apply 逐项执行、逐项勾选 → 红/绿/重构阶段直接体现在 N/M 进度里随时可见当前处在 TDD 哪个阶段apply 的护栏本来就有「遇错、遇阻、需求不清时暂停——不猜」→ 红阶段测试意外通过正好触发暂停条件等于 TDD 的 red checkpoint 白送DSH 环境里 apply 是真的跑 shell 命令pwsh / npm test红绿证据是真实命令输出不是 agent 的自我声明。4.3 方法一config.yaml always-on第 12 层推荐起点适用希望项目内所有变更统一要求 TDD 的团队。操作步骤确认项目已有 OpenSpec 根项目根运行openspec list若没有openspec/目录先运行openspec init创建含 config.yaml。编写openspec/config.yaml新增或合并保留已有内容# openspec/config.yamlTDD-ready按你的技术栈调整context:|技术栈: Node.js 24 TypeScript Vitest Playwright 测试纪律apply 阶段必须遵守: - 严格 TDD: 每个新行为先写失败测试并确认其失败红 再写最小实现使其通过绿最后才重构 - 单元测试覆盖所有新行为跨模块变更必须有 Playwright E2E - 对应测试未实际运行并通过任务视为未完成 - 红阶段测试若意外通过必须暂停排查原因不得直接勾选rules:tasks:|tasks.md 必须按 TDD 循环拆分每个功能项依次包含: 1. 写失败测试并确认失败红 2. 最小实现使测试通过绿 3. 重构保持测试绿 末尾固定两条验收: - 全部单元测试通过npm test - E2E 全部通过npm run e2e说明context是每次 apply 的必需 prompt 级输入实现时作为约束应用rules.tasks仅在 propose 生成 tasks.md 时生效把 TDD 拆分结构固定在任务层。生效后 tasks.md 形如## 1. 登录校验 - [ ] 1.1 写失败单测: 密码为空时抛 INVALID_CREDENTIALS确认失败红 - [ ] 1.2 最小实现登录校验器测试通过绿 - [ ] 1.3 抽取校验规则复用重构测试保持绿 ## 2. E2E 拉通 - [ ] 2.1 Playwright 流程: 注册 → 登录 → 访问受保护页红 - [ ] 2.2 完成路由守卫使流程通过绿 ## 3. 验收 - [ ] 3.1 npm test 全部通过 - [ ] 3.2 npm run e2e 全部通过验证规则生效对任一变更运行openspec instructions tasks --change name --json确认返回的rules包含 TDD 规则propose 完成后打开 tasks.md 确认已按红/绿/重构 验收项拆分。照常使用/openspec-propose→ 评审 →/openspec-applyapply 开头读 context 中的 TDD 纪律逐项执行。可选推荐加第 4 层硬闸门让「测试不过 不能提交/合并」成为最终兜底。示例GitHub ActionsPR 触发# .github/workflows/ci.yml示例name:cion:pull_request:jobs:test:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-uses:actions/setup-nodev4with:node-version:24-run:npm ci-run:npm test-run:npm run e2e本地则可用 husky pre-commit 在git commit前跑npm test。4.4 方法二spec-driven-tdd 自定义 schema第 3 层按 change 可选适用默认不想被 TDD 约束但希望某个变更单独「开启严格 TDD」的团队。操作步骤列出现有 schemaopenspec schemas --json确认内置 spec-driven 与已发现的自定义 schema。创建自定义 schema项目根openspec/schemas/spec-driven-tdd/目录写入schema.yaml。schema.yaml 参考骨架以内置 spec-driven schema 为模板复制仅把 tasks 工件的instruction换成 TDD 版四工件与 applyRequires 保持不变# openspec/schemas/spec-driven-tdd/schema.yaml参考骨架# 字段名以本机 openspec schemas --json 的输出为准以内置 spec-driven schema 为模板name:spec-driven-tdddescription:spec-driven 严格 TDD红-绿-重构artifacts:-id:proposalgenerates:proposal.mdinstruction:同内置 spec-driven做什么与为什么-id:specsgenerates:specs/**/*.mdinstruction:同内置delta specSHALL / WHEN-THEN-id:designgenerates:design.mdinstruction:同内置怎么做建议追加「设计须说明每个需求如何被测试验证」-id:tasksgenerates:tasks.mdinstruction:|tasks.md 必须按 TDD 循环拆分每个功能项依次包含: 1. 写失败测试并确认失败红 2. 最小实现使测试通过绿 3. 重构保持测试绿 末尾固定两条验收: - 全部单元测试通过 - E2E 全部通过applyRequires:-tasks与方法一的区别方法一的 rules 作用于「默认 schema 的 tasks」always-on方法二的 instruction 写在 schema 自身只对显式选择 spec-driven-tdd 的变更生效。两者可叠加第 1 层 context 的 TDD 纪律始终生效schema 只负责任务结构。验证 schema 被发现openspec schemas --json输出中应出现 spec-driven-tdd。按变更开启openspec new change add-user-auth --schema spec-driven-tdd之后照常走 propose / apply 流程默认变更不加--schema继续走轻量 spec-driven。验证指令openspec instructions tasks --change add-user-auth --json返回 TDD 版 instruction。4.5 诚实的边界第 1–3 层都是 prompt/结构级约束OpenSpec CLI 只管工件存在性与状态openspec validate校验的是规格格式它不跑任何测试——agent 理论上可以「声称」绿了。真正的严格 第 4 层硬闸门CI / pre-commit / 分支保护。四层叠加才是真严格单靠 OpenSpec 没有「强制」二字。折中做法在任务描述里要求「附npm test真实输出确认」评审时核对DSH 环境里 apply 实际执行命令可以拿到真实输出。4.6 Token 经济学对比 SuperpowersSuperpowers 收的税brainstorming 苏格拉底往返 2–5 分钟极细 plan executing-plans 检查点 subagent 各自独立上下文 TDD skill 开销。TDD 化的 OpenSpec单上下文、粗粒度但结构化为 TDD 的任务清单、无人格无 subagent。纪律保住了税砍掉了——TDD 拆分会让任务数变多但每步更小、自验证、返工更少总体比「先写代码后补测试」便宜也远便宜于 Superpowers。五、参考Superpowersobra/superpowersagentic skills frameworkhttps://github.com/obra/superpowersSuperpowers 核心技能详解writing-plans / executing-planshttps://datawhalechina.github.io/easy-vibe/en/stage-3/core-skills/superpowers/BMAD Standard WorkflowPRD → Architecture → Epics Stories → Sprint → Devhttps://dev.to/jacktt/bmad-standard-workflow-2kmaSpec-Driven Development with the BMAD Methodhttps://sam-solutions.com/blog/spec-driven-development-with-bmad-method/OpenSpec 技能组explore / propose / update / apply / sync / archive本地 DSH skills基于 openspec CLI v1.8.0OpenSpec CLIv1.8.0本机全局安装命令详情见openspec --helpinit/new change/status/instructions/schemas/validate/archive
阅读完成 · 觉得有帮助？
