mattpocock skills

定义与身份

mattpocock skills 是 Matt Pocock 开源在 GitHub 上的仓库 mattpocock/skills。 它也被明确命名为“Skills for Real Engineers”，定位是一套给真实工程协作使用的 .claude Skills。 该项目不是若干互不关联的 prompt 文档集合，而是一整套围绕 Agent 参与软件工程流程而设计的方法论与操作规程。 按文中描述，仓库内包含 21 个 Skill，用来约束 Agent 在不同阶段的行为，使其从“有一个模糊想法”一路走到“代码可合并进主干”。

项目要解决的四类问题

项目把自己要解决的问题概括为四类，而且都直接对应 Agent 在真实开发中的高频失效模式。

1. 需求失配：Agent 自作主张

最常见的问题是，开发者以为 Agent 已经理解需求，但实际产出的是另一回事。 因此这套 Skills 把“先把要什么审清楚”放在最前面，避免在理解尚未对齐时直接生成实现。

2. 缺少共同语言：Agent 每次都重新猜项目黑话

当项目内部没有稳定术语时，Agent 会不断重新解释、重新猜测上下文，结果通常是表达冗长且不精确。 项目给出的药方是建立项目内部共同语言，让团队和 Agent 共享同一套词汇。 文中举了一个很具体的例子：原本一段冗长描述，大意是“某节课在某个章节里被落到文件系统上生成实体文件时会出问题”；在统一术语后，这句话可以直接缩成“物化级联出问题了”。 这个例子说明，Skill 的作用不是单纯润色表达，而是把重复解释压缩成可复用的工程语言。

3. 没有测试反馈：代码写出来但跑不起来

如果没有测试反馈闭环，Agent 写代码就像“盲人摸象”，即使看起来完成了实现，也无法保证能运行。 因此仓库把测试驱动开发放进主流程，用红灯、绿灯、重构的循环来约束实现过程。

4. 代码库快速腐化：Agent 越快，烂代码也越快积累

项目认为，Agent 提高了产出速度，也会同步提高代码库腐化速度。 如果缺少持续审查与架构体检，几周内代码库就可能变成谁都不敢动的烂摊子。 所以这套 Skill 不只关心“能否生成功能”，也关心代码坏味道、偏题实现和长期可维护性。

核心角色：把软件工程流程做成 Agent 可执行纪律

mattpocock skills 的核心职责，是把软件工程中的关键动作拆成可重复执行的 Skill。 它覆盖的不是单一步骤，而是一条完整主线：

• 需求澄清
• 原型验证
• 规格文档整理
• 工单切分
• 实现
• 测试驱动开发
• 代码审查
• 问题分诊
• 疑难问题定位
• 大型规划

换言之，它并不试图把 Agent 变成“自动写代码机器”，而是试图让 Agent 在每个阶段遵守特定纪律。

主线工作流：idea → ship

仓库的核心工作流被描述为 idea → ship，即从一个想法走到可交付、可合并。

/grill-with-docs：先把需求审清楚

主线从 /grill-with-docs 开始。 这个 Skill 的作用不是立即写实现，而是像审问一样逐条追问决策点。 它会优先自己从代码库中查找可以确认的事实；只有查不到的部分，才继续向人提问。 目标是把双方对需求、约束和现状的理解对齐，而不是靠聊天中的模糊默契推进。

/prototype：用一次性原型验证不确定问题

如果中间存在靠讨论无法定论的问题，例如某个交互是否顺手，就从主线临时分岔到 /prototype。 这个 Skill 用来快速扔出一段一次性代码，以最小成本验证答案。 其边界也很明确：原型是“验完就扔”的，不是默认直接进入正式实现。

/to-spec：把对话整理成规格

当想法被澄清后，下一步是 /to-spec。 它负责把前面的对话结果整理为规格文档，使决策从对话上下文转为明确可引用的文档。

/to-tickets：把规格切成工单

规格确定后，再由 /to-tickets 把它拆成一张张工单。 这些工单之间会声明彼此的“卡点关系”，也就是依赖、阻塞或前后顺序关系。 工单既可以落在本地文件中，也可以接入 Linear 或 GitHub Issues。

/implement：按工单实施

每张工单接下来交给 /implement。 它不是无约束地直接生成代码，而是会在内部驱动其他纪律型 Skill。

/tdd：通过红绿重构循环保证代码可运行

/implement 内部会驱动 /tdd。 文中明确指出这里采用的是测试驱动开发循环，也就是先红灯、再绿灯、再重构。 它的意义在于，让 Agent 的实现始终带着可验证反馈，而不是凭空猜测代码是否有效。

/code-review：实现后自动审查

实现完成后，流程还会自动运行一次 /code-review 才算收工。 这一步不是单一维度检查，而是两条线并行：

• 一条检查代码坏味道
• 一条检查实现是否跑题

文中提到，代码坏味道检查内置了 12 条经典问题，其中明确举出的例子包括命名混乱、重复代码等。 两条审查线互不干扰，意味着项目同时把“代码质量”与“是否实现了正确目标”视为独立问题。

主线之外的额外入口

除了 idea → ship 主线，仓库还提供若干独立入口，用来处理不适合从头走主线的场景。

/triage：把外部粗糙反馈整理成可执行工单

对于别人扔过来的 bug 报告或需求，入口是 /triage。 它的职责是把原始、粗糙、信息不足的反馈，整理成 Agent 能直接接手的工单。 也就是说，它面向的是“输入质量差”的场景，而不是正式规格已经齐全的场景。

/diagnosing-bugs：先稳定复现，再修问题

对于莫名其妙、原因不明的疑难 bug，入口是 /diagnosing-bugs。 这个 Skill 明确拒绝瞎猜。 它要求先找到一个能够稳定复现问题的命令，然后才开始修复。 这条边界很重要：没有复现步骤，就不进入修复阶段。

/wayfinder：处理一次对话装不下的大规划

/wayfinder 用于“雾很大”的大型工程规划，尤其是那种复杂到一次对话根本装不下的问题。 它把整个规划过程比作在迷雾中认路。 具体做法是先把“已知”和“未知”分成两栏挂到工单系统上，然后一次次解决迷雾中的问题，直到路径足够清晰。 它在规划期间只产出决定，不产出代码。 因此它更像是大型探索型项目的导航 Skill，而不是实现 Skill。

/wayfinder 的更名背景与项目透明度

/wayfinder 还有一个很能体现项目风格的细节：它原来叫 decision-mapping。 根据公开更新日志，之所以改名，是因为作者后来认为旧名字“jargon 化且不准确”。 这说明项目并不把命名视为无关紧要的包装，而是把名称是否贴近实践、是否便于理解，当作工程质量的一部分。 更重要的是，项目把这类改名的心路过程直接写进公开更新日志。 这种做法体现出较强的透明度：不仅公开成果，也公开自己发现命名不当、再修正的过程。