我最近在大规模用 AI 编程助手做真实项目最大的感触是你让它写个函数它快得离谱你让它完整做一个模块它就开始东一榔头西一棒子想到哪写到哪需求澄清、任务拆解、测试、代码审查这些环节基本靠你催。说白了AI 编程助手的代码生成能力已经够强缺的是被人为加上去的“软件工程套路”。后来我开始用 Superpowers 框架它把 Claude Code 这类 AI 助手的工作方式从“你问我答”强行掰回到“需求 → 拆解 → 设计 → TDD → 实现 → 审查 → 文档”的流程上实测下来项目推进质量和可维护性明显提升。这篇文章就从一个长期使用者、踩坑者的角度聊聊 Superpowers 框架到底解决了什么问题、怎么用、有哪些值得注意的坑。1. 为什么 AI 编程助手需要“软件工程套路”1.1 从“会写代码”到“会做项目”AI 助手的普遍短板先说个大家都遇到过的事情。你让 AI 助手“帮我实现一个用户注册接口”它很快就能给你甩出 Controller、Service、Mapper 一套代码语法没毛病接口能跑。但如果你让它“帮我完成用户注册模块”问题就来了它不会先去确认用户名规则、密码加密方案、验证码逻辑、重复注册处理、日志埋点、异常码设计……它默认你什么都懂直接按它脑子里那个“平均脸”模板写一版。用一句程序员之间好理解的话说AI 现在是编码器不是工程师。编码器负责把精确的描述变成代码工程师负责把模糊的问题拆成精确的任务并且在过程中控制风险、保证质量、沉淀文档。这个差距在真实项目里非常扎眼不做需求澄清。AI 很少主动追问“你的业务规则是什么”“边界条件有哪些”经常默认需求然后做出一个华丽但不符合规则的方案。不拆任务直接写大文件。它会一次性生成 500 行代码像个学生交大作业而不是像团队里写代码的人那样拆成小步提交、每个提交都有意义。不写测试或者说得好听做得少。你让它写测试它先答应“好的”然后写两个 happy path 就完事边界条件、异常路径基本看心情。不维护文档和变更记录。改了接口不更新 README重构了模块不写设计说明README 永远是第一版的模样。没有代码审查意识。AI 写完就觉得自己对但它的代码里有安全问题、重复逻辑、不合理的依赖关系需要一双外部的眼睛去审。这些短板不是“AI 能力不足”而是缺少过程约束。就像让一个编程高手直接上手团队项目他如果不清需求、不写测试、不做评审照样能把代码库搞成一锅粥。1.2 Superpowers 的切入方式把软件工程流程变成可执行的框架Superpowers 框架解决的就是“让 AI 编程助手按软件工程套路干活”这件事。它不是另一个 IDE 插件也不是通用 agent 框架它更像一套装进 AI 助手里的流程操作系统。它的核心思想很朴素把敏捷开发、测试驱动开发、代码审查、持续重构、文档沉淀这些软件工程实践写成 AI 能理解和执行的“技能”skill然后通过一组命令唤起对应的工作流。AI 的行为不再是自由联想而是被引导着按步骤走。我试用下来觉得它有几个设计上的关键点特别聪明以 Markdown 技能文件为载体。每个技能就是一个带 YAML frontmatter 的 Markdown 文件里面写清楚了触发条件、执行的步骤清单、注意事项、输出格式。这比硬编码插件规则更透明你可以直接改技能文件理解 AI 为什么会那么做。用决策树避免“自由发挥”。它会给 AI 一套 Promise Theory 风格的文档结构让 AI 在需要选择时先讲清楚选项、再给建议、最后等用户确认。简单说就是逼 AI“先想后说先报给用户再动手”。内置了软件工程生命周期的工作流。从项目启动、需求澄清、任务拆解、TDD 循环、代码审查到文档生成都有对应的命令和技能。你只要在会话里敲一个/planAI 就不再是“回答你的问题”而是“开始执行一场软件工程流程”。使用场景上我个人觉得它最适合这几类人独立开发者。没人帮你 review 代码没人逼你写测试和文档Superpowers 等于给你配了一个“流程型虚拟同事”。小团队负责人。你不需要自己写各种 prompt 模板去“驯服”AI直接让全团队用同一套工作流产出一致性会好很多。AI 编程重度用户。如果你每天用 Claude Code、Gemini CLI 或类似的命令行 AI 编程助手你会发现这套框架能明显减少“改着改着就跑偏”的挫败感。2. Superpowers 框架拆解命令、技能与上下文2.1 安装与初始化先说安装。Superpowers 不是一个独立的应用它需要依附在一个已有的命令行 AI 编程助手之上。以我常用的 Claude Code 为例安装思路是把框架仓库里的技能目录复制到 Claude Code 的技能加载目录下然后在会话里通过命令让 AI 加载这些技能。按社区里常见实践大概是这样# 克隆框架仓库到你喜欢的地方 git clone https://github.com/your-local-path/superpowers.git ~/tools/superpowers # 找到你的 AI 助手技能目录 # Claude Code 一般用 ~/.claude/skills mkdir -p ~/.claude/skills # 把关键技能放进去 cp -r ~/tools/superpowers/skills/* ~/.claude/skills/不同版本的 AI 助手技能目录可能不一样安装前最好先看官方文档确认路径。装完之后你可以在 AI 会话里直接问“你现在有哪些技能”它如果正确加载会列出一串技能清单比如 plan、task-management、test-driven-development、code-review、documentation 等等。这里有一个我第一次用时的误区以为装完框架就意味着 AI 会自动进入“软件工程模式”。实际上它更像是给你武器库里塞了一堆工具但你需要用特定命令去唤起。比如你想开始规划一个项目就敲/plan你想进入 TDD 流程就敲/begin去创建一个任务。这个“唤起”的动作非常重要后面我会在实战部分展开。2.2 核心命令与技能结构用久了之后我常用的命令基本是下面这几个它们构成了日常开发的循环命令作用触发时机/plan启动需求澄清和项目规划拿到一个模糊任务时/todo查看当前任务列表任何时候/begin从任务列表里领取一个任务并开始实施准备动手编码前/test让 AI 按 TDD 方式为当前功能编写或运行测试开发一个功能时/review触发代码审查技能检查当前改动完成一个任务后/docs更新项目文档和 changelog一个里程碑完成后先说/plan。这个命令会唤起一个技能它的核心流程是AI 先分析需求然后向你提出澄清问题。注意它不是随便问两句而是会给出“我理解的需求是什么”“我打算采用哪些技术方向”“这里有几个开放性问题”这种结构化输出。问完之后它会等待你确认只有当你回答完所有问题它才会进入“生成计划”阶段。/todo和/begin是一对。在工程实践里一个庞大的需求会被拆成一个个任务每个任务对应一个 todo 项。AI 会维护一个todo.txt之类的任务清单文件用它来记忆当前进度。这特别重要因为** AI 的上下文是有限的但任务清单文件是持久的**。哪怕聊了几百行后 AI 忘了之前的约束只要它去读一下 todo 文件就能找回上下文。/test是 TDD 流程的触发入口。它会检查当前任务有没有对应的测试文件如果没有先让 AI 根据需求写出失败测试然后才进入实现阶段。这个顺序一旦反了效果就会大打折扣。/review是很多人忽视但价值极高的命令。它会让 AI 站在“代码审查者”的立场检查当前任务涉及的代码改动。注意这里有个细节它不仅仅是让 AI 看自己的代码而是要求 AI 以“外部 reviewer”的角度给出问题清单。我会在后面的实操里详细展示。2.3 几个常用的经典工作流Superpowers 框架里内置了多个技能但我实际用得最顺手的是下面三个工作流它们一起构成了一个接近真实团队节奏的开发循环。第一个是项目启动工作流。当我要开始一个新项目比如做一个 Python 后端服务我会先运行/plan。AI 会问我一系列问题项目的主要用户是谁要解决什么核心问题有没有必须遵守的技术标准对外接口如何设计数据模型大概是什么样这些问题回答完之后它会在项目目录下生成一份项目计划文档记录目标、假设、风险、里程碑。第二个是TDD 开发循环。它对应/begin/test。理想状态下你会先看到 AI 写一个失败的测试再写最小实现让测试通过然后运行测试套件最后回到 todo 列表把当前任务标记为完成。这个循环和我们平时做的“先写实现再补测试”完全不同刚开始会有种“多此一举”的感觉但坚持几个任务之后你会明显感到功能边界的清晰度大幅提升。第三个是代码审查与文档沉淀工作流。任务完成不代表模块完成。我会让 AI 运行/review审查一波当前改动把安全问题、重复代码、命名不一致的地方列出来再逐条修复。之后用/docs更新 README、API 文档和 CHANGELOG。这一步确保了项目在长期演进中不会烂掉。3. 实战让 AI 按软件工程流程从需求走到发布3.1 需求澄清与任务分解我先拿一个实际例子来说。假设我要做一个简单的“用户反馈收集系统”功能包括提交反馈、查看反馈列表、管理员标记处理状态。这个需求看起来够简单了吧但如果不经过澄清就直接让 AI 写大概率会得到一套“四不像”代码字段设计随意、状态流转不严谨、没有权限控制。我用 Superpowers 的流程走一遍。先运行/planAI 给出的第一个动作不是写代码而是输出一段结构化确认大致长这样我先梳理一下需求理解请你确认或补充 1. 核心用户 - 普通用户提交反馈、查看自己提交的反馈列表 - 管理员查看全部反馈、修改处理状态 2. 已经明确的点 - 反馈至少包含标题、内容、联系方式可选、提交时间 - 处理状态机待处理 - 处理中 - 已关闭 3. 需要你定的点 - 是否需要反馈分类标签建议加 - 是否需要邮件通知管理员MVP 阶段建议不做 - “已关闭”之后是否允许用户追问建议允许关联原反馈 请逐条答复或者直接输入“按建议执行”。这段输出好在哪里它把需求里模糊的部分全摊到了桌面上。我第一次用时直接说了句“按建议执行”AI 就开始进入下一步。这一步如果跳过后面所有代码都像没有地基的楼。接下来是任务分解。AI 会根据确认过的需求生成一个 todo 列表我印象里它会把整个项目拆成这样[ ] 搭建 Python FastAPI 项目骨架[ ] 设计数据模型用户反馈表[ ] 实现提交反馈接口[ ] 实现查询反馈列表接口[ ] 实现管理员状态更新接口[ ] 为上述接口补充 pytest 自动化测试[ ] 编写接口文档和 README看到这里你会发现它的任务拆解粒度非常适中不是一个大任务到底也不是碎成那种“敲一下键盘”的任务。每个任务都能独立验证、有完成标准。在真实工程里这种粒度最容易追踪进度。3.2 设计讨论与 TDD 开发任务列表拿到之后就可以用/begin领取第一个任务了。以“提交反馈接口”为例我先让 AI 进入这个任务然后运行/test触发 TDD 流程。TDD 流程的第一步是写测试。AI 会先根据任务描述写一个会失败的 pytest 测试比如# tests/test_feedback_submit.py from fastapi.testclient import TestClient from app.main import app client TestClient(app) def test_submit_feedback_success(): resp client.post(/api/feedback, json{ title: 登录页加载慢, content: 首页白屏超过3秒, contact: userexample.com }) assert resp.status_code 200 data resp.json() assert data[id] is not None assert data[status] pending这个测试写完之后AI 会停下来说明“测试当前会失败因为接口还不存在”然后才进入实现阶段。这个“顺序感”非常重要因为大多数 AI 默认是一上来写实现然后补一个看似通过的测试。而 TDD 模式下它必须让测试先崩溃一次再让测试变绿。整个过程你都能看到不会出现“测试永远都绿但什么都没测”的虚假安全感。实现写完AI 会自己运行测试命令。假设测试通过它会更新 todo 文件把这个任务标记成完成然后建议领取下一个任务。整个过程非常像一个远程开发者按小时报进度而不是一下子丢给你一堆代码。值得说的是如果你的项目本来就是 Spring Boot 或 Django 这类重量级框架TDD 循环的思路不会变变的只是测试库的选型。比如 Java 项目里可以用 JUnit Mockito前端项目可以用 Vitest核心逻辑是“红灯 → 绿灯 → 重构”。3.3 代码审查、重构与文档沉淀任务全部开发完真正的“软件工程味道”才开始显现。我习惯在项目功能完成一轮后运行/review。AI 会进入代码审查技能逐文件检查当前改动。它给的问题清单举几个我遇到的典型例子代码审查发现的问题 1. [安全] app/routers/feedback.py: 未校验用户身份管理员接口任何人可调用。 建议增加管理员身份鉴权中间件至少用 Bearer token 校验。 2. [健壮性] app/schemas/feedback.py: 反馈内容未做长度限制数据库字段为 VARCHAR(500) 超长输入会触发 500。建议限制输入长度为 500 并在字段上设置 max_length。 3. [一致性] tests/test_feedback_list.py: 测试数据直接写死在用例里 建议用 pytest fixture 统一管理避免后续改动大面积波及。 4. [可维护性] app/services/feedback_service.py: 状态流转逻辑集中在 if-else 里 建议抽成状态机常量表方便后续扩展更多状态。看到这个清单的那一刻我是真的有点震惊。它并不是在“敷衍式”地夸自己的代码而是真的站在审查者角度挑刺尤其是第一项管理员鉴权缺失这是个非常典型且容易被 AI 自动生成忽略的安全问题。如果没有/review这一步这个接口就带着漏洞上线了。按着问题清单我会让 AI 逐条修复。修复完一轮再运行/review确认。这个循环一般两三轮后就干净了。最后是/docs。AI 会检查项目的 README、API 接口文档、CHANGELOG并基于代码实际情况做更新。比如接口清单变了它会自动补齐新接口的请求、响应示例不会出现“文档停留在第一个月”的尴尬情况。这一步看起来不产生代码价值但对项目长期维护很关键。真实团队里写文档是最没人愿意干的活现在 AI 按套路帮你干了你只需要审一下有没有写歪就行。4. 使用中的常见坑与排查技巧实录4.1 上下文失忆AI 聊着聊着就忘了约束用 Superpowers 跑长任务最容易遇到的问题就是“中途失忆”。比如一开始计划里定了“不用外键”结果做到第三个任务时AI 在生成的数据库迁移文件里偷偷加了ForeignKey。原因很简单它的上下文窗口有限早期对话内容被挤出去了。我排查这类问题的思路分三步第一步检查 todo 文件。框架会维护任务清单文件但如果你发现 todo 文件里没有把“不用外键”这种全局约束记录进去说明这个约束没有进入“持久记忆”。这是我一开始踩过最深的坑。第二步把全局约定写进项目根目录的规则文件。Superpowers 支持把工程约定放在一个显眼的位置让 AI 每次读取 todo 或技能时都能看到。比如我在项目根目录专门放了一个AGENTS.md或者CLAUDE.md里面写明禁止外键、测试必须覆盖边界、错误码统一格式等等。AI 在每轮任务开始时会自动读取它。第三步阶段小结写清楚。一个任务做完后让 AI 在 todo 文件里更新“已完成内容摘要”和“当前技术决策”。这相当于给它自己留了一本笔记后续任务靠读笔记恢复上下文而不是靠猜。4.2 权限策略AI 被卡在“需要确认”里出不来另一个常见的问题是权限。Superpowers 的工作流里AI 需要频繁执行命令比如运行 pytest、执行 git 提交、读取文件。如果你的 AI 编程助手的权限策略设得太紧每个命令都要手动确认一次那整个工作流会碎成一地完全没有“丝滑感”。我现在的做法是分两层设权限安全命令放行读操作、列出文件、运行测试这类命令直接放行比如Read、Glob、Grep、Test。这是 TDD 循环里最频繁的操作不放开就没法跑。高风险命令保持确认比如Write写文件、Edit、Bash里带rm -rf这类操作保持手动确认。毕竟 AI 再强你也得自己担责不能让它一键清了数据库。权限调整工具的界面各家不同但思路是一样的你要把“命令确认”这层摩擦只留在真正有风险的地方而不是所有操作都半路截停。如果你发现 AI 跑一个/plan要确认八次不要骂框架蠢先去调权限。这里提醒一句如果你用的是闭源云端模型执行危险命令时务必自己盯一下终端输出。框架不背这个锅最终责任在你。4.3 自定义技能的正确姿势Superpowers 自带的技能已经能覆盖大多数场景但总有一些团队特有的流程比如“上线前必须更新数据库迁移脚本”“接口必须生成 OpenAPI schema”“提交信息必须带任务编号”。这些需求没法靠通用技能满足所以你要学着自己给 AI 加技能。自定义技能的本质是写一个 Markdown 文件。文件前面加一段 YAML frontmatter声明技能名称和描述然后正文里写清楚技能执行的步骤和约束。举个例子我想让 AI 在提交代码前强制检查“有没有未提交的迁移脚本”--- name: migration-check description: 在提交代码前检查数据库迁移脚本是否齐全并输出检查结果。 --- # 迁移检查技能 ## 触发条件 - 用户要求提交代码 - 当前项目使用数据库迁移工具 ## 执行步骤 1. 收集当前分支所有涉及数据库模型的改动文件。 2. 检查对应迁移脚本是否已生成命名是否包含任务编号。 3. 若有缺失输出缺失清单并主动生成迁移脚本。 4. 若全部齐全输出“迁移检查通过”。 ## 注意事项 - 不要修改已生成的迁移脚本。 - 只允许新增迁移不允许删除历史迁移。把这个文件放在技能目录下AI 下次就能自动识别这个技能。它跟“你在 prompt 里让 AI 记住某件事”的区别在于技能是有触发条件和执行步骤的AI 会在特定时刻主动想起它而不是等用户提醒。这一点非常强大。自定义技能你写几次就会摸到规律不要写空话每一条指令都要能让 AI 当成检查清单来执行。你写得越具体AI 表现得就越像一个守规矩的工程师。5. 写在最后的实操体会用 Superpowers 框架这段时间我最深的体会是让 AI 走软件工程流程本质上不是技术问题而是规则问题。AI 的能力早就够了缺的是被强制执行的流程约束。这个框架做的不是“让 AI 更聪明”而是“让 AI 更规矩”。它把需求澄清、任务拆解、TDD、代码审查、文档沉淀这些曾经依赖团队纪律才能做到的事变成了一套代码化的流程AI 只要按流程走项目质量就能稳定在及格线以上。你如果是第一次接触我不建议马上把它用在大型老项目里。先拿一个新项目或者一个边界清晰的小模块试水跑完一个完整的/plan到/docs循环你就能感受到“流程快感”到底是什么。等你熟悉了那套命令和技能文件结构再慢慢往团队流程里推会平滑很多。另外自己没有把握的工程决策该自己拍板的还是要拍板AI 永远只是那个执行力很强的“流程执行者”方向感还得人来掌握。