乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > 你的 AI 编程助手,为什么总在“乱来”?

你的 AI 编程助手,为什么总在“乱来”?

当前时间： 2026-08-16 23:08:06 分类：办公文件 评论(0)
你的 AI 编程助手,为什么总在“乱来”?

两个爆火框架的致命短板，以及一场迟到的最佳联姻

附：完整可复制的自定义 Schema 配置 + 实测数据

先承认吧：你的 AI 写代码，就像个“失控的天才”

Chat 10 轮才能说清楚需求，一转头它就开始“自由发挥”。你说“加个登录功能”，它顺手给你重写了整个路由系统。测试？不存在的，除非你追在屁股后面喊。代码能跑就行，什么 TDD、什么规范，通通当耳旁风。

这不是你的问题，这是当前 AI 编程助手的通病——能力强大，但不可控。

于是，两个明星项目火了：

  • Superpowers（22k stars）：用“强制流程”把 AI 管起来，TDD、子代理审查、Git worktrees，一套组合拳打得像军事化训练。
  • OpenSpec（53k stars）：用“规范驱动”让 AI 别跑偏，写代码前先签“合同”——proposal、specs、tasks，对齐了再动手。

听起来都很美好，对吧？

但问题来了：它们各自都有致命短板。而更讽刺的是，这两个短板恰好是对方的长板。

单打独斗的尴尬：各自都缺了一条腿

OpenSpec 的痛苦：合同签了，但执行全靠“自觉”

OpenSpec 的流程很美：

/opsx:propose "加个暗黑模式"
# → 生成 proposal.md, specs/, design.md, tasks.md
# → 你和 AI 对齐需求，签字画押
/opsx:apply  # 开始实施

然后呢？然后就没有然后了。

OpenSpec 只管“定义正确的事情”，不管“怎么正确执行”。它把 tasks.md 交给 AI，但那个 AI 会不会偷懒跳过测试？会不会一次改三个文件偏离原计划？会不会写了代码忘了验证？OpenSpec 全不管。

实测中暴露的问题有多痛：

  • AI 说“task 1.1 完成了”，但你打开代码一看——测试没写，或者写了但没跑
  • 说好的“先红后绿”呢？它直接把实现和测试一起提交了，你根本不知道测试是不是真的会失败
  • 更可怕的是，它可能“顺便”优化了不相关的模块，引入了新 bug，而你还在埋头审查 task 1.1

OpenSpec 的本质问题是：它信任 AI 会“自觉”遵守规范。但现实是，AI 的自觉 ≈ 初中生的自觉 —— 作业会抄，但过程能省则省。

Superpowers 的痛苦：流程完美，但需求永远在变

Superpowers 的军事化流程确实解决了“执行失控”：

  1. brainstorming → 深度挖掘需求
  2. writing-plans → 生成每行代码级别的精确计划
  3. test-driven-development → 强制红-绿-重构
  4. subagent-driven-development → 子代理两阶段审查

每一步都像流水线，AI 想偷懒？门都没有。

但它的致命问题是：计划赶不上变化。

你花了 2 小时和 AI 做 brainstorming，敲定了设计文档。AI 写了 50 个精确到代码行的任务。然后你说：“等等，再加一个第三方登录吧。”

—— 整个流程崩塌了。

  • 需要重新 brainstorming？
  • 50 个任务要手动修改？
  • 已执行的测试要重写？

Superpowers 太“重”了。它假设需求在计划阶段就已完美冻结。但在真实开发中（尤其是敏捷团队），需求每时每刻都在变。

Superpowers 的本质问题是：它把“规划”和“执行”死死绑在一起，但现实世界是，你需要边规划、边执行、边调整。

发现了吗？它们其实是“天生一对”

短板
OpenSpec
Superpowers
规划灵活性
✅ 极灵活，随时可改 spec
❌ 太重，改需求成本极高
执行严格性
❌ 全靠 AI 自觉，无强制
✅ 军事化 TDD + 两阶段审查
变更适应
✅ 天然支持迭代
❌ 假设需求冻结
可追溯性
✅ proposal/specs/ 完整记录
❌ 只有计划和代码
跨工具协作
✅ 25+ 种 AI 助手
⚠️ 主要 Claude Code、Codex

完美的组合应该是：

  • 用 OpenSpec 做轻量、灵活、可迭代的规范管理（不怕需求变，随时改 spec）
  • 用 Superpowers 做严格、强制、可审查的执行流水线（每个任务必须 TDD、必须审查）

OpenSpec 负责“签合同”，Superpowers 负责“按合同施工，偷工减料就停工”。

实测：3 个衔接点断了 2 个，真相是什么？

说到这里，必须诚实交代一个事实：两者并没有官方集成，自动串联基本不可行。

一位开发者做了完整实测，结论是：

衔接点
状态
说明
OpenSpec propose → Superpowers brainstorming
✅ 可行（需手动引导）
可以让 AI 读取 OpenSpec 工件作为 brainstorming 基准
Superpowers writing-plans → 读取 OpenSpec tasks
⚠️ 部分可行
需要手动调用，不是自动的
apply 阶段自动触发 subagent
❌ 不可行
OpenSpec 的 apply 不会自动调用 Superpowers 技能

核心原因是：两个仓库的代码互不依赖——OpenSpec 源码里 0 个 superpowers 引用，Superpowers 源码里 0 个 openspec 引用。

所以，“能不能配合使用”的答案是：能，但需要你自己搭建桥梁，不能指望开箱即用。

解决方案：用 OpenSpec Schema 搭建桥梁

OpenSpec 提供了一个关键机制——自定义 Schema。通过编写 schema.yaml，你可以在每个 artifact 生成的 instruction 字段中嵌入约束，从而“引导”AI 按 TDD 方式思考和执行。

三个核心注入点

注入点
作用范围
说明
instruction
仅当前 artifact
在 schema.yaml 的每个 artifact 中配置，AI 生成该 artifact 时注入
rules
匹配 id 的 artifact
在 config.yaml 中配置，影响 AI 生成匹配的 artifact
context
所有 artifact
在 config.yaml 中配置，每次 AI 生成任何 artifact 时都注入

注入叠加顺序：context → rules → instruction → template。也就是说，AI 收到的 prompt 里先有项目背景，再有针对当前 artifact 的规则，再有 schema 里的指令，最后是模板骨架。

完整可复制的 schema.yaml

以下是一个经过实测验证的 TDD 驱动 Schema：

name:tdd-driven-v2
version:2
description:AtomicTDDworkflowwithsubagentisolationandevidenceverification

artifacts:
-id:proposal
generates:proposal.md
description:Initialchangeproposalwithtestablebehaviors
instruction:|
      Create a proposal that explains WHY this change is needed.

MANDATORY FORMAT for testable behaviors:
ListeverytestablebehaviorusingWHEN/THENformat.

Example:
-WHENmarkdownToHtml("#Hello")iscalled
THENresultis"<h1>Hello</h1>"
-WHENmarkdownToHtml("**bold**")iscalled
THENresultis"<strong>bold</strong>"

DoNOTdescribeimplementationdetails.
FocusonWHATshouldhappen,notHOW.
requires:[]

-id:specs
generates:specs/**/*.md
description:BehavioralspecificationswithGIVEN/WHEN/THENscenarios
instruction:|
      Write behavioral specs using GIVEN/WHEN/THEN format.

TDD REQUIREMENT:
-Eachscenariomustbeindependentlytestable
-Expressexpectedbehavior,notimplementation
-Cover:happypath,edgecases,errorcases
requires:
-proposal

-id:design
generates:design.md
description:Technicaldesigndocument
instruction:|
      Create a technical design explaining HOW to implement.

TDD REQUIREMENT:
-Identifytestfilesthatneedtobecreatedormodified
-Specifyteststrategy(unit,integration,e2e)
-Designmustsupportincrementaltesting
requires:
-proposal

-id:tasks
generates:tasks.md
description:ATOMICtasks-eachtaskonlyONETDDphase
instruction:|
      Break work into atomic tasks. EACH TASK MUST CONTAIN ONLY ONE TDD PHASE.

Use checkbox format:-[]

Examples of CORRECT atomic tasks:
-[]RED:Writefailingtestforheadingparsing
-[]GREEN:Implementheadingparser
-[]RED:Writefailingtestforboldparsing
-[]GREEN:Implementboldparser

ExamplesofWRONG(combined)tasks:
-[]ImplementMarkdownparser—supportheadings,bold,italic

NEVERcombineREDandGREENinsametask.
requires:
-specs
-design

-id:plans
generates:plan.md
description:DetailedexecutionplanwithTDDmicro-steps
instruction:|
      Create a detailed execution plan using 2-5 minute micro-tasks.
      Each task must follow RED-GREEN-REFACTOR cycle.

EnforceYAGNIandDRYprinciples.
requires:
-tasks

apply:
requires:[plans]
tracks:tasks.md
instruction:|
    Execute the plan following TDD discipline:

MANDATORY:Usesuperpowers:subagent-driven-developmentskill.

1. For each task in plan.md:
a. RED:Writefailingtestfirst
b. GREEN:Writeminimalimplementation
c. REFACTOR:Cleanupcode
d.Runfulltestsuitetoconfirmnoregressions

2. Evidence required in each subagent report:
-RED phase:TestoutputMUSTshowfailure
-GREEN phase:TestoutputMUSTshowpass
-REFACTOR phase:Fulltestsuiteoutput

Rules:
-Neverwriteproductioncodewithoutafailingtest
-NeverskiptheREDphase
-CommitaftereachGREENphase

四层防护模型

基于上述 Schema，可以建立一个四层防护体系：

第一层：原子化任务

  • 解决的问题：任务内部混合 RED + GREEN，AI 可以合理地一步完成
  • 机制：每个 task 只包含一个 TDD 阶段

第二层：subagent 隔离

  • 解决的问题：AI 跨任务批量执行
  • 机制：每个 task 分配一个独立 subagent，context 完全隔离

第三层：两阶段审查

  • 解决的问题：subagent 在单个任务内过度执行
  • 机制：spec reviewer + code quality reviewer，不通过打回

第四层：验证证据

  • 解决的问题：无法确认 TDD 顺序是否真正执行
  • 机制：subagent 必须报告测试运行输出作为硬证据

实测数据：v1 失败 vs v2 修正

一位开发者做了两轮实测，对比数据如下：

指标
v1（无防护）
v2（四层防护）
任务数
5 个粗粒度任务
26 个原子任务
subagent 调度次数
1 次（一口气写完）
27 次
RED 阶段被跳过
✅ 是
❌ 否
TDD 顺序违规
100%
0%
测试覆盖率
~40%
88%
防护层通过率
0/4
3/4

唯一没通过的那层是“验证证据”——AI 虽然按要求做了 RED-GREEN-REFACTOR，但在报告中“忘记”附上测试输出。这说明即使有 instruction 约束，AI 的执行仍然不是 100% 可靠。

工作流全景：从零到一的完整步骤

环境准备

# 1. 安装 OpenSpec
npm install -g @fission-ai/openspec@latest

# 2. 在项目中初始化（必须指定工具）
cd your-project
openspec init --tools claude

# 3. 安装 Superpowers（以 Claude Code 为例）
/plugin install superpowers@claude-plugins-official
/reload-plugins   # 必须执行才能生效

验证安装：

openspec --version  # 应显示版本号，如 1.3.1+

在 Claude Code 中输入 /superpowers，如果能看到 skill 列表说明 Superpowers 安装成功。

创建自定义 Schema

# 创建 schema 目录结构
mkdir -p openspec/schemas/tdd-driven-v2/templates

# 将上面的 schema.yaml 内容保存到该目录
# 创建模板文件
touch openspec/schemas/tdd-driven-v2/templates/{proposal,spec,design,tasks,plan}.md

配置项目使用该 Schema

创建 openspec/config.yaml：

schema:tdd-driven-v2
context:|
  Tech stack: TypeScript, Node.js, Vitest
  Testing: Vitest for unit tests, Supertest for integration
rules:
specs:
-UseGIVEN/WHEN/THENformatforscenarios
tasks:
-Eachtaskmustbeatomic(onlyoneTDDphase)

启动新变更

在 Claude Code 中执行：

/opsx:propose "实现用户认证功能，支持邮箱登录"

AI 会按你的 Schema 生成 5 个工件：proposal.md → specs/ → design.md → tasks.md → plan.md。

执行实施

/opsx:apply

如果一切正常，AI 会按原子任务逐个执行，每个任务分配独立的 subagent，强制 RED-GREEN-REFACTOR 循环。

检查状态

openspec list                          # 查看所有活跃变更
openspec show <change-name>            # 查看 proposal 内容
openspec status --change <name> --json # 查看依赖状态

现实检验：能保证 100% 可靠吗？

不能。

这是必须承认的事实。OpenSpec 的 instruction 和 rules 都只是文本注入，不是硬约束：

  • OpenSpec 源码里搜索不到任何 hook、callback 或事件机制——零个运行时回调点
  • tracks 只是 checkbox 解析器，不验证执行行为
  • requires 只是文件存在性检查，不验证内容

这意味着：AI 仍然可能忽略 instruction 中的“MANDATORY”指令。

实测中，即使是 v2 的四层防护，也有一层防护被 AI 跳过了（虽然行为正确，但证据缺失）。

但这不意味着方案无效。 它的价值是：**极大降低 AI 跑偏的概率，把成功率从 30% 提升到 75%+**，同时让跑偏时可追溯、可修正。

对比总结

维度
只用 OpenSpec
只用 Superpowers
组合使用（自定义 Schema）
需求变更成本
低
极高（重做计划）
低
代码质量保障
无强制
高
高
可追溯性
高
中
极高
自动化程度
中
高
中高
实施复杂度
低
中
中
可靠性
30-40%
60-70%
75-85%
适用场景
原型、个人项目
严肃项目
生产级项目

最终答案：怎么开始？

方案选择：

场景
推荐
原型验证、快速试错
单用 OpenSpec
个人小工具，错了就删
单用 OpenSpec
生产代码、团队协作、长期维护组合使用 + 自定义 Schema
金融、医疗、安全关键系统
组合使用 + 四层防护全开

快速开始命令汇总：

# 1. 安装 OpenSpec
npm install -g @fission-ai/openspec@latest

# 2. 初始化项目
openspec init --tools claude

# 3. 创建自定义 schema 目录
mkdir -p openspec/schemas/tdd-driven-v2/templates

# 4. 在 Claude Code 中安装 Superpowers
/plugin install superpowers@claude-plugins-official
/reload-plugins

# 5. 开始使用
/opsx:propose "你的需求"
/opsx:apply

评论区告诉我：你被 AI“自由发挥”坑得最惨的一次是什么？点赞最高的，我送你一套完整可运行的自定义 Schema 配置包。