1. 项目概述AI编程的“方法论”革命如果你和我一样在过去一年里深度体验过 Claude Code、Cursor、Hermes Agent 这些新一代的 AI 编程工具你肯定经历过一个从“惊艳”到“困惑”再到“寻求解法”的过程。最初你惊叹于 AI 能理解你的模糊需求并生成代码接着你发现它经常“答非所问”比如你让它“给用户模块加个批量导出功能”它可能直接写一个没有分页、不考虑内存溢出的同步函数最后你开始琢磨如何让 AI 真正理解“高质量代码”背后的工作流和思考过程这正是superpowers-zh要解决的核心问题。superpowers-zh不是一个代码生成器也不是一个插件库。它是一套系统化的 AI 编程工作方法论的中文增强版。简单来说它通过一系列被称为 “skills” 的指令集教会你的 AI 编程助手如 Claude Code如何像一个经验丰富的工程师那样去思考和行动。这套方法论源自 GitHub 上拥有超过 15.9 万星标的明星项目obra/superpowers而superpowers-zh在完整汉化的基础上针对中国开发者的实际工作环境新增了 6 个原创技能并一口气将支持的工具从 6 款扩展到了 17 款。它的价值在于将你从“与 AI 进行低效对话、反复纠正”的泥潭中解放出来。安装后当你再提出“批量导出”的需求时AI 会先反问你关于格式、数据量、权限等关键问题并提供 2-3 个可选方案供你确认然后再动手。这背后就是brainstorming头脑风暴和writing-plans编写计划这两个 skills 在起作用。无论你是前端、后端还是全栈开发者无论你使用 Cursor 还是通义灵码这套方法论都能显著提升你与 AI 协作的效率和产出质量。2. 核心设计思路从“工具适配”到“工作流内化”为什么我们需要superpowers-zh这样的项目这源于当前 AI 编程工具的一个普遍短板它们很“聪明”但缺乏“经验”。它们能生成语法正确的代码却不懂一个功能从构思到上线需要经过哪些严谨的步骤。superpowers-zh的设计哲学就是将这些隐性的、属于资深工程师的“经验”和“工作流”显式地编码成 AI 能理解和执行的指令。2.1 方法论内核14个通用编程技能英文原版的 14 个 skills 构成了这套方法论的核心骨架。它们不是针对某个特定语言或框架而是覆盖了软件开发的通用生命周期需求与设计阶段brainstorming和writing-plans确保在写第一行代码前需求和方案是清晰的。开发与实施阶段executing-plans指导 AI 分步骤实施test-driven-development强制推行先写测试的纪律systematic-debugging提供结构化的排查方法。协作与交付阶段requesting-code-review和receiving-code-review规范了代码审查流程verification-before-completion要求在声称完成前必须提供通过测试的证据。高级工作流dispatching-parallel-agents和subagent-driven-development引入了多智能体协作的概念适合复杂任务分解。using-git-worktrees和finishing-a-development-branch则集成了现代 Git 工作流。注意这些 skills 不是魔法。它们本质上是精心设计的、高度结构化的 prompt 模板。当你激活某个 skill 后AI 助手会在处理你的请求时自动将这些预设的思考框架和检查清单融入其响应中。例如激活 TDD skill 后AI 会坚持先为你生成测试用例再生成实现代码。2.2 中国特色增强6个原创技能的实战价值英文原版的方法论虽好但直接套用到国内开发环境难免有些“水土不服”。superpowers-zh的 6 个原创技能正是为了解决这些痛点chinese-code-review(中文代码审查)西方的代码审查评论可能非常直接如“This is wrong.”。在国内团队协作中我们更倾向于“建议式”或“疑问式”的沟通比如“这里是否可以考虑……以避免潜在的并发问题” 这个 skill 会引导 AI 在生成审查意见时采用更符合国内团队文化的表达方式强调建设性和可操作性。chinese-git-workflow(中文 Git 工作流)国内开发者不仅用 GitHub还大量使用 Gitee、Coding、极狐GitLab等平台。这个 skill 教会 AI 理解这些平台的特性分支命名规范、PR/MR 模板、以及 CI/CD 集成方式如.cnb.yml用于腾讯云原生构建。chinese-documentation(中文技术文档)直接机翻的英文文档读起来生硬且容易产生歧义。这个 skill 定义了中文技术文档的排版规范、中英文术语混排规则如何时用中文括号、何时保留英文术语旨在生成阅读流畅、符合国内开发者习惯的文档。chinese-commit-conventions(中文提交规范)虽然 Conventional Commits 是国际标准但全英文的 commit message 对部分国内团队门槛较高。这个 skill 提供了一种中英文混合的适配方案例如feat(用户模块): 新增批量导出功能支持 CSV/Excel 格式既保持了结构又提升了可读性。mcp-builder(MCP 服务器构建)Model Context Protocol (MCP) 是让 AI 连接外部工具和数据源的新兴标准。这个 skill 指导 AI 如何规划、设计和实现一个生产可用的 MCP 服务器例如连接内部数据库、调用企业 API 等极大地扩展了 AI 编程助手的边界。workflow-runner(工作流执行器)这是对subagent-driven-development的强化和具体化。它允许你在 AI 工具内通过一个 YAML 文件定义包含多个角色如架构师、开发、测试的复杂工作流并让 AI 自动按流程执行和协调模拟一个小型团队的协作。这 6 个技能并非简单的翻译或包装而是基于中国开发者日常工作中的真实痛点提炼而成是superpowers-zh区别于原版的真正价值增量。2.3 广泛工具链支持一键覆盖你的主力工具原版superpowers主要支持 6 款工具。superpowers-zh则将支持列表扩展到了17 款几乎囊括了目前所有主流的 AI 编程 CLI 和 IDE。这背后的工程考量是降低使用门槛。无论你的团队或个人习惯使用哪款工具都能无缝接入这套方法论。更重要的是其安装策略智能识别一键安装。通过npx superpowers-zh命令工具会自动扫描你的项目目录识别出你正在使用的 AI 编程工具通过检测特定的配置文件或目录如.cursor/、.hermes/等并将所有 20 个 skills 安装到正确的位置。如果自动识别失败你也可以通过--tool 工具名参数显式指定。这种设计极大地简化了配置流程避免了用户需要为不同工具记忆不同安装命令的麻烦。3. 核心技能深度解析与实战要点理解了设计思路我们再来深入看看几个核心技能是如何工作的以及在实战中需要注意什么。我将以最常用的几个技能为例拆解其内部机制和使用技巧。3.1 头脑风暴与编写计划避免“方向性返工”很多低效的 AI 编程对话都始于需求不清。brainstorming技能强制 AI 在动手前先与你进行一轮“需求澄清会话”。实操示例 当你对 AI 说“我们需要一个用户登录系统。” 如果激活了brainstormingAI 的回应将不再是直接写代码而是会提出一系列问题认证方式是邮箱/密码、手机号验证码、还是第三方 OAuth微信/钉钉/飞书安全要求是否需要双因素认证2FA密码存储策略加盐哈希会话管理使用 JWT 还是 Session CookieToken 刷新机制如何用户体验是否需要记住我、忘记密码、注册验证等功能非功能需求预计用户量级是否需要考虑防刷机制这个过程看似“慢”实则“快”。它避免了 AI 基于错误假设生成一个不完整的系统导致你后续需要花费大量时间进行补充和修改。writing-plans技能则是在brainstorming达成共识后将确认后的需求拆解成具体的、可执行的开发任务列表例如“1. 设计用户表结构2. 实现密码加密工具函数3. 编写登录 API 端点4. 实现 JWT 签发与验证中间件……”实操心得在与 AI 进行头脑风暴时尽量用业务语言描述问题而不是技术语言。不要说“实现一个 RESTful API”而应该说“提供一个接口让前端能提交用户名和密码并返回一个令牌用于后续访问”。AI 通过 skill 引导会帮你将业务语言转化为技术方案。3.2 测试驱动开发提升代码信心的不二法门TDD 是公认的优秀实践但靠自律坚持很难。test-driven-development技能将 TDD 流程固化到了与 AI 的交互中。工作流程红你提出一个功能需求如“给UserService添加一个根据邮箱查找用户的方法”。AI 会首先为你编写这个方法的测试用例例如测试查找成功、查找失败、参数为空等情况并运行这些测试当然会失败因为方法不存在。绿接着AI 会编写最少量的代码来实现这个功能使刚才的测试通过。重构在测试通过的保护下AI 会建议或执行代码重构优化结构、提高可读性并确保重构后所有测试依然通过。这个技能的强大之处在于它让 TDD 变成了一个自动化的、与 AI 对话的自然流程。你不需要额外记忆 TDD 的步骤只需要正常提出需求AI 就会引导你完成整个过程。注意事项对于复杂的、涉及外部依赖如数据库、第三方 API的功能直接写单元测试可能比较困难。此时test-driven-developmentskill 会引导你先使用 Mock 或 Stub 来隔离外部依赖。你需要确保你的项目已经配置了相应的测试框架如 Jest for JavaScript, pytest for Python和 Mock 库AI 才能生成正确的测试代码。3.3 系统化调试从“猜谜”到“侦查”当代码出现 Bug 时新手和高手的主要区别在于排查的系统性。systematic-debugging技能将调试过程分为四个阶段教会 AI 有条理地帮你解决问题定位首先AI 会要求你提供尽可能多的上下文错误信息、堆栈跟踪、输入数据、预期输出与实际输出。它会引导你增加日志或使用调试器来缩小问题范围。分析基于收集到的信息AI 会分析可能的原因并列出假设清单按可能性排序。假设针对最可能的假设AI 会设计一个验证实验例如修改某行代码或提供一个特定的输入。修复验证假设成立后AI 会提出修复方案并提醒你修复后需要运行哪些相关的测试来确保没有引入回归。实战场景你的 API 在压力测试下返回 500 错误。没有 skill 的 AI 可能直接猜是数据库连接池问题。而拥有systematic-debugging技能的 AI 会先让你检查日志定位到是某个服务调用超时然后分析是网络问题、下游服务负载过高还是自身配置不当接着建议你调整超时参数或增加熔断机制进行验证最后给出配置代码并提醒你更新对应的集成测试。3.4 中文代码审查与 Git 工作流贴合国情的协作规范chinese-code-review和chinese-git-workflow这两个技能是团队协作的润滑剂。代码审查风格当 AI 扮演审查者时它会使用诸如“这里的内存释放逻辑在异常路径下是否能保证执行”、“这个魔法数字86400是否考虑提取为常量SECONDS_PER_DAY以提高可读性” 这类建议性口吻。同时它会特别关注国内项目中常见的痛点比如拼音命名的变量、过于复杂的中文注释、以及对某些国内特有中间件如 RocketMQ, Dubbo的使用规范。Git 工作流集成这个技能让 AI 理解基于git-flow或GitHub Flow变体的中文团队实践。例如当你要求“为 JIRA 编号为 PROJ-123 的需求创建一个特性分支”时AI 不仅会执行git checkout -b feature/PROJ-123-user-export还可能提示你“分支已创建。根据我们团队的规则是否需要先在 Gitee 上创建对应的 Pull Request 草案并关联PROJ-123任务” 它还能帮你生成符合 Gitee 或 Coding 平台规范的 PR 描述模板。4. 安装、配置与多工具实战指南理论讲完了我们进入实战环节。superpowers-zh的安装力求简便但针对不同工具仍有细节需要注意。4.1 一键安装与原理剖析最推荐的方式是使用 npm或 yarn/pnpmcd /your/project npx superpowers-zh这条命令背后做了很多事情依赖检查它会检查本地是否安装了superpowers-zh的 npm 包如果没有则从网络获取。环境探测递归扫描当前项目目录寻找特定工具的标志性文件或文件夹。例如发现.cursor/目录 - 识别为 Cursor IDE 项目。发现.hermes/目录 - 识别为 Hermes Agent 项目。发现CLAUDE.md文件 - 识别为 Claude Code 或 Copilot CLI 项目。技能安装根据识别到的工具将skills/目录下的所有技能文件夹复制到该工具约定的技能存放路径。例如对于 Claude Code会复制到./.claude/skills/下。配置更新对于某些工具如 Kiro、Trae可能还需要在对应的配置文件如.kiro/steering/always.md中添加引用这些技能的指令。如果自动识别失败例如在一个全新空目录你可以使用--tool参数显式指定npx superpowers-zh --tool cursor npx superpowers-zh --tool claude-code4.2 主流工具配置详解虽然一键安装覆盖了大部分场景但了解不同工具的配置机制有助于你排查问题和进行高级定制。对于 Claude Code / Copilot CLI 技能会被安装在./.claude/skills/目录下。每个技能是一个独立的文件夹内含一个SKILL.md文件。Claude Code 会自动加载该目录下所有技能。你可以在项目根目录的CLAUDE.md文件中通过特定指令如Use the brainstorming skill来激活某个技能。对于 Cursor Cursor 的技能或称规则存放在./.cursor/rules/目录。superpowers-zh会将技能安装到这里。你需要在 Cursor 的设置中启用“项目级规则”或者直接在聊天框中通过rules来引用它们。一个关键技巧是你可以在.cursor/rules/always.md文件中import你最常用的几个技能让它们在所有对话中默认生效。对于 Hermes Agent Hermes 的技能路径是./.hermes/skills/。安装后你需要在项目根目录的HERMES.md或.hermes.md文件中显式地引用你需要的技能。例如添加一行- skills/brainstorming。Hermes 的一个优势是它对长上下文和复杂指令的支持非常好非常适合运行subagent-driven-development这类需要多轮复杂规划的技能。对于 VS Code GitHub Copilot 这是通过 Copilot 的“自定义指令”功能实现的。技能会被安装到./.github/superpowers/目录。你需要在 VS Code 的 Copilot 设置中将./.github/copilot-instructions.md文件的内容复制到“自定义指令”框中。这个文件会引用superpowers/目录下的技能。注意这种方式下技能的交互性可能不如原生 CLI 工具强更多是提供背景知识和思维框架。避坑指南安装后技能不生效请按以下步骤排查确认路径检查技能文件是否被复制到了正确的目录。例如对于 Cursor确认./.cursor/rules/下存在brainstorming.md等文件。检查工具配置确保你的 AI 工具已启用“自定义技能/规则”功能。例如在 Cursor 设置中搜索“Rules”。查看加载日志部分工具如 Hermes Agent在启动时会输出加载了哪些技能。查看终端输出是否有错误信息。显式调用在对话中尝试显式输入“使用头脑风暴技能”或“Use the brainstorming skill”。有些工具需要手动激活。查阅专属文档superpowers-zh项目的docs/目录下有针对每个工具的详细安装指南如README.cursor.md里面常有针对特定工具的疑难解答。4.3 技能的组合使用与优先级20 个技能并非每次都要全部使用。合理的策略是根据任务类型组合激活核心技能。开发新功能brainstorming-writing-plans-test-driven-development-executing-plans。这是一个完整的闭环。修复复杂 Bugsystematic-debugging是主力。如果 Bug 涉及多个模块可以结合dispatching-parallel-agents让 AI 分头排查不同假设。进行代码重构requesting-code-review在重构前评估风险test-driven-development确保重构安全verification-before-completion在完成后进行全面测试。团队协作任务chinese-git-workflow管理分支chinese-code-review进行审查chinese-commit-conventions规范提交信息。在 Claude Code 等工具中你可以在一条指令中指定多个技能例如“请使用brainstorming和test-driven-development技能为购物车添加商品库存校验功能。” AI 会融合这两个技能的流程来响应你。5. 常见问题与进阶技巧实录在实际使用中你可能会遇到一些疑问。以下是我和社区成员遇到的一些典型问题及解决方案。5.1 技能冲突与自定义覆盖问题superpowers-zh的技能和我自己写的项目特定规则冲突了怎么办解决大多数 AI 编程工具遵循“就近原则”或“显式优先原则”。以 Cursor 为例你可以在.cursor/rules/下创建更具体的规则文件如for-api.md并在其中import你需要的superpowers-zh技能同时覆盖某些指令。你的项目特定规则会与导入的技能合并当指令冲突时通常后定义的或更具体的规则会生效。关键是理解你所用工具的规则加载和合并机制。5.2 处理 AI 的“过度流程化”问题有时候AI 过于严格地遵循技能流程对于非常简单的任务比如改个变量名也会走一遍“头脑风暴”显得效率低下。解决这是“方法论”类工具的通病。有两个应对策略临时禁用在对话中明确告诉 AI “对于这个简单的重命名任务请跳过 brainstorming 流程直接修改”。创建快捷指令在你的工具中设置一些快捷命令或别名。例如在 Claude Code 的CLAUDE.md中定义quickfix 表示跳过所有技能直接修复代码问题。这样当你输入quickfix 修复拼写错误时AI 就会绕过技能直接执行。5.3 将技能集成到 CI/CD 流水线问题能否在代码合并前自动用chinese-code-review技能进行 AI 审查解决可以但这需要结合工具的 API 和 CI/CD 脚本。例如对于 GitHub Actions你可以创建一个 job在pull_request事件触发时使用actions/checkout拉取代码。安装 Hermes Agent CLI 和superpowers-zh。运行一个脚本让 Hermes Agent 加载chinese-code-review技能并对变更的文件进行分析。将 AI 生成的审查评论通过 GitHub API 提交到 PR 中。 这个过程需要一定的脚本编写能力但superpowers-zh项目提供了针对 Gitee Go、Coding CI 等国内平台的示例配置片段可以作为起点参考。5.4 创作你自己的技能superpowers-zh欢迎符合其定位的 PR。如果你想创作一个针对中国开发者痛点的技能比如“如何为微信小程序设计云函数”可以参考自带的writing-skills技能。它详细阐述了优秀 skill 的构成清晰的定位解决一个具体的、上游未覆盖的工作流问题。结构化的步骤将方法论分解为 AI 可执行的、离散的步骤。具体的示例包含输入、输出示例让 AI 更好地理解其应用场景。检查清单在关键节点提供检查项确保工作质量。创作的核心是不要教 AI 某个框架的语法而是教它使用这个框架完成任务的“最佳思考路径”。5.5 与生态项目的联动superpowers-zh并非孤立存在。正如其文档所述它与agency-agents-zh专家角色库和agency-orchestrator编排引擎构成了一个强大的生态。方法论 角色你可以用superpowers-zh的workflow-runner技能去调用agency-agents-zh中定义好的“资深后端架构师”角色来设计系统再用“测试开发工程师”角色来编写测试用例。superpowers-zh管“怎么做事”agency-agents-zh提供“谁来做”。一键编排对于极其复杂的任务你可以直接使用agency-orchestrator。你只需要一句自然语言描述它就能自动调度agency-agents-zh中的多个专家角色并可能隐式地应用superpowers-zh中的方法论来协调他们的工作。这相当于将“项目管理”和“质量控制”也自动化了。我个人在实际使用中的体会是初期需要一点时间来适应这种“与有方法的 AI”协作的节奏。一旦你熟悉了核心技能的应用场景并将其融入你的日常开发习惯你会发现它带来的不仅仅是效率的提升更是一种代码质量和设计思维上的潜移默化的改善。它强迫你和你的 AI 伙伴在动手前多思考在交付前多验证这恰恰是优秀软件工程的基石。