从需求到上线，27 个 skills 每站给 AI 编码钉一道闸

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划 第 212 篇，AI 编程最佳实战「2026」系列第 74 篇

大家好，欢迎来到 术哥无界 | ShugeX ｜ 运维有术。

我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！

Talk is cheap, let's explore。无界探索，有术而行。

封面：想法到上线的轨道上立着三道闸机，最近的一道挂着「退出条件」的牌子

图 1：每站一道闸，每个研发环节都被钉死一个退出条件

用 Claude Code 或 Codex 写过一阵子真实项目的人，多半体会过这种失控感：需求说了三句，agent 交付了一堆你没要的东西；它把二十个词才能说清的事翻来覆去讲；代码看起来能跑，测试一跑全红；三个月后回头一看，仓库已经搅成一团泥球。

Matt Pocock（Total TypeScript 的作者）开源了一套 agent skills，仓库定位语写得很直白：做真正的工程，不做氛围编程（real engineering, not vibe coding）。我把 27 份 SKILL.md 翻完之后，觉得这套东西最值得说的只有一个点：它给研发流程里的每个环节都钉死了一个退出条件。

agent 失控的病根不是模型笨，是流程没有边界。没人告诉过它澄清到什么程度算澄清完，也没人说过修 bug 从哪一刻起才准开始猜。

1. AI 写代码的四种死法

README 把 agent 编码的失败模式归成四类，每一类都引了一句软件工程经典。

第一种，对齐失败。 你以为它懂了，交付物证明它完全没懂。《程序员修炼之道》里那句 没有人确切知道自己想要什么 说的就是这事。解法是让 agent 反过来盘问你，这套仓库里对应 grill-me 和 grill-with-docs 两个盘问技能，README 称它们是全仓库最受欢迎的技能。

第二种，啰嗦。 agent 被空投进项目，边干边猜你的黑话，于是用二十个词说一个词的事。《领域驱动设计》的作者 Evans 给的药方是统一语言：README 里那个例子很典型，一句啰嗦的 课程里某一节的内容变成真实文件 可以压缩成 物化级联（materialization cascade）一个词。共享词汇落在 GLOSSARY.md 里，一次沉淀，每个会话都受益。

第三种，代码不工作。 对齐了也白搭，agent 没有反馈回路就是在盲飞。反馈的速度就是你的速度上限，这是《程序员修炼之道》的又一句。解法是静态类型、自动化测试加红绿循环，对应 tdd 和 diagnosing-bugs。

第四种，泥球。 agent 加速写代码的同时也在加速软件熵增。Kent Beck 说要每天投资系统设计，Ousterhout 说好模块是深的：大量行为藏在很小的接口后面。这套仓库把设计关心内建进了每一层。

四种死法，四种药。药方背后那个共同的骨架，才是这套仓库真正的产品。

2. 全景：一条主线，三个汇入口

整个体系的路由文件是 ask-matt，它把 27 个 skill 组织成一张分层地图：

• 一条主线：idea 到 ship，需求从模糊想法一路走到上线
• 三个汇入口：triage 接外部工单、diagnosing-bugs 接硬 bug、wayfinder 接大雾型需求，三条支路最终都并回主线
• 一条还债通道：improve-codebase-architecture 空闲时扫代码库找改进机会
• 一层词汇垫底：domain-modeling 和 codebase-design 定义了全套流程共享的设计用语

汇流全景：工单分诊、修锅、大雾找路三条支流汇入同一条主线通向上线，主线下方一条虚线还债通道绕回

图 2：一条主线，三个汇入口

地图看着不小，但真正的主线只有八个活动。下面逐个过。

3. 需求线：八个活动，各自什么时候算完

先上总表，再说细节。

登山路线：想法出发的之字形山路上八个营地，澄清分支设计三站旗已插上，拆票编码评审交付复盘五站旗杆空着

图 3：需求线八个活动，每站插旗才算完

几个活动值得展开。

澄清是整套体系的入口，机制是一棵设计树：每个决策分叉出挂在它下面的子决策，每一轮只问 frontier，也就是所有前置决策已落定、现在就能问的问题。整批编号提问，每题附 agent 的推荐答案。分工是铁律：查事实是 agent 的活，派个子代理去翻；拍板决定是你的活，它等着。退出条件写得斩钉截铁：frontier 为空、没有分支被默默假设，并且你确认了共识，否则不许动手。

两个分支判断发生在澄清之后。问题在纸面上谈不清（状态机走得对不对、UI 长什么样）？handoff 出去写一次性原型找答案，结论折回主线，原型本身留档。一个会话装不下整个需求？wayfinder 把大雾画成一张决策票地图，一次解决一张票，只产决策不产交付，雾散后合流回 to-spec。

方案设计的态度是克制：不重新访谈，只综合已经聊过的内容。但有一个强制动作，先画出测试要落位的 seam（接缝）并和你确认，seam 越少越好，理想是一个。spec 的非目标一节明确写出不做什么，发布时直接打 ready-for-agent 标签，跳过分诊。

任务拆解切成曳光弹式的竖切片：每张票窄但完整地穿过所有层，做完就能演示，且必须装得进一个全新的上下文窗口。宽重构是例外，走扩展再收缩的三段式，先让新旧并存，分批迁移，最后删旧。

编码这一环反而最朴素。implement 的全部内容就几行：取票、在约定 seam 上驱动 tdd、常跑类型检查和单测、收尾跑 code-review、提交。一票一个新会话，上下文干净。红绿循环之外，重构被明确排除在循环外，归评审阶段管。需求够大就换 implement-spec：把票当任务图，多个子代理各自开 worktree 并行干活。

评审跑两个并行子代理，一个查标准轴（符合仓库编码规范吗，外带 12 条 Fowler 坏味道基线），一个查需求轴（忠实实现了 spec 吗）。两轴分开出报告，不合并不排序，因为完全可能出现代码规范全对但做错了东西的情况。

交付的 PR 只有三节：最小可视摘要（伪代码、调用树或文件树，哪个小用哪个）、前后证据（截图是 S 级，测试输出是 A 级）、合并风险（单向门还是双向门，影响面一个词）。

复盘是整个循环的闭环，方向很特别：改环境，不改代码。导航指针、自动检查、编码规范、工具开销，七个类别挨个过一遍。机械性错误变成确定性检查，判断类问题变成编码规范，下一次构建从一个更好的环境起步。

你现在的 agent 工作流里，哪一步是没写退出条件的？可以对着这张表挨个问一遍。

4. bug 线：先造一条会变红的回路

需求线之外，另一条线处理坏掉的东西。

外部报告先进 triage：两类目（bug 还是增强）加五状态的角色状态机，把杂乱进件加工成 agent 能直接接手的 brief。两个细节见性格：AI 在 triage 里发出的每条评论必须带免责声明，声明这是 AI 生成的；外部 PR 被当作带代码的 issue 走同一套机器。

调试回路：面包板上一条闭合回路红灯亮起，旁边四张验收徽章，右下角一张画着叉的旧卡片写着上来就猜

图 4：先造一条对本 bug 变红的回路，再谈假设

真正的纪律核心在 diagnosing-bugs。它的第一阶段只有一件事：造出一条对这个 bug 变红的反馈回路。原文的说法是，这一步就是这个技能本身，其余全是体力活。造法按序排了十种，从失败测试、curl 脚本，到重放捕获的请求、属性模糊测试、供 git bisect 用的自动化脚本。

回路的验收标准相当苛刻：你能报出一条命令，它已经跑过至少一次，能在几秒内复现用户的原始症状，而且不需要人盯着。没造出来之前禁止提出任何假设。你抓过自己还没造回路就开始读代码猜原因吗？这条红线拦的就是那个动作。

修完之后同会话跑 retro 找根因。如果发现代码里没有合适的 seam 能用回归测试锁住这个 bug，这本身就是发现：架构在阻止你把它钉死，转还债通道 improve-codebase-architecture。

5. 上手三步

安装比看起来简单：

1. 装技能包。Claude Code 用户一条 claude plugin install 命令；其他 agent 用 npx skills add mattpocock/skills，选择技能时记得带上 setup-matt-pocock-skills
2. 每个仓库跑一次 /setup-matt-pocock-skills，配置三件事：issue tracker 用哪家、triage 标签怎么映射、文档放哪
3. 开始用。人打命令触发的 user-invoked 技能管编排（比如 /to-spec），agent 自己会取用的 model-invoked 技能管纪律（比如 tdd），一个编排一个纪律，不互相越界

6. 这是一个系列的第一篇

往后还有 14 篇。理论轨 7 篇讲机制，下一篇聊需求越小链越短的减配阶梯（不是所有活都配走全链）；实战轨 8 篇在一个叫 Shorty 的短链服务仓库上做真机会话实录，八条套路各对应一篇。

本篇对应的实战：S1 到 S8 全部，它是全系列的地基。

说到底，这套技能治的从来不是模型能力，是流程边界。27 个文件翻下来，真正被反复写的就是同一句话：这一步做到什么程度，才算做完。

相关资源

GitHub 仓库：https://github.com/mattpocock/skills