matt-pocock-skills

Table Of Contents

  1. matt-pocock-skills
    1. 一、设计依据
      1. 1.1 Agent 未理解需求
      2. 1.2 Agent 缺乏领域语言
      3. 1.3 代码缺乏验证
      4. 1.4 架构熵增
    2. 二、技能目录
      1. 2.1 工程技能（Engineering）
      2. 2.2 生产力技能（Productivity）
      3. 2.3 其他技能（Misc）
    3. 三、关键机制
      1. 3.1 Grill Session 工作模型
      2. 3.2 垂直切片 vs 水平切片
      3. 3.3 反馈循环优先
      4. 3.4 深化机会（Deepening Opportunities）
    4. 四、与 Superpowers 的关系
      1. 4.1 定位差异
      2. 4.2 组合流水线

matt-pocock-skills

Matt Pocock Skills 是一套作用于 coding agent 的行为塑形技能集，针对 agent 在软件开发中的特定失败模式提供流程性干预。

一、设计依据

Matt Pocock Skills 围绕四种 agent 常见失败模式设计：

1.1 Agent 未理解需求

“没有人确切知道自己想要什么” — 《The Pragmatic Programmer》

开发中最常见的失败模式是理解偏差。用户认为 agent 理解其意图，而 agent 产出的结果不符预期。

干预手段：在执行前启动 grilling session，让 agent 对用户进行结构化提问，直至双方就需求达成一致。提供两档技能：

  • /grill-me — 非代码场景的拷问
  • /grill-with-docs — 带文档能力的拷问，同步更新 CONTEXT.md 和 ADR

1.2 Agent 缺乏领域语言

Agent 进入项目后缺乏领域术语知识，导致使用大量冗余描述。

干预手段：构建共享语言（Ubiquitous Language）。CONTEXT.md 作为术语表，使 agent 能使用精确的领域词汇。一致命名的附带收益包括：变量/函数/文件命名一致、代码库更易导航、agent 思维 token 消耗降低。

1.3 代码缺乏验证

即便需求对齐，agent 产出的代码仍可能包含缺陷。

干预手段：建立反馈循环（静态类型、浏览器访问、自动化测试）：

  • /tdd — 红绿重构循环，每次只写一个垂直切片
  • /diagnose — 结构化调试流程：复现 → 最小化 → 假设 → 仪表化 → 修复 → 回归测试

1.4 架构熵增

Agent 加速代码复杂度增长，导致代码库快速演变为”泥球”（ball of mud）。

干预手段：

  • /to-prd — 在创建 PRD 时审查模块设计
  • /zoom-out — 让 agent 从全局视角解释代码
  • /improve-codebase-architecture — 定期识别并实施深化机会（deepening opportunities）

二、技能目录

2.1 工程技能（Engineering）

setup-matt-pocock-skills

  • 时机：新仓库首次使用工程技能前
  • 职责：初始化 issue tracker 配置、triage 标签词汇表、领域文档布局
  • 产出：docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md

grill-with-docs

  • 时机：启动新需求、变更计划前
  • 职责：挑战现有计划与领域模型的兼容性，精炼术语，内联更新 CONTEXT.md 和 ADR
  • 流程：探索代码库 → 逐一提问（每次给出推荐答案）→ 精炼术语 → 场景压力测试 → 代码交叉验证 → 内联更新文档 → 谨慎创建 ADR
  • 限制：CONTEXT.md 不得包含实现细节，仅作为术语表；ADR 仅在满足”难以逆转、无上下文令人困惑、真实取舍”三条件时创建

to-prd

  • 时机：需求已讨论完毕，需形成正式文档
  • 职责：基于会话上下文和代码库理解合成 PRD，发布至 issue tracker
  • 规则：不面试用户，仅综合已有信息；识别需构建的模块并定位深层模块机会；PRD 模板包含问题陈述、解决方案、用户故事、实施决策、测试决策、范围外

to-issues

  • 时机：PRD 或计划已就绪，需拆解为可执行工作项
  • 职责：将计划拆解为独立可领取的 issue，使用垂直切片（tracer bullet）方式
  • 规则：每个切片横跨所有集成层（schema、API、UI、测试）；优先 AFK（无需人工介入）切片；发布前与用户确认粒度与依赖关系

triage

  • 时机：需要分类 issue、审查 incoming bug 或 feature request
  • 职责：通过状态机驱动 issue 流转
  • 状态角色：needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix
  • 流程：读取完整 issue 上下文 → 推荐分类 → 复现（bug）→ 拷问（如需）→ 应用状态

tdd

  • 时机：新功能开发或缺陷修复
  • 职责：通过红绿重构循环保障测试质量
  • 核心原则：
    • 测试验证行为而非实现细节，通过公共接口执行
    • 反对水平切片（先写所有测试再写所有代码），采用垂直切片（每次一个测试→实现→下一个）
    • 实现前需与用户确认接口设计与行为优先级

diagnose

  • 时机：硬缺陷、性能回归
  • 职责：通过六阶段结构化流程阻止猜测式调试
  • 流程：
    1. 构建反馈循环——快速、确定性、agent 可运行的 pass/fail 信号
    2. 复现——确认复现的是用户描述的缺陷
    3. 假设——生成 3-5 个可证伪假设，排序后展示给用户
    4. 仪表化——每个探测对应一个假设，一次只变一个变量
    5. 修复 + 回归测试——在正确接缝处写回归测试
    6. 清理 + 事后分析——问”什么可以阻止此缺陷”

improve-codebase-architecture

  • 时机：代码库存在架构摩擦、需要重构
  • 职责：识别深化机会（deepening opportunities），将浅模块重构为深模块
  • 核心概念：Module / Interface / Depth / Seam / Adapter / Leverage / Locality
  • 判断工具：删除测试——若删除模块后复杂度消失，则该模块为透传；若复杂度在 N 个调用者处重新出现，则模块在发挥价值
  • 流程：探索 → 候选列表 → 逐一拷问 → 内联更新文档

zoom-out

  • 时机：需要理解不熟悉的代码区域
  • 职责：从更高抽象层提供代码映射，使用领域术语解释模块与调用者关系

prototype

  • 时机：需验证设计方向
  • 职责：构建一次性原型回答具体问题
  • 两条路径：终端应用（逻辑/状态验证）或 UI 变体（多方案切换）
  • 规则：一次性、单命令运行、无持久化、无测试、完成后删除或吸收决策

2.2 生产力技能（Productivity）

grill-me

  • 时机：非代码场景需要需求对齐
  • 职责：逐一提问直至双方达成共享理解，无文档更新

caveman

  • 时机：需要压缩通信 token 消耗
  • 职责：超压缩通信模式，减少约 75% token

handoff

  • 时机：需要将当前会话交接给其他 agent
  • 职责：压缩会话为交接文档，引用已有 artifact 而非重复内容

write-a-skill

  • 时机：需要创建新技能
  • 职责：提供正确的技能结构与渐进式披露指南

2.3 其他技能（Misc）

git-guardrails-claude-code

  • 时机：需要防止危险 git 操作
  • 职责：通过 Claude Code hooks 拦截 push、reset、clean 等危险命令

migrate-to-shoehorn

  • 时机：迁移测试文件中的类型断言
  • 职责：将 as 断言迁移至 @total-typescript/shoehorn

三、关键机制

3.1 Grill Session 工作模型

Grill session 是 Matt Pocock 体系中最核心的机制。其工作方式：

  1. 代码库探索：读取 CONTEXT.md 和 docs/adr/，理解现有领域模型
  2. 逐一提问：每次一个问题，给出推荐答案，等待反馈
  3. 术语校准：当用户使用模糊或冲突术语时，提议精确的规范术语
  4. 场景压力测试：构造边界案例，迫使用户明确概念边界
  5. 代码交叉验证：将用户所述情况与代码实际行为对比，发现矛盾时指正
  6. 内联文档更新：术语一经确定即写入 CONTEXT.md，不批量处理

3.2 垂直切片 vs 水平切片

水平切片[错误]:
  RED:   test1, test2, test3, test4, test5
  GREEN: impl1, impl2, impl3, impl4, impl5

垂直切片[正确]:
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  RED→GREEN: test3→impl3
  ...

水平切片的问题：测试在批量编写时会测试”想象的行为”而非”实际的行为”，导致测试对行为变化不敏感。垂直切片让每个测试从上一个实现中学习，保证测试反映真实行为。

3.3 反馈循环优先

diagnose 技能强调：在进入调试循环前，必须建立快速、确定性、agent 可运行的 pass/fail 信号。无此信号不得进入假设阶段。反馈循环的构建方式包括：失败测试、curl/HTTP 脚本、CLI 调用、headless browser、重放捕获数据、一次性 harness、property/fuzz 循环、bisection harness、差分循环。

3.4 深化机会（Deepening Opportunities）

术语 定义
Module 有接口和实现的任何单元（函数、类、包、切片）
Interface 调用者需了解的全部信息：类型、不变量、错误模式、顺序、配置
Depth 小接口封装大行为 = 深；接口与实现复杂度接近 = 浅
Seam 接口所在位置；可在不原地编辑的情况下改变行为
Adapter 在 seam 处满足接口的具体实现
Leverage 调用者从深度中获得的收益
Locality 维护者从深度中获得的收益：变更、缺陷、知识集中在一处

四、与 Superpowers 的关系

4.1 定位差异

维度 Matt Pocock Skills Superpowers
定位 上游需求管理与工程语境建设 下游交付流程控制
核心关注 人与 agent 的对齐、领域语言、代码设计 流程门禁、防止 agent 跳过步骤
启动方式 /setup-matt-pocock-skills + 按需调用 会话启动自动注入
需求阶段 grill → PRD → issues brainstorming → plans
实施阶段 tdd、prototype TDD、subagents、worktree
质量阶段 diagnose verification、code review
强制程度 推荐式（技能供用户调用） 门禁式（必须遵守）

4.2 组合流水线

前者负责需求管理与工程语境建设，后者负责受控交付流程。两者可组合为完整流水线。

需求池
  │
  ▼
Matt Pocock Skills:  grill → PRD → issues → triage → ready-for-agent
  │
  ▼
Superpowers:         brainstorming → plans → worktree → TDD → subagents → review → PR
  │
  ▼
交付

Matt Pocock Skills 处理”要做什么”，Superpowers 处理”如何有质量地交付”。前者将模糊需求转化为结构化的就绪工作项，后者确保这些工作项以受控流程实施。