第一章：项目概览与学习路线

1.1 superpowers-zh 是什么

superpowers-zh 是 jnMetaCode 基于英文上游 superpowers 做出的中文增强版 AI 编程方法论集合。它不是一个普通代码库，也不是某种语言框架，而是一套面向 AI 编程工具的「工作方式插件」：把需求澄清、设计、计划、TDD、调试、代码审查、验证、分支收尾等实践写成可被 AI 助手加载的 Skills，让 AI 在执行任务时先遵循流程，再生成代码。

项目的核心目标可以概括为三句话：

1. 让 AI 先想清楚再动手。 不直接从模糊需求跳到编码，而是先澄清目的、约束、成功标准和可选方案。
2. 让 AI 用工程纪律工作。 用 TDD、系统化调试、完成前验证和代码审查约束「看起来能跑」的草率实现。
3. 让中文团队能直接落地。 在完整汉化基础上补充中文代码审查、中文 Git 工作流、中文技术文档、中文提交规范等本土化能力。

从 README 和 package.json 可以看出，superpowers-zh 当前以 npm 包形式发布，包名为 superpowers-zh，版本示例为 1.1.9，要求 Node.js >=20.0.0。它包含 skills/、agents/、commands/、hooks/、各类工具安装文档以及一键安装脚本 bin/superpowers-zh.js。

1.2 它解决的核心问题

AI 编程工具的常见问题不是「不会写代码」，而是「工作方式太随意」。典型表现包括：

• 用户一句话描述需求，AI 立即开始改代码，遗漏格式、权限、边界条件和性能约束。
• 修 Bug 时凭直觉乱试补丁，没有复现、没有根因、没有回归测试。
• 写完后说「应该好了」，但没有运行测试、构建或 lint。
• 代码审查反馈来了就盲目附和，或者没有验证建议是否适用于当前代码库。
• 中文团队使用英文方法论时，审查表达、提交规范、文档排版和国内 Git 平台流程不贴合实际。

superpowers-zh 的解法是把这些「应该怎么做」固化为 Skills。每个 Skill 都有名称、触发描述和详细流程。当 AI 工具支持 Skill 发现或自定义指令时，AI 就可以在对应场景加载这些流程，用流程约束行动。

1.3 与英文上游的关系

英文上游 superpowers 提供方法论内核：头脑风暴、计划、执行、TDD、调试、代码审查、完成前验证、并行 Agent、子 Agent、Git Worktree 等。superpowers-zh 在此基础上做了三类增强：

1. 完整中文化。 Skill 内容以中文表达，关键技术术语保留英文，降低中文团队理解成本。
2. 工具覆盖扩大。 通过一键安装脚本适配 Claude Code、Copilot CLI、Hermes Agent、Cursor、Windsurf、Kiro、Gemini CLI、Codex、Aider、Trae、VS Code Copilot、DeerFlow、OpenCode、OpenClaw、Qwen Code、Antigravity、Claw Code 等工具。
3. 本土化 Skills。 新增 6 个中国原创 Skill：中文代码审查、中文 Git 工作流、中文技术文档、中文提交规范、MCP 服务器构建、工作流执行器。

因此，可以把英文上游理解为「通用方法论内核」，把 superpowers-zh 理解为「中文团队可直接安装使用的增强发行版」。

1.4 项目目录结构概览

superpowers-zh 的关键目录如下：

学习时不需要一开始阅读全部源文件。建议先理解 README 的项目定位，再从 skills/using-superpowers/SKILL.md 开始，因为它定义了「何时加载其他 Skill」的总入口。

1.5 20 个 Skills 的知识地图

superpowers-zh 的 Skills 可以按学习目标分成 6 组：

1. 工作流入口与元规则

• using-superpowers：开始任何任务时先检查是否有匹配 Skill；如果有，必须使用。
• brainstorming：创造性工作开始前先澄清需求、探索方案、形成设计规格。
• writing-plans：把已确认的规格拆成可执行的实现计划。
• executing-plans：在单独会话中执行计划并设置检查点。

2. 编码质量纪律

• test-driven-development：新功能、Bug 修复、重构和行为变更都先写失败测试。
• systematic-debugging：任何 Bug、测试失败或异常行为都先找根因。
• verification-before-completion：没有新鲜验证证据，不许宣称完成。

3. 审查与协作

• requesting-code-review：完成重要功能后派遣审查者尽早发现问题。
• receiving-code-review：收到反馈后先理解、验证、评估，再实施。
• finishing-a-development-branch：完成后验证测试、提供合并/PR/保留/丢弃选项。

4. 并行与隔离开发

• dispatching-parallel-agents：多个独立问题域时并发分派 Agent。
• subagent-driven-development：每个任务一个全新子 Agent，并进行两阶段审查。
• using-git-worktrees：用 Git Worktree 创建隔离开发空间。

5. 中文团队增强

• chinese-code-review：中文代码审查表达、分级和文化适配。
• chinese-git-workflow：Gitee、Coding、极狐 GitLab、CNB 等国内平台工作流。
• chinese-documentation：中文排版、中英混排、API 文档和技术文档规范。
• chinese-commit-conventions：Conventional Commits 的中文适配和工具链落地。

6. 扩展能力

• mcp-builder：系统化构建生产级 MCP Server。
• workflow-runner：在 AI 工具中运行 agency-orchestrator YAML 多角色工作流。
• writing-skills：像 TDD 一样编写和验证新的 Skill。

1.6 推荐学习路线

入门路线：先让 AI 不乱来

适合刚接触 superpowers-zh 的个人开发者：

1. 阅读 using-superpowers，理解「先匹配 Skill」这条元规则。
2. 学习 brainstorming，让 AI 在实现前先问问题和给方案。
3. 学习 verification-before-completion，要求 AI 用命令输出证明完成。
4. 在真实项目中安装，并用一个小需求验证是否会先设计再编码。

标准工程路线：形成闭环

适合希望把 AI 编程纳入日常开发流程的工程师：

1. brainstorming 产出设计规格。
2. writing-plans 产出实施计划。
3. test-driven-development 按红-绿-重构实现。
4. systematic-debugging 处理失败和异常。
5. requesting-code-review 和 receiving-code-review 处理审查。
6. verification-before-completion 作为最终完成门禁。
7. finishing-a-development-branch 收尾。

团队落地路线：补齐中文规范

适合中文团队：

1. 先落地 chinese-documentation 和 chinese-commit-conventions，统一文档与提交语言。
2. 再落地 chinese-code-review，统一 Review 表达和优先级。
3. 如果团队使用 Gitee、Coding、极狐 GitLab、CNB，则补充 chinese-git-workflow。
4. 在 PR 模板、CI 检查和 AI 自定义指令中引用这些规范。

1.7 学习方法建议

学习 superpowers-zh 不建议「只读不练」。每个 Skill 都是流程型知识，必须在真实任务中体验：

• 选择一个小功能，要求 AI 使用 brainstorming，不允许直接写代码。
• 对一个简单 Bug，要求 AI 使用 systematic-debugging，观察它是否先复现和找根因。
• 对一个已有函数，要求 AI 用 TDD 加一个行为，检查是否先写失败测试。
• 完成任务后，要求 AI 使用 verification-before-completion，只接受真实命令输出。
• 写一段中文技术文档，用 chinese-documentation 检查中英文空格、标点和结构。

最终目标不是背下每个 Skill 的全文，而是在不同场景下知道该启用哪个 Skill，并且能判断 AI 有没有真正遵守它。