1. 为什么要用 AI 工程化工具？
1.1 AI 编程的痛点
如今，用 Claude Code、Cursor、Copilot 等 AI 编程助手写出几百行代码已经很容易，但用过一段时间后，很多人都会遇到类似的问题：
-
AI 容易“自由发挥” —— 你说“加个登录功能”，它可能直接写个完整的 OAuth，而你要的只是一个简单的验证码校验。
-
缺乏结构化思考 —— 需求不清时，AI 不会主动问“为什么”、“有哪些替代方案”，而是直接给出一个看似能跑、但完全不符合长期维护需求的实现。
-
反复返工 —— 因为前期没有对齐规格，代码写到一半才发现方向错了，又得让 AI 重写。
-
团队协作困难 —— 每个开发者使用的 AI 行为不一致，代码风格、提交信息、设计文档五花八门，难以统一。
这些问题的本质是：AI 默认模式是“尽力完成当前指令”，而不是“遵循一套严谨的工程流程”。我们需要给 AI 装上“工程化的大脑”。
1.2 解决方案简介
目前社区中出现了两类工具，从不同角度解决上述问题：
| Superpowers | 给 AI 注入一套“强制遵守的工程工作流” | 让 AI 按照需求分析 → 制定计划 → TDD → 代码审查 → 验证的流程工作，减少随机性 |
| OpenSpec | 规范驱动开发 (Spec-Driven Development) | 让 AI “先写规格，再写代码”，确保实现与需求契约完全一致 |
两者可以结合使用：Superpowers 管流程纪律，OpenSpec 管需求契约。
2. Superpowers 详解
2.1 什么是 Superpowers？
Superpowers 是 GitHub 用户 obra 发起的一个开源项目（obra/superpowers），其核心是一组 skills（技能）。每个技能是一个 Markdown 文件（SKILL.md），里面描述了 AI 在某个特定场景下应该遵循的行为模式、工作流步骤和注意事项。
当这些技能文件被放到 AI 工具指定的目录后（如 .claude/skills/），AI 就可以在合适的时机自动加载并使用它们。
中文社区有一个增强版 superpowers-zh，它在原版基础上：
-
翻译并优化了所有技能描述，更符合中文开发者的阅读习惯
-
增加了 6 个中国特色技能（中文代码审查、中文 Git 工作流、中文文档排版等）
-
提供了更便捷的一键安装脚本
一个典型的 Superpowers 工作流看起来是这样的：
text
用户提需求
↓
[brainstorming] → 需求分析、方案对比、生成设计文档
↓
[writing-plans] → 将设计拆解为可执行任务清单
↓
[executing-plans] → 按计划逐步实施
↓
[test-driven-development] → 红-绿-重构循环
↓
[code-review] → 审查代码质量
↓
[verification-before-completion] → 最终验证
2.2 安装方式
2.2.1 一键全量安装（最推荐）
对于 superpowers-zh，最简单的方式是运行其自带的安装脚本：
bash
npx superpowers-zh
这个命令会：
自动检测你当前项目中使用的 AI 编程工具（Claude Code、Cursor、Windsurf 等）
将全部 20 个技能文件复制到对应工具的 skills 目录（例如 .claude/skills/）
如果检测到需要，还会生成一个 CLAUDE.md 引导文件，帮助 AI 激活技能
适合人群：新手、希望快速体验完整工作流的人。
2.2.2 手动复制技能文件夹
如果你想完全掌握安装细节，或者只想安装部分技能，可以手动操作：
克隆或下载 superpowers-zh 仓库：
bash
git clone https://github.com/jnMetaCode/superpowers-zh.git
进入仓库，找到 skills/ 目录：
bash
cd superpowers-zh/skills
ls # 你会看到 20 个文件夹，每个是一个技能
在你的项目根目录下创建对应的技能目录（以 Claude Code 为例）：
bash
mkdir -p .claude/skills
将你需要的技能文件夹整个复制过去：
bash
cp -r brainstorming .claude/skills/
cp -r test-driven-development .claude/skills/
# 只复制你想要的
2.2.3 仅安装特定技能（进阶精选）
如果你对工作流已经比较熟悉，只想增强某几个能力，可以只复制下面几个最核心的技能：
| using-superpowers | 必须安装。它是所有技能的“调度器”，强制 AI 在会话开始时遵守整个流程 |
| brainstorming | 需求分析与设计 |
| test-driven-development | TDD 实施 |
| systematic-debugging | 系统化调试 |
| verification-before-completion | 任务完成前的自动验证 |
注意：即使只安装一个技能，也建议把 using-superpowers 一并装上，否则 AI 可能不会主动触发其他技能。
2.3 如何让 AI 真正“学会”使用技能？
很多用户遇到的问题是：我已经把技能文件复制到 .claude/skills/ 了，但 Claude 依然我行我素，根本不用那些技能。
2.3.1 为什么会这样？
Claude Code 加载技能的逻辑是：读取每个技能文件夹下的 SKILL.md，其中开头的 YAML 元数据中有一个 description 字段。只有当当前用户问题的语义与某个技能的 description 匹配时，Claude 才会考虑使用该技能。
而 superpowers-zh 的技能中，只有 using-superpowers 的 description 被设为了极为激进的内容（类似“在任何会话开始时都必须考虑使用本技能”）。其他技能（如 brainstorming）的 description 相对温和，需要 AI 判断“当前是否在分析需求”才会触发。
如果 AI 在会话一开始没有感知到 using-superpowers，那么整个流程就不会被激活。
2.3.2 解决方案
方案 A：运行一键安装脚本（推荐）
npx superpowers-zh 会在你的项目根目录生成一个 CLAUDE.md 文件。这个文件是在每次新会话开始时自动加载的，内容中会明确告诉 AI：“请先加载并使用 using-superpowers 技能”。这是最省心的方式。
方案 B：手动创建 CLAUDE.md
在项目根目录手动创建一个 CLAUDE.md，写入以下内容：
markdown
# 项目开发规范
本项目已集成 Superpowers 工程化技能，所有技能位于 .claude/skills/ 目录。
请严格遵守以下流程：
1. **会话启动时**：首先加载 `using-superpowers` 技能，并遵循其指引。
2. **收到新任务**：必须先使用 `brainstorming` 技能进行需求分析和方案设计。
3. **开始编码**：默认遵循 `test-driven-development` 流程。
4. **遇到 Bug**：必须使用 `systematic-debugging` 进行根因分析。
5. **声称“完成”之前**：必须执行 `verification-before-completion` 验证。
6. **提交代码**：提交信息遵循 `.claude/skills/chinese-commit-conventions/SKILL.md` 中的规范。
如果你不确定当前应该使用哪个技能，请询问我。
方案 C：手动调用斜杠命令
如果你不想依赖 AI 的自动判断，可以直接使用斜杠命令来强制调用某个技能。superpowers-zh 会自动注册以下命令（以 Claude Code 为例）：
text
/superpowers:brainstorming
/superpowers:writing-plans
/superpowers:test-driven-development
/superpowers:code-review
…
例如，直接输入 /superpowers:brainstorming，Claude 就会进入头脑风暴模式，引导你完成需求分析。
2.3.3 验证安装
重启 Claude Code 后，输入一个宽泛的问题，比如：“我想给这个项目添加一个新功能，请帮我按照正确的工程流程来做。” 然后观察 Claude 的回答是否包含“我将先使用 brainstorming 技能分析需求”之类的话。如果看到，说明技能已被正确激活。
2.4 常用技能清单与触发时机
下面是 superpowers-zh 中包含的 20 个技能的分类速查表。
核心工程实践（10个）
| brainstorming | 需求分析、方案对比、生成设计文档 | 接到复杂、模糊的新需求时 |
| writing-plans | 将设计拆解为可执行任务清单 | 在 brainstorming 产出设计后 |
| executing-plans | 按计划逐步实施，控制节奏 | 计划已就绪，开始编码时 |
| test-driven-development | 遵循“红-绿-重构”的 TDD 流程 | 实现核心逻辑时 |
| systematic-debugging | 根因分析、日志取证、修复验证 | 遇到难以定位的 bug 时 |
| code-review | 审查代码质量，提出改进建议 | 完成一个功能模块或提交 PR 前 |
| requesting-code-review | 主动请求同事或 AI 进行审查 | 需要外部视角检查代码时 |
| finishing-a-development-branch | 规范合并分支的流程 | 功能开发完成，准备合并分支时 |
| using-git-worktrees | 使用 Git worktree 隔离开发任务 | 需要并行开发多个不相关的功能时 |
| verification-before-completion | 完成前强制跑测试、lint、构建 | 声称“完成”或“没问题”之前 |
协作与流程（4个）
| dispatching-parallel-agents | 将无依赖的任务派发给多个 AI 并行处理 | 面对多个独立、可并行的子任务时 |
| subagent-driven-development | 启动子 Agent 执行任务，并进行双重审查 | 任务可以被明确委派给子 Agent 时 |
| receiving-code-review | 处理他人发起的代码审查反馈 | 收到 PR 审查意见，需要更新代码时 |
| using-superpowers | 主技能，作为其他技能的“启动器” | 系统在后台自动运行，分发任务 |
中国特色增强（6个）
| chinese-code-review | 符合国内团队文化的“中文+话术模板”代码审查 | 进行代码审查，且团队沟通偏好温和建议时 |
| chinese-git-workflow | 为国内 Git 平台（Gitee 等）优化的工作流 | 项目托管在国内 Git 平台时 |
| chinese-documentation | 规范中文排版、中英文混排、术语保留 | 书写中文技术文档时 |
| chinese-commit-conventions | 中文团队适用的提交规范（Type 英文，Scope 中文） | 编写 Git 提交信息时 |
| mcp-builder | 指导构建 Model Context Protocol 服务器的标准化流程 | 需要开发 MCP 服务器以扩展 AI 能力时 |
| workflow-runner | 在 AI 编程工具内直接运行 YAML 定义的多角色工作流 | 需要执行跨文件的、多步骤的自动化流程时 |
小技巧：你可以在对话中直接说“请使用 chinese-code-review 技能检查这段代码”，AI 会严格按照该技能定义的规范执行。
3. OpenSpec 详解
3.1 什么是 OpenSpec？
OpenSpec 是由 Fission AI 团队开发的开源工具（Fission-AI/OpenSpec），它的核心思想是 规范驱动开发（Spec-Driven Development, SDD）。
简单说：在写任何代码之前，先用一种半结构化的语言（EARS 语法）写出一份“规格说明书”（spec），这份说明书明确定义了系统应该做什么、不应该做什么。然后，AI 根据这份规格说明书去实现代码。实现完成后，还可以自动验证代码是否严格遵循了规格。
这与 Superpowers 形成互补：
-
Superpowers 强调 流程的纪律性（先分析、再计划、再 TDD……）
-
OpenSpec 强调 需求的前置契约化（把“要做什么”写得清清楚楚，AI 照着做）
OpenSpec 为 Claude Code、Cursor 等 20 多种 AI 工具提供了插件支持，表现为一组斜杠命令（如 /opsx:propose）和对应的技能文件。
3.2 安装步骤
环境要求
-
Node.js >= 20.19.0（建议使用最新的 LTS 版本）
-
一个支持 OpenSpec 的 AI 编程工具（Claude Code、Cursor、Continue 等）
检查 Node.js 版本：
bash
node –version
# 应输出 v20.19.0 或更高
Step 1：全局安装 OpenSpec CLI
bash
npm install -g @fission-ai/openspec@latest
安装完成后，验证：
bash
openspec –version
# 例如：1.3.0
Step 2：在项目中初始化
进入你的项目根目录，运行：
bash
cd your-project
openspec init
初始化过程中，CLI 会做几件事：
自动检测你项目中已安装的 AI 工具（如检查是否有 .claude/ 目录）
询问你是否要为这些工具安装 OpenSpec 插件（选择 yes）
创建以下目录结构：
text
your-project/
├── openspec/
│ ├── specs/ # 主规格文档存放处
│ ├── changes/ # 进行中的变更（提案）
│ └── config.yaml # OpenSpec 配置
├── .claude/
│ ├── skills/ # 会生成 opsx-*.md 技能文件
│ └── commands/
│ └── openspec/ # 会生成所有斜杠命令定义
如果你是第一次运行，还会在 openspec/specs/ 下生成一个示例规格文档。
注意：如果你使用的是 Cursor，初始化时选择 Cursor，CLI 会在 .cursor/ 目录下生成对应的技能和命令。
3.3 核心工作流命令
OpenSpec 定义了一套完整的“提案 → 实施 → 验证 → 归档”工作流，每个阶段有对应的斜杠命令（在 Claude Code 中直接输入即可）。
| 提案 | /opsx:propose | 一次性生成完整的变更提案 | proposal.md, specs/, tasks.md, design.md |
| /opsx:explore | 非结构化的想法探索，不产生正式提案 | 对话记录，可后续转为提案 | |
| /opsx:new | 开始一个新的变更（创建 change 目录） | 空白的变更骨架 | |
| 实施 | /opsx:apply | 根据 tasks.md 逐步实现代码 | 实现代码，自动更新任务状态 |
| /opsx:continue | 基于依赖关系，逐步创建下一个缺失的工件 | 按顺序生成规格/设计/任务 | |
| /opsx:ff | 快速创建所有规划工件（一次产出全部） | 提案 + 规格 + 设计 + 任务 | |
| 验证 | /opsx:verify | 验证实现代码与规格说明是否一致 | 验证报告 |
| 同步与归档 | /opsx:sync | 将变更中的规格差异合并到主规格文档 | 更新 openspec/specs/ |
| /opsx:archive | 归档一个已完成的变更 | 将变更移到 archive/，合并规格 | |
| /opsx:bulk-archive | 批量归档多个已完成的变更 | 同上，批量处理 |
推荐新手使用的命令序列： /opsx:propose 添加xxx功能 → 审查生成的文档 → /opsx:apply → /opsx:verify → /opsx:archive
3.4 实战示例：为 React 项目添加暗黑模式
假设我们有一个 React 项目，需要添加暗黑模式（dark mode）功能。下面展示完整的 OpenSpec 流程。
3.4.1 生成提案
在 Claude Code 中，输入：
text
/opsx:propose 为项目添加暗黑模式功能
几秒钟后，OpenSpec 会在 openspec/changes/add-dark-mode/ 目录下生成 4 个文件：
1. proposal.md（为什么做？做什么？）
markdown
# 添加暗黑模式
## Why
当前应用只有亮色主题，在夜间使用时刺眼，用户需要手动调节系统亮度。添加暗黑模式可以提升夜间使用体验。
## What
– 新增主题切换按钮（亮色/暗黑/跟随系统）
– 定义 CSS 变量主题系统
– 使用 `localStorage` 持久化用户选择
2. design.md（怎么做？技术设计）
markdown
# 技术设计
## 主题管理策略
– 使用 React Context 提供主题状态
– 定义 `–bg-primary`, `–text-primary` 等 CSS 变量
– 在 `document.documentElement` 上切换 `data-theme` 属性
## 组件改动
– 新增 `ThemeProvider` 包装整个应用
– 新增 `ThemeToggle` 组件
– 修改现有组件的硬编码颜色为 CSS 变量
3. specs/ui.md（规格，使用 EARS 语法）
markdown
# UI 规格 – 暗黑模式
## 主题切换
### REQ-1: 提供主题切换按钮
**当** 用户点击主题切换按钮时，系统 **应** 在亮色和暗黑主题之间切换。
### REQ-2: 持久化用户偏好
**当** 用户切换主题后，系统 **应** 将当前主题保存到 `localStorage`，并在页面重载时恢复。
### REQ-3: 跟随系统主题
**当** 系统主题偏好发生变化时，如果用户未手动指定主题，系统 **应** 自动切换到对应的主题。
4. tasks.md（任务清单）
markdown
# 实施任务
– [ ] 1. 在 `src/styles/themes.css` 中定义亮色和暗黑的 CSS 变量
– [ ] 2. 创建 `src/context/ThemeContext.tsx` 实现主题状态逻辑
– [ ] 3. 在 `src/App.tsx` 中使用 `ThemeProvider` 包装
– [ ] 4. 创建 `src/components/ThemeToggle.tsx` 主题切换按钮
– [ ] 5. 将现有组件中的硬编码颜色替换为 CSS 变量
– [ ] 6. 添加跟随系统主题的监听器
3.4.2 审查与调整
你可以直接对 Claude 说：“我看了提案，觉得 REQ-3 跟随系统主题可以先不做，去掉它。” Claude 会自动更新 specs/ui.md 和 tasks.md，移除对应的任务。
3.4.3 实施开发
确认提案无误后，输入：
text
/opsx:apply
Claude 会按照 tasks.md 的顺序，逐步实现每个任务，并在完成后自动将任务标记为 [x]。你只需要在关键节点（比如完成 CSS 变量定义后）确认一下即可。
3.4.4 验证与归档
所有任务完成后，运行验证：
text
/opsx:verify
OpenSpec 会检查实现是否满足规格中的每条需求。如果发现有偏差（比如缺少主题持久化），验证会失败并指出具体问题。
修复所有问题后，运行归档：
text
/opsx:archive
此时，openspec/changes/add-dark-mode/ 目录会被移动到 openspec/archive/，而 specs/ui.md 中的增量规格会被合并到 openspec/specs/ui.md 主规格文档中，成为项目永久的设计资产。
4. 两者如何协同使用？
Superpowers 和 OpenSpec 不是竞争关系，而是可以完美互补：
| 需求模糊 | brainstorming 生成设计文档 | （可选）/opsx:explore 非正式讨论 |
| 需求明确 | （跳过） | /opsx:propose 生成规格和任务清单 |
| 编码实施 | test-driven-development 按 TDD 写代码 | /opsx:apply 按任务清单实施 |
| 遇到 Bug | systematic-debugging 根因分析 | （可选）/opsx:verify 检查规格一致性 |
| 完成验证 | verification-before-completion | /opsx:verify 最终验证 |
| 归档 | （可选）finishing-a-development-branch | /opsx:archive 合并规格 |
一个典型的高效组合流程：
text
用户提出一个不太清晰的需求
↓
[Superpowers] 使用 brainstorming 技能 → 产出清晰的设计文档
↓
[OpenSpec] 根据设计文档，运行 /opsx:propose → 生成规格和任务清单
↓
[Superpowers] 使用 test-driven-development 技能 + [OpenSpec] /opsx:apply → 编写代码
↓
[OpenSpec] /opsx:verify → 验证规格覆盖
↓
[Superpowers] verification-before-completion → 最终确认
↓
[OpenSpec] /opsx:archive → 归档
在实际对话中，你可以这样告诉 AI 组合使用：
“请按照 Superpowers 工作流来分析这个新需求，完成 brainstorming 后，用 OpenSpec 生成正式提案，然后用 TDD 方式实现。”
5. 常见问题与避坑指南
5.1 技能复制后 AI 仍不遵循流程
现象：已经将 skills/ 文件夹复制到 .claude/skills/，但 Claude 完全无视，还是随意发挥。
原因：如前文 2.3 所述，AI 需要被“引导”才能激活 using-superpowers 技能。
解决：
-
首选：运行 npx superpowers-zh 重新生成 CLAUDE.md。
-
次选：手动创建 CLAUDE.md，内容参考 2.3.2 中的模板。
-
临时方案：每次对话开始时，先输入“请加载 using-superpowers 技能”。
5.2 OpenSpec 命令不可用（command not found）
现象：输入 /opsx:propose 后，Claude 提示“Unknown command”。
原因：
-
没有在项目中运行 openspec init。
-
或者运行后没有重启 Claude Code。
解决：
确认项目根目录存在 openspec/ 文件夹。
确认 .claude/commands/openspec/ 目录下存在 .md 命令文件。
完全退出 Claude Code，重新在项目目录启动。
5.3 技能全部是英文，我想要中文
现象：无论是 Superpowers 还是 OpenSpec，生成的文档、提示信息都是英文。
解决：
-
Superpowers：使用 superpowers-zh 替代官方原版。它的所有技能描述、模板都是中文的。
-
OpenSpec：在项目根目录的 openspec/config.yaml 中添加：
yaml
language: zh-CN
重新运行 /opsx:propose 后，生成的文档就会是中文。
5.4 权限弹窗太多，每步都要确认
现象：AI 执行 git commit、读写文件、运行测试时，Claude Code 频繁弹出“是否允许执行”的窗口。
解决：启动 Claude Code 时加上 –dangerously-skip-permissions 参数（仅在个人开发环境、且你信任 AI 行为时使用）：
bash
claude –dangerously-skip-permissions
5.5 想只保留部分技能，但不知道依赖关系
现象：我只想要 test-driven-development 技能，但复制过去后发现 AI 不会用。
原因：某些技能（如 TDD）虽然在 SKILL.md 中写明了行为，但 AI 可能因为没有 using-superpowers 的“调度”而从不主动调用。
建议的最小技能集合：
-
必须装：using-superpowers
-
按需装：brainstorming, test-driven-development, systematic-debugging, verification-before-completion 这 4 个基本覆盖了 90% 的开发场景。
如果想精简到极致，甚至可以只保留 using-superpowers 和一个你最想要的技能（比如 code-review）。
5.6 如何更新技能到最新版本？
-
Superpowers：重新运行 npx superpowers-zh，它会覆盖旧文件（但不会删除你手动添加的额外技能）。或者 git pull 你 clone 的仓库，再手动复制。
-
OpenSpec：运行 openspec update，CLI 会根据 config.yaml 重新生成所有技能文件和命令。
6. 总结与延伸
6.1 效果评价
经过一段时间的实际使用，这两套工具带来的改变是显著的：
| AI 输出一致性 | 经常偏离需求 | 严格遵循分析→计划→实施流程 |
| 返工率 | 30% 以上的代码需要重写 | 降到 10% 以下 |
| 文档完整度 | 几乎没有设计文档 | 每次变更都有 proposal + specs |
| 团队协作 | 每个人的 AI 行为不同 | 通过共享 skills 目录统一行为 |
| 调试时间 | 随机改代码碰运气 | 系统化根因分析，效率提升 2~3 倍 |
一句话总结：Superpowers 把 AI 从“随性发挥的自由职业者”变成了“遵守公司流程的资深工程师”；OpenSpec 则把“口头需求”变成了“可验证的契约”。
6.2 进阶方向
如果你已经熟练掌握了基础用法，可以继续探索以下方向：
编写自定义技能：在 .claude/skills/ 下新建一个文件夹，参照现有技能的 SKILL.md 格式，编写你自己的团队专属技能（比如“安全审查技能”“性能优化技能”）。
使用 mcp-builder 开发 MCP Server：superpowers-zh 中自带 mcp-builder 技能，可以指导你一步步创建 Model Context Protocol 服务器，让 AI 能够访问内部 API、数据库等。
将 OpenSpec 流程转化为自然语言：社区已有 skilled-spec-cn 项目，它将 OpenSpec 的命令封装成了 4 个自然语言技能（proposal、apply、verify、archive），你直接说“我要提一个提案”，AI 就会执行 /opsx:propose。适合不喜欢记命令的人。
团队配置共享：将 .claude/skills/ 和 openspec/ 目录提交到 Git 仓库，整个团队的 AI 行为会自动同步。还可以在 .claude/settings.json 中统一配置模型参数、禁用某些技能等。
结合 CI/CD：在 PR 流水线中加入 openspec verify 步骤，自动检查 PR 中的代码变更是否与规格文档一致，实现“规格即测试”。
6.3 参考资源
-
Superpowers 官方仓库
-
Superpowers-zh 中文站
-
OpenSpec 官方仓库
-
OpenSpec 官方文档
最后，不要一开始就尝试使用全部 20 个技能 + OpenSpec 全部命令。建议按以下顺序渐进学习：
先单独安装 Superpowers 的 using-superpowers + brainstorming 两个技能，习惯 AI 主动分析需求。
再加入 test-driven-development，体验 TDD 流程。
尝试一个完整功能的 OpenSpec 提案/实施/归档。
最后，将两者结合使用，形成你自己的 AI 工程化工作流。
希望这篇指南能帮助你真正驾驭 AI 编程，让 AI 成为可靠的结对编程伙伴。如果在使用中遇到任何问题，欢迎在评论区交流讨论！
