skills

面向真正工程师的 Skills

我每天使用的 agent 技能，用于做真正的工程——而不是 vibe coding（氛围编程）。

开发真正的应用程序很困难。像 GSD、BMAD 和 Spec-Kit 这样的方法试图通过拥有整个流程来提供帮助。但与此同时，它们夺走了你的控制权，并使流程中的 bug 难以解决。

这些技能被设计成小巧、易于修改且可组合。它们适用于任何模型。它们基于数十年的工程经验。随意 hack 它们，让它们成为你自己的。享受吧。

如果你想跟上这些技能的更新以及我创建的任何新技能，你可以加入我的 newsletter，和约 60,000 名开发者一起：

注册 Newsletter

快速开始（30 秒设置）

1. 运行 skills.sh 安装器：

npx skills@latest add mattpocock/skills

1. 选择你想要的技能，以及你想将它们安装到哪些 coding agent 上。确保你选择了 /setup-matt-pocock-skills。

2. 在你的 agent 中运行 /setup-matt-pocock-skills。它会：

   • 询问你想使用哪个 issue 追踪器（GitHub、Linear 或本地文件）
   • 询问你在分类（triage）时给 ticket 应用哪些标签（/triage 使用标签）
   • 询问你想把我们创建的任何文档保存在哪里

3. 搞定——你已经准备好了。

为什么这些技能存在

我构建这些技能是为了修复我在 Claude Code、Codex 和其他 coding agent 中常见的失败模式。

#1：Agent 没有按我预想的方式行动

“没有人确切知道自己想要什么”

David Thomas & Andrew Hunt，《程序员修炼之道》

问题。软件开发中最常见的失败模式是未对齐（misalignment）。你以为开发者知道你想要什么。然后你看到他们构建的东西——发现它完全没理解你。

在 AI 时代，这同样如此。你和 agent 之间存在沟通鸿沟。解决方案是进行一次拷问会话（grilling session）——让 agent 对你要构建的内容提出详细问题。

解决方案是使用：

• /grill-me —— 适用于非代码用途
• /grill-with-docs —— 与 /grill-me 相同，但增加了更多内容（见下文）

这些是我最受欢迎的技能。它们帮助你在开始之前与 agent 对齐，并深入思考你要进行的变更。每次你想做改动时都使用它们。

#2：Agent 过于啰嗦

“拥有一种通用语言（ubiquitous language），开发者之间的对话和代码的表达都源于同一个领域模型。”

Eric Evans，《领域驱动设计》

问题：项目开始时，开发者和他们为其构建软件的领域专家通常说的是不同的语言。

我在我的 agent 中也感受到了同样的张力。Agent 通常被直接丢进项目中，让它们边做边摸索术语。所以它们用了 20 个词，而一个词就够了。

解决方案是建立一种共享语言。这是一份帮助 agent 解码项目中使用的术语的文档。

示例

这里是我 course-video-manager 仓库中 CONTEXT.md 的一个例子。哪个更容易阅读？

• 之前：“当课程某节中的一个课时被设为‘真实’（即给予文件系统中的一个位置）时，会出现问题”
• 之后：“物化级联（materialization cascade）存在问题”

这种简洁性在每次会话中都会带来回报。

这已内置于 /grill-with-docs 中。它是一个拷问会话，但会帮助你与 AI 建立共享语言，并将难以解释的决策记录在 ADR 中。

很难解释这有多么强大。它可能是这个仓库中最酷的技巧。试试看，你就知道了。

[!TIP] 共享语言除了减少啰嗦外，还有很多其他好处：

• 变量、函数和文件使用共享语言命名，保持一致
• 因此，代码库对于 agent 来说更易于导航
• Agent 同时也花费更少的 tokens 用于思考，因为它可以访问更简洁的语言

#3：代码不工作

“始终采取小而谨慎的步骤。反馈速度就是你的速度限制。永远不要承担太大的任务。”

David Thomas & Andrew Hunt，《程序员修炼之道》

问题：假设你和 agent 在要构建什么上达成了共识。当 agent 依然产生了糟糕的代码时，该怎么办？

此时需要审视你的反馈循环。如果没有关于它实际运行代码的反馈，agent 就是在盲飞。

解决方案：你需要常规的反馈循环：静态类型、浏览器访问和自动化测试。

对于自动化测试，红-绿-重构（red-green-refactor）循环至关重要。即 agent 先编写一个失败的测试，然后修复测试。这有助于 agent 获得一致的反馈水平，从而产生更好的代码。

我构建了一个 /tdd 技能，你可以将其插入任何项目。它鼓励红-绿-重构，并给 agent 提供了大量关于什么是好测试和坏测试的指导。

对于调试，我还构建了一个 /diagnose 技能，将最佳调试实践封装在一个简单循环中。

#4：我们构建了一个泥球（架构混乱）

“每天都对系统设计进行投资。”

Kent Beck，《解析极限编程》

“最好的模块是深的。它们通过一个简单的接口提供大量功能。”

John Ousterhout，《软件设计哲学》

问题：大多数用 agent 构建的应用程序复杂且难以改动。因为 agent 可以大幅加速编码，它们也加速了软件熵（software entropy）。代码库以前所未有的速度变得越来越复杂。

解决方案是采用一种全新的 AI 驱动开发方法：关心代码的设计。

这已内置于这些技能的每一层中：

• /to-prd 在创建 PRD 之前询问你正在接触哪些模块
• /zoom-out 告诉 agent 在整个系统的上下文中解释代码

最关键的是，/improve-codebase-architecture 帮助你拯救一个已经变成泥球的代码库。我建议每几天在你的代码库上运行一次。

总结

软件工程基础比以往任何时候都更重要。这些技能是我将这些基础浓缩为可重复实践的最佳努力，以帮助你交付职业生涯中最好的应用程序。享受吧。

参考

工程类（Engineering）

我日常用于代码工作的技能。

• diagnose —— 针对棘手 bug 和性能回归的纪律性诊断循环：复现 → 最小化 → 假设 → 检测 → 修复 → 回归测试。
• grill-with-docs —— 拷问会话，根据现有领域模型挑战你的计划，精炼术语，并内联更新 CONTEXT.md 和 ADR。
• triage —— 通过一个包含 triage 角色的状态机来分类 issue。
• improve-codebase-architecture —— 在代码库中发现深化（deepening）机会，参考 CONTEXT.md 中的领域语言和 docs/adr/ 中的决策。
• setup-matt-pocock-skills —— 搭建每个仓库的配置（issue 追踪器、triage 标签词汇表、领域文档布局），这些配置被其他工程技能使用。在使用 to-issues、to-prd、triage、diagnose、tdd、improve-codebase-architecture 或 zoom-out 之前，对每个仓库运行一次。
• tdd —— 利用红-绿-重构循环的测试驱动开发。每次一个垂直切片（vertical slice）地构建功能或修复 bug。
• to-issues —— 将任何计划、规格或 PRD 分解为可独立抓取的 GitHub issues，使用垂直切片。
• to-prd —— 将当前对话上下文转化为 PRD 并作为 GitHub issue 提交。无需面谈——只是综合你已经讨论过的内容。
• zoom-out —— 告诉 agent 拉远视角，给出更广泛的上下文或对代码中不熟悉部分的高层视角。

生产力类（Productivity）

通用工作流工具，不针对代码。

• caveman —— 超紧凑的通信模式。通过去除填充词，同时保持完整的技术准确性，将 token 使用量减少约 75%。
• grill-me —— 对计划或设计进行无情的面谈，直到决策树的每个分支都被解决。
• write-a-skill —— 创建新技能，具有恰当的结构、渐进式披露和打包的资源。

其他（Misc）

我保留但很少使用的工具。

• git-guardrails-claude-code —— 设置 Claude Code 钩子，阻止危险的 git 命令（push、reset --hard、clean 等）在执行前触发。
• migrate-to-shoehorn —— 将测试文件从 as 类型断言迁移到 @total-typescript/shoehorn。
• scaffold-exercises —— 创建包含章节、问题、解决方案和讲解的练习目录结构。
• setup-pre-commit —— 设置 Husky pre-commit 钩子，集成 lint-staged、Prettier、类型检查和测试。