8 个 SKILL 的设计逻辑

上一篇我提到,那些用真实事故换来的防线,最终沉淀为了 8 个具体的 SKILL。这篇我就来解释这8个技能怎么用。

在拆解前,必须对齐一个认知底座:工具围绕 项目规格化文档(ProjectSpec) 服务,因为它才是这套体系的一等公民。它不仅仅是给人看的文档资产,更是给 AI 读的机器契约——项目、模块、功能三层结构泾渭分明,每条硬约束都有编号,能被精准定位与检查。

为什么最终落地的形态是 8 个 SKILL,而不是其它形态?因为这8个SKILL,覆盖了从设计到开发再到评审的所有环节,我希望使用的时候能够目的明确的做出选择,而不是一堆技能列表。

这 8 个动作为什么长成现在这个形状?它们的底层逻辑全在这里。

一、议题链:管住讨论与落盘的边界

人驱动 AI 最自然的方式是聊天,但聊天极易发散。如果第一步就让 AI 直接修改文档,代码和文档很快就会面目全非。议题链的 4 个 SKILL,专门用于约束“从讨论到落盘”的失控。

  • spec-start:解决“AI 对话易发散、无头绪”的问题。判断:议程是锚点。没有一份能逐条结清的待决议清单,就无法判定讨论是否真正结束,后续也无从追踪。

  • spec-pause:解决“上下文不足或下次再继续讨论”的问题。判断:保存进展不等于修改设计。它负责中途记录详实的会话纪要,在决议正式落定前,绝不触碰任何项目文档。这里需要说明,这个技能很少被使用,只有在需要跨AI会话讨论时才需要。

  • spec-close:解决“从会议讨论到形成文档”的问题。判断:会议结束不是“聊完了”,而是把决议准确放进它该在的ProjectSpec里。写错层的决议比没写更致命,因为它看起来像权威。

  • spec-archive:解决“异常中断留下脏数据”的残局。判断:兜底工具的权限必须比正常路径更小。它只做状态搬迁,绝不越权执行删除或修改文件的危险操作。

这四个 SKILL 守的是第二篇中的核心方法论:分层解决契约在哪。它们确保了每一个动作都知道自己该写哪些事、绝不能写哪些事。但是真正常用的只有spec-start和spec-close。

二、交付链:防范设计与实现的分叉

设计从来都不是完美的,开发中途必然会遇到需要调整的地方。如果一味要求按设计开发,错误就会被固化;如果允许 AI 随意改,代码和文档必然分叉。交付链的 4 个 SKILL,就是在这两者之间开的一道受控的口子。

  • spec-dev-loop:解决“AI 拿到需求直接瞎写且自我证伪”的问题。判断:先冻结代码骨架,再派发具体实现。主代理掌握全局负责验收,绝不盲信子代理“我做完了”的单方面自述。这个技能可能是所有8个SKILL中最复杂的,它会首先启动设计评估流程,如果它觉得设计有冲突或描述不清晰的地方,会向用户提问,并将它们记录到开发日志中。正式进入开发阶段,它会检查本地仓库的分支状态,然后新开一个以dev-loop/为前缀的分支,所有修改都会在这个分支中进行。直到主代理完成验收提交修改,然后它会通知用户审查并要求用户手动合并分支。

  • spec-code-review:解决“开发环节修改设计导致文档过期”的问题。判断:代码评审不是给代码打分,而是把不一致的证据摆到人面前。让“改代码还是改文档”的最终裁决,发生在正确的位置。它也是从代码反向同步文档的唯一出口。

  • spec-code-smell:解决“代码质量”的问题。判断:代码评审只解决设计与实现是否一致的问题,而“坏味道”则是编码质量的天敌。

  • spec-smart-git:解决“一把梭提交导致无法单独回滚”的问题。判断:提交粒度就是未来的可回滚粒度。必须按逻辑意图切分,绝不能按“这次干了多少活”切分。

这四个 SKILL 守的是第二篇的另一半核心:约束必须可执行。它们把“AI 宣称它做对了”转换成了“提供一份可被机械复核的证据”。

三、诚实的边界

这 8 个 SKILL 不是为了凑齐一个“研发全流程”的全家桶,而是专门针对各环节设计的防线。清楚它们能干什么,更要清楚它们不解决什么:

  1. 不替代人工判断:哪些约定算硬约束、两个架构方案选哪个,依然靠人。SKILL 只保证定下的事不被绕过,不保证你想得足够周全,所以我们拒绝在技能中添加一键执行。

  2. 不保证设计本身正确:它只能让偏离和错误更早暴露,但改错仍然需要人来拍板(这也是 code-review 必须由人裁决的原因)。

  3. 不过渡干涉发布流程:通常不同的技术团队有自己的CI/CD规范,技能包应该尽量不碰这些内部流程。让它们可以独立运行是必要的。

四、30 分钟跑通第一个 Loop

看到这里,我依然不建议你立刻去啃冗长的文档说明。最快的上手方式,是花 30 分钟跑通第一个最小 Loop。

初始化项目并装载技能后,开一个议题,聊一个小决策,保存一次,再关闭一次。在这个极简的流转中,你会亲眼看到议程如何被确认、讨论如何被封存、决议最终如何被精准写进某一层文档。这个 Loop 的目的不是让你穷尽所有功能,而是确认这套思维方式能否与你的真实项目咬合。

完整 8 个 SKILL 的能力包与 GitHub 地址已正式开源发布: https://github.com/13813385093/dockit.git

仓库根目录下的 readme,就是第二篇提到的“方法论的完整落地版”。

至此,这套软件开发能力包的介绍已经完结——它只管“单个功能如何被忠诚实现”。但当我们把视线拉高,能力包是让1个 Agent 运行符合预期,但是如何让 10 个 Agent 并行工作,问题就换了一个层面:谁有权和谁通信?上下文如何管理?如何给不同的Agent定义功能职责?同一个任务是否可以让Agent:A和Agent:B一起执行?你的账单如何不失控?

下一篇,我想要和你聊聊能力包之外的故事。

posted @ 2026-11-18 21:31  冷豪  阅读(0)  评论(0)    收藏  举报