Matt Skills 是 Matt Pocock 开源的 AI 编码 Skill 集合（mattpocock/skills），用一条可自由拼装的流水线把模糊需求变成可控的交付：追问对齐、规格化、任务切片、TDD 实现、双轴审查。本文带你走完这条流水线，再聊聊背后的设计哲学与常见误区。

认识这条流水线

为什么需要这样一条流水线？直接给 AI 抛模糊需求（Vibe Coding），本质上是把几百个微观架构决策外包给一个随机性黑盒，AI 常常拼出最难维护的「斜塔」架构；而像 Superpowers 这样的重型框架，用固定步骤把规格、计划、实现强行绑定，前置步骤一旦偏离，错误就会沿整条流水线传染。Matt Skills 走的是中间路线：极简而模块化——一个 Skill 只解决一个问题，允许自由拼装，把决策主导权重新交还给人类。

假设你手里只有一个模糊需求——一句话，没有验收标准，甚至说不清要解决什么问题。在把它直接扔给 AI 之前，Matt Skills 先把这段旅程铺成一条流水线：追问对齐（/grill-with-docs 与 /wayfinder）、规格化（/to-spec）、任务切片（/to-tickets）、逐个实现（/implement），最后双轴审查（/code-review）。

这些环节不是焊死的固定步骤——每个都是独立的 Skill，自由拼装，你想从哪一环进入，就调哪个。这条流水线也不是每次都要走完：单 Session 能完成的需求，追问对齐后直接进入 /implement；需要跨 Session 的大需求，才在中间补上 /to-spec 与 /to-tickets。

装进项目：安装与初始化

在走进第一站之前，先把它装进项目。一条命令：npx skills@latest add mattpocock/skills。装完再跑 /setup-matt-pocock-skills，完成三项基础设定：

• Issue Tracker：任务放哪——GitHub Issues、Linear、Jira 或本地 Markdown。
• Triage Labels：任务分类与优先级标签。
• Domain Documentation：Single Context 适合大多数项目，Multi Context 适合大型 Monorepo。

配置完成后，AI 会在 claude.md 或 agents.md 里自动建立索引，让每个 Skill 都知道任务、标签与文档结构在哪里。v1.2 起还附带 openai.yaml 侧车配置，让这套规则在 Codex 等不同 harness 下同样生效。

第一站：追问对齐

追问的目标很简单：把模糊需求磨清晰。有代码库时走 /grill-with-docs——AI 在提问的同时维护两份文档：context.md 沉淀项目的通用语言与关键实体，ADR 记录那些不可逆的架构决策。

它还把「事实」和「决策」严格分开：事实由 AI 检索代码库得出，决策由你来拍板；每轮只问一个问题，附带推荐选项，而不是一次抛出一长串琐碎问题。

没有代码库的脑暴场景则换成更轻的 /grill-me——同样在达成共识前不写任何代码，每次只问一个问题。

需求大到单次会话装不下、迷雾重重时，单靠一轮轮问答就不够了，这时用 /wayfinder 在任务跟踪器上画一张带依赖关系的共享地图，把主任务拆成四类子任务：grilling（细节追问）、research（后台调研）、prototype（原型验证）、tasks（环境配置等硬任务）。

子任务全部闭环后，地图汇总完毕——下一步就能流向下游的 /to-spec。

从共识到任务：Spec 与 Ticket

追问磨出来的共识不能只留在对话里——一场动辄数万 Token 的讨论，一旦被清除就全部蒸发。所以第一件事是固化：/to-spec 把追问产生的上下文压缩成一份规格书，包含背景、方案、用户故事、实现决策与测试要求。

它严格禁止写代码：Spec 只定义「要解决什么问题」，不碰「怎么实现」——代码的变动远快于业务逻辑，Spec 里一旦出现代码，重构时文档和实现就会互相打架。

/to-tickets 再把规格拆成一张张独立的 Ticket，原则是垂直切片：反对按技术架构横切（先建完所有数据库，再写完所有后端，最后画前端——每做完一步都无法独立测试），而是按用户功能切。比如 Ticket 1 只做「会员登录」，这一张里就自带专属数据库、后端逻辑和前端画面。

每完成一张，就能立刻打开浏览器端到端验证；每张的工作量也控制在单次会话能承载的范围内。

实现与审查

规格与 Ticket 就绪，进入实现站。在干净的新会话里运行 /implement [Ticket-ID]，它会强制走 TDD 红绿循环：先写出必定报错的测试（红灯），再写功能代码让它通过（绿灯）——从机制上杜绝 AI 编造「必然通过」的假测试。

实现完成后自动跑类型检查与单元测试，通过后自动触发 /code-review 并提交分支。

审查这一步，/code-review 派出两个干净的平行子进程，各自只带一份任务入场：规格轴逐条对照 Spec / Ticket 的验收标准；规范轴对照仓库的 coding-standards.md，并主动识别 Martin Fowler 的经典重构坏味道——feature envy、data clumps、primitive obsession、message chains 等。

为什么非要在主 Agent 之外另开进程？刚写完代码的 Agent 带着自我偏见和上下文污染，很难抓出自己的 Bug；干净的上下文才能客观审查。

维护与底层哲学

审查拦得住眼前的 Bug，拦不住 AI 写代码的结构病：它为了交差，很容易产出大量浅模组——内部只有几行代码、暴露一堆接口、没有统一大门，逻辑散落在多个文件里，一旦超出上下文边界，修 Bug 时就会盲目跳转、瞎猜乱改。

/improve-codebase-architecture 用「残酷删除测试」诊断：在脑海中把某个模组拔掉，若系统大乱，说明它是藏着复杂度的有效深模组；若代码反而变清爽，说明它是多余的浅模组。定期运行还能生成可视化 HTML 报告，对比重构前后的架构。

这一整套纪律，归根结底来自同一条约束：模型号称百万级上下文，但注意力在 120k–140k Token 之后会退化，进入幻觉与逻辑混乱的「Dumb Zone」。所以流水线要求单 Ticket 单会话、讨论结果及时转存、必要时交接——一切都是为了把交互留在「Smart Zone」内，让模型始终处于高智商状态。

这甚至决定模型选型：追问阶段必须用顶级旗舰模型，靠参数知识抛出有深度的盲点；实现阶段已有详细上下文指导，可以降级用便宜模型。

再往下一层，是 Prompt 撰写本身的三原则：

• 修剪：砍掉废话和模型已知的知识。
• 指引词：用 data clumps、ubiquitous language 这类高密度术语，一个词替代上百字的解释。
• 明确完成标准：给 AI 设下停止门槛，防止它偷跑写代码。

同一套可预测性追求，也延伸到写给 Agent 的文档：/writing-for-agents 统一了 Skill、AGENTS.md / CLAUDE.md 与被 context pointer 引用的外部文档的写法——包装形式不同，原则一样：让 Agent 每次走同一套流程，而不是碰运气。

它讲清了 context pointer（指针的措辞决定 Agent 何时会取到材料）、两种成本（常驻上下文的 context load，与靠人记住的 cognitive load）、信息层级与渐进披露、完成标准与 premature completion、leading word，以及修剪纪律和 no-op、sediment 等失效模式。

工作流中的专项环节：原型验证与交接

主流程之外还有几个按需调用的专项 Skill。首先是 /prototype：追问中常遇到文字说不清的问题——界面看起来如何、某个交互手感对不对，这类是高保真问题，用文本硬讨论效率极低；而接口命名、数据字段设计这类低保真问题，文字追问就够。

原型就是回答高保真问题的最便宜工具：UI 原型在真实页面里生成多个交互方案对比，Logic 原型用小型终端程序推演状态机、验证边界条件。

上下文转移交给 /handoff：它把当前 Session 的进展与关键信息压缩成一份 Markdown 文件，存入操作系统临时目录，交给一个全新的 Session 接棒——这跟 /compact 的原地压缩完全不同。

它的价值有三：保持主 Session 上下文纯净（比如追问中发现一个无关 Bug，直接派给新 Agent 修，修完再把结论传回）；跨工具兼容（Claude Code 生成的交接文档可以丢给 Codex 或 Copilot CLI）；交接文档会附带 suggested skills，并自动剥离 API Keys 与敏感信息。

/ask-matt 是整套 Skill 的导航员：它熟悉仓库里所有 Skill 的用法与标准流程，随时回答「下一步该调哪个 Skill」。当你拿不准该从哪一环进入时，先问它。

教学与写作类 Skill

工程流程之外，还有一组专门服务学习与写作的 Skill。

/teach 把当前目录变成一个有状态的教学工作区，跨多个 Session 教你一项技能：MISSION.md 记录学习动机，./lessons/ 每次产出一份独立、精美的 HTML 课程（一次只讲一件事），./reference/ 沉淀可快速翻阅的速查资料，learning-records 记录已学内容。

练习刻意设计「合意困难」（desirable difficulty）——检索、间隔、交错——让知识真正存进长期记忆，而不是当下觉得懂了。

/writing-beats 是「素材 → 文章」的写作流程：给定一份 Markdown 原材料，先确认读者已掌握的前提，再按 beat 逐段推进——每次给出 2–3 个候选起始段（每个是不同的入口），你选一个，它只写那一段；然后根据当前进度再给 2–3 个下一步候选，直到文章自然收尾。

它有一条「接地」纪律：任何概念在被后面的段落使用前，必须先由某个 beat 引入（或属于读者自带的前提）。素材用不完也没关系——旅程走完即止，料堆本来就是用来挑的。

9 大常见误区对照表

最后，把全文的纪律反着读一遍，就得到一张最实用的对照表。九个常见误区，各有纠偏方案：

1. 用文字硬回答高保真问题——UI 感受、交互手感这类问题，文本讨论效率极低；应挂起追问，交给 /prototype 出可运行原型。
2. 追问 Scope 过大——试图一次规划数天的大需求，上下文 Token 爆满，掉进 Dumb Zone，AI 逻辑退化；应拆小范围，或用 /wayfinder 分片。
3. 被动接受 AI 拷问——任由 AI 抛出几百个琐碎问题，炸裂上下文；应保持架构师角色，主动砍掉无关分支。
4. 直接 /clear 丢弃追问成果——几万 Token 的共识瞬间蒸发；应先用 /to-spec、/to-tickets 或 /handoff 固化。
5. 追问阶段用弱模型——弱模型缺少参数知识，抛不出有深度的盲点；追问必须用旗舰模型，实现阶段才可降级。
6. 单线程串行追问——坐在屏幕前等 AI 回复，吞吐量低；应像处理多个 Slack 线程一样并行开多个 Session。
7. Spec 里写代码——代码变动远快于业务逻辑，Spec 含代码会让文档与实现互相打架；Spec 只写问题与验收标准。
8. 按技术架构层横切 Ticket——先建库、再写后端、最后画前端，做完的步骤无法独立测试；应垂直切片，每张 Ticket 自带 DB、逻辑与画面。
9. 在主 Agent 里直接做 Code Review——刚写完代码的 Agent 带着自我偏见，抓不出自己的 Bug；应派干净的平行子进程做双轴审查。

这张表里的每一条，前文都有对应设计：Matt Skills 的每个环节都不是锦上添花，它只是把 AI 最容易失手的地方，逐一装上了护栏。