一篇能直接照做的干活文不讲概念废话只讲怎么在项目里把 spec-driven 开发真正跑起来。0. 写在前面问题到底出在哪用 AI 编程助手写代码大家基本都经历过这几个循环让 AI 加个功能它直接开干写完了发现理解偏了改需求返工聊到一半 context 被压缩AI 忘了前面定好的边界写出来的东西和前一轮自相矛盾一个功能拆给多个 subagent 并行做每个 agent 各自理解一套合并的时候互相打架项目稍微复杂一点AI 就自由发挥没有统一的验收标准代码风格、行为口径全看运气。根子上是一件事我们一直在聊天驱动开发而不是规格驱动开发。聊天驱动的问题在于对话是易失的、非结构化的、不可追溯的。AI 凭上下文里的印象写代码印象一丢行为就漂移。而规格驱动Spec-Driven Development的思路是在写任何代码之前先把做什么、为什么、怎么做、拆成哪些任务固化成一份可读、可审、可执行的规格代码只是规格的实现。AI 的任务不再是猜需求而是照着规格执行。今天要讲的这套组合拳——OpenSpec Superpowers就是把这个思路落地的两件套。本文不是概念科普而是围绕一份真实的工程编排规范一个在真实项目中沉淀下来的orchestrate-spec-driven-devSkill把它掰开揉碎讲清楚每一步怎么操作、挂什么技能、避开什么坑。你可以直接照抄到自己的项目里。文章较长如果已经熟悉了openspec和superpowers可以直接跳到第9节进行实操下就清楚流程。1. 先认识两位主角1.1 OpenSpec管产物与状态OpenSpec 是一个面向 AI 编程时代的轻量级规格管理工具CLI 一组自动生成的 AI Skill核心思想是把每次改动change变成一个持久化的目录目录里放结构化的产物。它的定位可以概括为一句话OpenSpec 提供产物与状态——openspec/changes/name/下的 proposal / design / tasks / spec delta是跨 session、跨 subagent、跨 context 压缩都不丢的持久事实来源。安装与初始化# 前置Node.js 20.19.0npminstall-gfission-ai/openspeclatest# 验证openspec--version# 进入项目并初始化会询问你用的 AI 工具自动生成对应斜杠命令cdyour-project openspec init初始化后生成的目录结构your-project/ └── openspec/ ├── specs/ # 主规格目录 系统当前行为的真相来源 │ └── capability/ # 按能力域组织如 bank-account、receipt-statement │ └── spec.md # 该能力域的规格Requirement 用 SHALL 写 ├── changes/ # 进行中的变更每个变更一个独立目录 │ └── change-name/ │ ├── proposal.md # 为什么和是什么意图、范围、方法 │ ├── design.md # 怎么做技术方案、架构决策 │ ├── tasks.md # 带复选框的实施清单 │ ├── .openspec.yaml # change 元数据 │ └── specs/ # Delta 规格本次变更相对主规格的增量 │ └── capability/ │ └── spec.md └── archive/ # 已归档的变更保留完整历史注意看这套设计的关键openspec/specs/是主规格描述系统当前就是这样openspec/changes/name/specs/是增量规格Delta Specs只描述这次我要怎么改。改完验收通过、archive归档时增量才合并回主规格。Delta Specs 的格式长这样# Requirement: 支持暗黑模式 ## ADDED Requirements ### Requirement: 用户可切换暗黑模式 The system SHALL allow users to toggle between light and dark themes. SHALL persist the preference in localStorage. ### Requirement: 跟随系统主题 The system SHALL detect the OS theme and apply it by default. ## MODIFIED Requirements ### Requirement: 主题色板 The system SHALL use a theme-aware color palette. (从固定色板改为响应主题切换的色板) ## REMOVED Requirements ### Requirement: 仅亮色主题 The system SHALL only render in light theme.核心命令OPSX 工作流命令作用/opsx:explore无负担地探索想法、调研问题、澄清需求写作前的思考伙伴/opsx:propose一步创建 change 并生成规划产物proposal/design/tasks/opsx:new只搭 change 脚手架停在第一个产物模板配合 continue 逐步走/opsx:continue按依赖逐个生成下一个产物/opsx:ff快速生成全部规划产物/opsx:apply按 tasks 实现边做边勾选/opsx:update修订已生成的规划产物保持各产物间一致/opsx:verify校验实现是否符合规格/opsx:sync把 Delta Specs 合并进主规格可选的归档前会提示/opsx:archive归档变更收尾1.2 Superpowers管每一步的思考纪律Superpowers 是 Jesse Vincent 发起的一套开源技能包现在是 Claude-Skills-Org 维护本质是一组强制的、自动触发的思考流程 Skill。它不是为了某个具体功能而是为软件开发的全流程提供方法论纪律。Superpowers 提供每一步的思考纪律——何时压测想法、怎么写可执行的计划、怎么 TDD、怎么调试、怎么验收。安装以 Claude Code 为例/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace # 验证 /help # 应能看到 /superpowers:brainstorm、/superpowers:write-plan、/superpowers:execute-plan 等它默认的工作流长这样brainstorming压测想法 → using-git-worktrees隔离环境 → writing-plans写可执行计划 → subagent-driven-development / executing-plans执行 → test-driven-developmentTDDRED-GREEN-REFACTOR → requesting-code-review评审 → finishing-a-development-branch收尾合分支核心技能速览技能作用brainstorming苏格拉底式提问阻止 AI 直接写代码先理清需求、边界、方案writing-plans把设计转成可执行计划拆成 2-5 分钟的微任务精确到文件路径executing-plans分批执行计划带人工检查点subagent-driven-development每个任务派一个全新 subagent带质量门禁的快速迭代test-driven-development强制 RED-GREEN-REFACTOR先写失败测试→看它失败→写最少代码→看它通过→提交systematic-debugging4 阶段根因定位杜绝瞎试verification-before-completion交付前真正验证而不是打勾走过场using-git-worktrees并行开发时开独立工作区验证干净测试基线requesting-code-review/receiving-code-review发起评审 / 消化评审反馈finishing-a-development-branch合并/PR/保留/丢弃的收尾决策它的哲学只有四条但每条都是硬约束测试驱动、系统化优于碰运气、复杂化是敌人、用证据说话验证过才算完成。2. 核心心法互补的两层不是二选一很多人误以为 OpenSpec 和 Superpowers 是竞品二选一。这是最大的误解。它们是互补的两层管的事完全不同维度OpenSpecSuperpowers管什么产物与状态过程与纪律回答什么问题“现在系统应该长什么样这次改什么”“每一步该怎么思考”产物形态openspec/changes/name/下的文件一系列行为习惯 / Skill持久性跨 session、跨 subagent、跨 context 压缩不丢靠触发机制保证不被跳过本质持久事实来源source of truth执行方法论最常见的错误只在apply编码阶段才想起 superpowers。大多数人的用法是规划阶段随便聊两句一进到写代码才说哎用一下 TDD。但 superpowers 价值最大的地方恰恰在编码之前——把想法压测清楚brainstorming、把 tasks 写到subagent 拿了就能无歧义执行writing-plans。这两步做不好后面 TDD 再严格也只是在错误的规格上写正确的代码。所以正确姿势是在 spec 生命周期的每个阶段挂上对应的 superpowers 技能并且先判定这次改动到底需要多重的流程。下面三步就是这份编排规范的核心建议按顺序落地。3. 第一步判定重量档先做这个不是每个改动都要建 change、跑全流水线。过度流程化是这套东西唯一的失败模式。一个空格修正也走 propose→apply→verify→archive没人能坚持一个月。动手前 30 秒先判定这次改动属于哪一档档位判定标准走法trivial拼写、单行修正、明确无歧义的小改、纯配置调整不新增/改变任何 capability不建 change直接改 跑测试/自查跳过整个 OpenSpec 流程standard单一 capability 的新增或修改需求清楚不涉及架构决策opsx:propose可不做独立 brainstorm→opsx:applyTDD→opsx:verify→opsx:archivemajor跨多个 capability、有架构/取舍决策、需求不清、或影响面大brainstorm →opsx:propose含完整 design→opsx:applysubagent TDD→opsx:verify code review→opsx:archive两个容易踩的细节一个 capability指什么OpenSpec 里openspec/specs/capability/下的一个能力单元如bank-account、receipt-statement。改动落在单个已有能力目录内 → standard需要新建能力目录、或横跨多个能力目录 → 倾向 major。判不准怎么办降一档试探。先当 standard 起手一旦发现有真正的设计取舍再升到 major。宁可欠流程也不要给琐碎改动套全流水线。注意走法列里的opsx:*是 OpenSpec 命令而brainstorm、TDD、subagent、code review、finishing-branch 不是命令是要挂载的 superpowers 技能。具体挂哪个看下一步的映射表。4. 第二步阶段 → 技能映射表对 standard / major 档按当前所处的 OpenSpec 阶段挂对应技能。这张表是整套编排的地图建议打印出来贴在工位上时机OpenSpec 阶段挂载的 superpowers 技能适用档位想清楚做什么/为什么opsx:propose之前superpowers:brainstorming仅 major写 proposal / design / tasksopsx:propose或opsx:continue逐个补superpowers:writing-plans让 tasks.md 达到可执行标准standard major隔离环境并行开发实现前superpowers:using-git-worktrees仅当同时开多个 change、或需与主工作区隔离时实现 tasksopsx:applysuperpowers:executing-planssuperpowers:test-driven-development任务可拆成多个独立子任务时叠加superpowers:subagent-driven-developmentstandard major实现中卡壳 / 出 bugopsx:apply途中superpowers:systematic-debuggingstandard major校验实现是否符合 specopsx:verifysuperpowers:verification-before-completion外加 code review见下standard major归档收尾、合分支opsx:archivesuperpowers:finishing-a-development-branchstandard major几个补充说明关于 code reviewmajor 档在 verify 阶段必做standard 档默认可跳过但只要改动碰了钱 / 权限 / 对账等高风险逻辑就升级为必做。发起评审让另一个 agent 或同事看你的代码用requesting-code-review收到评审意见、要消化并回应时用receiving-code-review。自评场景spec-driven 常见下由你派 subagent 评审自己的 change先requesting-code-review发起拿到结果后receiving-code-review处理反馈——两个都要走一遍。关于opsx:new与opsx:proposeopsx:propose一次性建 change 并生成 proposal/design/tasks是常规入口opsx:new只建 change 并停在第一个产物模板适合你想手动逐步走配合opsx:continue。上表中opsx:propose之前泛指两者的起手前。5. 第三步阶段入口强制核对每次阶段切换必做映射表是checklist不是参考文档。如果你把上面那张表当有空再看一眼的参考资料那它等于没用。每次进入一个 OpenSpec 阶段propose / apply / verify / archive必须显式做一次核对产出本阶段挂哪些 skill的明确清单。不做核对 漏挂载。真实项目里有过血泪教训一次对账单查询条件的改动因为觉得不涉及对账逻辑跳过了 code review 的高风险判定结果上线后出问题——根因就是 verify 阶段入口没做强制核对。5.1 核对动作每个阶段入口执行说出当前阶段名明确我现在进入xxx阶段。逐行扫映射表对每一行判断本行是否适用本次适用则列出要 invoke 的 skill 名。对 code review 单独做高风险判定见 5.3产出必做 / 跳过的显式结论。写入任务清单把本阶段要 invoke 的 skill 列成任务逐个 invoke 后再开始阶段工作。5.2 context 压缩后恢复context 被压缩后恢复时第一件事是重做当前阶段的入口核对——不要直接接着上一步的代码继续。阶段锚点在压缩中会丢失必须重新对齐我在哪个阶段、该挂哪些 skill。最稳妥的方式是从openspec/changes/name/目录恢复状态而不是靠记忆。5.3 code review 高风险判定verify 阶段入口必做产出 yes/nostandard 档 code review 默认可跳过但必须显式判定是否升级为必做。判定不是感觉是对着清单逐项过命中任一条 → 升级为必做改动涉及金额计算改动涉及权限校验、数据可见性改动涉及认证、token、密码、敏感字段加解密改动涉及数据库 schema如 Flyway 脚本、不可逆操作删除、状态机变更改动涉及对外服务契约改了接口签名改动涉及并发、事务边界、分布式锁改动涉及文件上传 / 下载、DFS、对外暴露文件内容全部不命中 → 可跳过但要在 verify 报告里写明已逐项核对均不命中跳过 code review——留痕不靠记忆。那条教训再强调一遍当时这个判定没过就跳过了。即使结论是不涉及对账逻辑本身、仅 WHERE 条件追加、可跳过也必须把判定过程写出来而不是直接跳过。留痕的意义在于下次有人 review 这个 change 时能看到你是想过的而不是忘了的。6. 粘合点change 就是 subagent 的事实来源subagent-driven-development和 context 压缩都需要一份交给下一个执行者的事实。这份事实就是 OpenSpec 的 changeproposal design tasks spec delta。这是整个体系能转起来的关键不用上下文传话用文件传话。三条铁律派 subagent 实现某个 task 时让它读openspec/changes/name/而不是复述上下文。上下文会丢、会被压缩、会被主观过滤文件不会。实现中发现设计问题改 design.md / tasks.md单一事实来源不要另开一份笔记。一旦你允许旁边再记一份很快就会出现两份不一致的事实subagent 不知道信谁。context 被压缩后从 change 目录恢复状态而不是靠记忆。恢复后的第一件事就是第 5 节的阶段入口核对。一句话总结OpenSpec 负责事实在文件里superpowers 负责每个执行者都被强制去读文件、按纪律干活。7. 常见错误与纠正把最容易翻车的十种情况列成对照表自查用错误纠正只在 apply 阶段用 superpowers编码前的brainstormingwriting-plans才是杠杆最大处先挂上它们给 trivial 改动建 change、跑全流程先判定重量档trivial 直接改superpowers 的 plan 和 OpenSpec 的 design.md 各写一份writing-plans是用来约束 design.md / tasks.md 的质量的纪律不另起炉灶避免文档冗余verify当打勾式走过场挂verification-before-completion让它成为真正的门禁不是形式major 变更跳过 brainstorm 直接 propose需求不清 / 有架构取舍时brainstorm 的产出正是 proposal 的 Why / What把映射表当参考文档阶段切换时不显式核对每个阶段入口强制做第 5 节核对产出本阶段挂哪些 skill清单并写入任务code review 的高风险升级靠感觉判断或直接跳过判定verify 阶段入口必做高风险判定对着清单逐项过产出 yes/no 结论并留痕context 压缩后直接接着写代码压缩恢复第一件事是重做当前阶段入口核对重新对齐阶段锚点用 verify 的一致性校验替代 code review 的质量评审两者维度不同verify 实现是否匹配 speccode review 代码是否写得对。不可互替8. 实战把一个 standard 改动完整走一遍理论讲完实战一把。假设有个 Todo API 项目已经openspec init过主规格里已有todocapability。现在要加一个任务支持优先级标记的功能。Step 0判定重量档落在单个 capabilitytodo内需求清楚无架构决策 →standard。Step 1进入 propose 阶段 → 先做入口核对说出阶段名“我现在进入propose阶段。”扫映射表本阶段适用writing-plans约束 tasks.md 质量。standard 不需要 brainstorm。code review 判定现在还没到 verify先不急但把涉及排序逻辑记下来留到 verify 再判。写入任务invokewriting-plans然后跑/opsx:propose。Step 2/opsx:propose生成产物/opsx:propose 为任务增加优先级标记P0/P1/P2并支持按优先级排序生成openspec/changes/add-task-priority/ ├── proposal.md # 意图用户需要区分任务轻重缓急范围仅 todo capability ├── design.md # 方案priority 字段枚举 列表排序参数 ├── tasks.md # 实施清单被 writing-plans 约束成可执行标准 └── specs/ └── todo/ └── spec.md # DeltaADDED 一条 Requirementtasks.md 在writing-plans的约束下应该长成这样而不是实现优先级功能这种废话# Tasks: 为任务增加优先级标记 ## 1. 数据层 - [ ] 1.1 在 Task 实体中新增 priority 字段枚举 P0/P1/P2默认 P2 - 文件src/models/task.ts - 测试tests/unit/task.test.ts先写失败测试 - 验证npm run test -- task - [ ] 1.2 数据库迁移新增 priority 列不可逆操作需人工确认 - 文件db/migrations/xxx_add_task_priority.sql - 验证migrate rollback 演练 ## 2. 接口层 - [ ] 2.1 GET /tasks 支持 ?sortpriority|created_at - 文件src/routes/tasks.ts、tests/api/tasks.test.ts - 验证curl 实测排序结果 ## 3. 验收 - [ ] 3.1 全部测试通过 - [ ] 3.2 手动验证 P0 排在 P2 前面Step 3进入 apply 阶段 → 入口核对阶段名“我现在进入apply阶段。”扫映射表挂executing-planstest-driven-development。tasks 拆得够独立可叠加subagent-driven-development。写入任务逐个 invoke 后开干。实现中如果卡壳systematic-debugging兜底。Step 4进入 verify 阶段 → 入口核对 高风险判定阶段名“我现在进入verify阶段。”挂verification-before-completion。code review 高风险判定逐项过金额/对账否权限/DataScope否认证/token/加解密否数据库 schema迁移脚本是——升级为必做。结论涉及 DB schema必做 code review。派 subagent 评审requesting-code-review→ 收到反馈 →receiving-code-review消化。Step 5进入 archive 阶段 → 入口核对阶段名“我现在进入archive阶段。”挂finishing-a-development-branch跑/opsx:archive。归档时 Delta Specs 合并回主规格openspec/specs/todo/spec.mdchange 移入archive/。至此一次 standard 改动完整闭环。整个过程中superpowers 管纪律OpenSpec 管状态谁也没抢谁的活。9. 落地清单明天就能开始如果要从零开始按这个顺序来第 1 步装工具一次性# OpenSpecnpminstall-gfission-ai/openspeclatest# 然后在 Claude Code 里装 superpowers/plugin marketplaceaddobra/superpowers-marketplace /plugininstallsuperpowerssuperpowers-marketplace第 2 步项目初始化一次性cdyour-project openspec init第 3 步把编排纪律交给 Skill直接调用它开工把编排规范做成可复用的 Skill如orchestrate-spec-driven-dev挂进 AI 编程工具。正式开工时在工具里直接调用并 上需求 / PRD 文档/orchestrate-spec-driven-dev PRD文档技能会自动替你完成整套编排判定这次改动属于 trivial / standard / major → 按当前 OpenSpec 阶段挂载对应的 superpowers 技能 → 在每个阶段入口强制核对含 code review 高风险判定。你不需要手动记忆映射表和核对清单让 Skill 替你执行纪律。第 4 步从一次 trivial 之外的改动开始练手建议第一次完整走一遍 standard 档把阶段入口核对这个动作练成肌肉记忆后面就顺了。10. 结语一句话收尾OpenSpec 负责让事实活下来文件Superpowers 负责让纪律不被跳过流程。这套编排规范真正反直觉的地方在于它对 AI 最大的价值不在写代码阶段而在写代码之前。把想法压测清楚、把计划写到傻瓜也能执行这两件事做好后面的 TDD 和 code review 只是顺水推舟。如果只记住三件事那就是先判重量档——不要给 trivial 套全流程也不要让 major 裸奔。每个阶段入口强制核对——映射表是 checklist不是参考文档。change 目录是唯一事实来源——subagent、context 压缩恢复都靠它对齐。把这套东西跑进真实项目一个月你会明显感觉到AI 返工少了多个 agent 并行不打架了context 压缩也不慌了。因为系统不再依赖对话记忆这种易失介质而是依赖一份永远在文件里的规格。参考链接OpenSpec 官方文档https://openspec.devOpenSpec 仓库https://github.com/Fission-AI/OpenSpecSuperpowers 仓库https://github.com/Claude-Skills-Org/superpowersSuperpowers Marketplacehttps://github.com/obra/superpowers-marketplace附orchestrate-spec-driven-dev Skill 原文本文依据的编排 Skill 完整原文随文附上方便对照查阅、直接拿去用。--- name: orchestrate-spec-driven-dev description: Use when starting or working through any OpenSpec change in this repo — including deciding whether a task needs a change, running any opsx command (propose/apply/verify/archive), AND when transitioning between OpenSpec phases (each phase transition requires an explicit skill-mounting checklist per step 3 of this skill). Use when tempted to jump straight to coding, or when youve only been invoking superpowers during the apply/coding phase, or when recovering from context compaction mid-change. --- # 编排 spec-driven 开发(OpenSpec × superpowers) ## 核心原则 OpenSpec 和 superpowers 是**互补的两层**,不是二选一: - **OpenSpec** 提供**产物与状态** —— openspec/changes/name/ 下的 proposal / design / tasks / spec delta,是跨 session、跨 subagent、跨 context 压缩都不丢的**持久事实来源**。 - **superpowers** 提供**每一步的思考纪律** —— 何时压测想法、怎么写可执行的计划、怎么 TDD、怎么调试、怎么验收。 **最常见的错误:只在 apply(编码)阶段才想起 superpowers。** 价值最大的地方恰恰在编码之前——把想法压测清楚、把 tasks 写到subagent 拿了就能无歧义执行。这份 skill 的作用就是:在 spec 生命周期的**每个阶段**挂上对应的 superpowers 技能,并先判定这次改动到底需要多重的流程。 ## 第一步:判定重量档(先做这个) 不是每个改动都要建 change、跑全流水线。**过度流程化是这套东西唯一的失败模式。** | 档位 | 判定标准 | 走法 | |---|---|---| | **trivial** | 拼写、单行修正、明确无歧义的小改、纯配置调整;不新增/改变任何 capability | **不建 change**。直接改 跑测试/自查。跳过整个 OpenSpec 流程。 | | **standard** | 单一 capability 的新增或修改;需求清楚;不涉及架构决策 | opsx:propose(可不做独立 brainstorm)→ opsx:apply(TDD)→ opsx:verify → opsx:archive | | **major** | 跨多个 capability、有架构/取舍决策、需求不清、或影响面大 | brainstorm → opsx:propose(含完整 design)→ opsx:apply(subagent TDD)→ opsx:verify( code review)→ opsx:archive | 判不准时,**降一档试探**:先当 standard 起手,一旦发现有真正的设计取舍再升到 major。宁可欠流程也不要给琐碎改动套全流水线。 走法列里 opsx:* 是 OpenSpec 命令;**brainstorm、TDD、subagent、code review、finishing-branch 不是命令,而是下一节要挂载的 superpowers 技能**——具体挂哪个见第二步映射表。 **一个 capability指什么**:OpenSpec 里 openspec/specs/capability/ 下的一个能力单元(如 bank-account、receipt-statement)。改动落在单个已有能力目录内 → standard;需要新建能力目录、或横跨多个能力目录 → 倾向 major。 ## 第二步:阶段 → 技能映射 对 standard / major 档,按当前所处的 OpenSpec 阶段挂对应技能(用 Skill 工具 invoke)。**适用列标明该行属于哪档**: | 时机 | OpenSpec | 挂载的 superpowers 技能 | 适用 | |---|---|---|---| | 想清楚做什么/为什么 | opsx:propose 之前 | superpowers:brainstorming | 仅 major | | 写 proposal / design / tasks | opsx:propose(或 opsx:continue 逐个补) | superpowers:writing-plans(让 tasks.md 达到可执行标准) | standard major | | 隔离环境并行开发 | 实现前 | superpowers:using-git-worktrees | 仅当同时开多个 change、或需与主工作区隔离时 | | 实现 tasks | opsx:apply | superpowers:executing-plans superpowers:test-driven-development;任务可拆成多个独立子任务时叠加 superpowers:subagent-driven-development | standard major | | 实现中卡壳/出 bug | opsx:apply 途中 | superpowers:systematic-debugging | standard major | | 校验实现是否符合 spec | opsx:verify | superpowers:verification-before-completion;外加 code review(见下) | standard major | | 归档收尾、合分支 | opsx:archive | superpowers:finishing-a-development-branch | standard major | **关于 code review**:major 档在 verify 阶段**必做**;standard 档默认可跳过,但只要改动碰了钱/权限/对账等高风险逻辑,就升级为必做。发起评审(让另一个 agent 或同事看你的代码)用 superpowers:requesting-code-review;当你收到评审意见、要消化并回应时用 superpowers:receiving-code-review。自评场景下(spec-driven 常见)由你派 subagent 评审自己的 change,你先 requesting-code-review 发起,拿到结果后 receiving-code-review 处理反馈——两个都走一遍。 **关于 opsx:new 与 opsx:propose**:opsx:propose 会一次性建 change 并生成 proposal/design/tasks,是常规入口;opsx:new 只建 change 并停在第一个 artifact 模板,适合你想手动逐步走(配合 opsx:continue)。上表的opsx:propose 之前泛指两者的起手前。 ## 第三步:阶段入口强制核对(每次阶段切换必做,不可跳过) 映射表是 **checklist,不是参考文档**。每进入一个 OpenSpec 阶段(propose / apply / verify / archive),必须**显式**做一次核对,产出本阶段挂哪些 skill的明确清单。不做核对 漏挂载,这是本次 BI-87 漏掉 code review 的直接原因。 ### 核对动作(每个阶段入口执行) 1. **说出当前阶段名**:明确我现在进入 xxx 阶段。 2. **逐行扫映射表**:对每一行判断本行是否适用本次,适用则列出要 invoke 的 skill 名。 3. **对 code review 单独做高风险判定**(见下),产出必做/跳过的显式结论。 4. **写入 TaskCreate**:把本阶段要 invoke 的 skill 列成任务,逐个 invoke 后再开始阶段工作。 context 压缩后恢复时,**第一件事**是重做当前阶段的入口核对——不要直接接着上一步的代码继续。阶段锚点在压缩中会丢失,必须重新对齐我在哪个阶段、该挂哪些 skill。 ### code review 高风险判定(verify 阶段入口必做,产出 yes/no) standard 档 code review 默认可跳过,但**必须显式判定**是否升级为必做。判定不是感觉,是对着清单逐项过: **命中任一条 → 升级为必做**: - 改动涉及金额计算 - 改动涉及权限校验、数据可见性 - 改动涉及认证、token、密码、敏感字段加解密 - 改动涉及数据库 schema(Flyway 脚本)、不可逆操作(删除、状态机变更) - 改动涉及对外服务契约(改了接口签名) - 改动涉及并发、事务边界、分布式锁 - 改动涉及文件上传/下载、DFS、对外暴露文件内容 **全部不命中 → 可跳过**,但要在 verify 报告里写明已逐项核对,均不命中,跳过 code review——留痕,不靠记忆。 BI-87 教训:对账单查询条件改动当时没过这个判定就跳过了。即使结论是不涉及对账逻辑本身、仅 WHERE 条件追加、可跳过,也必须把判定过程写出来,而不是直接跳过。 ## 粘合点:change 就是 subagent 的事实来源 subagent-driven-development 和 context 压缩都需要一份交给下一个执行者的事实。**这份事实就是 OpenSpec 的 change**(proposal design tasks spec delta)。所以: - 派 subagent 实现某个 task 时,让它读 openspec/changes/name/ 而不是复述上下文。 - 实现中发现设计问题,**改 design.md / tasks.md**(单一事实来源),不要另开一份笔记。 - context 被压缩后,从 change 目录恢复状态,而不是靠记忆。 ## 常见错误 | 错误 | 纠正 | |---|---| | 只在 apply 阶段用 superpowers | 编码前的 brainstorming writing-plans 才是杠杆最大处;先挂上它们 | | 给 trivial 改动建 change、跑全流程 | 先判定重量档;trivial 直接改 | | superpowers 的 plan 和 OpenSpec 的 design.md 各写一份 | writing-plans 是用来**约束 design.md / tasks.md 的质量**的纪律,不另起炉灶,避免文档冗余 | | verify 当打勾式走过场 | 挂 verification-before-completion,让它成为真正的门禁,不是形式 | | major 变更跳过 brainstorm 直接 propose | 需求不清 / 有架构取舍时,brainstorm 的产出正是 proposal 的 Why/What | | 把映射表当参考文档,阶段切换时不显式核对 | 每个阶段入口强制做第三步核对,产出本阶段挂哪些 skill清单并写入 TaskCreate | | code review 的高风险升级靠感觉判断或直接跳过判定 | verify 阶段入口必做高风险判定,对着清单逐项过,产出 yes/no 结论并留痕 | | context 压缩后直接接着写代码 | 压缩恢复第一件事是重做当前阶段入口核对,重新对齐阶段锚点 | | 用 verify 的一致性校验替代 code review 的质量评审 | 两者维度不同:verify实现是否匹配 spec,code review代码是否写得对。不可互替 | ## 与项目约定的关系 用户在 CLAUDE.md / 直接指令中的要求优先级最高。本项目 TDD 是硬要求(见 CLAUDE.md),apply 阶段必须 test-first。