AI Agent辅助开发：三条技术路线与8个Skill的落地实践

1. 三条路线到底在解决什么问题先说结论。我最近一个月把手头一个中大型跨平台系统从传统编码方式切到 AI Agent 辅助开发模式为了让 Agent 在项目里真正干得动活前前后后试了 Spec Kit、OpenSpec 和 Superpowers 三条技术路线围绕需求澄清、影响分析、任务拆解、测试驱动、文档同步等场景拆出了 8 个独立 Skill。跑完一轮下来最直观的感受是这三样东西根本不是同一个层面上的竞品它们分别卡在软件开发流程的不同环节上。你如果只看名字觉得都是“给 AI 用的工具”就放在一起比那大概率会在落地时踩坑。先把三个东西各自是什么说清楚。Spec Kit 走的是“本地优先、规格驱动”的路线。它的核心思路是给 Agent 开发工作流套一层轻量的规格约束你先把要做的事情写成一个很薄的规格文件Agent 再照着这个规格去读代码、写代码、跑测试。我实际用下来它的最大价值在于“决策痕迹清晰”每一步改动的理由都被收拢到规格文件里出问题时回溯成本比传统对话式编程低很多。但它的代价也很直接工作流是自带的一套扩展能力只能跟着它的约定走。新场景出现时你需要在它给的框架内想办法而不是自由地加东西。OpenSpec 则是另一种姿态。它更像是一套开放规格协议核心主张是让 AI 生成的规格变更可以被人类直接审查。它不绑定具体工具通用做法是把规格拆成多个 Markdown 文档通过 diff 来呈现 AI 每一步做了什么决策。这个逻辑本质上是把规格当作一种可评审的协作产物来对待天然适配已有的 PR 审查流程。所以它解决的不是“怎么让 AI 干活”而是“怎么让 AI 干的活能被团队放心地验收”。Superpowers 的出发点又不一样它把重心放在 Agent 的能力封装上。每个 Skill 都是一个标准化的技能包包含系统提示词、行为模板、工具调用规范等Agent 在运行时可以按需加载。这套思路非常适合跨项目复用比如我在一个项目里实现好的“影响分析”技能拿到另一个项目里几乎不用改就能跑。它更像一个“能力市场”强调的是 Agent 本身的扩展性。这三者放在一起对比本质上是三种开发哲学的分野Spec Kit 认为先定规格再写代码是最高效的路径OpenSpec 认为规格的透明度和可审性比自动化更重要Superpowers 则认为 Agent 能力本身才是项目效能的杠杆点。我个人的判断是它们不是同一个维度上的替代关系而是可以分层组合的。真正的问题从来不是“选哪个”而是“每个在项目里该管哪一段”。2. 8 个 Skill 的落地实录从需求到验收全链路我在模拟项目 X 上陆续沉淀出 8 个 Skill覆盖了 Agent 辅助开发的完整链路。下面逐个拆解每个都给出它在三条路线里的不同实现方式以及我在实测中的真实判断。2.1 需求澄清 Skill把一句话变成可执行的问题清单这个 Skill 的目标是从一句模糊需求出发产出一份结构化的问题清单。传统做法是产品经理找开发开会现在则让 Agent 先问一轮。Spec Kit 路线利用规格模板直接生成问题列表。实测中它会基于内置的 spec 模板生成问题域但提问顺序偏固定遇到复杂需求时容易漏掉非功能性问题比如性能边界、安全约束。OpenSpec 路线用变更记录驱动澄清。每轮澄清都追加到 spec 的变更日志里形成可追溯的决策链。这个体验是所有方案里最好的因为它天然适合记录“为什么”。Superpowers 路线把澄清逻辑封装成一个独立 Skill提示词里放开自由度。Agent 会根据项目上下文自行决定提问顺序效果最灵活但也最依赖模型本身的理解能力。我的落地结论需求澄清这个技能放在 OpenSpec 的变更记录框架下最合适因为“提问的中间过程”本身就是规格上下文的一部分。如果用 Superpowers 封装效果也不错但需要额外做一轮问题收敛的约束否则 Agent 容易问出与项目无关的问题。2.2 影响分析 Skill变更前先摸清波及面影响分析是所有技能里价值回报率最高的一个。传统开发中改一个公共函数、换一个接口签名影响范围靠人脑硬记。在 Agent 模式下这个技能让 AI 先扫一遍代码库把受影响的位置列出来再决定怎么改。Spec Kit对代码库做静态扫描输出一份影响面清单。实测中它表现稳定但深度有限只能识别直接引用关系跨模块的间接影响经常漏。OpenSpec通过对比规格变更前后 diff 来推断影响区域。这个方案准确度最高前提是代码库规格文件维护得够好。Superpowers配合文件读取和代码检索 MCP 工具做成一个独立分析技能。实测效果最好能结合理解能力发现“这个函数被反射调用了”这类静态分析覆盖不到的隐性依赖。我的落地结论影响分析是 Superpowers 最能发挥优势的场景。它恰恰需要的是对代码库语义层面的理解而不仅靠文本匹配规格文件里也不会有这些关系。2.3 任务拆解 Skill把需求切成可执行的子任务任务拆解决定了 Agent 的执行粒度粒度太大会导致单次上下文爆掉粒度太小又会产生大量无效往返。我的标准是每个子任务必须能独立验收。Spec Kit自带一套固定的 task checklist 模板按“实现、测试、文档”三段切适合标准功能开发但遇到重构类任务时显得死板。OpenSpec约定以 PR 粒度来拆天然贴合最适合团队审查的最小变更集。实测下来拆出来的任务普遍比 Spec Kit 更细也更适合走 Code Review。Superpowers做成 Planner 技能让 Agent 自己决定拆法。灵活性最高但也最容易拆出不均衡的任务颗粒需要额外给约束。落地结论任务拆解不应该被框架写死。我在最终组合方案里用 Superpowers 做了规划器但要求它输出的每个任务必须以“可提交评审”作为兜底标准。2.4 测试驱动 Skill先红后绿的循环推进AI 写代码最容易出现问题的地方就是“自欺欺人”——模型以为自己写对了实际上连编译都没过。测试驱动技能是为了强制 Agent 先写测试、再写实现用执行结果来替代模型自信。Spec Kit内置了测试钩子规格里写验收标准实现后自动跑测试。这套闭环体验最顺畅因为它把验收标准当作规格的一部分来强制约束。OpenSpec测试作为规格的验收标准之一但不会自动执行需要配合 CI 才能形成闭环。Superpowers做成了独立的 TDD 技能先产出测试清单再逐条实现。实测效果最好的是它对失败态的处理让 Agent 保留运行失败的信息再进入下一轮修正。我在实际项目里强烈建议无论是哪条路线测试执行必须由 Agent 调真实测试工具完成绝不能让它脑补测试结果。否则这个技能就变成了表演。2.5 文档同步 Skill代码变更后自动更新文档文档永远是开发链条里最容易被偷工减料的一环。这个 Skill 的价值不在于“生成文档”而在于每次代码变更后自动检测 README、接口说明等文档与代码的漂移并生成一致的修订。Spec Kit会同步维护规格文件代码变更后规格文档跟着更新一致性靠工作流保证。OpenSpec通过规格变更记录驱动文档更新思路是“规格变了文档就要变”但不会主动扫描代码实现与文档是否一致。Superpowers做成文档生成 Skill配合文件读取能力扫描项目里所有 doc 文件识别新增、变更、废弃接口再批量更新。落地结论文档同步需要的是“扫描能力 更新模板”放在 Superpowers 里封装最合适因为它能灵活调取文件工具不受固定流程限制。2.6 代码审查 SkillAI 自查再提交我的习惯是让 Agent 在每次提交前先审查自己的 Diff而不是写完直接提 PR。这一步能拦住很多低级问题死代码、硬编码、调试日志残留、错误处理缺失。Spec Kit审查范围限定在工作流框架内的 diff逻辑简单但覆盖不到跨文件的改动。OpenSpec审查视角天然站在 PR 评审者的位置重点检查规格和代码是否一致这个定位非常准确。Superpowers独立 review skill提示词里可以注入团队个性化审查规则比如“不允许使用 any 类型”“日志必须带上下文”等。落地心得代码审查这个技能最适合复用我把团队多年的 review 意见沉淀成了一条条规则文本直接挂到 Superpowers 的 review skill 里实测拦住问题的能力比默认规则强不少。2.7 计划执行 Skill多步骤长任务的进度掌控Agent 处理长任务时最怕的是“走着走着忘了要干什么”。计划执行技能负责把多步计划输出成一个带状态的文件或结构体每完成一步就更新状态异常时能回滚或转人工。Spec Kit按阶段执行内置 plan流程清晰但遇到中途变更时需要重写 plan灵活性一般。OpenSpec每个计划步骤对应一个 PR天然带进度概念就是成本高一点。Superpowers做了计划器 Skill支持状态持久化到本地文件中断后可以恢复。实测在超长任务里表现最好。2.8 上下文压缩 Skill处理长对话超限问题跑过 Agent 开发的人都知道上下文爆掉是家常便饭。这个技能负责把已经完成的讨论、已确认的决策、已不相关的代码片段从上下文里摘除。Spec Kit通过精简规格文件来控制上下文思路是“规格即记忆”。OpenSpec压缩 changelog 和 spec diff 历史把已完成部分的记录合并成摘要。Superpowers做成 token 管理技能定期把对话历史和任务状态导出成摘要文件再让 Agent 重新加载。实测下来上下文压缩技能在所有路线里都不可或缺。没有它Agent 在项目后半程的智商明显下降行为开始变得“心不在焉”。3. 同一个 Skill三种实现方式的代价与收益只看每个 Skill 的单点表现还不够我按照实际工程投入做了个横向对比把成本、维护、扩展三个维度拉在一张表里看这样才比较客观。对比维度Spec KitOpenSpecSuperpowers上手成本低自带完整工作流中需要设计规格结构中高需要理解技能定义协议项目适配成本中格式固定需要迁就中低格式开放低技能按需加载团队协作体验一般面向个人开发者好面向团队评审流好面向能力复用可扩展性低受框架边界限制中依赖约定习惯高可自研技能包中途换路线成本高流程和产物都绑死中规格文档可迁移低技能独立存在最适合的场景个人快速验证团队平台化协作多项目复用能力沉淀这张表背后有几条我实际踩出来的经验。第一Spec Kit 的“低上手成本”是个诱惑陷阱。单项目试水时它最快但一旦你开始第二个项目会发现复用得重新适配跨项目的封装能力几乎为零。它适合做一个 PoC 验证不适合作为团队基建。第二OpenSpec 的初创成本主要体现在规格结构设计上你把规格拆成什么粒度、变更日志怎么写、评审门槛定在哪都需要前期统一约定。但只要约定形成后续的协作体验是所有方案里最顺滑的。它解决的并不是自动化问题而是“可信”问题——AI 干活人类审得放心。第三Superpowers 的上手成本其实不在技能本身而在于你要先想清楚“哪些能力值得做成技能”。一旦定义做完了所有后续项目都受益这是唯一一条“先难受后轻松”的路线。最终我在项目里的组合方案是以 OpenSpec 作为规格与评审的规范层用 Superpowers 承载所有可复用的技能能力遇到快速验证场景才单独起一个 Spec Kit 环境。三者的边界很清晰规范层、能力层、快速验证层各管一摊不冲突。4. 从工具对比中沉淀的工程方法论工具用满一个月后我更有收获的反而不是工具本身而是被逼出来的方法论。这些东西在任何一个工具的文档里都学不到。4.1 规格的价值不在终态而在中间态传统开发里规格文档是给人看的写完基本就归档了。但在 AI 辅助开发模式里规格的真正价值在于它是“Agent 决策的中间态快照”Agent 怎么理解需求、为什么这么设计接口、哪些约束是它基于上下文推断出来的这些信息全部体现在规格从无到有的演化过程中。这个认知直接影响了我对规格文件的管理方式不再追求“最终版规格写得漂不漂亮”而是保证每一次变更都有记录、有理由。OpenSpec 的 changelog 思路在这个维度上确实比另外两者领先它就是为这个场景设计的。如果你手头项目已经开始用 AI Agent 写代码但规格文件还是一次性写完的那实际上丢掉了一半的价值。4.2 技能拆分的判断标准能不能独立验收8 个 Skill 的拆分不是拍脑袋定的我试过更粗的拆法一个大规划技能包揽拆解和影响分析也试过更细的拆法把需求澄清拆成提问和数据整理两个技能。最终的经验是多轮试错后收敛到 8 个判断标准只有一个这个技能能不能独立验收。能独立验收的定义是技能执行完后产出物可以被人工或自动化规则判定“通过/不通过”而不需要依赖链条下游的另一个技能。比如影响分析的执行产出是“受影响文件清单”这个清单能直接对照代码库验证但如果你把“影响分析”和“修改代码”拆在一起就无法验收前半段做得好不好只能看最终代码对不对。按这个标准拆下来不会多也不会少。4.3 工具链必须分层规范层、能力层、执行层这是我这一个月项目里最大的方法论收获。任何 AI Agent 辅助开发体系都应该拆三层来理解规范层定义“怎么做才是对的”对应 OpenSpec 的规格评审流解决信任问题。能力层定义“Agent 能做什么”对应 Superpowers 的技能包解决复用问题。执行层定义“具体怎么跑”对应 Spec Kit 的任务工作流解决效率问题。绝大多数团队选型出问题都是因为拿一个层级的工具去解决另一个层级的问题。比如指望 OpenSpec 提升代码生成效率或者指望 Superpowers 保证产出质量这个方向本身就是错的。效率靠流程和工具质量靠评审和标准复用靠抽象和封装三条腿缺一不可。4.4 必须保留人工闸门无论工具链怎么搭一个原则我不能让步Agent 可以负责分析、拆解、写代码、写测试、写文档但合并代码的决定权永远在人类手上。我见过一些团队把整个变更流程全部自动化托管给 Agent看起来效率很高但一旦 AI 基于错误的上下文做了一个错误的推断并且规格文件也随着这个错误一起生成整个链条上的产物都会带着同一个错误认知人工审查的成本反而更高。所以我的做法是Agent 产出的一切都是“建议稿”包括规格文件、代码 Diff、测试用例全部走 Pull Request 流程由人来做最终确认。这个闸门看着拖慢了速度实际上挡住了类“系统性错误的连锁传播”。4.5 评估一个 Skill 是否值得做用“有效产出时间”来衡量大家常问“8 个 Skill 是不是太多了”“有没有必要每个都封装”。我自己的衡量指标是看这个技能能不能减少人与 Agent 之间的往返时间。具体操作是同一个任务分别用“提示词临时驱动”和“封装成 Skill”各跑一遍对比从目标到有效产出物之间的时间和质量。比如任务拆解我发现临时让 Agent 拆容易拆得太粗重来两轮才符合预期封装成技能后加上了验收标准约束第一轮就能产出可用结果。这个时间差就是技能的价值。如果一个技能没有带来可感知的往返减少就不值得封装用提示词写死就够了。5. 常见问题与排查经验实录工具落地过程中免不了碰到各种坑我挑几个典型的记录一下给准备走同样路线的朋友省点时间。问题一Spec Kit 规格文件越写越大Agent 到后面上下文直接爆炸。原因很直接规格文件承载了所有决策信息项目一复杂规格就成了比代码本身还厚的文档Agent 每次加载都要吃掉大量上下文。我的解决办法是给规格加“索引化”和“分层化”处理顶级规格只保留当前阶段有效的决策摘要细节和已废弃的决策下沉到子文档需要时按路径加载。简单说就是不要让 Agent 一口气读完整份规格而是给它一个导航结构。问题二OpenSpec 的变更记录没人维护跑两周就成僵尸文件。这几乎是 OpenSpec 落地的头号杀手。解决思路只有一个把规格评审和代码评审绑在同一个流程里面PR 不带上对应 spec diff 就视为无效变更。这不是技术问题是流程强制问题。我实际推行时在 Merge 前加了一个检查脚本检测到代码变更但规格未更新时直接打回一周后团队就养成了习惯。问题三Superpowers 的多个技能同时跑出现互相冲突。典型场景是文档同步技能和代码审查技能同时被加载时一个在改文档一个在报“文档已被外部修改”来回拉扯。排查后发现是技能之间的文件读写没有做冲突控制。解决办法是给每个技能定义明确的文件作用域文档同步技能只允许写 doc 目录代码审查技能只读不写路径重叠时按明确的优先级排队执行。问题四AI 生成的规格描述和实际代码实现不一致。这个最隐蔽也是最危险的。AI 可能在规格里写“支持限流”但代码里实际没有实现或者实现方式完全不同。我最终的兜底办法是在 CI 里加一个“规格一致性校验”环节抽取规格里的验收关键词对照测试用例名称做匹配覆盖率低于阈值就拒绝通过。代价是会有一些误报需要人工确认但这个成本远比漏掉真实的不一致要低。问题五Agent 在长任务执行到一半时“失忆”忘记前面定的约束。排查下来和模型上下文窗口有关任务超长时模型开始“选择性记忆”。我的处理是让计划执行技能每完成一步就把当前约束、已完成事项、待办事项重新写入一个状态文件下一步开始时强制先读这个文件再做。等于把模型的工作记忆外置了效果立竿见影。问题六整体链路通了但人工审查效率成了瓶颈。这个问题的表象是“AI 干活太快人审不过来”。实际上真正的问题是审查的标准没有模板化。我的经验是把 Code Review 的通用检查清单沉淀成规则文本挂到代码审查技能里让 Agent 先按清单自查一轮人工只审 Agent 审查完后的增量差异。带宽一下子就释放出来了。遇到过的这些坑大部分其实和工具本身关系不大更多是“把新工具套进旧流程”时产生的摩擦。我现在的做法是任何技能和流程落地前都先明确边界和兜底方案而不是直接信任 Agent 的输出。这大概是我这一个月下来最想说的一句话——AI 辅助开发的瓶颈根本不是模型能力而是工程约束能力。