这半年我大部分精力都扑在大模型编程的技能工程上，前后折腾了三个工具链：Spec Kit、OpenSpec，还有后来重度使用的 Superpowers，陆陆续续落地了 8 个 Skill，从最开始单纯的“写提示词”进化到一套相对完整的“技能工程方法论”。这三个东西名字看着都是“规范”“技能”，但实际定位差得挺多：Spec Kit 是帮你把需求翻译成规范文档的脚手架，OpenSpec 是定义“规范长什么样、怎么流转”的协议层，Superpowers 则是把多个技能打包成可安装、可复用、可持续演进的工程化体系。这三个配合起来用，才真正把大模型从“问一句答一句”变成“能扛起一条流水线”的协作角色。这篇文章就围绕这 8 个 Skill 的落地过程，把选型逻辑、实操步骤、踩坑记录，以及沉淀下来的方法论一起梳理一遍，给正在做同类事情的朋友一个可以直接参考的样本。
1. 为什么同时用三个工具，而不是只选一个
先说清楚一个容易混淆的点：Spec Kit、OpenSpec、Superpowers 不是同类工具的平替关系，它们各自解决的是不同层面的问题。
1.1 Spec Kit：把模糊想法砸实成工程语言
最早接触 Spec Kit 的时候，我踩过一个很实在的坑：直接让大模型写代码，它写得飞快，但经常不是我要的东西。问题不在模型能力，而在“需求本身没说清楚”。Spec Kit 的价值就在这里，它提供一整套目录结构、文档模板、撰写引导，逼着你在写代码之前先把以下东西定下来：
- 这个功能解决谁的问题，当前流程哪里痛
- 输入是什么，输出是什么，边界条件有哪些
- 验收标准长什么样，怎么验证它真的做对了
- 涉及哪些关联模块，改动会影响谁
它的思考方式很像传统软件工程里的“需求规格说明书”，但比那个轻量得多。它不要求你写几十页文档，而是用模板一步步引导，让最终产出物是结构化、可评审、可执行的内容。在实际项目里，我们用 Spec Kit 为每个新功能建立独立目录，一个需求一个文件夹，里面包含需求描述、技术方案、验收条目、变更记录四个文件，结构固定，入口统一。
这个工具我评估下来是“上手即用”的类型，没有太多学习成本。但用了两周之后，我发现了它的一个明显短板：它是单机工作流。也就是说，它管好“我和模型之间怎么对齐需求”，却管不了“多个人、多个模型、多个任务之间怎么保持标准一致”。一旦场景从一个人写 Demo 放大到一个小团队并行推进多个模块，规格文档的格式、字段、流转方式就开始各写各的，混乱随之而来。
1.2 OpenSpec：定义一套大家都要遵守的“接口协议”
OpenSpec 解决的正是上一节说的混乱问题。你可以把它理解成“规格文档的接口规范”。它不关心你具体写什么业务内容，它只定义四件事：
- 规范文档必须有哪些字段，每个字段什么含义
- 需求变更怎么提交、怎么评审、怎么归档
- 如何标识状态：草稿、评审中、已批准、已废弃
- 如何建立需求之间的依赖和引用关系
说直接一点，Spec Kit 是帮你“写出一份好文档”的工具，OpenSpec 是“让所有文档能被协作处理”的协议。我们是在同时接入三个模块、三个人并行维护的节点上引入 OpenSpec 的。当时最痛的问题就是：同一个人提交的两个需求里，对同一个数据字段写了两种不同的定义，而两位开发者各自按自己看到的版本去实现，最后联调阶段才发现对不上。
引入 OpenSpec 之后，所有规格文档强制套用同一套 Schema，字段定义、变更类型、状态流转都在一个固定的数据模型里。我们当时只做了一件事：把所有规格文档统一成 YAML 头部加 Markdown 正文的结构，头部存元信息（编号、状态、负责人、关联需求），正文存具体描述。这套结构看着不起眼，但它让“规格文档”从一个写作问题变成了一个工程问题，可以 diff、可以版本化、可以做变更记录。
不过 OpenSpec 也有它的代价——它要求团队先对齐约定，再开始写内容。这种“先建规则再用规则”的方式，在快节奏的项目里会让人觉得累赘。如果你的项目只有一个人写代码、需求不超过三五个，直接上 OpenSpec 就是过度设计。它的最佳适用场景是：多人协作、长期维护、模块之间有明确依赖关系的项目。
1.3 Superpowers：从“单个技能”走到“技能系统”
Superpowers 是我三个工具里最晚接触、但最终用得最深的一个。它可以理解为“技能的打包与运行框架”。如果用生活类比：Spec Kit 是教你写菜谱的模板，OpenSpec 是规定菜谱统一格式的行业标准，Superpowers 则是中央厨房——它不仅存放菜谱，还管理食材采购、切配流程、出锅标准、出餐顺序，甚至能根据当日订单自动组合成一套完整的出餐方案。
落到实际场景里，Superpowers 的作用是让多个 Skill 不再是零散的提示词文件，而是被组织成一个具备依赖关系、调用顺序、上下文传递机制的系统。举个具体的例子，我们定义“需求澄清专家”和“接口文档生成器”两个技能，前者负责把模糊需求追问成结构化描述，后者负责把结构化描述转成接口文档。如果它们是孤立的两个文件，每次都要手动把前者的输出复制给后者。但当我们把这俩放进同一个技能包，通过 Superpowers 定义它们之间的数据流，就能自动完成“澄清结果 → 文档生成”的流水线调用。
它带来的另一个关键能力是“上下文隔离”。一个技能产生的中间数据、临时文件、思考过程，不会污染其他技能的运行现场。你可以想象成每个技能都有自己的工作台，做完事只把成品放到公共货架上，不把工作台的杂物也一并倒出来。这种隔离机制在多个技能串行执行时特别重要，能显著减少模型被历史输出带偏的概率。
我个人的体会是：Spec Kit 适合起步期，OpenSpec 适合协作期，Superpowers 适合规模化期。三者不是“选一个”的关系，而是“叠着用”的关系。下面我会用一个完整的实战案例来说明它们怎么配合。
2. 8 个 Skill 的选型与落地拆解
先把我这半年陆续落地、目前在生产环境里稳定运行的 8 个 Skill 列出来。实际项目背景是一个跨平台的数据处理系统改造，涉及需求梳理、接口开发、测试、文档、迁移多个环节。为了避免说空话，每个技能我都标注了它在整条链路中的位置、输入输出以及依赖的其他技能。
| 编号 | 技能名称 | 职责定位 | 输入 | 输出 | 主要依赖 |
|---|---|---|---|---|---|
| S1 | 需求澄清专家 | 对话式打磨原始需求 | 一句话需求 | 结构化需求描述 | 无 |
| S2 | 规范生成器 | 基于需求生成规格文档 | S1输出 | OpenSpec 格式规格文档 | S1 |
| S3 | 拆单助手 | 规格文档拆成开发工单 | S2输出 | 带验收标准的工单 | S2 |
| S4 | 代码评审专家 | 按工单标准做代码评审 | 代码 + S3工单 | 评审判定与修改建议 | S3 |
| S5 | 测试用例生成器 | 从规格推导测试用例 | S2输出 | 覆盖矩阵 + 用例清单 | S2 |
| S6 | 迁移影响分析器 | 分析改动影响范围 | 代码库 + 技术方案 | 影响面报告 | S3 |
| S7 | 接口文档生成器 | 生成接口文档和变更日志 | S2输出 + 代码 | 接口文档 | S2、S6 |
| S8 | 回归看门狗 | 回归阶段自动巡检 | 测试报告 + 代码 | 风险清单与阻塞项 | S5、S6 |
这张表看下来，覆盖了从“需求进”到“验收出”的完整闭环。接下来重点拆四个有代表性的技能，讲清它们的实现路径和关键决策。
2.1 S1 + S2：从一句话需求到标准规格文档
这是整条链路的地基，也是我认为最容易做砸的部分。S1（需求澄清专家）的输入往往是一句非常粗暴的描述，比如“用户希望导出报告的时候能选时间范围”，这句话有大量歧义：时间范围是预设选项还是自定义？导出的格式受影响吗？和历史版本是否兼容？如果这里不问清楚，后面每一步都会歪。
所以我给 S1 定了几条硬规则：
- 每轮最多追问三个问题，避免把人问烦
- 所有问题只围绕“目标、边界、验收”三个维度展开
- 不猜测，用户没说过的默认不存在
- 每轮追问结束都输出一份“当前理解摘要”，让用户有机会纠偏
实测下来，这四条规则把需求澄清的准确率提升得非常明显。最初版本没有这些约束，S1 会漫无边际地问十几个问题，用户答到后面明显失去耐心。加了约束之后，平均只要三轮对话就能锁定一个需求的核心要素。
S2（规范生成器）吃下 S1 的结构化输出之后，生成一份符合 OpenSpec 约定的规格文档。这里我踩过的最深的坑是：直接照搬通用模板生成的内容往往逻辑通顺但信息缺失，尤其是“非功能需求”和“边界条件”这两个部分，模型很少主动补充。后来我给 S2 加了一个“补全检查清单”，每次生成完必须逐项自查以下问题：
- 非功能需求是否覆盖性能、安全、可用性？
- 是否明确描述异常场景下的行为？
- 是否列出了不做的事情（反向边界）？
- 验收标准是否可量化、可测试？
补全检查清单这个东西是整条链路的核心技巧。它本质上是用一个固定的流程，逼着模型把最容易遗漏的部分补齐。这个思路后来延续到了所有技能中。
2.2 S4 + S8：评审和回归里的工程化设计
代码评审这个技能值得多说几句。传统做法是直接把代码丢给模型说“帮我看下有没有问题”，这种做法效果极差——模型的注意力会被变量命名、代码风格这类细枝末节带跑，反而忽略真正的逻辑问题。
我后来调整了 S4 的输入结构，强制要求它接收七个片段：
- 工单编号与需求描述（S3输出）
- 本次变更涉及的代码 diff
- 关联的规格文档摘要
- 已知的边界条件与异常场景
- 测试覆盖要求
- 非功能指标约束
- 开发者自查记录
这个设计的核心思路是：评审不是“看代码写得好不好”，而是“代码有没有兑现规格”。把规格文件作为输入的一部分，模型的评审基准就从“凭经验挑刺”变成“按契约核对”。S4 输出的评审意见也做了分类，分为阻塞性问题、建议性问题、风格问题三级，只有第一类会阻断合并流程。
S8（回归看门狗）是最后落地的技能，也是我认为最值得投入的一个。它的职责不是找 bug，而是做风险闸门。回归阶段会生成大量测试报告，人工全部看一遍既不现实也无必要，但一个包含风险清单的自动化总结，能显著节省决策时间。
我的做法是：S8 接收三份输入——测试报告、S5 生成的用例覆盖矩阵、S6 生成的影响面分析，然后按优先级输出一份风险清单。这里的关键是“结论先行”：S8 的输出必须是能够直接指导行动的内容，比如“模块 A 的导出功能存在高概率回归风险，建议阻塞发布，理由如下”。它输出的内容不是信息堆砌，而是经过裁量的决策辅助。运行一两周后我又给它加了一条输出约束：每条风险必须标注置信度，低置信度条目单独归类，避免干扰核心决策。
2.3 S6：迁移影响分析的特殊价值
S6（迁移影响分析器）是所有 8 个技能里唯一一个直接和代码库静态结构打交道的。其他技能处理的是“说清楚”和“写清楚”，它处理的是“查清楚”——某个改动到底会牵连哪些模块。
最开始我们测试过让模型直接通读整个代码库来分析影响面，效果非常差，原因很简单：模型注意力是有限的，代码库超过几万行之后，它就会“前读后忘”。后来我调整了策略，把 S6 的输入改成一个结构化的“模块调用图谱”，这个图谱是由脚本预先从代码库里扫描生成的，只保留模块依赖信息，过滤掉具体实现逻辑，体积小、路径清晰、模型不需要真正阅读理解全部代码。
S6 的工作方式从“读代码找影响”变成“看图找路径”，准确率提升非常明显。操作方法大致是：
- 用扫描脚本提取模块间调用关系
- 按被改动模块在图中做深度优先搜索
- 将触及到的路径聚合为影响面报告
- 报告中明确标注直接受影响和间接受影响的模块
这个案例体现了一个重要的方法论倾向：不应该让模型去做那些“确定性工具能做得更好”的事情。扫描调用关系，脚本一秒钟能完成，而且百分百准确；模型花大半天读完代码还不一定记得全。S6 真正发挥价值的地方在“判断影响的性质”，是判断这个依赖是硬依赖还是可剥离、这个调用路径是否被测试覆盖，而不是做信息收集。
3. 实操过程与核心环节实现
这一节把前面讲的工具链和技能落到地上，给出可以照抄的配置过程和注意事项。我会按目录结构、技能包配置、主从调用机制三个层面展开。
3.1 技能包目录结构与配置要点
Superpowers 里的技能是以“技能包”为单位组织的。我们维护的仓库结构大致如下：
skills/ role/ requirement-clarifier/ SKILL.md assets/ (示例对话库) spec-writer/ SKILL.md templates/ code-reviewer/ SKILL.md rules/ workflow/ delivery-pipeline/ WORKFLOW.md steps/每个技能目录下至少包含一个 SKILL.md，这是技能的主文件，负责定义技能的核心能力、触发条件、执行步骤和输出格式。我强烈建议在 SKILL.md 里写清楚三件事：这个技能的边界在哪里、输入长什么样、输出必须符合什么格式。边界是防止技能越权最有效的工具，比如 S4 只做评审、不做修改；S5 只生成用例，不执行测试。
配置技能包有几个容易忽略的坑。第一个坑是运行时依赖不声明。Superpowers 支持技能间互调，但如果被调用的技能没有被明确声明为依赖，执行到一半会失败。所以我在每个 SKILL.md 里加了一个 dependencies 区块，列出所依赖的其他技能，不声明的直接拒绝执行，很大程度上避免运行时挑错。第二个坑是上下文过渡缺失。技能 A 的最终输出不一定是技能 B 的理想输入，中间需要格式适配。这里的经验是显式定义一个“公共数据模型”，所有技能的输出都往这个公共数据模型上靠，而不是任其自由发挥。
3.2 主从技能调用链路的一个参考配置
在 8 个技能全部跑通之后，我把这套流水线固化成一个工作流定义文件。下面给出一个精简版的示意，方便你理解主从调用的组织方式。生产环境中字段信息比这个多，这里只保留关键框架：
name: delivery-pipeline version: 1.0.0 trigger: pull_request.opened steps: - skill: S2 input: pr.description output: spec_draft - skill: S3 input: spec_draft output: work_order - skill: S5 input: spec_draft output: test_matrix - skill: S6 input: [work_order, repo_graph] output: impact_report - skill: S4 input: [work_order, diff, spec_draft, impact_report] output: review_verdict - skill: S8 input: [test_matrix, impact_report, ci_report] output: risk_gate - check: review_verdict.blocker_count == 0 action: approve_pull_request - check: risk_gate.high_risk_count > 0 action: block_release这个配置的价值在于它把每一个环节的输入输出关系显式化。整体逻辑是“需求进来 → 规格生成 → 拆单 → 针对规格设计测试 → 分析影响面 → 按单评审 → 回归风险闸门”。最核心的监督点是交付链路末尾的四个依赖判断——它把“人拍板”变成了“数据驱动拍板”。
配置 8 个技能串联跑通之后，瓶颈会从“技能本身的效果”转移到“技能之间的衔接”。衔接做得好不好，看两个指标：上下文传递的完整率，以及每次调用时的重复澄清次数。理想状态下，上一个技能的产物被下一个技能使用时，不应该要求用户重新回答一遍需求细节。如果你发现用户在流水线跑完以后还要反复补充说明，说明中间某个技能的输出格式不达标准。
3.3 落地时我用过的一套调试流程
一口气配置 8 个技能并期望一次跑通，是不现实的。我的习惯是分四步调试，每一层解决了再往上加。
第一步是单技能测试：把每个技能独立抽出来，用一组固定的测试输入验证它的输出是否符合预期。这个阶段只调单个技能，不涉及协作。第二步是两两串联测试：先连 S1→S2，再连 S2→S3，逐个把上下游关系打通。这个阶段最容易发现问题，因为上下游技能经常因为术语不统一或者上下文格式不匹配导致执行失败。第三步是链路跑通测试：全流程串跑，但只用一个模拟需求，重点关注有没有漏传信息、有没有卡死循环。第四步是用真实项目数据做灰度验证：拿最近一次历史需求当测试样本，把整条流水线跑一遍，对比输出结果和人工处理的差距。
我非常推荐每步都把错误日志保留下来。调试技能之间的衔接问题时，错误信息远比想象中有用。例如，“技能 B 期望输入张三字段，技能 A 输出的是李四字段”这类报错，一时间看起来是格式问题，拉开日志却能顺藤摸瓜定位到某个模板里字段命名不一致的老毛病。
4. 常见问题与排查技巧实录
这一段把实际踩过的坑挑最典型的列出来，附带排查思路和最终解法，按照速查的形式整理。方便你遇到相似问题时直接对照定位。
4.1 规格文档“自说自话”问题
现象是 S2 生成出来的规格文档结构工整、语言通顺，但内容跟原始需求脱节，甚至出现原始需求中根本没有的假设前提。例如需求只说“导出报告可以选时间范围”，文档里却不合理地写“支持自定义时间粒度到秒级”。
排查后我发现根因是 S2 在补全检查清单时“脑补过度”。它为了满足“完整性”而主动添加了它认为合理的细节。我们的解决办法是双管齐下：一方面在规格文档里单独开设一个“假设与待确认项”区块，凡是模型不确定的内容必须写进这个区块而不是正文；另一方面在输出约束里明确写“未经验证的信息不得进入主要章节”。这样既保留信息完整性的意图，又将未经验证的内容与正式契约做隔离。
这个坑的频率最高，几乎每次调整 S2 模板后都会复现。建议在技能设计中专门加一个“幻觉自检”的步骤，“幻觉自检”就是让模型输出前自己审查一遍：我写的这些验收标准，在上文里有明确依据吗？没有依据的部分，单独归类。
4.2 技能间职责重叠导致“多头管理”
S4（代码评审）和 S8（回归看门狗）在最初版本里有功能重叠，两个技能都会输出“风险提示”。代码评审阶段出现疑似风险，回归阶段又复述一遍同样的内容，造成资源浪费，严重时甚至给出相互矛盾的结论。
解决方式是明确划分职责边界：S4 只处理“代码自身的风险”，关注代码逻辑实现层面的加减项；S8 只处理“变更引入的系统性风险”，关注测试覆盖与影响面的交叉分析。两条线各自独立输出，后台合并展示时保留各自的分类标签，不允许跨级结论覆盖。
这让我想明白一件事：技能规划时一定要画好“职责边界矩阵”，否则技能越多、协同越混乱。每一个功能点都必须有且仅有一个“负责人”。如果两个技能都会管同一件事，那不是留了兜底，而是埋了冲突。
4.3 规格文档膨胀与“文档负债”
项目跑到第二个月，单是规格文档总量就已经超过了代码量，S2 每次生成新文档时还会参考旧文档，旧的过时信息被不断复制到新文档里，“文档负债”越来越重。
我们最后推行了一套“规范保洁”机制。具体动作有三个：第一，每个规格文档必须带有效期，超过有效期默认失效；第二，每周定期扫描归档所有引用次数为零的文档；第三，新文档引用旧文档时，不允许原文复制，必须转述并用链接指向原文件。第三条的效果立竿见影，切断了过时信息的传播链。
这个坑想特别提醒：技能工程里，文档不是资产本身，文档带来的“一致性”才是资产。一堆过时的、互相矛盾的文档比没有文档更危险，因为它会误导所有下游技能的错误决策方向。
4.4 多人协作时的版本漂移
团队所有人用同一套技能包，但不同人改了不同版本后，技能行为开始分叉。同样一段需求，在 A 的机器上跑出的规范文档和 B 的不一致，字段顺序、默认值、验收标准写法都不同。
解决路径是“集中式版本管理 + 变更记录强制化”。技能包仓库只允许在主干分支上修改，任何改动必须附带变更记录，说明“改了什么、为什么改、影响哪些技能”。这个机制跟 OpenSpec 的变更管理思路完全一致，只不过把对象从“规格文档”扩展到了“技能包本身”。技能是一等公民，它跟代码一样需要版本控制、需要评审、需要变更记录。
这条经验，是我认为这套方法论里最不应该跳过的一环。如果你打算长期维护多个技能，就把技能当作代码一样认真对待。
5. 沉淀下来的工程方法论
说完具体案例和问题，最后聊一聊我真正沉淀下来的方法论。这些思考不完全依赖某一个工具或框架，即便你换成别的技能定义体系，大概率依然适用。
5.1 文档先行不是“先写文档”，而是“先立验收标尺”
很多团队一提“文档先行”就会走向两个极端：要么文档写了没人看，沦为摆设；要么文档绑架了进度，陷入无止境的评审。我自己的体会是，文档先行真正的价值不在于“先产出文档”，而在于“先把验收标准定下来”。
以 S2 为例，这张规格文档写得好不好，不是看它是否条目清晰、排版美观，而是看它能否回答三个问题：做完了怎么算好？没做到会有什么后果？边界在哪里？如果文档生成完，这三个问题都能从中找到明确依据，后续代码评审、测试设计、回归巡检都能自动对齐；反之，文档再规整也是自我感动。
这也是我开始理解 Spec Kit 那一整套模板设计的底层逻辑：它所有字段都是在逼你“先交作业再开工”，先把验收标尺立起来再谈实现。我后来在所有技能里都贯彻了这个思想，凡是输出里有“验收标准”的环节，优先保证它的质量。
5.2 最小闭环优先，再谈规模和效率
另一个重要的心得是：不要一上来就想做全流程。我最初尝试一次性接入 8 个技能，结果是一周都在折腾框架和配置文档，业务价值为零。后来推倒重来，只保留 S1 和 S2 两个技能跑最小闭环，等这块稳定了再加 S5、S4，最后才上 S6 和 S8。
整个过程到目前为止最受影响的是 S6，它一开始根本跑不动，我花了不少时间才意识到问题出在破坏整个调用链的输入格式上。如果当初坚持全流程一步到位，大概率连问题在哪都定位不到。孵化技能的正确节奏是：先单点突破，再连成链路，最后做成系统。
“最小闭环优先”还带来一个额外的好处：闭环里的每个环节都可以量化评估。S1 的准确率、S2 的一次通过率、S4 的阻塞项命中率，都是可测的。数据出来之后，你可以明确知道下一步优化改哪个环节最有效，而不是凭感觉猜。
5.3 技能能力越收敛，系统能力越强大
最后一个也是我很想强调的方法论。现在的技能包里，每一个技能的能力边界都定义得很收敛，这让整个系统的行为变得可预测。往回看最初的经验不足的阶段，S4 特别容易“抢戏”，让它评审代码，它不仅挑逻辑问题，还会顺带给出重构建议、性能优化甚至新需求提醒。这听起来很智能，实际上很危险，这些越权输出会污染下游的判断。
所以说到底，技能工程的核心不是“让模型变得更聪明”，而是“让模型的输出变得更可控”。Spec Kit、OpenSpec、Superpowers 这三个工具，本质上都是从不同层面做“约束”：Spec Kit 约束需求表达的完整性，OpenSpec 约束文档结构的统一性，Superpowers 约束技能运行的组织性。三层约束叠起来，再加上 8 个技能各自的输入输出约束，最终这套流水线的行为是可以被预先判断的。
这一点，我认为是被很多人低估的工程价值。大模型本身确实强，但如果你把它当泼墨画来用，每个环节出来的墨迹都不确定方向；只有给它装上足够的滤网和轨道，它才能从“才华型选手”变成“靠谱型同事”。
我个人在实操中最大的体会是，方法论从来不是一次成型，而是被一个个问题逼出来的。从最开始被自说自话的规格文档逼着加补全检查清单，到被技能间职责重叠逼着画边界矩阵，再到现在把这些经验固化进标准流程，整个过程没有一步是凭空设计得来的。如果你也正在做类似的事情，我唯一的建议就是：不用一上来就追求完全体，选定两个最痛的环节先切入，让方法在解决真实问题的过程中自己长出来。
