1. 项目概述superpowers到底是什么先说结论superpowers 不是一个具体的软件而是一套围绕 AI 编程助手 Codex 构建的工作流增强方案。它的核心思路是把 Codex 这种 AI 编程工具从“问一句答一句”的被动助手变成“能自主规划任务、多轮迭代执行、自动验证结果”的半自主开发代理。我第一次接触这个概念是在一个技术社区的技术分享里。当时看到标题我就愣住了“superpowers”这个名字起得确实有水平——它不叫“codex-plus”也不叫“ai-agent-toolkit”而是用“超能力”这种略带中二感的词准确抓住了这套方案的核心价值弥补 Codex 原生交互模式的短板把开发者从繁琐的提示词管理和上下文拼接中解放出来。这玩意到底解决什么问题用过 Codex 的人应该都有共鸣单次对话表现惊艳但一涉及到跨文件修改、多步骤重构、持续迭代这类长任务就会频繁出现上下文丢失、方向跑偏、改完不验证的问题。superpowers 的思路就是给 Codex 装上“项目管理脑”——通过约定好的工作区结构、任务清单、进度追踪文件让 AI 自己管理自己的执行过程开发者只需要把控大方向和审核产出。这套方案适合谁如果满足下面任一条件都值得深入看看主力使用 Codex CLI 或类似 AI 编程工具的开发人员正在探索 AI 辅助开发但苦于质量不稳定、返工率高的团队对 AI Agent 工作流设计感兴趣想理解“提示词工程之外的另一种提效思路”的技术爱好者。需要提醒的是superpowers 目前并不是一个官方项目更像是一种社区实践。但正因为如此它的设计思路非常接地气不少想法可以直接嫁接到自己的开发流程里。接下来我会从几个层面展开它的核心设计逻辑、关键文件解析、完整实操流程、常见坑和排查手册最后是一点个人体会。2. 核心设计思路拆解为什么是“工作区 计划 追踪”2.1 Codex 原生模式的三个痛点要理解 superpowers 的价值得先看清楚 Codex 原生使用方式的痛点。我把日常使用中遇到的主要问题归纳为三类第一会话上下文容量瓶颈。Codex 的上下文窗口虽然大但塞进去太多内容后模型对早期信息的“注意”会衰减甚至发生遗忘。典型症状是改到一半AI 忘了最开始确定的架构约束开始“自由发挥”。第二方向漂移。连续多轮对话后AI 容易顺着最近的话题跑偏而不是持续朝最终目标前进。很多人应该经历过这种情形本来让它重构一个模块的日志逻辑改着改着它开始优化无关的依赖库版本。第三验证缺失。对话式 AI 默认“完成任务 生成完代码”它不会主动去跑测试、检查编译错误。如果你不明确要求并贴出执行反馈它就默认自己写的没错。2.2 核心解法把 AI 变成“有项目管理意识的开发人员”superpowers 针对上述痛点给出的方案并不花哨概括成一句话给 AI 一套可写可读的“项目文档系统”。具体拆开包含三个设计支柱支柱一约定式工作区结构。项目内划分出专门存放 AI 辅助信息的目录比如计划文档、进度追踪、规范说明。这不是给 AI 看的装饰性文件而是 AI 每次决策前必须“阅读”的参考资料。相当于给 AI 配了一个项目笔记本随时翻看之前记下的重点。支柱二任务清单即执行蓝图。把所有要完成的工作分解成明确的条目每一条包含任务描述、完成标准、依赖关系。AI 执行时不是“凭感觉下一步”而是对照清单逐项推进。完成一条就标记一条就像人用“待办清单”管理自己的日常工作一样。支柱三阶段性验证闭环。每完成一个任务块要求 AI 自动执行验证动作——跑测试、检查语法、启动服务等并把结果记录到进度文件里。下一步行动必须基于前一步的验证结果而不是 AI 的自我感觉。2.3 为什么这套思路能行得通有人可能觉得不就是让 AI 多读几个文件吗至于搞得这么玄乎这里要注意给 AI 看文档和给 AI 建立“工作记忆闭环”本质上是两码事。前者还是你在向 AI 单向灌输信息后者则让 AI 拥有了一套自我管理和自我校验的机制。打个不恰当的比方你雇了一个聪明但健忘的实习生与其每次反复叮嘱不如教会他自己记账、自己列计划、自己检查工作结果。superpowers 做的就是这个“教会记账”的过程。从模型行为的角度来看这套方案利用了 LLM 的一个特性当模型需要连续处理大量信息时把关键信息“外置”到文件里比全部塞进上下文更可靠。通过文件读写AI 可以在关键节点主动“回忆”之前的内容相当于给它做了持久化的记忆管理。这也是为什么很多 AI Agent 框架都在往“带存储的智能体”方向靠拢superpowers 可以算是一个轻量级的实践样本。3. 核心文件与配置详解3.1 工作区目录结构一套典型的 superpowers 工作区目录长这样基于社区常见实践整理your-project/ ├── .ai/ │ ├── project_rules.md # 项目全局规则AI 每次进入必须先读 │ ├── current_tasks.md # 当前任务清单AI 执行的唯一依据 │ ├── progress_log.md # 进度追踪日志记录每步动作与验证结果 │ └── reference/ # 参考文档目录 │ ├── architecture.md # 架构决策记录 │ └── code_style.md # 代码风格约定 ├── src/ └── tests/第一眼看上去无非是多建了个.ai目录但真正用起来这个目录才是整套流程的“中枢神经”。3.2 project_rules.md给 AI 立的规矩这个文件解决的是“AI 每次进入项目后应该遵循什么原则”的问题。建议包含以下内容# 项目规则 1. 在修改任何代码前必须先阅读 current_tasks.md确认当前任务。 2. 每个任务完成后必须运行项目测试命令本项目为 pytest。 3. 修改公共接口时必须同步更新相关调用方。 4. 涉及架构变动的决策必须先写入 reference/architecture.md 再动手。 5. 完成一个任务后立即更新 progress_log.md记录实际改动不要写 已完成 这种空话。写规则时有个关键点规则要具体、可执行、可验证。比如“修改完要测试”AI 可能理解为跑一下语法检查如果写成“必须运行 pytest 并保证所有用例通过”就完全没有歧义。尽量把动词落到具体操作上。3.3 current_tasks.md任务分解的艺术这是整个方案里最有技术含量的部分。任务拆得好不好直接决定 AI 执行的稳定性和产出质量。一条高质量任务条目应当具备五个要素要素说明示例任务编号全局唯一标识TASK-003完成标准可验证的产出物或行为新增calculate_tax()函数并包含边界值测试依赖关系依赖哪些前置任务依赖 TASK-002 的配置模块涉及文件预计触碰的文件范围src/pricing.py、tests/test_tax.py备注其它注意事项兼容 Python 3.9 语法比如可以这样写## 当前任务清单 ### TASK-001搭建配置模块 完成标准src/config.py 提供 get_config() 函数读取 config.yaml。 依赖无 涉及文件src/config.py, config.yaml 备注使用 dataclass 存储配置不引入额外依赖。 状态已完成 ### TASK-002实现税率计算 完成标准新增 calculate_tax()对给定金额返回税率结果处理金额为负数时抛 ValueError。 依赖TASK-001 涉及文件src/pricing.py, tests/test_pricing.py 备注税率表从 config.yaml 读取。 状态进行中这种格式的优势在于AI 不需要从大段对话里推断当前进度一眼就能看到“做到哪了下一步是什么”。3.4 progress_log.md过程留痕的价值progress_log.md 的记录方式比任务清单更细每个执行阶段都要追加条目。推荐按时间顺序记录以下内容## 2025-06-15 10:20 — TASK-002 开工 - 读取 config.yaml确认税率字段 key 为 tax_rate。 - 发现 config.py 中 get_config() 未开放内部字段访问决定增加一个 get_tax_rate() 方法。 - 已运行测试pytest tests/test_config.py全部通过。为什么要这么细致因为 AI 的执行是连续的这个日志记录的就是它自己的“思考过程”和“决策依据”。当上下文中断或方向跑偏时它能通过读日志“拾回记忆”。对于人类审计者来说这个文件也很有价值——万一 AI 出了个隐蔽 bug从日志里能回溯它当时的改动意图定位根因会快很多。3.5 初始化 prompt第一次“唤醒”有了目录结构和模板文件后首次启动要让 AI 进入“superpowers 模式”。比较有效的初始化 prompt 长这样你是本项目的高级开发工程师。请严格按照以下流程工作 1. 先阅读 .ai/project_rules.md并确认理解。 2. 阅读 .ai/current_tasks.md识别当前进行中的任务。 3. 阅读 .ai/progress_log.md了解历史执行情况。 4. 对于当前任务先思考并给出实施计划确认后再动手。 5. 每完成一个子步骤更新 progress_log.md。 6. 完成一个任务后更新 current_tasks.md 中的状态并运行验证命令。这个 prompt 本身不神奇但它把 AI 的“工作模式”从一个盲目填代码的工具切换成了有流程意识的开发人员。实际测试下来初始化 prompt 里提到的规则越具体AI 后续“跑偏率”越低。4. 从零到一的完整实操流程4.1 在已有项目里快速启用 superpowers如果要在现有项目里启用这套流程不建议重写直接增量式引入就行。我的做法是分三步第一步建立配置中心目录如果项目用的是 Git这一步比较重要。cd your-project mkdir -p .ai/reference touch .ai/project_rules.md .ai/current_tasks.md .ai/progress_log.md第二步写项目规则项目规则要小、要准。刚起步时不用一次写十条先写最核心的几条比如“改代码必须跑测试”“完成一步记录一步”。后续遇到重复踩坑再逐步追加规则。规则文件更像是“踩坑案例的沉淀库”不是一次性工程。第三步用一次完整任务验证流程选一个中等复杂度的真实任务比如给现有模块增加一个接口走一遍完整流程初始化 prompt → 生成任务清单 → 执行 → 验证 → 记录。这次验证很关键能发现规则文件里哪些表述有歧义哪些环节 AI 容易卡壳。4.2 新项目从零搭建的参考步骤新项目会更顺畅一些因为约束可以从一开始就定死。我的推荐顺序是写好.ai/project_rules.md尤其是测试命令和目录规范。在current_tasks.md里把第一个里程碑拆成 3 到 5 个任务条目。不写任何业务代码先用初始化 prompt 让 AI 读取所有配置并生成一段简单的测试代码。确认 AI 正确理解流程后再把任务清单逐项放开让它按顺序执行。这里有个小技巧第一轮给 AI 的任务不要接业务功能而是让它搭建工程骨架。比如创建项目目录结构、写 README、初始化配置文件。这类任务边界清晰、不容易出错能让 AI 在低风险环境中熟悉这套工作流。4.3 让 AI 自动更新进度可预期与不可预期两种情况实操中会发现AI 更新进度文件的主动性并不总是稳定。我这里区分两种情况预期更新。每个任务完成节点比如测试通过后明确要求它更新 log。这类更新可以在流程化 prompt 里固定下来让它形成习惯。非预期更新。当 AI 发现计划外的问题比如某个依赖版本冲突、某段代码逻辑隐患要鼓励它先把情况记录下来再继续。我在规则文件里加了一条非常有效的规则如果在执行中发现任何与当前任务无关、但可能影响后续工作的问题请先记录到 progress_log.md再向用户说明情况继续当前任务。不要在没记录的情况下直接忽略或擅自修改。这条规则的价值在于既允许 AI 暴露问题又防止它脱离主线。实际运行时很多“意外发现”都成了后续任务的输入项目进展没有被打断信息也没有丢失。4.4 多轮迭代时的边界控制superpowers 工作流跑起来后还有一个要控制的问题迭代边界。AI 会倾向于在一个任务上越做越深比如实现了功能后顺手把代码风格也优化一遍再补一批它觉得“需要”的注释。我的做法是在规则文件里追加一条不要做任务描述之外的事。任何额外的重构、优化或补充先写入 progress_log.md 的“建议后续任务”部分由用户确认后再执行。这条规则最初是为了防跑偏实际使用中反而成了一个很好的“灵感收集箱”。AI 提出的很多建议确实有价值但因为工作流约束没有当场打断主线最后统一审视时效率极高。5. 把 superpowers 接入 Codex 的实战配置5.1 准备环境在开始之前把依赖环境准备干净。这里以 Codex CLI 环境为例需要一个可用的 Codex CLI 或支持技能调用的 Codex 集成环境一个真实项目目录含 Git 仓库大小无所谓但最好结构清晰可用的测试命令比如pytest或npm test用于验证环节如果对 Codex 配置不熟先把最基础的“能跑通单轮问答”搞定再升级到这套流程。5.2 初始化脚本示例可以用一个简单的命令启动流程。先在自己的 shell profile 里加一个函数把所有零散步骤收拢成一个命令。# 在 ~/.bashrc 或 ~/.zshrc 中 ai_start() { local task${1:-} if [ -z $task ]; then echo Usage: ai_start 你的任务描述 return 1 fi # 确保核心目录存在 mkdir -p .ai/reference [ -f .ai/project_rules.md ] || touch .ai/project_rules.md [ -f .ai/current_tasks.md ] || echo # 当前任务 .ai/current_tasks.md [ -f .ai/progress_log.md ] || echo # 进度日志 .ai/progress_log.md # 调用 Codex CLI传入初始化 prompt 和任务描述 codex $(ai_start_prompt $task) } ai_start_prompt() { cat EOF 你是本项目的高级开发工程师。请严格按照以下流程 1. 阅读 .ai/project_rules.md 2. 阅读 .ai/current_tasks.md 3. 阅读 .ai/progress_log.md 4. 特别关注历史记录中发现但未解决的事项 5. 面向新任务输出实施计划确认后开始执行 6. 每完成一个子步骤追加更新 progress_log.md 7. 任务完成时更新 current_tasks.md 状态并运行验证命令 本次任务$1 EOF }这个脚本的价值不是省那几行打字而是确保每次启动的工作模式一致。人的记忆会模糊脚本不会。所有 AI 辅助会话从一开始就走同一条流程长期维护项目时优势非常明显。5.3 验证环节到底怎么设验证环节设计是整个流程里容易出问题的部分。如果验证太轻比如只做语法检查AI 完全可能出现“代码能编译但业务逻辑全错”的情况。如果验证太重比如要求每次改动都完整跑一遍集成测试执行速度又会拖得人崩溃。我的建议是分成两级验证任务级验证每个任务完成后跑对应的单元测试或构建检查目标是快速发现低级错误。里程碑级验证一组相关任务完成后跑全量测试 类型检查 核心流程手工复测目标是验证集成正确性。在current_tasks.md里用状态字段区分这两级状态已完成任务测试通过 状态已完成里程碑验证通过这种区分能让 AI 和人都清楚“这个功能到底有没有经过完整验证”也能避免“单元测试过了就以为全项目没问题”的误判。5.4 日常使用中的执行节奏建议用超级工作流时我自己习惯用“番茄钟式”的节奏每次给 AI 一个中等任务执行时间控制在 10 到 30 分钟。任务太小流程开销占比过高不如直接手写任务太大中间出现的计划外问题太多上下文消耗会指数级上升。判断任务粒度是否合适的标准很简单这个任务的完成标准能否在一句话内说清楚。如果说不清楚先继续拆分。这个标准对传统开发也适用但在 AI 辅助场景下尤其重要因为你没办法靠“当面沟通”把模糊目标拉回来。6. 常见问题与排查技巧实录6.1 AI 无视任务清单自创需求怎么办现象AI 中途开始改无关文件或者给某个函数增加了清单里没有的参数。原因通常是初始化 prompt 中“先读清单”的指令不够硬或者规则文件没有包含“禁止越界改动”的条款。排查顺序确认project_rules.md里是否包含“不做任务外修改”的规则。没有就先补上。检查 codex 输入的起始 prompt 是否真的让 AI 读了current_tasks.md注意对话历史中可能残留了旧指令。查看progress_log.md看 AI 是从哪一步开始偏离的下次在该节点前后追加更明确的约束。预防加密在规则里写“涉及文件清单以外的修改必须向用户申请”。申请格式固定为“建议新增xxx原因xxx”。这让跑偏从“沉默发生”变成“显式审批”风险大大降低。6.2 上下文还是不够用怎么做压缩现象执行到中间阶段AI 开始忘记早期任务清单里的关键细节。方案不要硬续上下文做一次“定向压缩”。把当前进度和下一步计划固化成一段摘要然后新开会话。摘要建议包含四块- 已完成的里程碑状态摘要 - 当前正在执行的任务描述 - 下一步要执行的动作明确到文件级别 - 最近一次验证命令及其输出摘要这段摘要直接存进progress_log.md的顶部然后在新会话里让 AI 先读摘要再开工。这个方法我实测过不止一次比硬把全部历史搬进上下文有效得多。6.3 AI 的验证结果可信度不高现象AI 说“测试通过”其实根本没跑或者跑了但选择性忽略了失败项。原因模型有时会“脑补”执行结果尤其是它认为“自己写的东西肯定是好的”时。解决方案执行验证时要求 AI 必须贴出原始命令输出片段而不是总结性结论。给出一个格式模板验证命令pytest tests/test_pricing.py -v 验证结果通过 12 项失败 2 项 失败详情test_negative_amount断言异常期望 ValueError 实际返回 None如果发现频繁虚报可以在规则文件里写死“禁止输出不包含原始输出的验证结论”。这一步对稍大型项目尤其重要因为测试失败的排查成本远高于测试本身。6.4 什么时候这套流程不值得用需要老实说一句不是所有项目都适合上 superpowers 这类工作流。判断一个项目适不适合可以参考这几个信号任务高度临时、一次性后续几乎不会再次触碰的脚本不值得。项目尚在架构混沌期每天方向都在剧变的原型代码也不太适合因为任务清单很快就会失真。代码库很大且构建时间长验证成本极高执行效率会大打折扣。相对适合的场景是目标明确、任务可分解、有一定时长几天到几周、验证手段清晰的项目。比如老模块重构、新服务搭建、测试覆盖补齐等。这类项目里工作流带来的秩序感会充分体现。6.5 团队协作时如何避免冲突如果多人共用同一个 Git 仓库.ai目录的维护需要一定纪律。我们在团队里定了几条规则.ai/目录纳入 Git 版本管理让所有人都能看到任务状态的变迁。修改current_tasks.md的人同步在progress_log.md追加一条记录说明改了哪个任务状态、为什么改。如果 AI 在本地工作区里自动更新了任务状态提交前要求人工复核一次防止“AI marking done too early”这类误标。有过一次惨痛教训AI 在本地把任务标成“已完成”但代码根本没推上远程分支团队另一个成员看到状态后误以为功能可用了。从那以后我们规定 AI 不得直接修改远端状态本地状态也要在 PR 描述里同步变更说明。7. 经验总结与进一步思考经过几轮完整项目实验我对这套工作流的真实感受是它并不会让 AI 的代码质量“跳变式提升”但对开发过程的确定性和人机协作的可控性帮助很大。传统对话式 AI 像是一个随时能聊的专家但专家也会有状态波动的时候superpowers 做的事相当于给这个专家配了一本流程手册和一本备忘录让他在状态波动时也能按标准动作走完流程。我自己比较欣赏的设计细节是“进度日志要与任务清单分离”。这个设计早期的版本里任务清单和进度日志是合并的文件结果就是 AI 改状态时经常丢历史信息。拆开之后清单管“未来方向”日志管“历史事实”职责清楚AI 执行时也不会混。后续我自己在用的一个扩展方向是把验证命令从“写死在规则文件里”升级为“按模块动态读取”。比如在reference/下放一个verification.md每个模块指定它的专属验证命令。这样随着项目规模增长验证定义的维护压力不会全部堆在规则文件里AI 也能更精准地对改动模块做针对性检查。最后分享一个经常被忽略的小技巧一个月复盘一次progress_log.md把反复出现的提醒和踩坑点提炼成规则。这不是给 AI 用的是给未来三个月后的自己用的。我见过太多团队花力气建了工作流却从不让工作流自我进化最后只能靠人肉记忆维护规则体系。superpowers 这套东西最适合学习的方式不只是把它直接拿来用而是理解它“如何通过外置信息管理 AI 注意力”的设计哲学再嫁接到自己的日常开发习惯里。动手试一次给它一个真实的任务跑完一轮你就知道这套“超能力”到底能帮你省下多少重复沟通的时间了。 superpowers工作流：让Codex从对话助手变身自主开发代理
1. 项目概述superpowers到底是什么先说结论superpowers 不是一个具体的软件而是一套围绕 AI 编程助手 Codex 构建的工作流增强方案。它的核心思路是把 Codex 这种 AI 编程工具从“问一句答一句”的被动助手变成“能自主规划任务、多轮迭代执行、自动验证结果”的半自主开发代理。我第一次接触这个概念是在一个技术社区的技术分享里。当时看到标题我就愣住了“superpowers”这个名字起得确实有水平——它不叫“codex-plus”也不叫“ai-agent-toolkit”而是用“超能力”这种略带中二感的词准确抓住了这套方案的核心价值弥补 Codex 原生交互模式的短板把开发者从繁琐的提示词管理和上下文拼接中解放出来。这玩意到底解决什么问题用过 Codex 的人应该都有共鸣单次对话表现惊艳但一涉及到跨文件修改、多步骤重构、持续迭代这类长任务就会频繁出现上下文丢失、方向跑偏、改完不验证的问题。superpowers 的思路就是给 Codex 装上“项目管理脑”——通过约定好的工作区结构、任务清单、进度追踪文件让 AI 自己管理自己的执行过程开发者只需要把控大方向和审核产出。这套方案适合谁如果满足下面任一条件都值得深入看看主力使用 Codex CLI 或类似 AI 编程工具的开发人员正在探索 AI 辅助开发但苦于质量不稳定、返工率高的团队对 AI Agent 工作流设计感兴趣想理解“提示词工程之外的另一种提效思路”的技术爱好者。需要提醒的是superpowers 目前并不是一个官方项目更像是一种社区实践。但正因为如此它的设计思路非常接地气不少想法可以直接嫁接到自己的开发流程里。接下来我会从几个层面展开它的核心设计逻辑、关键文件解析、完整实操流程、常见坑和排查手册最后是一点个人体会。2. 核心设计思路拆解为什么是“工作区 计划 追踪”2.1 Codex 原生模式的三个痛点要理解 superpowers 的价值得先看清楚 Codex 原生使用方式的痛点。我把日常使用中遇到的主要问题归纳为三类第一会话上下文容量瓶颈。Codex 的上下文窗口虽然大但塞进去太多内容后模型对早期信息的“注意”会衰减甚至发生遗忘。典型症状是改到一半AI 忘了最开始确定的架构约束开始“自由发挥”。第二方向漂移。连续多轮对话后AI 容易顺着最近的话题跑偏而不是持续朝最终目标前进。很多人应该经历过这种情形本来让它重构一个模块的日志逻辑改着改着它开始优化无关的依赖库版本。第三验证缺失。对话式 AI 默认“完成任务 生成完代码”它不会主动去跑测试、检查编译错误。如果你不明确要求并贴出执行反馈它就默认自己写的没错。2.2 核心解法把 AI 变成“有项目管理意识的开发人员”superpowers 针对上述痛点给出的方案并不花哨概括成一句话给 AI 一套可写可读的“项目文档系统”。具体拆开包含三个设计支柱支柱一约定式工作区结构。项目内划分出专门存放 AI 辅助信息的目录比如计划文档、进度追踪、规范说明。这不是给 AI 看的装饰性文件而是 AI 每次决策前必须“阅读”的参考资料。相当于给 AI 配了一个项目笔记本随时翻看之前记下的重点。支柱二任务清单即执行蓝图。把所有要完成的工作分解成明确的条目每一条包含任务描述、完成标准、依赖关系。AI 执行时不是“凭感觉下一步”而是对照清单逐项推进。完成一条就标记一条就像人用“待办清单”管理自己的日常工作一样。支柱三阶段性验证闭环。每完成一个任务块要求 AI 自动执行验证动作——跑测试、检查语法、启动服务等并把结果记录到进度文件里。下一步行动必须基于前一步的验证结果而不是 AI 的自我感觉。2.3 为什么这套思路能行得通有人可能觉得不就是让 AI 多读几个文件吗至于搞得这么玄乎这里要注意给 AI 看文档和给 AI 建立“工作记忆闭环”本质上是两码事。前者还是你在向 AI 单向灌输信息后者则让 AI 拥有了一套自我管理和自我校验的机制。打个不恰当的比方你雇了一个聪明但健忘的实习生与其每次反复叮嘱不如教会他自己记账、自己列计划、自己检查工作结果。superpowers 做的就是这个“教会记账”的过程。从模型行为的角度来看这套方案利用了 LLM 的一个特性当模型需要连续处理大量信息时把关键信息“外置”到文件里比全部塞进上下文更可靠。通过文件读写AI 可以在关键节点主动“回忆”之前的内容相当于给它做了持久化的记忆管理。这也是为什么很多 AI Agent 框架都在往“带存储的智能体”方向靠拢superpowers 可以算是一个轻量级的实践样本。3. 核心文件与配置详解3.1 工作区目录结构一套典型的 superpowers 工作区目录长这样基于社区常见实践整理your-project/ ├── .ai/ │ ├── project_rules.md # 项目全局规则AI 每次进入必须先读 │ ├── current_tasks.md # 当前任务清单AI 执行的唯一依据 │ ├── progress_log.md # 进度追踪日志记录每步动作与验证结果 │ └── reference/ # 参考文档目录 │ ├── architecture.md # 架构决策记录 │ └── code_style.md # 代码风格约定 ├── src/ └── tests/第一眼看上去无非是多建了个.ai目录但真正用起来这个目录才是整套流程的“中枢神经”。3.2 project_rules.md给 AI 立的规矩这个文件解决的是“AI 每次进入项目后应该遵循什么原则”的问题。建议包含以下内容# 项目规则 1. 在修改任何代码前必须先阅读 current_tasks.md确认当前任务。 2. 每个任务完成后必须运行项目测试命令本项目为 pytest。 3. 修改公共接口时必须同步更新相关调用方。 4. 涉及架构变动的决策必须先写入 reference/architecture.md 再动手。 5. 完成一个任务后立即更新 progress_log.md记录实际改动不要写 已完成 这种空话。写规则时有个关键点规则要具体、可执行、可验证。比如“修改完要测试”AI 可能理解为跑一下语法检查如果写成“必须运行 pytest 并保证所有用例通过”就完全没有歧义。尽量把动词落到具体操作上。3.3 current_tasks.md任务分解的艺术这是整个方案里最有技术含量的部分。任务拆得好不好直接决定 AI 执行的稳定性和产出质量。一条高质量任务条目应当具备五个要素要素说明示例任务编号全局唯一标识TASK-003完成标准可验证的产出物或行为新增calculate_tax()函数并包含边界值测试依赖关系依赖哪些前置任务依赖 TASK-002 的配置模块涉及文件预计触碰的文件范围src/pricing.py、tests/test_tax.py备注其它注意事项兼容 Python 3.9 语法比如可以这样写## 当前任务清单 ### TASK-001搭建配置模块 完成标准src/config.py 提供 get_config() 函数读取 config.yaml。 依赖无 涉及文件src/config.py, config.yaml 备注使用 dataclass 存储配置不引入额外依赖。 状态已完成 ### TASK-002实现税率计算 完成标准新增 calculate_tax()对给定金额返回税率结果处理金额为负数时抛 ValueError。 依赖TASK-001 涉及文件src/pricing.py, tests/test_pricing.py 备注税率表从 config.yaml 读取。 状态进行中这种格式的优势在于AI 不需要从大段对话里推断当前进度一眼就能看到“做到哪了下一步是什么”。3.4 progress_log.md过程留痕的价值progress_log.md 的记录方式比任务清单更细每个执行阶段都要追加条目。推荐按时间顺序记录以下内容## 2025-06-15 10:20 — TASK-002 开工 - 读取 config.yaml确认税率字段 key 为 tax_rate。 - 发现 config.py 中 get_config() 未开放内部字段访问决定增加一个 get_tax_rate() 方法。 - 已运行测试pytest tests/test_config.py全部通过。为什么要这么细致因为 AI 的执行是连续的这个日志记录的就是它自己的“思考过程”和“决策依据”。当上下文中断或方向跑偏时它能通过读日志“拾回记忆”。对于人类审计者来说这个文件也很有价值——万一 AI 出了个隐蔽 bug从日志里能回溯它当时的改动意图定位根因会快很多。3.5 初始化 prompt第一次“唤醒”有了目录结构和模板文件后首次启动要让 AI 进入“superpowers 模式”。比较有效的初始化 prompt 长这样你是本项目的高级开发工程师。请严格按照以下流程工作 1. 先阅读 .ai/project_rules.md并确认理解。 2. 阅读 .ai/current_tasks.md识别当前进行中的任务。 3. 阅读 .ai/progress_log.md了解历史执行情况。 4. 对于当前任务先思考并给出实施计划确认后再动手。 5. 每完成一个子步骤更新 progress_log.md。 6. 完成一个任务后更新 current_tasks.md 中的状态并运行验证命令。这个 prompt 本身不神奇但它把 AI 的“工作模式”从一个盲目填代码的工具切换成了有流程意识的开发人员。实际测试下来初始化 prompt 里提到的规则越具体AI 后续“跑偏率”越低。4. 从零到一的完整实操流程4.1 在已有项目里快速启用 superpowers如果要在现有项目里启用这套流程不建议重写直接增量式引入就行。我的做法是分三步第一步建立配置中心目录如果项目用的是 Git这一步比较重要。cd your-project mkdir -p .ai/reference touch .ai/project_rules.md .ai/current_tasks.md .ai/progress_log.md第二步写项目规则项目规则要小、要准。刚起步时不用一次写十条先写最核心的几条比如“改代码必须跑测试”“完成一步记录一步”。后续遇到重复踩坑再逐步追加规则。规则文件更像是“踩坑案例的沉淀库”不是一次性工程。第三步用一次完整任务验证流程选一个中等复杂度的真实任务比如给现有模块增加一个接口走一遍完整流程初始化 prompt → 生成任务清单 → 执行 → 验证 → 记录。这次验证很关键能发现规则文件里哪些表述有歧义哪些环节 AI 容易卡壳。4.2 新项目从零搭建的参考步骤新项目会更顺畅一些因为约束可以从一开始就定死。我的推荐顺序是写好.ai/project_rules.md尤其是测试命令和目录规范。在current_tasks.md里把第一个里程碑拆成 3 到 5 个任务条目。不写任何业务代码先用初始化 prompt 让 AI 读取所有配置并生成一段简单的测试代码。确认 AI 正确理解流程后再把任务清单逐项放开让它按顺序执行。这里有个小技巧第一轮给 AI 的任务不要接业务功能而是让它搭建工程骨架。比如创建项目目录结构、写 README、初始化配置文件。这类任务边界清晰、不容易出错能让 AI 在低风险环境中熟悉这套工作流。4.3 让 AI 自动更新进度可预期与不可预期两种情况实操中会发现AI 更新进度文件的主动性并不总是稳定。我这里区分两种情况预期更新。每个任务完成节点比如测试通过后明确要求它更新 log。这类更新可以在流程化 prompt 里固定下来让它形成习惯。非预期更新。当 AI 发现计划外的问题比如某个依赖版本冲突、某段代码逻辑隐患要鼓励它先把情况记录下来再继续。我在规则文件里加了一条非常有效的规则如果在执行中发现任何与当前任务无关、但可能影响后续工作的问题请先记录到 progress_log.md再向用户说明情况继续当前任务。不要在没记录的情况下直接忽略或擅自修改。这条规则的价值在于既允许 AI 暴露问题又防止它脱离主线。实际运行时很多“意外发现”都成了后续任务的输入项目进展没有被打断信息也没有丢失。4.4 多轮迭代时的边界控制superpowers 工作流跑起来后还有一个要控制的问题迭代边界。AI 会倾向于在一个任务上越做越深比如实现了功能后顺手把代码风格也优化一遍再补一批它觉得“需要”的注释。我的做法是在规则文件里追加一条不要做任务描述之外的事。任何额外的重构、优化或补充先写入 progress_log.md 的“建议后续任务”部分由用户确认后再执行。这条规则最初是为了防跑偏实际使用中反而成了一个很好的“灵感收集箱”。AI 提出的很多建议确实有价值但因为工作流约束没有当场打断主线最后统一审视时效率极高。5. 把 superpowers 接入 Codex 的实战配置5.1 准备环境在开始之前把依赖环境准备干净。这里以 Codex CLI 环境为例需要一个可用的 Codex CLI 或支持技能调用的 Codex 集成环境一个真实项目目录含 Git 仓库大小无所谓但最好结构清晰可用的测试命令比如pytest或npm test用于验证环节如果对 Codex 配置不熟先把最基础的“能跑通单轮问答”搞定再升级到这套流程。5.2 初始化脚本示例可以用一个简单的命令启动流程。先在自己的 shell profile 里加一个函数把所有零散步骤收拢成一个命令。# 在 ~/.bashrc 或 ~/.zshrc 中 ai_start() { local task${1:-} if [ -z $task ]; then echo Usage: ai_start 你的任务描述 return 1 fi # 确保核心目录存在 mkdir -p .ai/reference [ -f .ai/project_rules.md ] || touch .ai/project_rules.md [ -f .ai/current_tasks.md ] || echo # 当前任务 .ai/current_tasks.md [ -f .ai/progress_log.md ] || echo # 进度日志 .ai/progress_log.md # 调用 Codex CLI传入初始化 prompt 和任务描述 codex $(ai_start_prompt $task) } ai_start_prompt() { cat EOF 你是本项目的高级开发工程师。请严格按照以下流程 1. 阅读 .ai/project_rules.md 2. 阅读 .ai/current_tasks.md 3. 阅读 .ai/progress_log.md 4. 特别关注历史记录中发现但未解决的事项 5. 面向新任务输出实施计划确认后开始执行 6. 每完成一个子步骤追加更新 progress_log.md 7. 任务完成时更新 current_tasks.md 状态并运行验证命令 本次任务$1 EOF }这个脚本的价值不是省那几行打字而是确保每次启动的工作模式一致。人的记忆会模糊脚本不会。所有 AI 辅助会话从一开始就走同一条流程长期维护项目时优势非常明显。5.3 验证环节到底怎么设验证环节设计是整个流程里容易出问题的部分。如果验证太轻比如只做语法检查AI 完全可能出现“代码能编译但业务逻辑全错”的情况。如果验证太重比如要求每次改动都完整跑一遍集成测试执行速度又会拖得人崩溃。我的建议是分成两级验证任务级验证每个任务完成后跑对应的单元测试或构建检查目标是快速发现低级错误。里程碑级验证一组相关任务完成后跑全量测试 类型检查 核心流程手工复测目标是验证集成正确性。在current_tasks.md里用状态字段区分这两级状态已完成任务测试通过 状态已完成里程碑验证通过这种区分能让 AI 和人都清楚“这个功能到底有没有经过完整验证”也能避免“单元测试过了就以为全项目没问题”的误判。5.4 日常使用中的执行节奏建议用超级工作流时我自己习惯用“番茄钟式”的节奏每次给 AI 一个中等任务执行时间控制在 10 到 30 分钟。任务太小流程开销占比过高不如直接手写任务太大中间出现的计划外问题太多上下文消耗会指数级上升。判断任务粒度是否合适的标准很简单这个任务的完成标准能否在一句话内说清楚。如果说不清楚先继续拆分。这个标准对传统开发也适用但在 AI 辅助场景下尤其重要因为你没办法靠“当面沟通”把模糊目标拉回来。6. 常见问题与排查技巧实录6.1 AI 无视任务清单自创需求怎么办现象AI 中途开始改无关文件或者给某个函数增加了清单里没有的参数。原因通常是初始化 prompt 中“先读清单”的指令不够硬或者规则文件没有包含“禁止越界改动”的条款。排查顺序确认project_rules.md里是否包含“不做任务外修改”的规则。没有就先补上。检查 codex 输入的起始 prompt 是否真的让 AI 读了current_tasks.md注意对话历史中可能残留了旧指令。查看progress_log.md看 AI 是从哪一步开始偏离的下次在该节点前后追加更明确的约束。预防加密在规则里写“涉及文件清单以外的修改必须向用户申请”。申请格式固定为“建议新增xxx原因xxx”。这让跑偏从“沉默发生”变成“显式审批”风险大大降低。6.2 上下文还是不够用怎么做压缩现象执行到中间阶段AI 开始忘记早期任务清单里的关键细节。方案不要硬续上下文做一次“定向压缩”。把当前进度和下一步计划固化成一段摘要然后新开会话。摘要建议包含四块- 已完成的里程碑状态摘要 - 当前正在执行的任务描述 - 下一步要执行的动作明确到文件级别 - 最近一次验证命令及其输出摘要这段摘要直接存进progress_log.md的顶部然后在新会话里让 AI 先读摘要再开工。这个方法我实测过不止一次比硬把全部历史搬进上下文有效得多。6.3 AI 的验证结果可信度不高现象AI 说“测试通过”其实根本没跑或者跑了但选择性忽略了失败项。原因模型有时会“脑补”执行结果尤其是它认为“自己写的东西肯定是好的”时。解决方案执行验证时要求 AI 必须贴出原始命令输出片段而不是总结性结论。给出一个格式模板验证命令pytest tests/test_pricing.py -v 验证结果通过 12 项失败 2 项 失败详情test_negative_amount断言异常期望 ValueError 实际返回 None如果发现频繁虚报可以在规则文件里写死“禁止输出不包含原始输出的验证结论”。这一步对稍大型项目尤其重要因为测试失败的排查成本远高于测试本身。6.4 什么时候这套流程不值得用需要老实说一句不是所有项目都适合上 superpowers 这类工作流。判断一个项目适不适合可以参考这几个信号任务高度临时、一次性后续几乎不会再次触碰的脚本不值得。项目尚在架构混沌期每天方向都在剧变的原型代码也不太适合因为任务清单很快就会失真。代码库很大且构建时间长验证成本极高执行效率会大打折扣。相对适合的场景是目标明确、任务可分解、有一定时长几天到几周、验证手段清晰的项目。比如老模块重构、新服务搭建、测试覆盖补齐等。这类项目里工作流带来的秩序感会充分体现。6.5 团队协作时如何避免冲突如果多人共用同一个 Git 仓库.ai目录的维护需要一定纪律。我们在团队里定了几条规则.ai/目录纳入 Git 版本管理让所有人都能看到任务状态的变迁。修改current_tasks.md的人同步在progress_log.md追加一条记录说明改了哪个任务状态、为什么改。如果 AI 在本地工作区里自动更新了任务状态提交前要求人工复核一次防止“AI marking done too early”这类误标。有过一次惨痛教训AI 在本地把任务标成“已完成”但代码根本没推上远程分支团队另一个成员看到状态后误以为功能可用了。从那以后我们规定 AI 不得直接修改远端状态本地状态也要在 PR 描述里同步变更说明。7. 经验总结与进一步思考经过几轮完整项目实验我对这套工作流的真实感受是它并不会让 AI 的代码质量“跳变式提升”但对开发过程的确定性和人机协作的可控性帮助很大。传统对话式 AI 像是一个随时能聊的专家但专家也会有状态波动的时候superpowers 做的事相当于给这个专家配了一本流程手册和一本备忘录让他在状态波动时也能按标准动作走完流程。我自己比较欣赏的设计细节是“进度日志要与任务清单分离”。这个设计早期的版本里任务清单和进度日志是合并的文件结果就是 AI 改状态时经常丢历史信息。拆开之后清单管“未来方向”日志管“历史事实”职责清楚AI 执行时也不会混。后续我自己在用的一个扩展方向是把验证命令从“写死在规则文件里”升级为“按模块动态读取”。比如在reference/下放一个verification.md每个模块指定它的专属验证命令。这样随着项目规模增长验证定义的维护压力不会全部堆在规则文件里AI 也能更精准地对改动模块做针对性检查。最后分享一个经常被忽略的小技巧一个月复盘一次progress_log.md把反复出现的提醒和踩坑点提炼成规则。这不是给 AI 用的是给未来三个月后的自己用的。我见过太多团队花力气建了工作流却从不让工作流自我进化最后只能靠人肉记忆维护规则体系。superpowers 这套东西最适合学习的方式不只是把它直接拿来用而是理解它“如何通过外置信息管理 AI 注意力”的设计哲学再嫁接到自己的日常开发习惯里。动手试一次给它一个真实的任务跑完一轮你就知道这套“超能力”到底能帮你省下多少重复沟通的时间了。