1. 从“superpowers”这个标题说起它到底是什么第一次看到“superpowers”这个词很多人脑子里蹦出来的可能是超级英雄、超能力这类画面。但在开发者和技术爱好者的语境里它指的是一套围绕 AI 编程助手构建的能力增强框架核心思路是给 AI 助手装上“外挂”让它在写代码、调试、重构、理解项目结构这些事上表现得像一个真正有经验的工程师而不是一个只会补全代码片段的工具。我最初接触这个概念是因为在几个技术社区里频繁看到有人讨论“superpowers 使用指南”“superpowers 安装”“codex superpowers”这些关键词。当时我的第一反应是又是一个包装概念的东西吧但真正上手用了一段时间之后我发现它解决的问题确实存在——AI 编程助手在单轮对话里很强但缺乏跨会话的记忆、缺乏对项目全局的理解、缺乏一套可复用的工作流。superpowers 要做的就是把这些缺失的能力补上。简单来说superpowers 不是一个独立的软件而是一套配置方案加工作流约定。它通常依附于某个 AI 编程助手比如 Codex 类的工具通过一系列配置文件、提示词模板、项目上下文注入机制让 AI 助手在每次交互时都能“记得”你的项目长什么样、你偏好什么风格、当前任务进展到哪一步。它适合谁适合那些已经在用 AI 辅助编程、但觉得“每次都要重新解释一遍项目背景”太累的开发者也适合刚接触 AI 编程、想从一开始就建立一套高效工作流的初学者。我自己的感受是没有这套东西的时候AI 助手像一个临时工每次来都要重新交代一遍有了这套东西之后它更像一个长期合作的搭档知道你的习惯知道项目的来龙去脉。这个差别在小型脚本里不明显但在一个几万行代码的项目里体验差距是巨大的。2. 核心设计思路拆解为什么需要这样一套框架2.1 AI 编程助手的三个天然短板要理解 superpowers 的设计逻辑得先看清楚当前 AI 编程助手普遍存在的三个短板。第一个短板是上下文窗口的局限性。不管你用的是哪个模型上下文窗口总是有限的。一个中型项目动辄几十个文件、上万行代码不可能全部塞进一次对话里。结果就是 AI 只能看到你粘贴给它的那部分代码对项目其他部分一无所知给出的建议经常“局部正确、全局错误”。第二个短板是跨会话记忆的缺失。今天你跟 AI 讨论了一个重构方案明天再打开对话它完全不记得昨天说过什么。你得重新解释一遍需求、重新粘贴代码、重新说明约束条件。这种重复劳动在长期项目里非常消耗精力。第三个短板是工作流的不统一。每个开发者使用 AI 助手的方式都不一样有人喜欢先让 AI 写测试再写实现有人喜欢先写实现再补测试有人习惯让 AI 先分析再动手。如果没有一套固定的工作流约定AI 每次的产出质量波动会很大。superpowers 的设计思路就是针对这三个短板分别给出解决方案。它通过项目级配置文件来解决上下文问题通过持久化记忆文件来解决跨会话问题通过标准化提示词模板来解决工作流问题。这三个东西组合在一起就构成了所谓的“超能力”。2.2 为什么选择配置文件而不是插件有人可能会问为什么不直接做一个插件或者扩展非要搞一堆配置文件我实际用下来配置文件方案有几个插件方案比不了的优势。第一是透明可控。配置文件是纯文本你随时可以打开看里面写了什么、改了什么不存在黑盒行为。插件就不一样了它内部做了什么你未必清楚。第二是版本可追踪。配置文件可以跟着项目一起提交到版本控制系统里团队成员拉取代码后自动获得相同的配置不需要每个人单独安装插件。第三是跨工具兼容。配置文件本质上是提示词和上下文的组织方式理论上可以适配不同的 AI 助手而插件往往绑定特定平台。当然配置文件方案也有代价——它需要你手动维护不像插件那样“装完就用”。但从长期项目管理的角度看这点维护成本是值得的。我自己的做法是把配置文件当作项目文档的一部分来对待每次项目结构有重大变化时顺手更新一下养成习惯之后并不觉得麻烦。2.3 核心组成三个关键文件一套典型的 superpowers 配置通常包含三个核心文件我分别说一下它们的作用和设计意图。第一个是项目上下文文件通常命名为类似project-context.md或.ai-context这样的名字。这个文件用自然语言描述项目的整体结构、技术栈、目录约定、命名规范、关键模块的职责。它的作用是让 AI 在每次对话开始时快速建立对项目的全局认知。我一般会在这个文件里写清楚项目是做什么的、用了哪些主要依赖、代码分了几层、每层负责什么、有哪些约定俗成的规则。第二个是工作流定义文件可能叫workflow.md或者ai-workflow.md。这个文件定义了你希望 AI 遵循的工作步骤。比如“接到需求后先复述理解、再列出方案、等我确认后再动手写代码”“写代码前先检查是否有现成的工具函数可以复用”“每次修改后自动生成对应的测试用例”。这些规则写下来之后AI 的行为会稳定很多。第三个是记忆与进度文件常见命名如memory.md或progress.md。这个文件记录当前任务的进展、已经做出的决策、待解决的问题。每次对话结束时让 AI 把关键信息更新到这个文件里下次对话开始时先让它读这个文件。这样就实现了跨会话的记忆延续。注意这三个文件的命名没有强制标准不同工具和不同人的习惯不一样。关键是理解它们各自承担的职责名字可以按自己的偏好来定。3. 安装与配置实操从零搭起一套可用的环境3.1 前置条件与工具选型在动手之前先确认你手头有什么。superpowers 这套东西本身不挑平台但它需要依附一个 AI 编程助手来发挥作用。目前社区里讨论比较多的是配合 Codex 类工具使用也就是热词里提到的“codex superpowers”。如果你用的是其他 AI 编程助手原理是相通的只是具体配置文件的格式和注入方式可能需要调整。前置条件方面你需要一个可用的 AI 编程助手账号或本地环境、一个正在进行中的代码项目、以及基本的 Markdown 编辑能力。对就这么简单不需要额外安装什么运行时或依赖库。这也是我欣赏这套方案的原因之一——零依赖纯文本随处可用。工具选型上我建议直接用你平时写代码的编辑器来编辑这些配置文件不需要专门找什么工具。VS Code、JetBrains 系列、甚至 Vim 都行。关键是保持文件格式统一我个人偏好用 Markdown因为可读性好AI 解析起来也顺畅。3.2 项目上下文文件的编写方法项目上下文文件是整套配置的地基写得好不好直接决定了后续 AI 的表现。我的经验是这个文件不要写成流水账而要写成一份给新入职工程师看的项目概览。想象一下一个刚加入团队的人需要知道什么你就写什么。具体来说我通常按这几个板块来组织。开头一段话概括项目是做什么的、面向什么用户、解决什么问题。然后是技术栈说明列出主要语言、框架、数据库、关键第三方库。接着是目录结构说明不用把每个文件都列出来但要把主要目录的职责讲清楚。再往后是编码约定比如命名风格、注释语言、错误处理方式、日志规范。最后是当前已知的技术债务或待改进点这部分能让 AI 在提建议时避开已知的坑。我踩过的一个坑是一开始写得太简略只写了“这是一个 Web 项目用 React 和 Node.js”。结果 AI 给出的建议经常跟项目实际架构不匹配。后来我把目录结构和关键模块职责补上之后建议的准确率明显提升。所以这个文件宁可写详细一点也不要偷懒。3.3 工作流定义文件的规则设计工作流定义文件的核心是把你脑子里的“默契”变成白纸黑字的“规则”。很多开发者用 AI 助手时心里有一套期望的行为模式但从来没明确表达过结果 AI 只能靠猜。把规则写下来就是在消除这种猜测。我自己的规则清单大概长这样接到任何需求后先用自己的话复述一遍理解确认无误再往下走提方案时至少给两个选项并说明各自的取舍写代码前先搜索项目里有没有可复用的现成实现修改代码后主动指出可能受影响的模块每次输出代码时附上简短的改动说明。这些规则看起来琐碎但累积起来对输出质量的提升非常明显。规则的数量不要贪多一开始五到八条就够了。写太多 AI 反而容易顾此失彼而且你自己也记不住。等用顺了之后再根据实际遇到的问题逐步补充。我现在的规则清单已经迭代了十几版每一条背后都是一次真实的踩坑经历。3.4 记忆文件的维护节奏记忆文件是最容易被忽视、但长期价值最高的一个。它的维护关键在于节奏——什么时候读、什么时候写、写什么内容。我的做法是每次开始一个新任务前先让 AI 读一遍记忆文件了解之前的进展和决策每次任务告一段落时让 AI 把这次做了什么、遇到什么问题、下一步计划是什么更新进去。更新内容要简洁用要点式记录不要写成大段叙述。我一般控制在每条记录不超过三句话这样文件不会膨胀得太快。有个细节值得注意记忆文件不要记录太琐碎的东西比如“今天改了第三行的变量名”这种就没必要。要记录的是决策层面的信息比如“决定用 Redis 做缓存而不是本地内存因为需要多实例共享”。这种信息在后续对话里价值很高能避免 AI 提出已经被否决过的方案。4. 实际使用中的核心场景与操作细节4.1 场景一接手一个陌生项目时的快速上手这个场景是我觉得 superpowers 价值最突出的地方。假设你刚加入一个新项目或者接手了一个别人写的代码库面对几十个文件一脸茫然。传统做法是一个个文件点开看费时费力还容易迷失方向。用 superpowers 的思路你可以先花二十分钟写一份项目上下文文件。写的过程本身就是一次快速梳理——你得搞清楚项目结构、技术栈、关键模块这些信息在写文件的过程中自然就掌握了。写完之后把文件交给 AI让它基于这份上下文回答你的问题比如“用户登录的完整流程涉及哪些文件”“如果要新增一个 API 接口需要改哪几个地方”。AI 有了全局上下文之后回答的准确度比直接问要高得多。我实测下来一个中等规模的项目用这种方式上手比纯人工阅读代码要快三到五倍。当然前提是上下文文件写得足够准确如果文件本身有错误AI 会跟着错。所以写完文件后最好自己抽查几个关键点确认描述和实际代码一致。4.2 场景二跨天开发时的上下文恢复跨天开发是很多人的痛点。昨天写了一下午的代码今天早上打开电脑脑子一片空白得花半小时回忆昨天做到哪了。有了记忆文件之后这个过程可以压缩到几分钟。具体操作是每天收工时花两分钟让 AI 更新记忆文件记录今天的进展和明天的计划。第二天开工时先让 AI 读记忆文件然后让它用几句话总结“我们昨天做了什么、今天该做什么”。这个总结会帮你快速回到状态。我坚持这个习惯大概两个月之后明显感觉每天早上的“启动时间”缩短了很多。这里有个技巧记忆文件里除了记录“做了什么”还要记录“为什么这么做”。比如“昨天把数据库查询改成了批量查询因为发现循环单条查询在数据量大时性能很差”。这种决策背景在第二天回顾时特别有用能帮你快速回忆起当时的思考过程。4.3 场景三多人协作时的配置共享如果是团队协作superpowers 的配置文件可以跟着项目一起提交到版本控制里这样每个成员拉取代码后都获得相同的 AI 助手配置。这对保持团队输出风格一致性很有帮助。但这里有个需要注意的地方个人偏好和团队规范的边界。有些配置是团队级的比如项目结构说明、编码规范、工作流步骤这些应该共享。有些配置是个人级的比如你习惯让 AI 用某种特定的注释风格、你偏好的输出格式这些就不适合强制所有人统一。我的做法是团队级配置放在项目根目录个人级配置放在本地忽略文件里两者分开管理。另外团队共享配置需要有人负责维护。我的经验是指定一个人作为“配置管理员”每次项目结构有重大调整时由他统一更新避免多人同时改导致冲突。这个角色不需要全职但需要有人担这个责任。4.4 场景四复杂重构任务的分步推进重构是 AI 助手最容易翻车的场景之一因为重构涉及面广牵一发动全身。superpowers 的工作流定义在这里能发挥很大作用。我的做法是把重构任务拆成多个小步骤每一步都让 AI 先分析影响范围、再给出方案、等我确认后再动手。工作流文件里会明确写“重构类任务必须分步执行每步完成后暂停等待确认”。这样虽然看起来慢但实际比让 AI 一次性大改要稳得多。我试过让 AI 一次性重构一个模块结果它改了十几个文件其中好几个改动是没必要的回滚起来很麻烦。分步走之后每步改动都可控出问题也容易定位。分步的粒度怎么把握我的经验是一个步骤的改动不超过三个文件。超过这个数量就再拆细一点。这个阈值不是绝对的但作为一个参考线挺实用。5. 常见问题与排查技巧实录5.1 AI 不遵守工作流规则怎么办这是新手最常遇到的问题。你明明在工作流文件里写了“先分析再动手”但 AI 还是直接开始写代码。原因通常有两个一是规则写得太模糊AI 理解不了二是规则太多AI 顾不过来。解决办法是把规则写得更具体、更可执行。比如“先分析再动手”这种表述就太抽象改成“接到需求后第一步输出你对需求的理解第二步列出至少两个实现方案第三步等待我回复‘确认’后再开始写代码”。这样 AI 就知道每一步具体该做什么。另外规则数量控制在八条以内优先级高的放前面。如果改了之后还是不遵守可以在对话开始时手动提醒一句“请先阅读工作流文件并确认你理解了规则”。这个动作看起来多余但实测能显著提高遵守率。5.2 上下文文件更新不及时导致建议过时项目在演进但上下文文件没跟着更新结果 AI 基于过时信息给出建议。这个问题很隐蔽因为 AI 不会主动告诉你“你的上下文文件过期了”它只会默默地给出不合时宜的建议。我的应对方法是在记忆文件里加一条定期提醒比如每两周检查一次上下文文件是否需要更新。另外每次项目有重大变更时比如换了框架、调整了目录结构、引入了新的核心依赖顺手更新上下文文件。养成习惯之后就不会出现严重过时的情况。还有一个技巧在上下文文件开头写一个“最后更新日期”这样你一眼就能看出它有多久没维护了。超过一个月没更新就该警惕了。5.3 记忆文件膨胀导致读取效率下降记忆文件用久了会越来越长每次让 AI 读一遍既消耗上下文窗口又可能让 AI 抓不住重点。我遇到过记忆文件写到几千字之后AI 反而记不住关键信息的情况。解决办法是定期归档。每个月把记忆文件里已经完成的任务记录移到单独的归档文件里主记忆文件只保留当前进行中的任务和近期决策。归档文件不用每次都读只在需要追溯历史时查阅。这样主文件始终保持在几百字的精简状态读取效率高AI 也更容易抓住重点。另外记忆文件里的记录要倒序排列最新的在最上面。这样即使 AI 只读了前面一部分也能获取到最新信息。5.4 常见问题速查表问题现象可能原因排查方向解决建议AI 忽略工作流规则规则模糊或过多检查规则是否可执行改写为具体步骤控制在八条内建议与项目实际不符上下文文件过时对比文件描述与代码现状更新上下文文件加更新日期AI 记不住之前决策记忆文件未更新或过长检查记忆文件维护节奏定期归档保持精简倒序排列重构改动范围失控未分步执行检查工作流是否要求分步强制分步每步不超过三个文件团队配置冲突个人与团队配置混在一起检查配置文件位置团队级放根目录个人级放本地忽略5.5 几个我踩过的坑和对应技巧第一个坑是过度依赖 AI 的自我判断。早期我完全信任 AI 对上下文文件的理解结果它有时候会“脑补”一些文件里没写的内容。后来我养成了一个习惯在关键决策点上让 AI 引用上下文文件里的原文来支撑它的判断。如果它引用的内容跟文件实际内容对不上就说明它在脑补这时候就要警惕了。第二个坑是配置文件写得太“完美”。我一开始想把所有规则都写进去结果文件又长又复杂AI 反而抓不住重点。后来我学会了做减法只写最重要的规则其他的靠对话中临时补充。配置文件不是越全越好而是越精越好。第三个坑是忘记同步更新。有次我改了项目目录结构但忘了更新上下文文件结果 AI 连续几天给出的文件路径都是错的。从那以后我在项目根目录放了一个检查清单每次做结构性改动时对照检查是否需要更新配置文件。6. 进阶玩法把这套思路用到更多场景6.1 从单项目到多项目的配置复用当你手头有多个项目时每个项目都从头写一套配置太累了。我的做法是维护一份基础模板包含通用的工作流规则和上下文文件框架新项目直接复制模板再按需修改。这样能把配置时间从半小时压缩到十分钟。模板的维护也有讲究。我会定期回顾各个项目的配置把反复出现的规则提取到模板里把项目特有的规则留在各自项目里。这样模板会越来越完善新项目的起步成本越来越低。6.2 结合版本控制做配置审计配置文件跟着项目走版本控制之后你可以通过提交历史看到配置的演变过程。这个历史其实很有价值——它能告诉你哪些规则是后来加的、为什么加的。我有时候会翻看几个月前的配置提交记录回顾当时遇到的问题和解决方案经常能发现一些已经被遗忘但依然有用的经验。如果团队协作还可以通过配置文件的修改记录来了解其他成员的使用习惯互相借鉴好的规则。我们团队就有一个约定任何人添加了新规则都要在提交信息里简要说明原因。这样规则库就成了团队集体智慧的沉淀。6.3 配置文件的版本兼容问题AI 编程助手本身也在迭代有时候工具更新之后原来的配置文件格式或注入方式可能不再适用。这个问题目前没有完美的解决方案只能靠关注工具的更新日志及时调整配置。我的应对策略是保持配置文件的“薄”。也就是说配置文件尽量只包含内容和规则不包含太多跟特定工具绑定的技术细节。这样即使工具换了内容部分还能复用只需要调整注入方式。如果你把大量工具特有的语法写进配置文件迁移成本会很高。6.4 个人使用心得少即是多用了大半年 superpowers 这套思路之后我最大的体会是少即是多。一开始我恨不得把所有能想到的规则都写进去结果配置文件臃肿不堪维护成本高效果反而不好。后来我不断做减法只保留真正影响输出质量的核心规则整体体验反而提升了。现在我的配置大概是这样上下文文件控制在五百字以内工作流规则六条记忆文件保持在一百字左右的活跃状态。就这么精简的一套东西解决了我百分之八十的痛点。剩下的百分之二十靠对话中临时补充就够了。如果你刚开始尝试我的建议是从最小可用配置开始。先写一份上下文文件加三条工作流规则用一周之后再根据实际需要逐步补充。不要一上来就追求大而全那样很容易因为维护成本太高而放弃。这套东西的价值在于长期坚持使用而不是一次性的完美配置。