1. 项目从哪来为什么起名叫“superpowers”这两年AI编程工具多到看不过来大家吐槽最多的却是“工具越强人越傻”——明明上下文窗口越来越大生成速度越来越快结果写出来的代码还是经常跑不通。原因很简单工具本身没有变强变强的是工具背后的提示词和调用方式。我也是从这个痛点出发做了这套名为“superpowers”的个人项目它不是某个具体的插件或框架而是一整套把AI编程助手的能力真正“榨出来”的方法论和配套脚手架。说白了superpowers要解决的不是“让AI写更多代码”而是“让AI每一次输出都更接近你要的东西”。它围绕一个核心假设AI本身没有超能力超能力来自你给它的环境和约束。给它清晰的角色、可复用的技能包、自动化的验证闭环它就能从“一个偶尔聪明的编辑器插件”升级成“一个真正懂你项目结构的协作者”。这个项目适合谁两类人最合适一是被AI生成代码反复“坑”过、花了大量时间在调试上的开发者二是想在公司内部推行AI辅助开发、又不想只停留在“用ChatGPT写个正则”层面的技术负责人。前者能在这里找到一套完整的技能包设计方法后者能直接拿走一套带验证机制的落地框架。为了讲清楚这套东西我会从设计思路、核心细节、实操过程和问题排查四个部分展开把我在开发superpowers过程中踩过的坑和实测有效的方案都留在下面。2. 整体设计与思路拆解2.1 为什么那么多AI工具都“中看不中用”先聊一个让很多人困惑的现象Cursor、Copilot、Codex这些工具单看演示视频个个封神真到自己项目里却经常出现“看起来合理、跑起来崩溃”的代码。我花了很长时间才想明白问题不在工具而在使用方式。绝大多数人用AI编程工具是把它当成“高级自动补全”写个函数名让AI补完或者选中一段代码问“这段有什么问题”。这种用法本质上是在用单轮的、无状态的方式跟一个有记忆却不会主动调用的系统对话。AI不知道你项目的目录结构不了解你的命名规范更不清楚你之前踩过哪些坑。它的上下文窗口里只有当前这段代码自然只能给出“局部最优解”而这个解放在整体架构里往往是灾难。superpowers的设计初衷就是把“上下文”从一条条零散消息变成一套可供AI主动调用的资产。项目里每个技能包skill都不只是提示词模板而是包含说明书、代码片段、单元测试、甚至工作流描述的文件集合。AI可以在需要的时候主动去读技能包里的内容而不是等你把相关信息手动粘贴给它。这是整个项目最核心的认知转变从“喂AI”到“让AI自己来拿”。2.2 技能包Skills结构的三个设计原则技能包是superpowers的原子单位我把每个技能包设计成三层结构每一层都对应一个实际要解决的问题。第一层是角色定义。比如我写了一个“数据库性能优化师”的技能包AI读到这个包之后会先输出自己的角色认知“我是数据库性能调优专家先收集慢查询日志再分析执行计划……”这一层的作用是让AI在动手之前先“校准目标”避免一上来就给你一版改得面目全非的SQL。第二层是流程引导。技能包里会明确“先做什么、后做什么、什么情况下停止并请求信息”。这一步是补齐AI最欠缺的元认知能力。比如“根据代码审查的规范先检查错误处理是否完备再审视并发安全发现问题时标注严重等级而不是直接改”。第三层是输出约束。我会在技能包里规定所有代码必须包含错误处理所有配置修改必须附带回滚方案所有方案建议必须给出预估工作量。这一层看起来最啰嗦却是我实测下来最能减少无效输出的设计——约束越明确输出越靠谱。这套三层结构与现代软件工程的分层思想一脉相承。角色定义相当于接口约束流程引导类似业务逻辑编排输出约束就是数据校验。你不需要照搬这个结构但它能帮你建立“AI提示词的模块化思维”。2.3 为什么不是做一个“万能大提示词”也许你会问我以前写的提示词也很长效果也不错为什么非要拆成技能包因为“长提示词”有一个被低估的问题不可维护。当你的项目从两个文件扩展到几百个文件时一段很长的提示词要么被截断要么互相矛盾。技能包的方式则把提示词“碎片化”按需加载互不干扰。用的时候只加载与当前任务相关的技能包上下文窗口利用效率高出很多。你可以把这种思路理解成“前端工程化”的另一种表现形式不把所有的CSS写进一个index.css而是按组件拆分、按路由懒加载。superpowers只是把这套最佳实践搬到了提示词工程里。这个决策带来的好处在大型项目里尤其明显——AI不用再“通读全文”才能开始干活它只需要读跟当前任务相关的几个文件。3. 核心细节与实操要点3.1 技能注册表AI怎么知道它有哪些“超能力”光把技能包写出来放在文件夹里没用AI得知道“什么情况下该用哪个技能”。所以我在项目里做了一份技能注册表registry本质是一个index文件列出当前可用的技能包名称、功能描述、触发条件和引入方式。以我的某个实际项目为例注册表内容长这样{ skills: { code-review: { description: Code review with severity-rated suggestions, no silent changes, trigger: When asked to review code changes or pull requests, path: ./skills/code-review.md }, refactor: { description: Safe refactoring with before/after preview and test guidance, trigger: When asked to refactor existing functions or modules, path: ./skills/refactor.md }, debug: { description: Systematic debugging, hypothesis-based root cause hunting, trigger: When encountering failing tests or runtime issues, path: ./skills/debug.md } } }这里的关键不是格式而是触发性描述要写得足够具体。如果“debug”技能的触发条件写的是“当用户提到问题时”注册表就形同虚设——因为用户可能不会明说“debug”他只会说“这个接口报401了”。更好的触发写法是“当用户描述错误码、堆栈信息、异常行为或明确要求排查问题时建议调用此技能。”实操中我还会给每个技能包加一个priority字段用来处理多个技能同时匹配的情况。比如“code-review”和“refactor”很容易同时命中如果AI两个技能包都加载输出大概率会混乱。设置优先级之后AI会先按高优先级技能处理另一个技能的内容只作为参考。3.2 “技能包”文件到底写什么一段可复制的模板很多人看到这里会问技能包文件具体长什么样我直接给出一份我反复修改后相对稳的模板你可以直接抄进自己的项目里。每个技能包文件统一三个段落Context背景、Process流程、Constraints约束。拿“debug”这个技能举例Context你是一名经验丰富的高级调试专家。你的工作不是直接修改代码而是通过假设驱动的方式辅助开发者定位并验证根因。在调试过程中你会接触到不同类型的错误编译错误、运行时异常、逻辑错误、以及与外部系统交互产生的错误。你深知在没有充分信息情况下做出的修改是危险的因此你的首要步骤是收集信息而不是修改代码。Process明确本次调试的输入条件复现步骤、错误信息、相关代码片段。列出至少两个根因假设按“花费成本最低优先验证”排序。针对第一个假设设计一个隔离实验来验证而不是直接修改目标代码。清晰描述实验方法获得开发者确认后再进行下一步操作。验证成功后说明根因再提供最小化修复方案并给出回归测试建议。Constraints在你收集齐所有必要信息之前禁止直接给出修复代码。每次只验证一个假设除非开发者明确要求。对修复方案的任何副作用保持透明不能隐藏可能影响其他模块的风险。如果两次验证都失败立即退回到步骤1重新梳理信息而不是继续盲目尝试。这段模板写得比较“硬”但好处也很明显AI对照它跑出来的“调试”过程和我过去手动给提示词的输出质量完全是两个水平。省掉的是双方之间反复来回的无效沟通成本换来的是说话更少的开发者、更有章法的AI。3.3 上下文管理的三个隐藏细节技能包能用起来不只是内容的功劳。我在实测中发现下面三个细节缺一不可。细节一要“绑定”技能包到具体操作而不是让它“常驻内存”。一开始我把核心技能包全写进系统提示词里结果AI对话一长上下文就乱套。改成注册表之后只有匹配到当前任务的技能包才被加载效果立刻改善。细节二每个技能包的前几行必须是“执行优先级规则”。如果不写AI经常会自作主张跳过某些步骤。比如我在code-review技能包里明确规定“发现问题先打标签标签格式为[严重等级-影响范围]”AI就很少再直接改代码。细节三技能包要有“退出条件”。很多人忘了定义“什么情况下AI应该承认干不了、请求更多信息”。没有退出条件的技能包跟没有失败恢复机制的系统一样脆弱。我在每个技能包的末尾都会固定写一句“如果提供了三个可能性方案但无法确认哪个最合适请如实告知用户并请求提供更多项目背景而不是强行选择一个方案继续执行。”这句话看着简单但在实操里帮我避免了很多次“自信的错误输出”。4. 实操过程从配置到生产可用的完整路径4.1 环境搭建与项目初始化在介绍配置步骤之前需要说明一点下面涉及的路径、目录结构、命令行操作是基于我实际项目的通用做法整理出来的可能不完全适配每个环境但思路和方法是可迁移的。第一步你得给AI助手准备好“技能仓库”的存放位置。我习惯把所有技能包按类型分在三个目录下skills/coding编码相关、skills/review审查相关、skills/meta关于自身工作方式的技能比如“如何划分任务粒度”。第二步初始化注册表。这一步建议手动完成不要交给AI“自动生成”。因为注册表本质上是你整个辅助系统的架构文档它需要你清楚自己的开发流程中哪几个环节最值得AI介入。我自己只保留了三个技能包优化而不是硬凑十个就是因为在配置阶段我发现我的开发流程真正卡壳的只有这几个环节代码审查、重构、和调试。第三步建立版本管理。技能包也要走Git流程每次修改都留commit记录。别小看这一条当你调整了某个技能的流程、发现AI行为变“怪”时能快速回退到上一个可用版本这个能力太重要了。4.2 开发一个技能包以“代码审查”为例我不想空谈理论直接带你在顶层过一遍“代码审查”技能包的真实开发过程。最早版本很简单就一段话“你是一名资深工程师请审查这段代码”。结果AI输出了一堆模板化建议什么“考虑使用更清晰的变量名”“建议提取公共逻辑”通通等于没审。原因在于AI根本没收到“审查标准”。第二版我开始给标准读代码发现问题列表式输出必须包含严重等级。这次好一点但仍然不够因为AI不知道“严重等级”对什么项目、什么语言来说算严重。第三版我引入“适配规则”每个项目在注册表里登记自己用的语言、框架、面对的主要风险比如支付系统最关注资金安全和幂等性后台管理项目最关注权限边界。这个改动让审查技能包从一个通用模板变成真正能识别“当前上下文”的智能助手。第四版也是目前的最新版我加入了“语义化反馈”约束要求AI在指出问题的同时说明“为什么这是个问题”以及“修复它可能带来的副作用是什么”。这套约束跑下来AI给出的审查意见明显更像一个高级工程师而不是一个背诵清单的实习生。技能包迭代开发的过程本质上是在“训练”你与AI协作的工作共识。每个版本都要写changelog这个习惯帮我清楚地看到哪次改动让AI表现出现了明显提升哪次又引入了新问题。4.3 在真实项目里如何“灌输”技能包建好技能包之后真正决定成败的一环是“如何在AI工具里启用它”。以命令行式AI编程助手为例需要在配置文件中设置一行instruction指向你的注册表文件路径同时设定一个关键词约定比如你的上下文里出现“review this code”时AI会主动加载code-review技能。如果用图形界面工具通常会在设置面板的“自定义提示词”区域找到对应的加载入口。注意一个容易被忽视的点技能包文件和AI工具之间最好通过相对路径引用确保项目在不同机器上克隆下来后不用重新配置绝对路径。我在一次团队内分享时就发现同事的AI死活加载不上技能包排查半天失败原因就是他把本机路径写死了。启用之后建议做一个“冒烟测试”准备一个包含三个已知问题的代码文件让AI加载技能包去审查看它能不能按预期找到三个问题、正确分等级、不提一堆无关建议。这一步能快速验证技能包是否传达了你定义的“语气”和“准则”也能提前把不合理的设计挡在正式使用之前。5. 常见问题与排查技巧实录5.1 问题速查表我把这两周使用过程中遇到的问题整理成一个速查表每一条都是真金白银的“学费”换来的。问题现象可能原因排查方向AI完全不按技能包执行技能包没有被加载检查注册表路径、触发条件是否命中技能包加载了但效果和没用一样技能包内容写得太像“建议”改成明确指令把“可以尝试”改为“必须执行”多个技能包同时触发输出混乱缺少优先级设置在注册表字段中填写不同数值强制排序技能包在对话长文本后失效上下文窗口覆盖了早期指令在关键节点再次显式触发技能包入口比如“现在请使用debug技能”AI违反输出约束直接改代码约束语句缺少惩罚性表述补充“如果未经允许修改最终回答视为无效”技能包对项目结构不了解没提供Project Profile文件单独建一个project.md描述目录结构、技术栈和约定5.2 三个让我印象最深的排查案例案例一很长很完整的技能包反而把AI“带偏”了我曾为“前端性能优化”写了一个接近两千字的技能包涵盖网络加载、渲染路径、内存泄漏、打包体积等所有角度自认为面面俱到。结果AI一上来就按部就班地输出“从网络层面分析性能”的冗长报告完全没有结合我项目“低端机帧率低”的具体症状。后来我想明白问题就在“全”字上技能包太全AI没有“诊断”步骤直接按清单执行反而忽略了项目个体差异。把技能包改成“先定位瓶颈类型再加载对应子章节”的流程写法之后效果好得惊人。你的技能包不是百科全书而是分诊台。案例二明明配置正确AI却不主动调用技能有段时间我连续给不同项目配置同样的技能包一个项目灵一个项目死。来回对比才发现失效的那个项目API Key配置的是基础模型基础模型对指令遵循能力明显弱于高级模型。这个案例让我意识到superpowers这套东西的效果上限依然高度依赖底层模型能力。你可以把技能包看成“方向盘”基础模型则像“小排量发动机”方向盘转得再准动力不足照样跑不快。案例三把“技能包”当成万能解药结果维护成本爆炸我早期一口气写了十几个技能包覆盖写文档、写测试、做估算、做分解还全部挂到注册表里。结果每次启用AI都要很长时间才能进入真实任务因为AI要花大量上下文“消化”那些技能包。后来我做了一次大规模减负只保留直接与核心开发动作相关的五个技能包其余全部移到“按需手工触发”区。这个教训让我重新理解了“上下文预算”这件事。给AI的每一份技能包都在无形中占用它的注意力。技能包不是越多越好而是越精准越好就像给新手程序员塞一百本参考书不如让他先啃透一本最常用的。5.3 避坑实战清单照着做就能省下半天调试时间第一升级底层模型前先冻结技能包版本。换模型相当于换了一个“AI大脑”它的语言理解风格和指令遵循偏好都会变。我通常先跑一遍已有的冒烟测试确认所有技能包输出符合预期再决定是否“上线”新模型。第二把单个技能包控制在600字以内。太长的技能包在对话中后段容易被“遗忘”而且修改维护成本高。如果内容确实多拆成多个子技能用“流程”把它们串联起来。第三每次修改技能包之后写一条“变更记录”在文件头部。包括改动内容、依据哪个翻车场景触发的、验证结果。这样过一个月再回头看你依然能快速理解当初为什么这样设计。第四为每个技能包准备一个“反例”作为禁用边界。我会在code-review技能里明确写“不审查依赖升级相关的改动这类任务应直接转给专门的依赖分析流程”。这个做法极大地减少了技能间的“抢活”现象。第五新手从模仿开始不要从原创开始。先照抄我这套模板改一版跑通流程、体会效果之后再按自己的项目做裁剪。最怕的就是技能包还没跑顺就陷入“微调措辞”的纠结里那是本末倒置。这个项目做到现在我最深的体感是AI能力的上限有一半其实是你定义协作方式的上限。superpowers只是一套让我和AI之间沟通变得更“有序”的桥梁。它不解决所有问题但它确实把我从“无限次改提示词”的泥潭里拉了出来。如果你也在跟AI协作不妨按这套思路先搭一个最小闭环然后一步步把真正适合你工作流的技能沉淀成自己的“超能力”。最后再分享一个小心得技能包这个东西写到第三版的时候最容易走火入魔总想着“再加一条规则AI就完美了”。实话说没有这种完美状态。规则加得越多AI的灵活性越低正确率也不一定跟着涨。找到那个动态平衡点让AI既听话又有灵性就是你自己的superpowers了。