1. 为什么你的 AI 编程助手总在“瞎写代码”用 AI 编程助手写代码这件事我猜你大概率经历过这样的场景你让它帮你实现一个用户登录模块它噼里啪啦给你吐出来两百行代码看起来像模像样结果一跑就报错。你让它改它改了一个地方又崩了另一个地方。来回折腾五六轮最后你发现还不如自己从头写来得快。问题出在哪不是模型不够聪明。现在的主流大模型写个快排、写个 REST API、甚至写个简单的状态管理能力都绰绰有余。真正的问题是AI 编程助手缺少“软件工程套路”。什么叫软件工程套路说白了就是一套让代码从“能跑”变成“可维护、可扩展、可测试”的工作方式。一个受过训练的软件工程师接到需求不会上来就写代码。他会先理解需求边界再设计接口再考虑异常处理再写测试最后才动手实现。而 AI 编程助手呢它拿到你的 prompt第一反应就是“我要输出代码”至于这段代码放在哪个文件、依赖什么模块、边界条件怎么处理、测试怎么写它基本靠猜。这就是Superpowers 框架要解决的核心问题。它不是另一个代码生成工具而是一套给 AI 编程助手套上的“软件工程行为规范”。你可以把它理解成给 AI 装了一个“工程思维操作系统”——让它不再是一个只会写代码的实习生而是一个懂得先设计再实现、先测试再交付的靠谱工程师。这篇文章适合谁看如果你正在用 Claude、Codex 这类 AI 编程助手但总觉得它们“不太听话”“写出来的东西没法直接用”那这篇就是写给你的。如果你在探索 agent 开发、agent skills 的设计模式想知道怎么让 agent 按结构化流程干活这篇同样有参考价值。我会从设计思路、核心机制、实操配置、常见坑四个维度把 Superpowers 这套框架拆开讲透。2. Superpowers 框架的整体设计思路拆解2.1 核心命题让 AI 从“写代码”转向“做工程”Superpowers 框架最根本的设计哲学是把 AI 编程助手的工作模式从“代码生成”扭转为“工程流程执行”。这两个词看起来差不多实际差别巨大。代码生成模式的逻辑是输入需求 → 输出代码 → 结束。AI 只关心“我能不能生成一段看起来合理的代码”它不关心这段代码在项目中的位置、和其他模块的关系、以及未来怎么维护。工程流程模式的逻辑是输入需求 → 理解上下文 → 设计方案 → 拆解任务 → 逐步实现 → 验证结果 → 交付。每一步都有明确的输入和输出每一步都可以被检查。Superpowers 的做法是通过一套skills 体系来约束和引导 AI 的行为。每个 skill 本质上是一个“行为模板”它定义了 AI 在特定场景下应该遵循的步骤、应该产出的内容格式、以及应该检查的关键点。比如有一个 skill 叫“需求澄清”当用户提出一个模糊需求时AI 不会直接开始写代码而是先按照这个 skill 定义的流程提出几个关键问题来明确需求边界。这种设计的好处在于它不依赖模型本身的“自觉性”。你不需要在 prompt 里反复强调“请先设计再实现”因为 skill 已经把这条规则固化下来了。AI 每次遇到类似场景都会自动走这套流程。2.2 为什么选择 skills 而不是 prompt 模板你可能会问为什么不直接写一套复杂的 prompt 模板为什么要搞一个 skills 框架我一开始也有这个疑问。后来实际用下来才明白prompt 模板和 skills 的本质区别在于结构化和可组合性。prompt 模板是一坨文本你很难在里面定义清晰的“步骤边界”。当你想要 AI 在某个步骤停下来等你确认时prompt 模板做不到——它只能一口气把整段 prompt 喂给模型模型一口气输出结果。skills 则不同。每个 skill 是一个独立的结构化单元它包含触发条件什么时候用这个 skill、执行步骤按什么顺序做什么、输出格式产出什么内容、检查点在哪里停下来确认。这些 skill 可以组合使用比如“需求澄清” skill 执行完后自动触发“方案设计” skill再触发“任务拆解” skill。这种可组合性带来的直接好处是你可以像搭积木一样为不同的项目类型配置不同的 skill 组合。做一个前端项目你可能需要“组件设计”“状态管理”“样式规范”这几个 skill做一个后端 API 项目你可能需要“接口设计”“数据库建模”“错误处理”这几个 skill。Superpowers 框架提供了一套基础的 skill 库同时允许你自定义扩展。2.3 框架的层级结构从“元规则”到“具体动作”Superpowers 的 skill 体系不是扁平的它有一个清晰的层级结构。理解这个层级结构是用好这个框架的关键。最上层是元规则Meta Rules。这些规则不针对具体任务而是定义 AI 的“工作态度”。比如“永远先理解再行动”“永远在修改代码前先读代码”“永远在完成一个任务后做自检”。这些元规则贯穿所有 skill是框架的底层约束。中间层是流程 skillProcess Skills。这类 skill 定义的是“做一件事的标准流程”。比如“新功能开发流程”可能包含需求分析 → 接口设计 → 测试编写 → 代码实现 → 集成验证。每个步骤都有明确的产出物要求。最下层是动作 skillAction Skills。这类 skill 定义的是“具体怎么做某件事”。比如“写单元测试”这个动作可能包含确定测试边界 → 选择测试框架 → 编写测试用例 → 运行测试 → 检查覆盖率。动作 skill 是最细粒度的执行单元。这种层级结构的好处是AI 在执行任务时会先匹配流程 skill再在流程的每个步骤中调用动作 skill。这样既保证了整体流程的规范性又保证了具体操作的可控性。2.4 与传统 agent 框架的本质区别市面上有很多 agent 框架比如 LangChain、AutoGPT 这类。Superpowers 和它们的区别在哪传统 agent 框架的核心是“工具调用”——给 agent 一堆工具搜索、计算、读写文件让它自己决定什么时候用什么工具。这种模式的问题在于agent 的决策空间太大容易跑偏。它可能花大量时间在无关的探索上或者陷入循环。Superpowers 的核心是“流程约束”——它不强调 agent 能调用多少工具而是强调 agent 必须按照预定义的流程走。每个流程步骤都有明确的进入条件和退出条件agent 不能随意跳过或乱序执行。打个比方传统 agent 框架像是给一个新人一堆工具让他自己摸索怎么干活Superpowers 像是给这个新人一本标准作业程序SOP告诉他第一步做什么、第二步做什么、每步做完要检查什么。对于编程这种高度结构化的任务后者的效率明显更高。3. 核心机制深度解析与配置实操3.1 Skill 的定义格式与加载机制Superpowers 的 skill 本质上是一个结构化的配置文件。我实测下来一个标准的 skill 定义通常包含以下几个字段name: 需求澄清 trigger: 用户提出模糊需求时 steps: - 识别需求中的不确定点 - 针对每个不确定点提出具体问题 - 等待用户确认后再进入下一阶段 output_format: 问题列表 确认后的需求描述 checkpoint: 用户确认需求描述后才允许进入方案设计这个格式看起来简单但每个字段都有讲究。trigger决定了 skill 什么时候被激活写得太宽泛会导致 AI 在不该用的时候乱用写得太窄又会导致该用的时候不触发。steps是核心执行逻辑每一步都应该是可验证的动作而不是模糊的描述。checkpoint是最关键的设计——它强制 AI 在关键节点停下来等待人工确认。加载机制方面Superpowers 支持两种模式全局加载和项目级加载。全局加载的 skill 对所有项目生效适合放一些通用的元规则和基础流程。项目级加载的 skill 只对当前项目生效适合放项目特有的规范比如“这个项目用 TypeScript 严格模式”“这个项目的 API 必须返回统一格式”。注意项目级 skill 的优先级高于全局 skill。如果两者冲突以项目级为准。这个设计是为了让项目特有的规范能够覆盖通用规则。3.2 流程编排如何让多个 skill 协同工作单个 skill 只能解决单点问题真正让 Superpowers 发挥威力的是多个 skill 的编排。编排的核心是定义 skill 之间的依赖关系和触发顺序。Superpowers 支持两种编排方式线性编排和条件编排。线性编排就是 A → B → C 的顺序执行。比如“新功能开发”这个流程就是“需求澄清” → “方案设计” → “任务拆解” → “代码实现” → “测试验证”依次执行。每个 skill 完成后自动触发下一个。条件编排则根据执行结果决定下一步走哪个分支。比如“代码审查” skill 执行完后如果发现问题就触发“修复问题” skill如果没问题就触发“合并代码” skill。这种编排方式更灵活但也更复杂需要仔细定义每个分支的触发条件。我个人的经验是新手先从线性编排开始把基础流程跑通再逐步引入条件编排。一上来就搞复杂的条件分支很容易因为某个条件定义不清晰导致整个流程卡死。3.3 上下文管理让 AI 记住“之前做了什么”AI 编程助手有一个天然缺陷上下文窗口有限记不住太长的历史。当你和 AI 来回对话几十轮后它可能已经忘了最开始的需求是什么。Superpowers 通过结构化上下文管理来解决这个问题。具体做法是每个 skill 执行完成后会把关键信息写入一个“上下文文件”。这个文件包含当前任务的目标、已经完成的步骤、待完成的步骤、关键决策记录。当 AI 进入下一个 skill 时它会先读取这个上下文文件而不是依赖对话历史。这样做的好处是即使对话历史被截断AI 仍然能通过上下文文件恢复工作状态。上下文文件的格式通常是 Markdown 或 JSON。我建议用 Markdown因为可读性好方便人工检查和修改。一个典型的上下文文件长这样## 当前任务 实现用户登录模块 ## 已完成 - 需求澄清确认支持邮箱密码登录不支持第三方登录 - 方案设计采用 JWT 方案token 有效期 24 小时 ## 待完成 - 任务拆解 - 代码实现 - 测试验证 ## 关键决策 - 密码加密用 bcryptcost factor 设为 12 - 错误信息统一返回 邮箱或密码错误不区分具体原因3.4 检查点机制在哪里“刹车”最有效检查点是 Superpowers 框架里我最喜欢的设计。它的作用是在关键节点强制 AI 停下来等待人工确认。为什么需要检查点因为 AI 有一个坏习惯它会沿着一个错误的方向一路狂奔。比如它误解了需求然后基于错误的理解设计了方案再基于错误的方案写了代码最后你发现整个东西都是错的只能全部推翻重来。检查点就是用来打断这个链条的。在需求澄清后设一个检查点确保需求理解正确在方案设计后设一个检查点确保技术选型合理在代码实现后设一个检查点确保实现符合预期。检查点的位置选择很关键。设得太少起不到纠偏作用设得太多会严重拖慢效率。我的经验是在“不可逆决策”之前设检查点。什么是不可逆决策比如技术选型、数据库表结构设计、API 接口定义——这些一旦定了后面改起来成本很高。至于变量命名、代码格式这些不需要设检查点让 AI 自己决定就行。4. 完整实操流程从零搭建一个 Superpowers 工作流4.1 环境准备与基础配置在开始之前你需要确认几件事你已经在使用某个支持 skill 机制的 AI 编程助手比如 Claude 的 Projects 功能或者 Codex 的 skill 系统你有一个明确的项目目录代码已经初始化有 package.json 或类似的项目描述文件你了解基本的 YAML 或 JSON 语法因为 skill 定义文件用这两种格式基础配置的第一步是在项目根目录下创建一个.superpowers目录。这个目录用来存放所有 skill 定义文件和上下文文件。目录结构建议如下.superpowers/ ├── skills/ # 存放 skill 定义文件 │ ├── meta/ # 元规则 skill │ ├── process/ # 流程 skill │ └── action/ # 动作 skill ├── context/ # 存放上下文文件 └── config.yaml # 框架配置文件config.yaml是框架的入口配置它定义了 skill 的加载路径、默认的检查点行为、上下文文件的更新频率等。一个最小化的配置长这样skill_paths: - .superpowers/skills/meta - .superpowers/skills/process - .superpowers/skills/action context_path: .superpowers/context auto_checkpoint: true checkpoint_timeout: 300auto_checkpoint设为 true 表示在预定义的检查点自动暂停checkpoint_timeout是等待人工确认的超时时间秒超过这个时间没有确认流程会自动终止避免 AI 无限等待。4.2 编写第一个 Skill从“需求澄清”开始我建议你从“需求澄清”这个 skill 开始写因为它是所有后续流程的入口。如果需求理解错了后面全白搭。一个完整的“需求澄清” skill 定义如下name: 需求澄清 version: 1.0 trigger: 用户提出新功能需求且需求描述中包含模糊词汇如大概类似差不多或缺少关键信息如输入输出格式、边界条件 steps: - action: 提取需求中的核心动词和名词 output: 需求关键词列表 - action: 识别缺失信息 output: 缺失信息清单按重要性排序 - action: 针对前三个最重要的缺失信息生成具体问题 output: 问题列表每个问题附带选项如果有的话 - action: 等待用户回答 checkpoint: true - action: 根据用户回答生成结构化的需求描述 output: 需求描述文档包含功能目标、输入、输出、边界条件、非功能要求 - action: 请求用户确认需求描述 checkpoint: true output_format: Markdown 格式的需求描述文档这个 skill 的关键设计点在于它不假设 AI 能自动理解模糊需求而是强制 AI 先识别模糊点再通过提问来消除模糊。这比让 AI 直接猜要靠谱得多。4.3 配置流程编排把 Skill 串起来有了单个 skill 之后下一步是把它们串成一个完整的流程。Superpowers 的流程编排通过一个叫workflow.yaml的文件来定义name: 新功能开发流程 steps: - skill: 需求澄清 next: 方案设计 - skill: 方案设计 next: 任务拆解 on_failure: 需求澄清 - skill: 任务拆解 next: 代码实现 - skill: 代码实现 next: 测试验证 - skill: 测试验证 next: 完成 on_failure: 代码实现这个编排定义了一个线性流程同时定义了两个失败回退路径方案设计失败时回退到需求澄清测试验证失败时回退到代码实现。这种回退机制很重要因为实际开发中经常出现“设计时发现需求没理解清楚”或者“测试时发现实现有 bug”的情况。4.4 实操现场用 Superpowers 开发一个真实功能光说不练假把式。我拿一个真实场景来演示用 Superpowers 框架让 AI 帮我实现一个“用户注册”功能。第一步触发需求澄清 skill我在 AI 编程助手里输入“帮我实现一个用户注册功能。”AI 没有直接写代码而是按照“需求澄清” skill 的流程先提取了关键词用户、注册然后识别出缺失信息注册方式邮箱/手机号/用户名、密码规则、是否需要邮箱验证、重复注册怎么处理。接着它生成了三个问题注册方式是什么选项邮箱密码 / 手机号验证码 / 用户名密码密码有什么规则选项最少8位含大小写和数字 / 最少6位任意字符 / 无限制是否需要邮箱或手机验证选项需要 / 不需要我回答了这三个问题后AI 生成了结构化的需求描述并请求我确认。我确认后流程自动进入“方案设计” skill。第二步方案设计 skill 执行AI 基于确认后的需求开始设计方案。它输出了技术选型Node.js Express PostgreSQL、接口定义POST /api/register请求体包含 email 和 password、数据库表结构users 表包含 id、email、password_hash、created_at、错误处理策略邮箱已存在返回 409密码不符合规则返回 400。这里有一个检查点AI 停下来等我确认方案。我看了一下觉得 PostgreSQL 对这个项目来说有点重改成了 SQLite。AI 根据我的反馈调整了方案再次请求确认。确认后进入“任务拆解”。第三步任务拆解与代码实现AI 把注册功能拆成了五个子任务创建数据库连接、创建 users 表、实现密码加密工具函数、实现注册接口、编写接口测试。然后按照顺序逐个实现。每个子任务完成后AI 会在上下文文件中更新进度。我随时可以查看上下文文件了解当前进展。第四步测试验证所有代码写完后AI 自动运行测试。第一次运行发现两个问题一个是密码加密的 cost factor 设得太高导致测试超时另一个是错误处理没有覆盖“邮箱格式不正确”的情况。AI 自动回退到“代码实现” skill修复了这两个问题再次运行测试全部通过。整个流程走下来从需求澄清到测试通过大概花了 15 分钟。如果不用 Superpowers我估计需要来回对话 20 多轮而且很可能漏掉一些边界条件。5. 常见问题与排查技巧实录5.1 Skill 不触发或触发错误怎么办这是最常见的问题。你定义了一个 skill期望 AI 在某个场景下使用它结果 AI 要么不用要么在不该用的时候乱用。排查思路分三步第一步检查 trigger 条件是否过于宽泛或过于狭窄。如果 trigger 写的是“用户提出需求时”那几乎每次对话都会触发AI 会疲于奔命。如果 trigger 写的是“用户提出包含注册和邮箱和密码三个关键词的需求时”那稍微换个说法就触发不了。我的经验是trigger 应该基于“需求类型”而不是“关键词”。比如“用户提出新功能需求时”就比“用户提到注册时”要好。第二步检查 skill 的优先级。如果多个 skill 的 trigger 条件重叠Superpowers 会按照优先级决定用哪个。优先级在 skill 定义的priority字段中设置数值越大优先级越高。默认优先级是 0如果你发现某个 skill 总是不触发可以尝试提高它的优先级。第三步查看执行日志。Superpowers 会记录每次 skill 的触发情况包括触发时间、触发原因、执行结果。日志文件在.superpowers/logs/目录下。通过日志可以清楚地看到 AI 在每一步做了什么决策。5.2 上下文文件膨胀导致性能下降用了一段时间后你可能会发现 AI 的响应速度变慢了。一个常见原因是上下文文件太大AI 每次读取都要花很多时间。上下文文件膨胀的原因通常是所有历史记录都往里塞从不清理。比如一个开发了三个月的项目上下文文件里可能积累了几百条已完成任务记录。解决办法是定期归档。我通常每周做一次归档把已经完成且不再需要的任务记录移到context/archive/目录下只保留最近一周的记录和所有未完成的任务。这样上下文文件的大小能控制在合理范围内。另外上下文文件中的“关键决策”部分应该只保留仍然有效的决策。如果某个决策后来被推翻了应该把它标记为“已废弃”或者直接删除避免 AI 被过时信息误导。5.3 AI 在检查点“卡死”不继续执行有时候 AI 到了检查点等你确认但你确认后它却没有继续执行。这种情况通常是因为检查点的状态没有正确传递。排查方法检查上下文文件中检查点相关的记录。正常情况下检查点应该有两个状态pending等待确认和confirmed已确认。如果状态一直是pending说明确认信号没有传达到。常见原因是确认方式不对。有些 AI 编程助手需要你用特定的命令来确认比如输入/confirm而不是随便说一句“好的”。你需要查看你所使用的助手的文档确认正确的确认方式。提示如果你经常忘记确认可以把checkpoint_timeout设长一点比如 600 秒给自己留足时间。5.4 多个 Skill 之间产生冲突当你定义的 skill 越来越多时可能会出现 skill 之间冲突的情况。比如“代码实现” skill 要求“先写测试再写实现”而“快速原型” skill 要求“先写实现再补测试”。如果这两个 skill 同时被触发AI 就会懵。解决冲突的原则是明确每个 skill 的适用场景避免重叠。“代码实现” skill 适用于正式功能开发“快速原型” skill 适用于探索性开发。你可以在 trigger 条件中明确区分如果用户说“快速试一下”“先跑通就行”就触发“快速原型”如果用户说“正式实现”“要上线的”就触发“代码实现”。如果冲突无法避免可以通过优先级来解决。给更重要的 skill 设置更高的优先级确保它在冲突时胜出。5.5 常见问题速查表问题现象可能原因排查方法解决方案Skill 不触发trigger 条件太窄查看执行日志放宽 trigger 条件Skill 乱触发trigger 条件太宽查看执行日志收紧 trigger 条件或降低优先级响应变慢上下文文件过大检查文件大小定期归档历史记录检查点卡死确认信号未传递检查上下文文件状态使用正确的确认命令Skill 冲突适用场景重叠查看触发记录明确场景区分或设置优先级流程中断某个 skill 执行失败查看错误日志修复 skill 定义或手动跳过5.6 我踩过的三个坑第一个坑skill 定义太细。一开始我恨不得把每个操作都定义成一个 skill结果 AI 每做一步都要加载一个 skill效率极低。后来我调整了粒度一个 skill 应该对应一个“有意义的阶段”而不是一个“具体操作”。比如“写代码”是一个阶段“创建一个文件”是一个操作前者适合做 skill后者不适合。第二个坑忽略元规则。我一开始只关注流程 skill忽略了元规则。结果 AI 虽然按流程走了但态度不对——比如修改代码前不读原代码导致改出 bug。后来我加了一条元规则“修改任何代码前必须先读取该文件并理解其逻辑”问题就解决了。第三个坑不做版本管理。skill 定义文件也是代码也需要版本管理。我有一次改了一个 skill 定义导致整个流程跑不通但因为没做版本管理回滚不了只能凭记忆重新写。从那以后我把.superpowers目录也纳入了 Git 管理。6. 进阶玩法让 Superpowers 适配你的团队6.1 团队级 Skill 库的搭建如果你在团队中使用 Superpowers建议搭建一个团队级的 skill 库。做法是在 Git 仓库中创建一个superpowers-skills仓库存放团队通用的 skill 定义。每个项目通过 Git submodule 或包管理工具引入这个库。团队级 skill 库应该包含团队的代码规范命名规则、注释要求、提交信息格式、团队的技术栈约定用什么框架、什么数据库、什么测试工具、团队的流程规范代码审查流程、发布流程。这样做的好处是新项目初始化时直接引入团队 skill 库就能让 AI 按照团队规范干活不需要每个项目重新配置一遍。6.2 根据项目类型定制 Skill 组合不同类型的项目需要不同的 skill 组合。我总结了几种常见项目类型的推荐配置前端项目需求澄清 → 组件设计 → 状态管理设计 → 样式规范检查 → 代码实现 → 视觉回归测试后端 API 项目需求澄清 → 接口设计 → 数据库建模 → 错误处理设计 → 代码实现 → 接口测试 → 性能测试数据处理脚本需求澄清 → 输入输出格式定义 → 异常处理设计 → 代码实现 → 边界测试重构项目现状分析 → 重构目标定义 → 重构方案设计 → 分步重构 → 回归测试你可以根据自己项目的实际情况从这些推荐配置出发增删 skill。6.3 用 Superpowers 做代码审查Superpowers 不仅可以用来写新代码还可以用来做代码审查。你可以定义一个“代码审查” skill让 AI 按照固定流程检查代码name: 代码审查 trigger: 用户请求审查代码时 steps: - action: 读取目标文件 - action: 检查命名规范 output: 命名问题列表 - action: 检查错误处理 output: 缺失的错误处理场景 - action: 检查边界条件 output: 未覆盖的边界条件 - action: 检查性能隐患 output: 潜在性能问题 - action: 生成审查报告 output: Markdown 格式的审查报告按严重程度排序这个 skill 的好处是审查过程标准化不会漏掉重要检查项。人工审查容易因为疲劳或疏忽漏掉一些问题AI 按流程走则不会。6.4 与 CI/CD 流程的集成思路Superpowers 目前主要是一个本地开发工具但你可以把它和 CI/CD 流程集成起来。思路是在 CI 流程中增加一个“AI 审查”步骤让 AI 按照预定义的 skill 检查代码如果发现问题就阻止合并。具体做法是在 CI 配置文件中增加一个 job调用 AI 编程助手的命令行接口传入代码变更和审查 skill获取审查结果。如果审查不通过job 失败PR 无法合并。这种集成方式可以作为一个“额外的安全网”在人工审查之前先过滤掉一些明显问题。但要注意AI 审查不能完全替代人工审查它只能发现一些模式化的问题对于业务逻辑层面的问题还是需要人来判断。6.5 后续扩展方向Superpowers 框架本身还在演进中我觉得有几个方向值得关注一是 skill 的市场化。如果社区能够共享 skill 定义大家就不需要每个人都从头写一遍。你可以直接下载别人写好的“React 组件开发 skill”“Python 数据处理 skill”直接用到自己的项目中。二是 skill 的自动优化。通过分析 AI 的执行日志自动发现哪些 skill 经常失败、哪些步骤经常被跳过然后自动调整 skill 定义。这需要一定的数据积累但长期来看很有价值。三是多 agent 协作。目前 Superpowers 主要面向单个 AI 编程助手未来可以扩展到多个 agent 协作——一个 agent 负责需求分析一个负责代码实现一个负责测试它们通过共享的上下文文件来协同工作。我个人在实际操作中的体会是Superpowers 这类框架的价值不在于让 AI 写出更聪明的代码而在于让 AI 写出更可控的代码。聪明但不控的代码在真实项目中往往是个负担可控但稍微笨一点的代码反而更容易维护和交付。这个取舍值得每个用 AI 编程的人认真想一想。