ARTICLE · 1138143
他用了二十年,把软件工程纪律翻译成了 AI 的母语
GitHub 上有一个 69,000 星的仓库，1230 万安装量，却连一行可执行代码都没有。
它只装了一堆 Markdown 文件——每个不到 100 行，加起来也就几千字。但用了它之后，AI 写的代码突然不那么"AI 味"了：它会先问你"你想做什么"，会在写测试前确认接缝在哪，会在 debug 时拒绝猜测。
这个仓库叫 mattpocock/skills，作者是 Matt Pocock。TypeScript 社区最知名的教育者之一，Total TypeScript 创始人，YouTube 订阅 19 万。
这篇文章不介绍"怎么用"，而是讲一个更底层的问题：他到底把哪些工程纪律，用哪种方式，翻译成了 AI 能执行的语言？以及为什么这套翻译，正在被百万开发者当成"AI 编程的基本功"。
一、一个反直觉的现象：为什么 AI 写了那么多"对但没用"的代码
用 AI 编程的人大概都经历过这种挫败感：
"我明明说了要一个用户登录模块，AI 给了我一个带 JWT refresh token 的 OAuth 2.0 完整方案，用了六张表，写了三万行代码。"
"我问 AI 为什么这个 bug 没修好，它给我解释了一个两小时长的理论。它没有去复现它。"
"三个月后回看，代码库已经变成了谁也看不懂的一团泥球。"
这不是 AI 不够聪明，而是它太急了。它把所有已知能力一股脑堆上去，把"写代码"等同于"解决问题"，把"代码跑通"等同于"需求实现"。
Matt Pocock 在仓库 README 里开宗明义：
软件开发中最常见的失败模式是对齐失败（misalignment）。你以为自己说清楚了，AI 也以为自己理解了，结果交付的东西和预期完全不是一回事。
——这是 AI 时代最普遍的工程问题，不是 AI 特有的。
这句话是关键。AI 没有创造新的失败模式，它只是把旧的模式放大了一百倍。需求没对齐、反馈循环断裂、代码熵增——这些是《程序员修炼之道》和《领域驱动设计》二十年前就写过的话。AI 时代的版本，只是把"人"换成了"agent"。
Matt 做的，就是把这套四十年的软件工程纪律，压缩成 28 个可执行的 Markdown 文件，让 AI 在动手之前先走一遍。
二、四条理论红线：他实际在约束 AI 什么
这个技能包的核心不是"很多技能"，而是四条贯穿始终的理论红线。理解了这四条，整个体系就通了。
红线一：事实与决策分离
这是整个体系最重要的设计决策，出现在 grilling（盘问）技能里，几乎是逐字写的：
"Finding facts is your job, never the user's.
When a frontier question needs a fact from the environment,
dispatch a sub-agent to find it.
The decisions are the user's: put each to them and wait."翻译成工程语言：查资料是 AI 的事，做决定是人的事。AI 去读文件、查 API、翻文档；但"该做哪个方案"、"seam 放哪里"、"这个重构值不值得"——这些决策权始终在人。
这条红线防止了两类失败：AI 替你做了你没要求它做的决策（自作主张），以及 AI 让你查了它自己能查到的东西（浪费你的时间）。
红线二：反馈循环先于假设
这是 diagnosing-bugs（诊断 bug）技能的第一原理。技能包里写得很强硬：
"如果你发现自己在看代码建理论而循环还没存在，停下：跳跃到假设是这个技能要防止的精确失败模式。没有变红的命令，不进入第二阶段。"
什么意思？调试一个 bug 之前，你必须先有一个能对这个 bug 变红的命令——一个失败测试、一个 curl 脚本、一个最小化复现脚本。没有它，所有的"我觉得原因是……"都是猜。
这个原则来自科学方法论里的"可证伪性"，但被 Matt 写进了一个 AI 可以直接执行的指令里。AI 现在被要求：没有红的能力，不许建理论。
红线三：深模块先于泥球
codebase-design 技能定义了一套词汇——这是从 John Ousterhout 的《软件设计哲学》里提取的，但被严格化了：
为什么禁止用 "component"、"service"？因为在 AI 时代，词汇漂移是代码库变成泥球的第一因。同一个概念在不同模块叫不同名字，AI 的导航能力直接归零。Matt 把"统一语言"（Ubiquitous Language，DDD 的核心概念）直接映射到 GLOSSARY.md 文件里，要求 AI 在每次操作前读取它。
这不是在"规定命名规范"，而是在定义 AI 的认知坐标系。
红线四：阶段边界——何时清空上下文
ask-matt（路由器技能）定义了一个"smart zone"概念：模型在大约 150K token 的窗口内推理仍然锋利。一旦接近这个边界，不要在退化的状态下继续。
阶段边界处有五个选项：
这个设计在 agent 时代是前所未有的。传统软件工程谈"什么时候重构"，agent 时代谈"什么时候清窗口"——上下文窗口本身成了工程资源。
三、架构：两层调用模型如何避免"技能爆炸"
28 个技能听起来很多，但整个体系的复杂度被一个架构决策压住了：调用方向被锁死。
User-Invoked（用户键入才触发，编排层）
├── ask-matt ← 路由器：不知道用哪个？先问它
├── grill-me ← 无状态盘问
├── grill-with-docs ← 有状态盘问 + 域建模
├── triage ← issue 状态机
├── implement ← 按 spec/tickets 实现
├── wayfinder ← 超大项目规划
├── retro ← 回顾
├── handoff ← 会话交接
│
│ 规则：user-invoked 可以调用 model-invoked，
│ 但永远不能调用另一个 user-invoked
│
└── ▼ 只能向下调用 ↓
Model-Invoked（模型自动触发，纪律层）
├── tdd ← red-green-refactor
├── code-review ← 双轴并行子代理
├── diagnosing-bugs ← 六阶段诊断
├── grilling ← 底层盘问原语
├── domain-modeling ← 域模型维护
├── codebase-design ← 深模块词汇
└── research ← 后台子代理研究这个分层解决了一个实际问题：什么时候 AI 应该自动做，什么时候必须人来触发？
用户主动触发的（user-invoked）是"我要开始一个流程"，AI 必须等你的指令。模型自动触发的（model-invoked）是"这件事符合触发条件"，AI 发现场景匹配就调用。
两层之间有严格的调用方向：编排层可以调用纪律层，但纪律层永远不知道其他纪律层的存在。这就是为什么 grilling 被 5 个技能调用，但 grilling 自己从不主动调用其他技能——它是原语，不是流程。
四、五个核心技能，逐个拆开看
4.1 grilling：设计树 + 前沿机制
这是整个体系的核心原语，被 grill-me、grill-with-docs、triage、wayfinder、improve-codebase-architecture 五个技能内部调用。
机制是这样的：
把设计问题映射为一棵决策树——每个决策是树的一个节点，每个节点依赖于它的前置决策 每轮只问"当前前沿"上的问题——即前置依赖已确定的决策 每个问题附推荐答案（降低用户负担，但不是替你决定） 事实由 AI 派子代理去查，不阻塞其他前沿问题 直到前沿为空（所有分支都走过）才结束
"The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding."
grilling/SKILL.md
"Nothing left silently assumed"——没有遗留任何静默假设。这一句是整条链路的验收标准。
4.2 tdd：seam 确认 + 三大反模式识别特征
传统的 TDD 技能包通常只写"红绿重构"四个字。Matt 的版本多了一个关键步骤：在写第一个测试之前，先确认 seam（接缝）的位置。
## Seams: where tests go
A seam is the public boundary you test at.
Tests live at seams, never against internals.
Test only at pre-agreed seams.
Before writing any test, write down the seams under test
and confirm them with the user.
No test is written at an unconfirmed seam.为什么这一步这么重要？因为测试设计本身就是一个设计决策。如果你先写了一堆测试，这些测试隐含的接缝选择就成了既成事实，后面的代码设计被测试结构绑架了。
此外，每个反模式都有"识别特征"（tell），不是教科书定义，是从真实 debug 中提炼的判据：
4.3 code-review：双轴并行，防止一轴掩盖另一轴
这是技术含量最高的一个技能。核心设计：Standards 和 Spec 两个轴，由两个并行子代理独立审查，结果不合并、不重排。
"A change can pass one axis and fail the other: code that follows every standard but implements the wrong thing → Standards pass, Spec fail. Code that does exactly what the issue asked but breaks the project's conventions → Spec pass, Standards fail. Reporting them separately stops one axis from masking the other."
code-review/SKILL.md
在 AI agent 时代，这个设计特别重要。Agent 可能完美遵循仓库的编码规范，但做错了事；或者做对了事，但破坏了项目约定。两个轴分开报告，就是防止"看起来都对，合在一起全错"。
Standards 轴还携带了一个 Fowler 坏味道基线（12 条），每条有"是什么→怎么修"的精确判据，且明确标注"仓库规范优先于基线"——即基线是默认值，项目自己的规范可以覆盖它。
4.4 diagnosing-bugs：六阶段，最硬的技能
这是整个技能包里最重型的一个（约 100 行），也是最体现工程纪律的：
第六阶段的最后一个要求——"正确的假设记录在 commit 消息里，让下一个调试者学到"——这是一个很成熟的工程习惯，被写进了 AI 的指令里。
4.5 wayfinder：迷雾规划，反直觉但正确
这是整个技能包里最"反项目管理"的一个：刻意不完整的规划。
传统项目管理要求 WBS（工作分解结构）尽可能完整。Wayfinder 恰恰相反——它维护一张"地图"（单个 issue），里面有一个叫 "Not yet specified"（迷雾）的章节，专门放"还没看清、无法 ticket 化"的部分。
## Fog of war
The map is deliberately incomplete:
don't chart what you can't yet see.
Beyond the live tickets lies the "fog of war":
the dim view of decisions you can tell are coming
but can't yet pin down.
Resolving a ticket clears the fog ahead of it,
graduating whatever's now specifiable
into fresh tickets, one at a time.判据非常精确："工单 vs 迷雾"的测试是你能否此刻精确陈述问题，而不是你能否此刻回答它。能陈述→工单，不能→迷雾。
这在 agent 时代是正确的，因为迷雾在工单解决后才清晰。硬要提前 ticket 化，浪费 token 和认知。"Wayfinding is about finding the way, not charging at the destination"——是找路，不是冲向目的地。
五、它为什么受欢迎：五个具体原因
69K Stars、12.3M 安装量、单技能最高 706K 安装（grill-me）。这个数字背后有五个原因，按重要性排序：
1. 抓住了根本矛盾，不是"更多技能"
市面上的 AI 编程工具（Devin、Cursor Agent、GSD/BMAD/Spec-Kit）都在解决"让 AI 更自动"。Matt 做的是反方向：让 AI 在自动之前先停下来对齐。这个取舍，才是大多数开发者真正需要的。
2. 小而精，可组合，不锁定流程
整个技能包没有"必须按顺序执行"的强制流程。你可以只装 3 个技能（tdd、diagnosing-bugs、grilling），也可以全装。GSD/BMAD 试图 own 整个流程，结果"过程 bug 难修"。Matt 的技能是原子，30 秒装完。
3. 不依赖特定模型
技能是纯 Markdown，不是 API 调用。Claude、Codex、Cursor、任意 agent 都能用。这是可移植性的核心——你不会被锁在某个工具链里。
4. 从实战提炼，不是教科书
每个技能都有"识别特征"（tell）：实现耦合测试的特征是"重构后测试挂了但行为没变"；非确定性 bug 的目标是"提高复现率而非干净复现"；仓库没有 guardrail 是"常设错失机会，不是中性默认"。这些判据不是从定义推出来的，是从真实的 debug 会话里抠出来的。
5. 作者背书 + 自我实践
Matt Pocock 在 TypeScript 社区有极高影响力（190K 订阅、60K newsletter 读者），他说的东西自带传播力。但更重要的是这些技能是他自己每天在用的。"Skills for Real Engineers. Straight from my .agents directory."——不是理论框架，是实战工具。
六、值得知道的三个局限
局限一：假设存在 issue tracker
多个技能（triage、to-tickets、wayfinder、improve-codebase-architecture）假设项目有 issue tracker，并通过 docs/agents/issue-tracker.md 配置。对于纯本地、个人项目，需要先运行 /setup-matt-pocock-skills 多走几步。本地 markdown 追踪器是支持的，但配置摩擦比"开箱即用"大。
局限二：子代理机制因 agent 而异
implement-spec 的并行子代理功能（"runs implementer subagents across the ready frontier for maximum concurrency"）依赖 agent 的 subagent 能力。Claude Code、Codex、Cursor 的子代理机制差异较大，同样的 skill 措辞在不同 agent 中效果可能不一致。
局限三：in-progress 桶的噪音
in-progress/ 桶有 7 个 Beta 技能，其中 writing-beats、writing-fragments、writing-shape 是写文章用的，与工程主线无关。装在工程 agent 里会增加上下文噪音。技能包明确标注"可随时消失"，但实际使用中你会看到它们。
七、与其他 AI 工程方案对比
Matt 在 README 里对全流程方案的批评很直接：
"Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve."
README.md
八、理论从哪里来：不是凭空设计的
理解这个技能包的"人格"，需要知道它的理论来源。每一条红线背后都有经典著作的影子：
这不是学术项目，但它的理论基础是扎实的。每一条技能指令都是对某一条经典原则的可执行化翻译。
九、实际怎么用：30 秒装完，5 分钟上手
# 安装（两种方式选其一）
# 方式一：Claude Code 官方插件市场（订阅式更新）
claude plugins install mattpocock-skills
# 方式二：skills.sh（可编辑，本地拥有文件）
npx skills@latest add mattpocock/skills
# 初始化（每个仓库跑一次）
/setup-matt-pocock-skills
# → 问你要用哪个 issue tracker（GitHub/GitLab/本地文件）
# → 问 triage 标签规范
# → 问文档保存位置日常工作流（主流程）：
有想法 → /grill-with-docs（盘问 + 域建模）
→ /to-spec（对话变成 spec）
→ /to-tickets（拆成 tracer-bullet tickets）
→ /implement（按 ticket 驱动 /tdd）
→ /code-review（双轴审查）
→ /retro（改进 agent 环境）不需要全用。三个最高频的组合：
- 对齐类
： /grill-me（无状态）或/grill-with-docs（有状态），每次开始前跑一遍 - 调试类
： /diagnosing-bugs，遇到硬 bug 或性能回归时 - 审查类
： /code-review，提交前或 PR 合并前
十、结论：它不是在让 AI 更强，而是在让 AI 更守纪律
mattpocock/skills 的本质，是把软件工程 40 年的纪律翻译成 AI 时代的可执行指令。它没有发明新的工程原则，它做了一件更难得的事：把这些原则写成 AI 能读、能执行、能遵守的格式。
三条最重要的理念，浓缩成一句话：
对齐先于行动（grilling）：在写代码之前把设计树走完
反馈先于假设（diagnosing-bugs）：没有变红的命令前，不许建理论
深模块先于泥球（codebase-design）：每天都投资设计，而非事后重构
加上"事实与决策分离"这条红线，构成了一个完整的 AI 工程方法论。它不追求自动化，它追求在自动化的边界上保留人的判断权。
这就是为什么 69,000 个开发者 star 了它：不是因为它让 AI 更聪明，而是因为它让 AI 终于开始守规矩了。