OpenSpec + Superpowers：AI 编程真正进项目的姿势

前几天看一个团队试 AI Coding。

不是玩具项目，是一个跑了好几年的后台系统。登录、权限、租户、审计都在里面，代码不算漂亮，但每一块都有历史原因。

产品提了个看起来很小的需求：

登录页加一个「记住我」。

听起来不复杂，对吧？

前端多一个 checkbox，后端把登录态留久一点，再补几条测试。于是大家把需求丢给 Agent，让它先出一版。

它确实很快。

十几分钟以后，代码已经改完了。session 逻辑动了，cookie 写了，页面也有了 checkbox，甚至还顺手补了几个测试。

当时几个人的反应都差不多：

这玩意儿真能省时间。

然后到了 code review，气氛就不太对了。

后端同学先问，这个 remember me token 的过期时间为什么写死 30 天？我们原来的租户安全策略怎么办？

安全同学接着问，用户改密码以后，老设备上的长期 cookie 会不会继续有效？

测试同学翻了半天需求，说等一下，产品只说「记住我」，没有说移动端、三方登录、管理员禁用账号这些场景怎么算。

更麻烦的是，Agent 写出来的代码并不是一眼看上去很烂。

它能跑。

测试也有。

页面也正常。

这才是最难受的地方。

如果代码明显不行，大家一眼就会打回去。真正危险的是那种「看起来已经完成了」的实现：功能有了，但需求边界没锁住；测试有了，但没有覆盖关键场景；代码提交了，但系统规格没有留下任何痕迹。

这时候你会发现，问题不是 Agent 不会写代码。

问题是它太容易把一句模糊需求，直接翻译成一堆看似完整的代码。

它干着干着，就把「功能能跑」当成了「需求成立」，把「代码通过」当成了「系统正确」。

这就是大型项目里最容易误判的一件事。

你以为问题是 Agent 写代码不够强。

其实更常见的问题是：Agent 太会写代码了，反而把需求、设计、测试、评审这些慢变量绕过去了。

所以我现在看大型项目引入 AI 编程，基本会问一句：

你只有一个会写代码的 Agent，还是有一套能约束 Agent 的工程流程？

这篇文章就聊一个很实用的组合：

OpenSpec 管「改什么、为什么改、验收标准是什么」。

Superpowers 管「怎么拆、怎么测、怎么执行、怎么 review 到结束」。

这两个东西配在一起，才更像一个能进大型项目的 AI 工程工作流。

先给一句不绕的判断

大型项目最怕的不是 Agent 慢。

大型项目最怕的是 Agent 很快，但方向没有被锁住。

OpenSpec 官方把自己定位成面向 AI Coding Assistant 的轻量 Spec-Driven Development 工具，核心是让人和 AI 在写代码前先对齐规格；它的变更通常会沉淀 proposal、specs、design、tasks 这些工件，并且支持 Claude Code、Cursor、Codex、GitHub Copilot、OpenCode、Gemini CLI 等多种工具。

Superpowers 的定位不一样。

它不是需求规格库，而是一套给 Coding Agent 用的工程方法论和 skills。它会让 Agent 在写代码前先澄清目标，设计通过后再写计划，然后按任务执行、TDD、review、收尾。

这两个东西不是互相替代。

它们像项目里的两种纪律：

一句话：

OpenSpec 是项目契约层，Superpowers 是 Agent 执行层。

大型项目要的是这两层同时存在。

第一层，别让需求只活在聊天窗口里

很多 AI 编程翻车，第一步就错了。

用户在聊天框里说：

给登录加个记住我，最好安全一点，别影响现有登录。

这句话对人来说都不够，对 Agent 更不够。

它缺了至少这些问题：

• 「记住我」是延长 session，还是发长期 refresh token？
• 默认多久过期，能不能租户配置？
• 用户改密码、退出登录、管理员禁用账号以后，旧 token 怎么处理？
• 多设备之间是否互相影响？
• 前端勾选框只在密码登录出现，还是三方登录也出现？
• 现有 session spec 被改了，还是新增 auth capability？

如果这一步不锁住，后面写得越快，偏得越远。

OpenSpec 在这里的价值，不是让你写一堆文档装正规。

它真正有用的是把一句模糊需求拆成可以审查的规格变化。

一个大型项目里，比较健康的 change 目录应该长这样：

openspec/
  changes/
    add-remember-me/
      proposal.md
      design.md
      tasks.md
      specs/
        auth-session/
          spec.md
  specs/
    auth-session/
      spec.md

proposal.md 讲为什么要改。

# Proposal: add-remember-me

## Why

当前登录态只支持短 session。用户关闭浏览器后需要频繁重新登录，
影响低风险后台系统的日常使用。

## What Changes

- 登录页新增 Remember me 选项
- 勾选后签发长期 refresh token
- 长期 token 受租户安全策略约束
- 用户改密码、退出全部设备、管理员禁用账号时撤销长期 token

## Non-Goals

- 不改三方 OAuth 登录流程
- 不支持永久登录
- 不改变普通 session 的默认过期时间

spec.md 讲系统必须满足什么。

### Requirement: Remember me session extension

The system SHALL allow password-login users to request an extended session.

#### Scenario: Extended session is created

- GIVEN a user logs in with username and password
- AND the user checks "Remember me"
- WHEN authentication succeeds
- THEN the system issues a refresh token with the tenant configured TTL
- AND records the device identifier

#### Scenario: Extended session is revoked after password change

- GIVEN a user has active remember-me tokens
- WHEN the user changes password
- THEN all remember-me tokens for that user are revoked

注意这里的关键不是 Markdown。

关键是「SHALL」和「Scenario」把需求从聊天语气变成了可审查的系统行为。

到了大型项目，这个差别很大。

聊天窗口里的需求，三天后没人敢说当时到底是什么意思。

spec 里的需求，三个月后还能被 review、被同步、被归档、被新加入的同事读到。

OpenSpec 官方文档里也强调，它不是传统 phase gate，而是 action-based workflow。你可以 propose、explore、apply、sync、archive，也可以在实现发现新事实后回头更新工件。

这点对老项目很重要。

因为老项目最真实的状态就是：没人一开始就知道全部答案。

第二层，OpenSpec 只锁意图，不替你写好执行纪律

但这里要小心一个误区。

有了 OpenSpec，不代表项目就稳了。

OpenSpec 更像「意图层」。

它告诉你应该改什么，为什么改，改完以后系统规格应该是什么样。

但它不保证 Agent 每一步都用 TDD，不保证每个小任务都足够小，不保证实现前先读相关代码，不保证写完以后有严格 review。

这就是 Superpowers 该进来的地方。

Superpowers 的 README 里把基础流程拆得很具体：brainstorming、git worktree、writing plans、subagent-driven-development 或 executing-plans、test-driven-development、requesting-code-review、finishing-a-development-branch。

翻成人话就是：

需求别急着写代码。

设计通过后，先把活拆成小任务。

每个任务最好能被一个没上下文的人照着做。

执行时要有测试、review、验证和收尾。

这正好补上 OpenSpec 的另一半。

一个可落地的配合方式是：

这套组合最怕的不是流程多。

最怕的是职责混在一起。

比如让 OpenSpec 的 tasks.md 直接变成粗糙 todo，然后让 Agent 自由发挥；或者让 Superpowers 的 plan 代替系统 spec，最后计划做完了，但规格没有归档。

这两种都会出问题。

tasks.md 是规格变更下的实施清单。

Superpowers plan 是执行层的施工图。

它们可以互相引用，但不要互相吞掉。

第三层，真正的配合应该从一个 change 开始

假设我们现在要做一个大型项目里的「组织级 API Key 管理」。

这不是一个按钮。

它可能涉及：

• 创建、禁用、轮换 API Key
• 权限范围和资源绑定
• 明文只展示一次
• 审计日志
• 速率限制
• 老接口兼容
• 管理员和普通成员权限差异

如果直接让 Agent 写，基本等于把一串系统设计题扔给它自由发挥。

更稳的做法是先用 OpenSpec 建 change：

/opsx:explore
我想给企业后台加组织级 API Key 管理，但不确定权限、审计、兼容性怎么切。

/opsx:propose add-organization-api-keys

然后让 OpenSpec 产出这些东西：

openspec/changes/add-organization-api-keys/
  proposal.md
  design.md
  tasks.md
  specs/
    api-key-management/spec.md
    audit-log/spec.md

这里 OpenSpec 最重要的产物不是任务列表，而是 capability spec。

比如：

### Requirement: API key secret visibility

The system SHALL display the API key secret only immediately after creation.

#### Scenario: Secret is visible once

- GIVEN an organization admin creates a new API key
- WHEN the API key is created successfully
- THEN the response includes the plaintext secret
- AND the system stores only a hashed representation

#### Scenario: Secret cannot be retrieved later

- GIVEN an API key already exists
- WHEN an admin views the API key detail page
- THEN the plaintext secret is not returned
- AND the UI shows the key prefix and last-used timestamp

这个 spec 很硬。

它直接把一个安全要求钉住了。

后面 Agent 如果写出 GET /api-keys/{id} 返回明文 secret 的代码，review 的时候不是「我感觉不安全」，而是「它违反了 Requirement: API key secret visibility」。

大型项目里，能把争论从感觉变成证据，这件事就值钱。

第四层，Superpowers 接手后，任务要拆到能被验证

OpenSpec 产出的 tasks.md 可能长这样：

- [ ] Add API key persistence model
- [ ] Implement create/list/revoke endpoints
- [ ] Add secret hashing and one-time display
- [ ] Add audit events
- [ ] Add admin UI
- [ ] Add tests

这个粒度可以做项目管理，但还不够适合 Agent 执行。

Superpowers 的 writing-plans 更适合把它拆成 2 到 5 分钟能完成的小任务，并且每一步带文件路径、代码边界和验证方式。

比如「Add secret hashing and one-time display」可以拆成：

### Task 3.1: Add failing test for one-time secret visibility

Files:
- `src/test/java/com/acme/apikey/ApiKeyServiceTest.java`

Steps:
- Create API key through service
- Assert returned DTO contains `plaintextSecret`
- Load API key again
- Assert detail DTO does not contain `plaintextSecret`
- Assert repository stores `secretHash`, not plaintext

Verification:
- `./mvnw -Dtest=ApiKeyServiceTest#createsSecretVisibleOnlyOnce test`

### Task 3.2: Implement hash-only storage

Files:
- `src/main/java/com/acme/apikey/ApiKeyService.java`
- `src/main/java/com/acme/apikey/ApiKeyEntity.java`

Steps:
- Generate random secret
- Store hash and prefix
- Return plaintext only from create method
- Never expose plaintext in detail/list methods

Verification:
- Run Task 3.1 test and full `ApiKeyServiceTest`

这就是执行纪律。

同样是「加 API Key」，上面的拆法会逼 Agent 先写失败测试，再写最小实现，再验证。

如果没有这层，Agent 很容易直接上来写一坨 service、controller、DTO、repository，看起来很完整，但你很难知道哪条需求是被哪段代码满足的。

Superpowers 的价值不是让 Agent 更像魔法。

恰恰相反，它是让 Agent 更像一个受约束的初级工程师：每次只做一小步，先证明失败，再证明通过，写完还要 review。

第五层，大型项目一定要处理“spec 漂移”

这里有个现实问题。

OpenSpec 的 spec 是 Markdown。

Markdown 最大的好处是轻，谁都能读，谁都能改。

Markdown 最大的坏处也是轻：它不会自己证明代码真的满足它。

第三方资料也提到过类似限制：轻量 spec 工具本身通常不是可执行契约，如果团队不维护，spec 会漂移。

所以 OpenSpec 和 Superpowers 配合时，不能只做「创建 change」。

还要做「完成 change」。

一个比较稳的收口动作应该是：

1. Superpowers 执行完所有 plan tasks
2. 跑单测、集成测试、关键 E2E
3. 对照 OpenSpec scenarios 做验收
4. 如果实现过程中发现设计变化，回写 design.md 或 specs delta
5. OpenSpec sync 当前 specs
6. OpenSpec archive change
7. PR 描述里引用 change id 和关键 scenarios

我更建议把 PR 模板也改掉。

## OpenSpec Change

- Change ID: add-organization-api-keys
- Specs touched:
  - api-key-management
  - audit-log

## Scenarios Verified

- [ ] Secret is visible once
- [ ] Secret cannot be retrieved later
- [ ] Revoked key cannot authenticate
- [ ] API key creation emits audit event

## Superpowers Execution

- [ ] Plan tasks completed
- [ ] Red/green tests included
- [ ] Code review issues resolved
- [ ] Final verification command attached

这不是形式主义。

它解决的是大型项目里最烦的两件事：

• 代码改了，但没人知道需求有没有同步
• 文档写了，但没人知道代码有没有兑现

OpenSpec 给你 spec 归档。

Superpowers 给你执行记录。

PR 把两者绑在一起。

这样半年后回头看，不是只剩一堆 commit。

你还能看到当时为什么改、改了哪个 capability、哪些 scenario 被验证、Agent 按什么计划做的。

第六层，失败信号要提前设计出来

大型项目不能靠「看起来不错」收工。

你要提前知道哪些信号说明这套流程跑偏了。

我会重点看四类风险。

这里最容易被忽略的是「任务过大」。

Agent 写大型任务时，前 20 分钟看起来特别厉害。

第 40 分钟以后，它开始在局部上下文里自圆其说。

第 60 分钟以后，你会看到一些很像工程代码、但没人敢合的东西。

所以我不太相信「一个 prompt 做完整模块」。

我更相信这种节奏：

spec 冻结一块
plan 拆小一块
test 证明一块
code 实现一块
review 挡住一块
archive 沉淀一块

大型项目不需要 Agent 表演长跑。

大型项目需要 Agent 按工程节拍跑短距离。

工程上怎么落地

如果你现在要在团队里落这套组合，我建议不要一上来全量推广。

先挑一个中等复杂度的功能。

不要太小。

太小体现不出 OpenSpec 的价值。

也不要太大。

太大第一轮容易被流程本身拖死。

比较适合的试点是：

• 登录态改造
• 权限模型新增一类角色
• API Key 管理
• 计费策略新增套餐
• 审计日志补齐关键事件
• 老接口迁移到新协议

落地可以按 7 步走。

1. 初始化 OpenSpec

npm install -g @fission-ai/openspec@latest
openspec init
openspec update

然后约定：

• 所有跨模块需求必须有 OpenSpec change
• change id 出现在分支名或 PR 描述里
• 归档后的 specs 才代表当前系统能力

2. 安装并启用 Superpowers

按你使用的 Agent 工具安装。

Superpowers 支持 Claude Code、Codex CLI、Codex App、Factory Droid、Gemini CLI、OpenCode、Cursor、GitHub Copilot CLI 等工具。不同 harness 的安装方式不同，但核心思想一样：让 Agent 在任务触发时自动读取对应 skill。

团队约定：

• 设计没通过，不写实现
• plan 没拆小，不进入执行
• 没有失败测试，不接受复杂逻辑实现
• review 发现 critical issue，必须停下来修

3. 为一个 change 写出四件套

最低要求：

proposal.md  讲 why 和 scope
design.md    讲技术路线和取舍
specs/       讲 requirement 和 scenario
tasks.md     讲实施清单

注意，tasks.md 不要写成一句话 todo。

它至少要能回答：

• 哪些文件会变
• 哪些接口会变
• 哪些测试要加
• 哪些兼容性不能破
• 哪些行为属于 non-goal

4. 让 Superpowers 生成执行计划

可以直接把 OpenSpec change 交给 Agent：

请基于 openspec/changes/add-organization-api-keys/
使用 Superpowers writing-plans 生成执行计划。

要求：
1. 每个任务 2 到 5 分钟可完成
2. 每个任务写明文件路径
3. 涉及业务逻辑必须先写失败测试
4. 每个任务带验证命令
5. 不允许超出 OpenSpec proposal 的 scope

这段 prompt 的重点是最后一句。

Agent 最大的问题不是不会做。

是太会顺手做。

大型项目里，顺手做就是风险。

5. 执行时按任务推进，不要让 Agent 自由漫游

每个任务结束后检查三件事：

• task checkbox 是否真的完成
• 测试是否能证明对应 scenario
• 是否引入了 spec 没提到的新行为

如果发现新事实，比如老系统没有设备表、token 撤销只能按 user 维度做，不要硬写。

回到 OpenSpec 更新 design 或拆新 change。

这一步很重要。

因为真实项目不是按文档长出来的。

真实项目经常是写到一半才发现历史债务。

6. PR 要绑定 spec 和执行证据

PR 不要只写「实现 API Key 管理」。

要写：

OpenSpec change: add-organization-api-keys

Implemented:
- api-key creation with one-time plaintext secret
- hash-only persistence
- revoke endpoint
- audit event on create/revoke

Verified scenarios:
- Secret is visible once
- Secret cannot be retrieved later
- Revoked key cannot authenticate

Verification:
- ./mvnw test
- ./mvnw -Dtest=ApiKeyServiceTest test

这样 reviewer 才能按 spec review，而不是在代码海里找感觉。

7. 完成后 sync 和 archive

最后一步不要省。

代码合了，但 OpenSpec 没归档，长期上下文就断了。

OpenSpec 的 workflow 文档里推荐完成变更时做 apply、verify、archive。verify 会从 completeness、correctness、coherence 这些维度检查实现和工件的一致性；archive 会把变更沉淀回 specs。

这一步做完，项目才真的多了一个能力。

不是聊天窗口里多了一段历史。

面试怎么答

如果面试官问：

大型项目里，Superpowers 和 OpenSpec 怎么配合？

不要回答「一个写规格，一个写代码」这么粗。

可以这样说：

我会把它们分成两层。

OpenSpec 做契约层，负责把需求变成 proposal、design、spec delta 和 tasks，
尤其是用 Requirement 和 Scenario 锁住验收行为。这样大型项目里需求不会只活在聊天记录里，
后续 review、归档、新人理解都有长期上下文。

Superpowers 做执行层，负责把 OpenSpec 的 change 拆成可执行计划，
要求小任务、TDD、review、验证和收尾。它解决的是 Agent 写代码过程中的跑偏、任务过大、
测试滞后和完成标准不清楚。

真正落地时，我会让 PR 同时引用 OpenSpec change id 和 Superpowers 执行证据。
也就是：代码满足哪些 spec scenarios，执行过哪些测试，哪些任务完成，最后 specs 有没有 sync 和 archive。

如果继续追问「为什么不只用 OpenSpec？」

可以回答：

OpenSpec 更偏意图和规格，它能让需求可审查、可追溯。
但它不天然保证每个实现步骤都按 TDD、小任务和 code review 推进。
大型项目里，规格正确但执行失控，还是会出问题。

所以需要 Superpowers 把执行过程管起来。

如果继续追问「为什么不只用 Superpowers？」

可以回答：

Superpowers 很适合管 Agent 怎么工作，但如果没有长期 spec，
很多需求仍然只在 plan 或聊天上下文里。大型项目最怕上下文丢失和需求漂移。

OpenSpec 的 specs/archive 可以把能力沉淀到仓库里，
让下一次改动能读到当前系统应该是什么样。

这个回答的核心是：

OpenSpec 解决长期上下文。

Superpowers 解决执行纪律。

大型项目两个都要。

最后回到开头那个登录页

开头那个「记住我」为什么会翻车？

不是因为 Agent 不会写 checkbox。

也不是因为 Agent 不会写 cookie。

恰恰相反，它太会顺着一句话往前写了。

但大型项目里的需求，往往不在那一句话里。

它藏在旧 session 策略里，藏在安全撤销逻辑里，藏在租户配置里，藏在审计要求里，也藏在半年后另一个人接手时还能不能看懂。

OpenSpec 把这些东西变成规格。

Superpowers 把规格变成可验证的执行。

这才是 AI 编程从 demo 走向大型项目时，真正需要补上的一层。

不是让 Agent 更自由。

而是让 Agent 在正确的轨道里快起来。

参考资料

• OpenSpec 官方网站：轻量级 spec-driven framework，支持多种 AI Coding 工具，强调 review intent 和持久化 specs。
• Fission-AI/OpenSpec GitHub README：OpenSpec 的定位、核心工件、工具支持和更新方式。
• OpenSpec Workflows 文档：propose、explore、apply、sync、archive、verify 等工作流说明。
• obra/superpowers GitHub README：Superpowers 的 skills 工作流、TDD、subagent-driven-development、code review 和 finishing branch。
• Spec-Driven: OpenSpec 工具分析：OpenSpec 的 proposal-first workflow、低仪式感优势和 Markdown spec 漂移风险。