1. 从“超级能力”说起这套技能框架到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个游戏模组或者科幻设定。但在软件开发圈子里它指的是一套围绕编码智能体coding agents构建的技能框架核心思路是把软件开发方法论拆解成一个个可组合、可复用的“技能单元”让智能体在写代码时不再只是“你问我答”的被动工具而是能主动调用一整套工程实践来完成复杂任务。我最初接触这套东西的时候正被一个很实际的问题困扰用编码智能体写小脚本、改单个文件确实很爽但一旦任务变成“给现有项目加一个完整的用户认证模块”智能体就开始犯迷糊——它会写出一堆看起来能跑但结构混乱的代码缺少测试、缺少边界处理、缺少和现有代码风格的一致性。问题的根源不在于模型不够聪明而在于它缺少一套结构化的方法论来指导它“先做什么、再做什么、怎么验证”。superpowers 这套框架的价值就在这里。它把软件工程里那些老生常谈但极其重要的实践——比如先写测试再写实现、先做接口设计再填逻辑、先分析需求边界再动手——变成了智能体可以显式调用的“技能”。每个技能是一个独立的、有明确输入输出的模块智能体可以根据当前任务阶段自主决定调用哪个技能。这就像给一个聪明但没经验的实习生配了一本操作手册手册里的每一页都是一个具体的工作方法。这套框架适合谁如果你只是偶尔用智能体写个爬虫脚本可能感受不到它的必要性。但如果你在认真地把智能体纳入日常开发流程——比如用它来维护一个有一定规模的项目、或者让它参与团队协作——那这套技能框架能显著提升输出质量的稳定性。它解决的核心问题是如何让智能体的编码行为从“随机发挥”变成“有章可循”。2. 技能框架的整体设计思路拆解2.1 为什么是“可组合技能”而不是“一个大提示词”很多人第一反应是为什么不直接写一个超长的系统提示词把所有要求都塞进去我一开始也这么想试过之后发现两个致命问题。第一提示词太长会导致模型注意力分散前面强调的规则到后面就被遗忘了。第二不同任务阶段需要不同的关注点用一个统一的提示词去覆盖所有阶段结果就是每个阶段都做得不够好。superpowers 的设计哲学是“分而治之”。它把开发流程拆成若干个阶段每个阶段对应一组技能。比如需求分析阶段有“需求澄清”技能设计阶段有“接口设计”技能实现阶段有“测试驱动开发”技能验证阶段有“代码审查”技能。智能体在每一步只需要关注当前该调用的技能认知负担大大降低。这种设计还有一个好处技能可以被替换和扩展。如果你觉得某个技能不符合团队习惯可以自己写一个替代版本。比如默认的测试技能可能用的是某种测试框架你可以换成团队实际在用的那套。这种灵活性是单一巨型提示词做不到的。2.2 技能之间的调用关系与状态传递技能不是孤立存在的它们之间有明确的依赖关系和状态传递机制。举个具体例子当智能体接到“给项目添加一个数据导出功能”这个任务时它的执行路径大致是这样的——首先调用“任务分解”技能把大任务拆成“确定导出格式”“设计数据查询接口”“实现导出逻辑”“编写测试”等子任务。然后针对每个子任务调用对应的技能。在“设计数据查询接口”这个子任务里它会调用“接口设计”技能产出一个接口定义。这个接口定义会作为状态传递给后续的“实现”技能确保实现和设计一致。这里的关键在于状态的结构化存储。如果状态只是散落在对话历史里智能体很容易在后续步骤中“忘记”前面的决策。superpowers 的做法是把每个技能的产出物以结构化格式保存下来后续技能可以显式地读取这些产出物。这就像在项目管理里每个阶段的交付物都有明确的文档记录而不是靠口头传达。2.3 与现有开发流程的融合方式这套框架并不是要取代现有的开发流程而是嵌入进去。我自己的做法是把它当作一个“智能体行为规范层”——在智能体开始工作之前先加载这套技能框架然后智能体在每一步操作时都会参考框架里的指导。具体融合方式有两种。一种是全流程托管你把一个完整任务交给智能体它自动按照技能框架走完从分析到实现的全部流程。这种方式适合任务边界清晰、风险可控的场景。另一种是按需调用你在某个特定环节手动触发某个技能比如你写完了代码让智能体调用“代码审查”技能来检查一遍。这种方式适合你已经有了明确的工作节奏只需要在特定环节增强的情况。两种方式我都用过实测下来对于新项目或者不熟悉的代码库全流程托管效果更好因为智能体可以从头建立完整的上下文。对于已经很熟悉的项目按需调用更高效不会打断你原有的工作流。3. 核心技能模块的详细解析与实操要点3.1 需求澄清技能把模糊需求变成可执行规格这是整个流程的起点也是最容易被忽视的环节。我见过太多人直接对智能体说“帮我加个登录功能”然后拿到一堆需要大改的代码。问题就出在需求没有被澄清。需求澄清技能的核心动作是提问。当智能体接收到一个模糊需求时它不会直接开始写代码而是先列出一系列需要确认的问题。比如对于“加个登录功能”它会问登录方式是什么用户名密码、邮箱、第三方密码策略是什么最小长度、复杂度要求会话管理用什么机制token、session失败次数限制是多少是否需要记住登录状态这些问题的答案会形成一个需求规格文档作为后续所有工作的基础。我在实际操作中的体会是这个环节花的时间越多后面返工的概率就越低。有一次我偷懒跳过了这个环节结果智能体实现了一个基于 session 的登录而我的项目是前后端分离的需要的是 token 机制最后不得不重写。注意需求澄清技能产出的规格文档要尽量具体避免“合理的密码策略”这种模糊表述要写成“密码长度至少8位包含大小写字母和数字”这样的可验证条件。3.2 测试驱动开发技能先写测试再写实现这是 superpowers 里我最喜欢的技能也是最能体现“方法论”价值的技能。它的工作流程非常明确接到一个实现任务后先写测试用例确认测试失败然后写实现代码让测试通过最后重构。为什么这个顺序很重要因为如果你先写实现再写测试测试往往会不自觉地“迁就”实现——你会不自觉地写一些刚好能通过的测试而不是真正覆盖边界条件的测试。先写测试则强迫你先想清楚“这个功能应该表现成什么样”实现只是让测试通过的手段。具体到智能体的操作它会先生成一个测试文件里面包含正常路径、边界条件、异常情况的测试用例。然后运行测试确认全部失败因为实现还不存在。接着生成实现代码再次运行测试直到全部通过。最后检查是否有可以重构的地方。我实测下来这个技能对智能体输出质量的提升非常明显。没有这个技能的时候智能体写的代码经常缺少边界处理比如数组为空、输入超长、并发访问这些情况。有了测试驱动这些情况在测试阶段就被覆盖了。提示如果项目已经有测试框架需要在技能配置里指定框架类型和测试文件命名规范否则智能体可能会用错框架或者把测试文件放错位置。3.3 代码审查技能自动化的质量守门员代码审查技能是在实现完成后自动触发的。它会从几个维度检查代码是否符合项目已有的代码风格、是否有明显的性能问题、是否有安全隐患、是否有重复代码可以抽取、命名是否清晰。这个技能的产出是一份审查报告里面会列出发现的问题和建议的修改方式。智能体可以选择自动修复也可以把报告交给人来决定。我通常的做法是让智能体自动修复那些明确的风格问题和明显的错误对于涉及业务逻辑的修改建议则人工确认。这里有个细节值得注意代码审查技能需要知道项目的代码风格规范。如果项目里有 ESLint 配置或者 Prettier 配置智能体会读取这些配置来作为审查依据。如果没有它会使用一套通用的最佳实践。我建议在项目里维护一份明确的代码风格配置这样审查结果会更符合团队习惯。3.4 技能的组合调用与优先级管理当多个技能都可以应用于当前任务时智能体需要决定调用顺序和优先级。superpowers 的做法是给每个技能定义一个触发条件和优先级权重。比如“测试驱动开发”技能的触发条件是“开始实现新功能”优先级高于“代码审查”技能因为审查应该在实现完成后进行。在实际运行中智能体会维护一个待调用技能队列按照优先级依次执行。如果某个技能的触发条件不满足就跳过。这个机制保证了流程的有序性不会出现“还没写实现就开始审查”这种逻辑错误。我遇到过一个情况项目里已经有一份遗留代码需要重构智能体同时触发了“重构”技能和“测试驱动开发”技能。按照优先级它先执行了“测试驱动开发”——先为现有行为写测试确保重构不会破坏功能然后再执行重构。这个顺序是对的如果反过来先重构再写测试就失去了测试的保护作用。4. 完整实操流程从零引入这套技能框架4.1 环境准备与框架引入引入 superpowers 的第一步是确认你的开发环境支持智能体调用外部工具或读取配置文件。大多数编码智能体平台都支持通过配置文件或项目根目录的特定文件来加载技能定义。具体操作上你需要在项目根目录创建一个技能配置目录通常命名为.skills或skills。然后在里面放置技能定义文件。每个技能定义文件包含技能名称、描述、触发条件、执行步骤和输出格式。框架本身会提供一个默认的技能集合你可以直接使用也可以按需修改。我建议第一次引入时先用默认技能集合跑一遍完整流程感受一下每个技能的实际效果然后再根据项目特点做定制。直接上手就大改配置很容易因为不熟悉机制而配错。注意技能定义文件里的触发条件要写得足够具体。比如“当任务涉及数据库操作时触发”就比“当需要时触发”要好得多后者会导致智能体在不该触发的时候也触发。4.2 技能配置文件的编写要点一个典型的技能配置文件包含以下几个部分。首先是元信息技能名称、版本、作者、描述。然后是触发条件什么情况下应该调用这个技能。接着是执行步骤具体要做什么分几步每步的输入输出是什么。最后是验证方式怎么确认这个技能执行成功了。以“接口设计”技能为例它的触发条件是“当需要定义模块间交互方式时”。执行步骤包括分析调用方需求、确定输入输出数据结构、定义错误处理方式、产出接口文档。验证方式是“接口文档中的每个方法都有明确的输入输出定义和至少一个错误场景说明”。编写配置文件时最容易犯的错误是步骤写得太笼统。比如“分析需求”这种步骤智能体不知道具体要分析什么。好的步骤应该是“列出所有调用方对每个调用方确认其需要的数据字段和操作类型”。越具体智能体的执行效果越稳定。4.3 实际运行中的参数调优框架运行时有几个关键参数可以调整。第一个是技能调用的最大深度也就是一个任务最多可以嵌套调用多少层技能。默认值通常是5对于大多数任务够用了。但如果任务特别复杂可能需要调高。不过调太高会导致执行时间过长需要权衡。第二个是技能执行的超时时间。每个技能执行都有一个时间上限超过就中断。这个参数要根据项目规模和任务复杂度来设。太小会导致技能还没执行完就被中断太大会导致卡住时等待过久。我一般设成默认值的1.5倍左右。第三个是技能间的状态传递格式。默认是 JSON结构清晰但体积较大。如果任务涉及大量数据传递可以考虑换成更紧凑的格式。不过除非遇到性能问题否则不建议改JSON 的可读性对调试很有帮助。4.4 与版本控制系统的配合技能框架在执行过程中会产生很多中间产物需求规格文档、测试文件、审查报告等。这些文件应该纳入版本控制因为它们记录了决策过程对后续维护很有价值。我的做法是在项目里建一个docs/agent-workspace目录专门存放智能体产生的文档类产物。代码和测试文件则按照项目原有的目录结构存放。每次智能体完成一个任务我会把这些变更作为一个独立的提交提交信息里注明使用了哪些技能。这样以后回溯的时候能清楚地看到每个决策是怎么做出来的。提示如果团队多人使用智能体建议在提交信息里加上技能调用的简要记录比如“使用需求澄清测试驱动开发技能实现用户导出功能”。这样其他人 review 的时候能快速理解变更的背景。5. 常见问题与排查技巧实录5.1 技能不触发或触发错误这是最常见的问题。表现是智能体该调用某个技能的时候没调用或者在不该调用的时候调用了。原因通常出在触发条件的定义上。排查思路是这样的先看技能配置文件里的触发条件描述确认它是否覆盖了当前场景。如果描述太窄智能体可能认为条件不满足。如果描述太宽又会导致误触发。我遇到过一次“代码审查”技能在需求分析阶段就被触发的情况原因是触发条件写成了“当有代码变更时”而需求分析阶段产生了一些示例代码片段被误判为代码变更。后来把条件改成“当实现代码文件发生变更时”就正常了。另一个可能的原因是技能之间的优先级冲突。如果两个技能同时满足触发条件优先级高的会先执行可能导致优先级低的那个被跳过。检查方法是查看执行日志里的技能调用顺序确认是否符合预期。5.2 技能执行结果不符合预期有时候技能确实触发了但产出质量很差。比如需求澄清技能只问了一两个无关痛痒的问题或者测试驱动开发技能写的测试用例覆盖不全。这种情况通常是因为技能定义里的执行步骤不够具体。智能体在执行时有一定的自由度如果步骤描述模糊它就会按照自己的理解来结果可能偏离你的预期。解决办法是把步骤写得更细必要时在步骤里加入具体的检查清单。还有一个原因是项目上下文不足。智能体对项目了解越少技能执行效果越差。我建议在项目根目录维护一份PROJECT_CONTEXT.md文件里面写明项目技术栈、目录结构、关键约定等信息。智能体在执行技能时会读取这份文件作为背景知识。5.3 技能执行时间过长复杂任务涉及多个技能串联执行时总耗时可能很长。如果发现某个技能执行特别慢可以从几个方面排查。一是技能本身的步骤是否过于复杂可以考虑拆分成更小的技能。二是技能之间的状态传递是否产生了大量数据导致序列化和反序列化耗时。三是智能体平台的响应速度这个通常无法控制只能通过减少不必要的技能调用来缓解。我的经验是把大技能拆小不仅能提速还能提高执行质量。因为每个小技能的关注点更集中智能体不容易分心。比如把“实现完整功能”拆成“设计接口”“实现核心逻辑”“处理边界情况”“编写测试”四个技能总耗时可能差不多但每个环节的质量都更可控。5.4 常见问题速查表问题现象可能原因排查方法解决方式技能不触发触发条件描述不准确检查配置文件中的条件描述调整条件描述使其更具体技能误触发触发条件过于宽泛查看执行日志中的触发记录收窄触发条件增加限定词产出质量差执行步骤不具体对比产出与预期的差距细化步骤加入检查清单执行超时技能粒度过大查看各技能耗时统计拆分技能减少单次处理量状态丢失传递格式不兼容检查技能间的数据传递日志统一状态格式增加校验与现有代码风格冲突缺少风格配置检查项目是否有风格配置文件添加 ESLint/Prettier 配置5.5 几个踩过的坑和应对技巧第一个坑是技能版本不一致。框架更新后技能定义文件可能也需要更新。如果只更新了框架没更新技能文件会出现兼容性问题。我的做法是在项目里锁定技能文件的版本升级时先在一个分支上测试确认没问题再合并。第二个坑是过度依赖自动化。技能框架能提升效率但不能完全替代人的判断。特别是涉及业务逻辑的决策智能体的理解可能和实际需求有偏差。我现在的做法是在关键决策点设置人工确认环节智能体给出建议后由人来拍板。第三个坑是技能配置的维护成本。随着项目演进技能配置也需要调整。如果没人维护过一段时间就会发现技能执行效果下降。建议指定一个人负责技能配置的维护定期 review 和更新。6. 技能框架的扩展与定制化实践6.1 根据团队习惯定制技能默认技能集合是一套通用最佳实践但每个团队都有自己的习惯。比如有的团队要求所有函数必须有 JSDoc 注释有的团队要求提交信息必须遵循特定格式。这些都可以通过定制技能来实现。定制的方式是复制默认技能定义文件修改执行步骤和验证条件。比如定制“代码审查”技能时在检查清单里加入“确认所有导出函数都有 JSDoc 注释”这一项。这样智能体在审查时就会检查这个要求。我建议定制时遵循“最小改动”原则只改必须改的部分保持和默认技能的一致性。这样框架升级时合并改动会容易很多。6.2 编写自定义技能的方法当默认技能集合不覆盖某个场景时可以编写自定义技能。编写步骤是先明确这个技能要解决什么问题然后定义触发条件和执行步骤最后设计验证方式。举个例子我们团队需要智能体在实现功能时遵循特定的数据库访问规范。我写了一个“数据库访问审查”技能触发条件是“当代码中包含数据库查询时”执行步骤是“检查是否使用了参数化查询、是否设置了合理的超时时间、是否有连接泄漏风险”验证方式是“所有数据库查询都通过检查清单”。编写自定义技能时最重要的是把领域知识显式地写进步骤里。智能体没有团队内部的隐性知识你必须把它变成显性的检查项。6.3 技能组合的进阶用法当熟悉了单个技能的使用后可以尝试更复杂的组合。比如把“需求澄清”“接口设计”“测试驱动开发”“代码审查”四个技能串联成一个完整的工作流用一个命令触发整个流程。这种组合技能的定义方式是在技能文件里引用其他技能并定义它们之间的执行顺序和数据传递关系。执行时框架会按照定义的顺序依次调用子技能并把前一个技能的产出作为后一个技能的输入。我用这种方式定义了一个“新功能开发”组合技能从需求分析一路走到代码审查。实测下来对于中等复杂度的功能开发这个组合技能能节省大量手动协调的时间。不过对于特别复杂或者需求不明确的任务还是建议分步执行以便在中间环节人工介入调整方向。6.4 技能效果的度量与持续改进引入技能框架后怎么知道它是否真的提升了开发质量我建议从几个维度来度量代码审查发现的问题数量、测试覆盖率的变化、返工次数、从任务开始到合并的周期时间。这些数据不需要很精确有个大致趋势就行。我的观察是引入技能框架后代码审查发现的问题数量先上升后下降——上升是因为审查更严格了发现了以前忽略的问题下降是因为智能体在实现阶段就避免了这些问题。测试覆盖率通常会有明显提升因为测试驱动开发技能强制要求先写测试。基于这些度量结果可以有针对性地调整技能配置。比如如果发现某类问题反复出现就在审查技能里加入对应的检查项。如果某个技能执行时间过长但效果不明显就考虑简化或移除它。7. 关于这套框架的一些个人体会用了一段时间 superpowers 之后我最大的感受是它把“让智能体好好写代码”这件事从玄学变成了工程。以前用智能体效果好坏很大程度上靠运气——提示词写得好就效果好写得不好就一堆问题。现在有了技能框架至少有了一个可预期、可调试、可改进的基础。另一个体会是这套框架逼着我把自己对软件开发的理解显性化。以前很多决策是凭直觉做的现在要把它们写成技能定义里的步骤和检查项这个过程本身就让我重新思考了很多习以为常的做法。比如“先写测试”这件事我以前也知道重要但真正把它写成技能定义里的强制步骤后才意识到自己以前有多少次是“先写实现再补测试”的。如果你打算引入这套框架我的建议是从小处开始。先选一个你最熟悉的场景用一个技能试试效果。确认有效后再逐步扩展。不要一上来就配置一大堆技能那样反而会增加认知负担而且出了问题也不好排查。技能框架的价值在于持续使用和迭代而不是一次性配置到位。 
长河君 · 2026/10/31 3:29:43 · 阅读 1.2k Superpowers技能框架：让编码智能体从随机发挥到有章可循
1. 从“超级能力”说起这套技能框架到底在解决什么问题第一次看到“superpowers”这个词很多人会以为是某个游戏模组或者科幻设定。但在软件开发圈子里它指的是一套围绕编码智能体coding agents构建的技能框架核心思路是把软件开发方法论拆解成一个个可组合、可复用的“技能单元”让智能体在写代码时不再只是“你问我答”的被动工具而是能主动调用一整套工程实践来完成复杂任务。我最初接触这套东西的时候正被一个很实际的问题困扰用编码智能体写小脚本、改单个文件确实很爽但一旦任务变成“给现有项目加一个完整的用户认证模块”智能体就开始犯迷糊——它会写出一堆看起来能跑但结构混乱的代码缺少测试、缺少边界处理、缺少和现有代码风格的一致性。问题的根源不在于模型不够聪明而在于它缺少一套结构化的方法论来指导它“先做什么、再做什么、怎么验证”。superpowers 这套框架的价值就在这里。它把软件工程里那些老生常谈但极其重要的实践——比如先写测试再写实现、先做接口设计再填逻辑、先分析需求边界再动手——变成了智能体可以显式调用的“技能”。每个技能是一个独立的、有明确输入输出的模块智能体可以根据当前任务阶段自主决定调用哪个技能。这就像给一个聪明但没经验的实习生配了一本操作手册手册里的每一页都是一个具体的工作方法。这套框架适合谁如果你只是偶尔用智能体写个爬虫脚本可能感受不到它的必要性。但如果你在认真地把智能体纳入日常开发流程——比如用它来维护一个有一定规模的项目、或者让它参与团队协作——那这套技能框架能显著提升输出质量的稳定性。它解决的核心问题是如何让智能体的编码行为从“随机发挥”变成“有章可循”。2. 技能框架的整体设计思路拆解2.1 为什么是“可组合技能”而不是“一个大提示词”很多人第一反应是为什么不直接写一个超长的系统提示词把所有要求都塞进去我一开始也这么想试过之后发现两个致命问题。第一提示词太长会导致模型注意力分散前面强调的规则到后面就被遗忘了。第二不同任务阶段需要不同的关注点用一个统一的提示词去覆盖所有阶段结果就是每个阶段都做得不够好。superpowers 的设计哲学是“分而治之”。它把开发流程拆成若干个阶段每个阶段对应一组技能。比如需求分析阶段有“需求澄清”技能设计阶段有“接口设计”技能实现阶段有“测试驱动开发”技能验证阶段有“代码审查”技能。智能体在每一步只需要关注当前该调用的技能认知负担大大降低。这种设计还有一个好处技能可以被替换和扩展。如果你觉得某个技能不符合团队习惯可以自己写一个替代版本。比如默认的测试技能可能用的是某种测试框架你可以换成团队实际在用的那套。这种灵活性是单一巨型提示词做不到的。2.2 技能之间的调用关系与状态传递技能不是孤立存在的它们之间有明确的依赖关系和状态传递机制。举个具体例子当智能体接到“给项目添加一个数据导出功能”这个任务时它的执行路径大致是这样的——首先调用“任务分解”技能把大任务拆成“确定导出格式”“设计数据查询接口”“实现导出逻辑”“编写测试”等子任务。然后针对每个子任务调用对应的技能。在“设计数据查询接口”这个子任务里它会调用“接口设计”技能产出一个接口定义。这个接口定义会作为状态传递给后续的“实现”技能确保实现和设计一致。这里的关键在于状态的结构化存储。如果状态只是散落在对话历史里智能体很容易在后续步骤中“忘记”前面的决策。superpowers 的做法是把每个技能的产出物以结构化格式保存下来后续技能可以显式地读取这些产出物。这就像在项目管理里每个阶段的交付物都有明确的文档记录而不是靠口头传达。2.3 与现有开发流程的融合方式这套框架并不是要取代现有的开发流程而是嵌入进去。我自己的做法是把它当作一个“智能体行为规范层”——在智能体开始工作之前先加载这套技能框架然后智能体在每一步操作时都会参考框架里的指导。具体融合方式有两种。一种是全流程托管你把一个完整任务交给智能体它自动按照技能框架走完从分析到实现的全部流程。这种方式适合任务边界清晰、风险可控的场景。另一种是按需调用你在某个特定环节手动触发某个技能比如你写完了代码让智能体调用“代码审查”技能来检查一遍。这种方式适合你已经有了明确的工作节奏只需要在特定环节增强的情况。两种方式我都用过实测下来对于新项目或者不熟悉的代码库全流程托管效果更好因为智能体可以从头建立完整的上下文。对于已经很熟悉的项目按需调用更高效不会打断你原有的工作流。3. 核心技能模块的详细解析与实操要点3.1 需求澄清技能把模糊需求变成可执行规格这是整个流程的起点也是最容易被忽视的环节。我见过太多人直接对智能体说“帮我加个登录功能”然后拿到一堆需要大改的代码。问题就出在需求没有被澄清。需求澄清技能的核心动作是提问。当智能体接收到一个模糊需求时它不会直接开始写代码而是先列出一系列需要确认的问题。比如对于“加个登录功能”它会问登录方式是什么用户名密码、邮箱、第三方密码策略是什么最小长度、复杂度要求会话管理用什么机制token、session失败次数限制是多少是否需要记住登录状态这些问题的答案会形成一个需求规格文档作为后续所有工作的基础。我在实际操作中的体会是这个环节花的时间越多后面返工的概率就越低。有一次我偷懒跳过了这个环节结果智能体实现了一个基于 session 的登录而我的项目是前后端分离的需要的是 token 机制最后不得不重写。注意需求澄清技能产出的规格文档要尽量具体避免“合理的密码策略”这种模糊表述要写成“密码长度至少8位包含大小写字母和数字”这样的可验证条件。3.2 测试驱动开发技能先写测试再写实现这是 superpowers 里我最喜欢的技能也是最能体现“方法论”价值的技能。它的工作流程非常明确接到一个实现任务后先写测试用例确认测试失败然后写实现代码让测试通过最后重构。为什么这个顺序很重要因为如果你先写实现再写测试测试往往会不自觉地“迁就”实现——你会不自觉地写一些刚好能通过的测试而不是真正覆盖边界条件的测试。先写测试则强迫你先想清楚“这个功能应该表现成什么样”实现只是让测试通过的手段。具体到智能体的操作它会先生成一个测试文件里面包含正常路径、边界条件、异常情况的测试用例。然后运行测试确认全部失败因为实现还不存在。接着生成实现代码再次运行测试直到全部通过。最后检查是否有可以重构的地方。我实测下来这个技能对智能体输出质量的提升非常明显。没有这个技能的时候智能体写的代码经常缺少边界处理比如数组为空、输入超长、并发访问这些情况。有了测试驱动这些情况在测试阶段就被覆盖了。提示如果项目已经有测试框架需要在技能配置里指定框架类型和测试文件命名规范否则智能体可能会用错框架或者把测试文件放错位置。3.3 代码审查技能自动化的质量守门员代码审查技能是在实现完成后自动触发的。它会从几个维度检查代码是否符合项目已有的代码风格、是否有明显的性能问题、是否有安全隐患、是否有重复代码可以抽取、命名是否清晰。这个技能的产出是一份审查报告里面会列出发现的问题和建议的修改方式。智能体可以选择自动修复也可以把报告交给人来决定。我通常的做法是让智能体自动修复那些明确的风格问题和明显的错误对于涉及业务逻辑的修改建议则人工确认。这里有个细节值得注意代码审查技能需要知道项目的代码风格规范。如果项目里有 ESLint 配置或者 Prettier 配置智能体会读取这些配置来作为审查依据。如果没有它会使用一套通用的最佳实践。我建议在项目里维护一份明确的代码风格配置这样审查结果会更符合团队习惯。3.4 技能的组合调用与优先级管理当多个技能都可以应用于当前任务时智能体需要决定调用顺序和优先级。superpowers 的做法是给每个技能定义一个触发条件和优先级权重。比如“测试驱动开发”技能的触发条件是“开始实现新功能”优先级高于“代码审查”技能因为审查应该在实现完成后进行。在实际运行中智能体会维护一个待调用技能队列按照优先级依次执行。如果某个技能的触发条件不满足就跳过。这个机制保证了流程的有序性不会出现“还没写实现就开始审查”这种逻辑错误。我遇到过一个情况项目里已经有一份遗留代码需要重构智能体同时触发了“重构”技能和“测试驱动开发”技能。按照优先级它先执行了“测试驱动开发”——先为现有行为写测试确保重构不会破坏功能然后再执行重构。这个顺序是对的如果反过来先重构再写测试就失去了测试的保护作用。4. 完整实操流程从零引入这套技能框架4.1 环境准备与框架引入引入 superpowers 的第一步是确认你的开发环境支持智能体调用外部工具或读取配置文件。大多数编码智能体平台都支持通过配置文件或项目根目录的特定文件来加载技能定义。具体操作上你需要在项目根目录创建一个技能配置目录通常命名为.skills或skills。然后在里面放置技能定义文件。每个技能定义文件包含技能名称、描述、触发条件、执行步骤和输出格式。框架本身会提供一个默认的技能集合你可以直接使用也可以按需修改。我建议第一次引入时先用默认技能集合跑一遍完整流程感受一下每个技能的实际效果然后再根据项目特点做定制。直接上手就大改配置很容易因为不熟悉机制而配错。注意技能定义文件里的触发条件要写得足够具体。比如“当任务涉及数据库操作时触发”就比“当需要时触发”要好得多后者会导致智能体在不该触发的时候也触发。4.2 技能配置文件的编写要点一个典型的技能配置文件包含以下几个部分。首先是元信息技能名称、版本、作者、描述。然后是触发条件什么情况下应该调用这个技能。接着是执行步骤具体要做什么分几步每步的输入输出是什么。最后是验证方式怎么确认这个技能执行成功了。以“接口设计”技能为例它的触发条件是“当需要定义模块间交互方式时”。执行步骤包括分析调用方需求、确定输入输出数据结构、定义错误处理方式、产出接口文档。验证方式是“接口文档中的每个方法都有明确的输入输出定义和至少一个错误场景说明”。编写配置文件时最容易犯的错误是步骤写得太笼统。比如“分析需求”这种步骤智能体不知道具体要分析什么。好的步骤应该是“列出所有调用方对每个调用方确认其需要的数据字段和操作类型”。越具体智能体的执行效果越稳定。4.3 实际运行中的参数调优框架运行时有几个关键参数可以调整。第一个是技能调用的最大深度也就是一个任务最多可以嵌套调用多少层技能。默认值通常是5对于大多数任务够用了。但如果任务特别复杂可能需要调高。不过调太高会导致执行时间过长需要权衡。第二个是技能执行的超时时间。每个技能执行都有一个时间上限超过就中断。这个参数要根据项目规模和任务复杂度来设。太小会导致技能还没执行完就被中断太大会导致卡住时等待过久。我一般设成默认值的1.5倍左右。第三个是技能间的状态传递格式。默认是 JSON结构清晰但体积较大。如果任务涉及大量数据传递可以考虑换成更紧凑的格式。不过除非遇到性能问题否则不建议改JSON 的可读性对调试很有帮助。4.4 与版本控制系统的配合技能框架在执行过程中会产生很多中间产物需求规格文档、测试文件、审查报告等。这些文件应该纳入版本控制因为它们记录了决策过程对后续维护很有价值。我的做法是在项目里建一个docs/agent-workspace目录专门存放智能体产生的文档类产物。代码和测试文件则按照项目原有的目录结构存放。每次智能体完成一个任务我会把这些变更作为一个独立的提交提交信息里注明使用了哪些技能。这样以后回溯的时候能清楚地看到每个决策是怎么做出来的。提示如果团队多人使用智能体建议在提交信息里加上技能调用的简要记录比如“使用需求澄清测试驱动开发技能实现用户导出功能”。这样其他人 review 的时候能快速理解变更的背景。5. 常见问题与排查技巧实录5.1 技能不触发或触发错误这是最常见的问题。表现是智能体该调用某个技能的时候没调用或者在不该调用的时候调用了。原因通常出在触发条件的定义上。排查思路是这样的先看技能配置文件里的触发条件描述确认它是否覆盖了当前场景。如果描述太窄智能体可能认为条件不满足。如果描述太宽又会导致误触发。我遇到过一次“代码审查”技能在需求分析阶段就被触发的情况原因是触发条件写成了“当有代码变更时”而需求分析阶段产生了一些示例代码片段被误判为代码变更。后来把条件改成“当实现代码文件发生变更时”就正常了。另一个可能的原因是技能之间的优先级冲突。如果两个技能同时满足触发条件优先级高的会先执行可能导致优先级低的那个被跳过。检查方法是查看执行日志里的技能调用顺序确认是否符合预期。5.2 技能执行结果不符合预期有时候技能确实触发了但产出质量很差。比如需求澄清技能只问了一两个无关痛痒的问题或者测试驱动开发技能写的测试用例覆盖不全。这种情况通常是因为技能定义里的执行步骤不够具体。智能体在执行时有一定的自由度如果步骤描述模糊它就会按照自己的理解来结果可能偏离你的预期。解决办法是把步骤写得更细必要时在步骤里加入具体的检查清单。还有一个原因是项目上下文不足。智能体对项目了解越少技能执行效果越差。我建议在项目根目录维护一份PROJECT_CONTEXT.md文件里面写明项目技术栈、目录结构、关键约定等信息。智能体在执行技能时会读取这份文件作为背景知识。5.3 技能执行时间过长复杂任务涉及多个技能串联执行时总耗时可能很长。如果发现某个技能执行特别慢可以从几个方面排查。一是技能本身的步骤是否过于复杂可以考虑拆分成更小的技能。二是技能之间的状态传递是否产生了大量数据导致序列化和反序列化耗时。三是智能体平台的响应速度这个通常无法控制只能通过减少不必要的技能调用来缓解。我的经验是把大技能拆小不仅能提速还能提高执行质量。因为每个小技能的关注点更集中智能体不容易分心。比如把“实现完整功能”拆成“设计接口”“实现核心逻辑”“处理边界情况”“编写测试”四个技能总耗时可能差不多但每个环节的质量都更可控。5.4 常见问题速查表问题现象可能原因排查方法解决方式技能不触发触发条件描述不准确检查配置文件中的条件描述调整条件描述使其更具体技能误触发触发条件过于宽泛查看执行日志中的触发记录收窄触发条件增加限定词产出质量差执行步骤不具体对比产出与预期的差距细化步骤加入检查清单执行超时技能粒度过大查看各技能耗时统计拆分技能减少单次处理量状态丢失传递格式不兼容检查技能间的数据传递日志统一状态格式增加校验与现有代码风格冲突缺少风格配置检查项目是否有风格配置文件添加 ESLint/Prettier 配置5.5 几个踩过的坑和应对技巧第一个坑是技能版本不一致。框架更新后技能定义文件可能也需要更新。如果只更新了框架没更新技能文件会出现兼容性问题。我的做法是在项目里锁定技能文件的版本升级时先在一个分支上测试确认没问题再合并。第二个坑是过度依赖自动化。技能框架能提升效率但不能完全替代人的判断。特别是涉及业务逻辑的决策智能体的理解可能和实际需求有偏差。我现在的做法是在关键决策点设置人工确认环节智能体给出建议后由人来拍板。第三个坑是技能配置的维护成本。随着项目演进技能配置也需要调整。如果没人维护过一段时间就会发现技能执行效果下降。建议指定一个人负责技能配置的维护定期 review 和更新。6. 技能框架的扩展与定制化实践6.1 根据团队习惯定制技能默认技能集合是一套通用最佳实践但每个团队都有自己的习惯。比如有的团队要求所有函数必须有 JSDoc 注释有的团队要求提交信息必须遵循特定格式。这些都可以通过定制技能来实现。定制的方式是复制默认技能定义文件修改执行步骤和验证条件。比如定制“代码审查”技能时在检查清单里加入“确认所有导出函数都有 JSDoc 注释”这一项。这样智能体在审查时就会检查这个要求。我建议定制时遵循“最小改动”原则只改必须改的部分保持和默认技能的一致性。这样框架升级时合并改动会容易很多。6.2 编写自定义技能的方法当默认技能集合不覆盖某个场景时可以编写自定义技能。编写步骤是先明确这个技能要解决什么问题然后定义触发条件和执行步骤最后设计验证方式。举个例子我们团队需要智能体在实现功能时遵循特定的数据库访问规范。我写了一个“数据库访问审查”技能触发条件是“当代码中包含数据库查询时”执行步骤是“检查是否使用了参数化查询、是否设置了合理的超时时间、是否有连接泄漏风险”验证方式是“所有数据库查询都通过检查清单”。编写自定义技能时最重要的是把领域知识显式地写进步骤里。智能体没有团队内部的隐性知识你必须把它变成显性的检查项。6.3 技能组合的进阶用法当熟悉了单个技能的使用后可以尝试更复杂的组合。比如把“需求澄清”“接口设计”“测试驱动开发”“代码审查”四个技能串联成一个完整的工作流用一个命令触发整个流程。这种组合技能的定义方式是在技能文件里引用其他技能并定义它们之间的执行顺序和数据传递关系。执行时框架会按照定义的顺序依次调用子技能并把前一个技能的产出作为后一个技能的输入。我用这种方式定义了一个“新功能开发”组合技能从需求分析一路走到代码审查。实测下来对于中等复杂度的功能开发这个组合技能能节省大量手动协调的时间。不过对于特别复杂或者需求不明确的任务还是建议分步执行以便在中间环节人工介入调整方向。6.4 技能效果的度量与持续改进引入技能框架后怎么知道它是否真的提升了开发质量我建议从几个维度来度量代码审查发现的问题数量、测试覆盖率的变化、返工次数、从任务开始到合并的周期时间。这些数据不需要很精确有个大致趋势就行。我的观察是引入技能框架后代码审查发现的问题数量先上升后下降——上升是因为审查更严格了发现了以前忽略的问题下降是因为智能体在实现阶段就避免了这些问题。测试覆盖率通常会有明显提升因为测试驱动开发技能强制要求先写测试。基于这些度量结果可以有针对性地调整技能配置。比如如果发现某类问题反复出现就在审查技能里加入对应的检查项。如果某个技能执行时间过长但效果不明显就考虑简化或移除它。7. 关于这套框架的一些个人体会用了一段时间 superpowers 之后我最大的感受是它把“让智能体好好写代码”这件事从玄学变成了工程。以前用智能体效果好坏很大程度上靠运气——提示词写得好就效果好写得不好就一堆问题。现在有了技能框架至少有了一个可预期、可调试、可改进的基础。另一个体会是这套框架逼着我把自己对软件开发的理解显性化。以前很多决策是凭直觉做的现在要把它们写成技能定义里的步骤和检查项这个过程本身就让我重新思考了很多习以为常的做法。比如“先写测试”这件事我以前也知道重要但真正把它写成技能定义里的强制步骤后才意识到自己以前有多少次是“先写实现再补测试”的。如果你打算引入这套框架我的建议是从小处开始。先选一个你最熟悉的场景用一个技能试试效果。确认有效后再逐步扩展。不要一上来就配置一大堆技能那样反而会增加认知负担而且出了问题也不好排查。技能框架的价值在于持续使用和迭代而不是一次性配置到位。