matt-pocock-skills-overview

江南烟雨QH

232人浏览 · 2026-07-27 11:08:48

江南烟雨QH · 2026-07-27 11:08:48 发布

Matt Pocock Skills 全景：一套从想法到上线的 Claude Code 工作流

用过一阵 Claude Code 之后，大多数人都会撞到同一面墙：模型本身很强，但每次会话都像重新开始——同样的决策反复纠结，上下文一长就开始跑偏，bug 修了又犯。问题往往不在模型，而在缺少一套稳定的工作流，把它的随机性收敛成可预测的产出。

Matt Pocock（Total TypeScript 的作者）开源的 mattpocock-skills 正是冲着这个来的。它不是又一堆 prompt 模板，而是一套互相咬合的技能（skills）——把从"有个想法"到"合进主干"的完整工程链路，拆成有纪律的阶段，每个阶段有明确的入口、产出和交接物。

这篇文章把整套技能梳理一遍：它怎么组织、每条命令干什么、什么时候用、彼此怎么衔接。已经熟悉 Claude Code 的开发者可以直接挑感兴趣的章节跳读。

这套技能是什么

mattpocock-skills 是一个 Claude Code 插件（skill 包），当前版本 1.2.0。从 Claude Code 的插件市场安装 mattpocock 后，你会得到二十多个 / 命令。命令统一是 /skill-name（若与其他插件重名，用完整前缀 /mattpocock-skills:skill-name）。

它的核心理念一句话：从随机系统中榨出可预测性。这里的"可预测"指过程每次一致，而非输出一字不差——同一类任务每次走同样的纪律，结果才稳定。

为此它有两个设计特点值得先知道：

技能会互相调用，形成流水线。 比如 /implement 内部会驱动 /tdd（测试先行）、收尾跑 /code-review（双轴评审）；/grill-with-docs 挂着 /domain-modeling 边问边写文档。你不是在背二十个命令，而是在用一条几条主干串起来的流程。
触发方式分两种。 大部分技能是手动触发（设了 disable-model-invocation，需要你显式输入命令），避免占用上下文；少数是底层原语——/grilling、/domain-modeling、/codebase-design——会被其他技能在需要时自动调用。你日常直接打的是前者。

和 superpowers 比怎样

市面上另一套流行的 skill 套装是 superpowers，它用 hooks 强制串起从头脑风暴到实现的完整流程——好处是不熟悉工程流程的人也能被动走完一遍，写出的 plan 甚至能派发给便宜的 coding agent；代价是强制、费 token，还容易把简单问题复杂化。Matt 这套走了相反的路：把"什么时候调用什么 skill"的决策权交回你手上，他称之为 Skills For Real Engineers。于是它更省 token、更灵活，代价是你得自己知道当前该走哪一步——这正是 /ask-matt 这张路由地图存在的意义。两套的基本流程其实同构：

superpowers	mattpocock-skills
brainstorming	`/grill-with-docs`
write-spec	`/to-spec`
write-plans	`/to-tickets`
execute-plan	`/implement`

Justin Yan 在这篇使用心得里用的是旧名 to-prd / to-issues，v1.0.0 后已更名为 to-spec / to-tickets。

整套技能围绕一条主线展开，外加若干上匝道、一层词汇地基和几个横向工具。下面这张图先给个全貌，再逐块拆开。

它要解决的四个问题

Matt 在仓库里写得很直白——这套技能存在，是因为用 AI 写代码时会反复撞到四类问题，每个问题对应一组技能。这个"问题驱动"的视角，比记命令更能帮你判断当下该用什么：

The Agent Didn’t Do What I Want（Agent 不按我想的做）——本质是 Agent 不知道你到底要什么。用 /grill-with-docs 通过问答把它逼到真正理解需求。
The Agent Is Way Too Verbose（Agent 太啰嗦）——你和 Agent 说的不是同一种"语言"。/grill-with-docs 配合 /domain-modeling，把项目术语和你习惯的转述记进 CONTEXT.md，下次不必重复解释，沟通才高效。
The Code Doesn’t Work（代码跑不通）——用 /tdd 测试先行锁住行为，跑不通时用 /diagnosing-bugs 按纪律排查。
We Built A Ball Of Mud（项目沦为泥球）——coding agent 跟人一样，喜欢在现有代码上雕花。每个规划阶段都倾向更好的设计（/to-spec 动手前就会确认到底该动哪些模块），但项目做久了难免一团浆糊，这时 /improve-codebase-architecture 负责重构——它会产出详细报告加一张可视化 HTML 图。

记住这四个问题，比背二十个命令有用：遇到哪类痛点，就去找对应的那组技能。

一个典型决策："这点要不要优化"该用哪个技能

一个高频的疑问：盯着某段代码或某个设计，想和 Agent 讨论它到底要不要优化——这种"动手前先压力测试一个决策"的场景，到底该走哪个技能？关键不在记住命令，而在分清你当前的意图处于哪一步：

你的真实意图	该用什么
还没锁定要改哪里，想让 Agent 扫描代码库主动找出值得优化的点	`/improve-codebase-architecture`（找候选）
已锁定某个点，想搞清楚到底改不改、改什么、为什么	`/grill-with-docs`（有代码库）或 `/grill-me`（无代码库）
已决定要改，想设计这个模块改成什么形状（接口怎么收窄、seam 放哪）	`/codebase-design`
想审查一个已有的分支 / PR / diff 改得对不对	`/code-review`

一句话记法：还没锁定点 → improve-codebase-architecture；锁定了、纠结要不要改 → grilling；决定要改、想设计怎么改 → codebase-design。

需要提醒一个常见误区：grilling 的本质是 Agent 反过来拷问你——一次只问一个问题、每个都附推荐答案、把"事实（自己查）"和"决策（问你）"分开——而不是单方面甩给你一个结论。所以如果你其实只想让 Agent 直接看一眼那个点、给个判断，不必套任何技能，把代码贴过去即可。技能是为"还没想清楚、需要纪律帮你逼近答案"的场景准备的；已经想清楚、只是想要个确认，套技能反而是杀鸡用牛刀。

一图看懂

主线纵向贯穿：配置 → 打磨想法 → 按规模分支 → 实现 → 上线。三个分组分别是从问题进入主线的"上匝道"、被反复引用的"词汇地基"、以及随时可用的"横向工具"。

主线：从想法到上线

这是绝大多数工作走的路径。

第 0 步：先配置

/setup-matt-pocock-skills 是每仓库跑一次的脚手架配置，必须最先执行。它配置三样东西：

Issue tracker（写到 docs/agents/issue-tracker.md）：按 git remote 推荐用 GitHub 的 gh、GitLab 的 glab、还是本地 markdown（.scratch/<feature>/，适合个人项目）。
Triage labels：needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix。
Domain docs layout：默认单上下文（根目录一份 CONTEXT.md + docs/adr/），只有 monorepo 才上多上下文。

为什么要先跑？因为 /to-tickets、/triage、/to-spec、/code-review 这些技能都依赖这份配置才知道往哪写、用什么标签。

不知道用哪个技能时，问 /ask-matt——它是整套技能的路由地图。

打磨想法：访谈式拷问

一切从一个想法开始。Matt 的做法是用 relentless 的访谈把想法逼到无路可退，事实自己去查（文件系统/工具），决策才问人，达成共识前不动手。

/grill-with-docs —— 有代码库时用。它启动拷问的同时挂着 /domain-modeling，边问边把敲定的术语写进 CONTEXT.md、把架构决策写成 docs/adr/ 下的 ADR。有状态，沉淀团队语言。
/grill-me —— 没代码库时用。同样的拷问，但不写文档，纯磨利想法。无状态。
/grilling —— 上面两个命令背后真正执行拷问的底层原语：一次只问一个问题、每个都给推荐答案、区分"事实（自己查）“和"决策（问用户）”。可被自动调用。

旁路：用一次性原型回答设计问题

有些问题纸面上 settle 不下来，得跑起来看。/prototype 建一个一次性小程序回答一个设计问题：

逻辑/状态模型对不对 → 建交互式终端小程序，把状态机推到难推理的边界。
UI 该长什么样 → 用 URL 参数 + 浮动底栏切换多个截然不同的变体。

规则是"从第一天起就当一次性代码"：内存态、不写测试、不做抽象、一条命令能跑。验证完把决策折回真实代码，原型本身丢进临时分支。

规划：从想法到可执行的工单

/to-spec 把当前对话和代码库理解综合成一份 spec（PRD）。它探索代码库、勾画测试接缝（seams）（尽量复用已有的、尽量用最高层、越少越好），然后按模板写 spec 发到 tracker 并打 ready-for-agent。注意它不再访谈用户，只做综合；也不写具体文件路径或代码（容易过期）。

/to-tickets 把 spec 拆成一组 “tracer-bullet” 纵切片——每片贯通 schema/API/UI/tests 全层、单独可 demo、能装进一个上下文窗口，并声明自己的阻塞边。宽泛重构是例外，用 expand–contract 序列（先并存 → 分批迁移保持 CI 绿 → 最后删旧）。拆完按依赖顺序发布，frontier（无阻塞的）立即可开干。

执行：测试驱动地落地

/implement 按 spec/tickets 实际写代码。它本身极简——按描述实现、在约定接缝处用 /tdd、定期跑类型检查和单测（结束时跑全量）、用 /code-review 审查、提交。质量几乎全靠上游 spec/tickets 和接缝约定。

/tdd 是测试驱动的 red→green 循环纪律。它先读 CONTEXT.md 让命名贴合领域语言，再先约定接缝（“我们能测一切，所以接缝要事先约定”，没确认的接缝不写测试），然后纵切片循环：一个接缝 → 一个失败测试 → 最小实现。重构不属于这个循环，归 /code-review。三个反模式要躲：实现耦合（mock 内部/测私有）、同义反复（期望值用被测代码同样方式算出来）、水平切片（先写完所有测试再实现，会测想象中的行为）。

/code-review 对"固定点到 HEAD"的 diff 做双轴并行评审。它钉住一个基线跑 git diff <fixed-point>...HEAD，找规格来源（commit 里的 issue 引用、用户给的路径、specs/ 或 .scratch/），然后并行起两个 sub-agent：Standards 查规范违反和代码异味、Spec 查需求缺失/超范围/实现错误。两份报告故意不合并排名，防止一轴掩盖另一轴。

三条上匝道：从问题进入主线

有些工作不是"我有个想法"，而是"有东西需要处理"。这三条上匝道把问题理清后并入主线。

/triage 处理你没创建的外来 issue（bug 报告、feature request、外部 PR）。它让 issue 在 triage 状态机里流转：看关注队列（Unlabeled / needs-triage / needs-info 三桶）→ 读全文查冗余（是否已实现）和历史否决（.out-of-scope/*.md）→ 给分类和状态推荐 → bug 按步骤复现、PR checkout 跑测试 → 必要时 /grilling 磨清 → 落地（ready-for-agent 发 agent brief 让 /implement 接手）。注意：/to-tickets 产出的 ticket 已经是 agent-ready 的，不要 triage 它们。

/diagnosing-bugs 是硬 bug 和性能回归的诊断纪律，六个阶段不可跳。核心是第一阶段（占 90% 工作）：建反馈回路——构造一个能针对这个 bug 变红的 pass/fail 信号（失败测试 → curl → CLI 快照 → 无头浏览器 → 重放 trace → 一次性 harness → 模糊测试 → 二分 → 差分），然后收紧它。没有红回路，绝不进入假设阶段。之后才是最小化复现、生成 3-5 个可证伪假设、带 [DEBUG-xxxx] 前缀插桩、先写回归测试再修、清理复盘。它拒绝在没复现信号前瞎猜，这是它和"看一眼就改"最大的区别。

/wayfinder 给超大、模糊、一个会话装不下的项目（绿地新项目或巨型 feature）画"决策地图"。它先锁定"终点"，再广度优先扫描开放决策，在 tracker 建一个 wayfinder:map 父 issue，把每个问题建成子 ticket（research/prototype/grilling/task 四类）。每会话只解一张票，产出的是决策而非交付物。雾推回去之后，它在 /to-spec 合流进主线——不要直接跳 /implement，否则会丢掉地图里的链接细节。

词汇地基：被反复引用的两层

这两个技能本身不直接产代码，却定义了其他技能说话用的词汇。

/domain-modeling 维护项目的领域语言。它管两个文件：CONTEXT.md（只写术语，不写实现的 glossary）和 docs/adr/（架构决策记录，克制使用——同时满足"难回滚 / 没上下文会困惑 / 真实权衡"才提议写）。会话中它做四件事：术语和现有 CONTEXT.md 冲突立刻指出、模糊词（比如 “account” 同时指 Customer 和 User）逼你二选一、用边界场景压测关系、用户说的和代码不一致当场揭穿。术语敲定立刻写、不攒批。/grill-with-docs 和 /wayfinder 都靠它保持术语一致。

/codebase-design 定义"深模块"的词汇：Module（有接口+实现的东西）、Interface（调用者必须知道的一切）、Depth（小接口背后的行为量）、Seam（不改此处即可改行为的地点）、Adapter、Leverage（调用者收益）、Locality（维护者收益）。核心判据是删除测试——删了复杂度消失的就是 pass-through 浅模块；以及"一个 adapter 是假设的缝，两个才是真的缝"。它明确拒绝用 component/service/API 这些词替代，要求术语精确。/tdd 和 /improve-codebase-architecture 都说这套话。

在此基础上，/improve-codebase-architecture 是代码库健康 upkeep：它扫描"深化机会"（理解一个概念要在多个小模块间跳、浅模块、为测试抽取但 bug 藏在调用处的纯函数），生成一份临时 HTML 报告（每候选含问题/方案/收益/前后对比图/推荐强度），你选定后它跑 /grilling 决策树、用 /codebase-design 探索替代接口。有空闲时刻跑一跑，能让代码库持续"对 agent 友好"。

跨会话与横向工具

/handoff 把当前对话压缩成一份交接文档存到系统临时目录（不污染仓库），让你开新会话引用它继续。文档必须含 “suggested skills” 小节，已被 spec/ADR/issue/commit 记录的内容引用而非复制，还要脱敏（抹掉密钥和 PII）。它和内置 /compact 的区别：/handoff 分叉到新会话，/compact 原地压缩——后者适合阶段间歇用，别在阶段中间压。

/research 把费时的阅读外包给一个后台 agent。它只追一手资料（官方文档、源码、规范），每条结论回溯源头并引用，写成带引用的 Markdown 存进仓库。主线程继续干别的。产出的文件是喂料——应被 /grill-with-docs 消费辅助决策，不替你思考。

/resolving-merge-conflicts 解决进行中的 merge/rebase 冲突。它的纪律是先找每个冲突的原始来源（commit/PR/issue）理解当初为何这么改，再逐 hunk 解决、保留两边意图，不兼容时记录权衡，绝不发明新行为、绝不 --abort。

/teach 把当前目录变成有状态的长期教学工作区，跨多会话教你一个主题，靠 retrieval/spacing/interleaving 制造"合意困难"。

/writing-great-skills 是写/改 skill 的参考手册，讲怎么用 progressive disclosure、leading words、completion criterion 让技能可预测——你想自己写 skill 时查它。

实验性和已弃用的部分

除了上面这些核心技能，包里还有一些你日常大概率用不到的：一批 in-progress（开发中，未必稳定，如 batch-grill-me、wizard、几个 writing-*）、几个 deprecated（已被替代，如 qa、ubiquitous-language）、几个 misc 杂项工具（git guardrails、pre-commit、迁移脚本），以及作者个人用的技能（edit-article、obsidian-vault）。知道有这些即可。

上手建议

第一次用，建议这样走：

先 /setup-matt-pocock-skills 做配置——这一步省不掉，后面的技能都依赖它。
有个想法 → 有代码库就 /grill-with-docs，没有就 /grill-me，把想法拷问清楚。
想清楚后 → 小活直接 /implement；大活 /to-spec → /to-tickets，每个 ticket 清空上下文后单独 /implement。
遇到 bug → 难搞的用 /diagnosing-bugs；别人提的 issue 堆积用 /triage。
代码库有空闲 → 跑 /improve-codebase-architecture 找深化机会。

几条来自实战的技巧：

模型分工：spec/PRD 这种吃理解力的活，交给最强的高智商模型（写一次、用很久）；真正写代码交给靠谱但更省的模型。计划写得清楚，下游就能用便宜的模型执行。
让 tracker 替你记：把 PRD 和 ticket 都留在 issue tracker（GitHub issues，或本地的 .scratch/）里。好处不只是流程规范——更重要的是你不会忘上次跟 Agent 做到哪一步，被多个项目折腾的记忆有了着落。
复杂视觉交互，先 /prototype：有些设计问题纸面说不清，又不想烧 token 跑重量级可视化对齐时，先用 /prototype 快速搭个简单原型近似验证，不合适直接扔掉。
跨模型/跨工具交接用 /handoff：比如在 Claude 和 Codex 之间切换时，用 /handoff 把上下文转交过去，而不是从头解释一遍。

还有一条上下文纪律值得记牢：第 2、3 步（拷问、spec、tickets）尽量在同一个未压缩的上下文窗口里完成，让它们建立在同一套思考上；每个 /implement 再开新窗口从 ticket 起步。接近 ~120k token 的"smart zone"上限时，用 /handoff 转到新会话，别硬撑到模型推理降级。

这套技能真正的价值不在某个单点命令，而在它们咬合成一条流水线：想法被拷问、被规划、被切片、被测试驱动地实现、被双轴评审，每一步都有交接物，上下文在合适的时机清空和恢复。一旦顺起来，你会发现 Claude Code 从"每次重新开始"变成了"沿着轨道前进"。

写在最后：从 harness 到 loop engineering

跳出来看，这套技能也折射出 AI 编程工程化的演进。早期基座模型能力弱、指令遵循差，我们强调 harness——用各种工程手段把模型按想要的方向拽住、别跑偏；随着模型越来越强、指令遵循更准，重心转向 loop engineering——长任务的稳定交付。mattpocock-skills 正是后者的代表：它不强制造流程，而是给"真实工程师"一套可组合的纪律，让你自己编排出稳定的长任务闭环。

严肃产品的打磨里，Taste 一直是 human-in-the-loop 中最难替代的一环。但随着更强模型（如 Fable 5 这一档）的出现，连"打磨"这个阶段也开始看到提效的曙光。下一代软件会长什么样，值得期待。