Offline handbook · v1

Matt Pocock Skills
中文使用手册

根据任务的清晰度、规模和问题类型选择合适的 AI 编程工作流：先对齐，再以小而可验证的切片交付。

场景化流程可复制提示词离线可打开支持打印

快速开始

每个仓库首次使用前：运行一次 /setup-matt-pocock-skills，配置 Issue tracker、triage 标签和领域文档位置。后续工程流程都以此配置为基础。

先澄清

在代码库内从 /grill-with-docs 开始，明确行为、边界、术语和关键决策。

按规模规划

单会话可完成则实施；跨会话时先生成 spec 和可独立交付的 Issue。

持续验证

/implement 通过 /tdd 推进，最后以 /code-review 收尾。

三问分流

先问什么？	答案为“是”	答案为“否”
需求、模块边界或关键决策仍说不清？	先用 `/grill-with-docs`；若大到一个会话无法理清，用 `/wayfinder`	继续下一问
工作会跨多个会话，或可拆成多个独立交付的切片？	`/to-spec` → `/to-tickets` → 每个 Issue 在新会话中 `/implement`	在当前会话中 `/implement`
当前要处理的是异常、错误结果、性能下降或偶发现象？	`/diagnosing-bugs`：先建立可重复、能变红的反馈循环	使用前两问决定的需求实现流程

不要只按改动行数判断。一个短小但涉及权限、状态迁移或跨服务契约的改动，仍值得先澄清和拆分；行为和边界明确的局部能力则可直接 test-first 实现。

主工作流：从想法到交付

/grill-with-docs澄清需求与术语

→

/to-spec多会话时固化规格

→

/to-tickets拆成垂直切片

→

/implementTDD、检查、review

小而明确的改动可跳过 /to-spec 与 /to-tickets，从 /grill-with-docs 直接进入 /implement。不在代码库内工作时，用无状态的 /grill-me 替代。

四类研发场景

场景 01

从零实现一个模块

模块不存在，需要定义职责、公共接口、数据流或与现有系统的边界。

目标明确，单会话可完成

/grill-with-docs → /implement

先确认模块职责和测试接缝，再以垂直切片实现。

包含多个能力或边界未知

/grill-with-docs → /to-spec → /to-tickets → /implement

若连技术路线或优先级都不明确，先用 /wayfinder 解决决策问题。

将稳定的领域术语写入 CONTEXT.md；只有难逆转、需要解释、且存在真实权衡的决策才写 ADR。
在 /implement 中以“一个公共接缝、一个失败测试、一个最小实现”推进。
原型用于回答设计问题，不应被直接当作生产代码提交。

推荐发起方式

/grill-with-docs
我要从零实现“优惠规则引擎”模块。它需要被结算服务调用，
目前已知输入是订单和用户信息，输出是可叠加的优惠明细。
请先帮我厘清模块职责、公共接口、规则冲突和测试接缝；
确定后再决定是否需要拆成多个 Issue。

场景 02

在现有代码库新增业务功能

已有模块和调用链，需要增加用户可见能力，例如审批流程、筛选条件或支付方式。

小而明确：/grill-with-docs → /implement
跨模块或多会话：/grill-with-docs → /to-spec → /to-tickets → /implement

不要从“修改哪些文件”开始；先确认用户行为、业务规则、失败处理、兼容性和影响范围。
状态模型或 UI 方案无法靠讨论定夺时，走 /handoff → /prototype → /handoff，再回到主流程。
多会话时，spec 和 Issue 在同一个上下文中生成；每个 Issue 由新会话从 /implement 开始。

推荐发起方式

/grill-with-docs
在现有订单后台增加“部分退款”能力。请先阅读相关领域文档和订单、
支付模块，确认允许退款的状态、金额校验、幂等要求、权限和审计行为。
这是一个可能跨订单与支付服务的功能；需求明确后，请建议直接实施还是
生成 spec 和拆分 Issue。

场景 03

在现有模块内新增方法或局部能力

调用方、模块职责和预期行为已明确，例如增加查询、校验或确定的状态转换。

行为和测试接缝明确

/tdd

先确认公共接口及测试接缝，再红—绿循环实现。

影响范围仍不确定

/grill-with-docs → /implement

涉及调用方、持久化格式、权限、缓存或状态机时，不应视作局部改动。

测试通过公共接口验证可观察行为；不要 mock 内部协作者，也不要测试私有实现。
/tdd 适合已确定的具体行为；/implement 适合需要完整实施、检查和 review 流程的工作。

推荐发起方式

/tdd
请为 Inventory 的公共接口新增 reserve(sku, quantity)。
已确认规则：库存不足时返回 InsufficientStock；成功时减少可用库存。
测试只通过 Inventory 的公开接口观察结果，不测试内部仓储实现。
先确认这个测试接缝，然后按红—绿循环实现。

场景 04

根据现象定位并修复 bug

出现报错、结果错误、性能回归、偶现问题，或需要从用户现象查找根因。

/diagnosing-bugs → 最小复现 → 假设与验证 → 修复 + 回归测试

第一步不是读代码猜原因。必须先建立紧凑、可重复、能捕获该现象的反馈循环：失败测试、HTTP/CLI 脚本、浏览器脚本、请求回放或最小 harness 都可以。若没有循环，应索取环境或脱敏后的证据，而不是直接改代码。

报告现象时提供

实际结果与预期结果
步骤、输入和发生频率
环境、版本、时间范围和近期变更
脱敏后的日志、请求或性能数据

完成前确认

原始复现不再出现
最小复现已成为回归测试
调试日志与临时代码已清理
无合适测试接缝时记录架构问题

推荐发起方式

/diagnosing-bugs
生产环境中，已支付订单偶尔显示为“待支付”。预期支付回调成功后订单应稳定
显示“已支付”。复现率约 5%，集中在移动端支付；附件是已脱敏的回调 payload
和订单状态日志。请先建立一个能稳定捕获该状态不一致的反馈循环，再最小化复现、
列出可证伪假设并验证；在未建立循环前不要直接修改代码。

外部 Issue 信息不足时：先用 /triage 补齐信息并标为 ready-for-agent。由 /to-tickets 生成的 Issue 已经可供 Agent 实施，不需要再次 triage。

新会话如何准确实施已拆分的 Issue

核心原则：用引用切入，不用回忆切入。每个由 /to-tickets 生成的 Issue 都应能在一个全新的上下文中完成。新会话以 当前 Issue、父级 spec、长期领域文档和代码当前状态为事实来源，而不是依赖上一轮聊天记录。

标准切入步骤

1. 选择 frontier确认所有 Blocked by 已完成

→

2. 读取契约Issue、spec、CONTEXT、ADR

→

3. 核对现状检查前置代码、接口和测试

→

4. 受限实施按验收标准 TDD，不扩范围

→

5. 验证收尾测试、review、提交、更新状态

新会话开始时应读取什么

当前 Issue：完整正文、评论、What to build、验收标准和 Blocked by。
父级 spec：业务规则、Implementation Decisions、Testing Decisions 与 Out of Scope。
长期上下文：相关 CONTEXT.md、ADR 和仓库的 Agent 指令。
当前代码：前置 Issue 实际落下的改动、相似功能、公共接口与现有测试。

实施边界

只实现当前 Issue 的 Acceptance criteria，不顺手带入后续 Issue。
先确认测试接缝与验证命令，再按 /tdd 的红—绿循环推进。
若父级 spec、Issue 和代码现状互相矛盾，停止并请求澄清；不要自行重划需求或猜测业务规则。
提交前运行局部验证、完整测试与 /code-review。

示例：实施“部分退款 API”

假设“部分退款”需求已经拆为以下 Issue：

Issue	交付内容	Blocked by
`#421`	建立部分退款的领域状态和金额校验	无，可立即开始
`#422`	提供部分退款 API	`#421`
`#423`	在订单后台展示并发起部分退款	`#422`
`#424`	记录退款审计事件	`#422`

当 #421 已完成后，#422 才处于可实施的 frontier。此时开一个干净会话，只以 #422 为本次工作范围。

GitHub Issue：可直接复制的新会话提示词

/implement

实施 GitHub Issue #422「提供部分退款 API」。

请将 #422 作为本次工作的唯一实施范围。开始修改前：

1. 读取 #422 的完整内容、评论和验收标准；
2. 确认前置 Issue #421 已完成，并检查前置改动已存在于当前代码；
3. 阅读 #422 引用的父级 spec，尤其是业务规则、测试决策和 Out of scope；
4. 阅读相关 CONTEXT.md 和 ADR；
5. 查找现有退款 API 及其测试，确认应测试的公共接缝和可运行的测试命令。

随后按 TDD 实施 #422 的验收标准。不要实现 UI、审计事件或其他后续
Issue 的内容；如果当前 Issue 无法在既定边界内完成，请说明缺失的决策或
阻塞项，而不要自行扩大范围。

在开始写代码前，请用不超过五条内容确认：交付行为、已确认的前置 Issue、
不包含的范围、测试接缝和验证命令。

本地 Markdown Issue：替换实施目标即可

/implement

实施 .scratch/partial-refund/issues/02-expose-partial-refund-api.md。

先读取该文件、它的 Blocked by、父级 spec、CONTEXT.md 和相关 ADR，
再检查前置 Issue 已落地的代码。严格按该 Issue 的验收标准实施；如果
信息不足或前置依赖未完成，请说明阻塞原因，不要根据上一个会话的记忆猜测。

让 Issue 本身成为可靠的交接契约

Issue 至少应包含

What to build：用户可感知的端到端行为，而不是层级任务清单。
Acceptance criteria：可验证、可判定完成。
Blocked by：所有真实前置依赖。
父级 spec 的引用，以及必要的 prototype 决策引用。
ready-for-agent 状态。

建议补充，但不要写死实现细节

Out of scope：例如“不包含退款 UI 与审计导出”。
测试决策或验证方式的引用，帮助找到正确接缝。
避免固化具体文件路径和代码片段；它们容易过期，应由新会话根据当前代码探索。
发现契约冲突时，把问题带回 Issue/spec，而不是静默改变范围。

通常不需要在两个 Issue 之间使用 /handoff。Issue 与 spec 已经是跨会话的正式交接物。/handoff 更适合在同一 Issue 未完成时切换目录、交给其他人、转去做原型，或保存尚未沉淀进 Issue/spec 的推理过程。

其他常见入口

Issue 或需求堆积

/triage → agent-ready Issue → /implement

适合处理别人提交的原始 bug 报告、需求或外部 PR。

大型模糊的绿地项目

/wayfinder → /to-spec → /to-tickets → /implement

先产生决策地图，不要把未澄清的方向直接交给实现流程。

验证状态模型或 UI 选择

/handoff → /prototype → /handoff → 主流程

原型用来回答一个具体设计问题，并保留结论作为后续决策依据。

代码库维护

/improve-codebase-architecture → /grill-with-docs → 主流程

先发现可加深模块的候选项，再挑选一个进入正常需求流程。

已发生 merge/rebase 冲突

/resolving-merge-conflicts

按双方的一手意图逐 hunk 解决并完成操作，而不是简单选一侧或 abort。

只想审查现有改动

/code-review

基于固定点审查 diff：同时检查编码标准与是否忠实实现原始 spec。

Skill 速查

没有匹配的 Skill。

Engineering · 用户手动调用

Skill	何时使用
`/ask-matt`	不确定该选哪个 skill 或工作流。
`/grill-with-docs`	在代码库内澄清计划，同时沉淀领域术语和 ADR。
`/triage`	处理别人提交、信息尚不完整的 Issue。
`/to-spec`	将已讨论清楚的内容综合成 spec。
`/to-tickets`	将 spec 拆成带依赖、可独立交付的垂直切片。
`/implement`	按 spec 或 Issue 实施，驱动 TDD 和代码审查。
`/wayfinder`	大型、路径不清晰的项目或功能。
`/improve-codebase-architecture`	发现并评估代码库的结构改进机会。

Engineering · 模型可调用

Skill	何时使用
`/tdd`	已确认公共接口和测试接缝时，test-first 构建具体行为。
`/diagnosing-bugs`	疑难 bug、性能回归、偶现问题的纪律化诊断。
`/prototype`	用一次性代码回答状态模型或 UI 设计问题。
`/research`	委托后台 Agent 基于一手来源进行带引用调研。
`/domain-modeling`	处理模糊或重载的领域术语，维护 `CONTEXT.md`。
`/code-review`	从标准和 spec 两个维度审查现有 diff。
`/resolving-merge-conflicts`	解决进行中的 merge 或 rebase 冲突。

Productivity · 常用

Skill	何时使用
`/grill-me`	不在代码库内，仍需要澄清计划或设计。
`/handoff`	切换目录、原型、协作者或需要携带上下文时。
`/teach`	跨多个会话系统学习一个概念或技能。
`/wait-what`	当前解释没有理解，希望 Agent 换一种易懂的方式说明。

上下文管理与实施纪律

保持规划阶段连续

从 /grill-with-docs 到 /to-spec、/to-tickets 应尽量在同一上下文中完成。这样需求澄清、规格和 Issue 建立在相同的判断之上。

每个 Issue 重新开始

每个 /implement 应在新会话中从自己的 Issue 开始。已拆分的 Issue 本身就是实现所需的上下文，上一项的工作记忆应被丢弃。

关注 Smart Zone

会话接近模型的高质量推理窗口时，不要强行延续。优先在阶段边界 compact；需要跨目录、交给同事或带往原型时使用 /handoff。

测试与 review

测试验证公共接口的行为，避免与实现细节耦合。/implement 结束前应运行类型检查、针对性测试、完整测试套件，并使用 /code-review 审查 diff。

常见问题

我记不住这些 Skill，怎么办？

使用 /ask-matt，并说明你的目标、当前已知信息和约束。它会把场景路由到合适的用户可调用 skill。

/grill-me 和 /grill-with-docs 怎么选？

在代码库中使用 /grill-with-docs：它会建立或更新 CONTEXT.md、ADR 等长期上下文。不在工作目录或是非代码场景时，使用无状态的 /grill-me。

什么时候直接 /implement，什么时候先拆 Issue？

能在一个会话内完成、边界明确的工作可直接实施。跨多个会话，或可拆为多个独立交付能力时，先 /to-spec 再 /to-tickets。

/triage 和 /to-tickets 有什么区别？

/triage 用来分类、补充别人提交的原始 Issue；/to-tickets 把自己的 spec 拆成已经 agent-ready 的实现 Issue，后者无需再次 triage。

诊断 bug 时为什么不能直接猜根因？

没有能针对该现象变红的反馈循环，推测很难验证，且容易修错问题。先建立最小、快速、确定的复现，再提出可证伪假设并逐一实验，最终将最小复现留作回归测试。

Matt Pocock Skills中文使用手册

快速开始

先澄清

按规模规划

持续验证

三问分流

主工作流：从想法到交付

四类研发场景

目标明确，单会话可完成

包含多个能力或边界未知

行为和测试接缝明确

影响范围仍不确定

报告现象时提供

完成前确认

新会话如何准确实施已拆分的 Issue

标准切入步骤

新会话开始时应读取什么

实施边界

示例：实施“部分退款 API”

让 Issue 本身成为可靠的交接契约

Issue 至少应包含

建议补充，但不要写死实现细节

其他常见入口

Issue 或需求堆积

大型模糊的绿地项目

验证状态模型或 UI 选择

代码库维护

已发生 merge/rebase 冲突

只想审查现有改动

Skill 速查

Engineering · 用户手动调用

Engineering · 模型可调用

Productivity · 常用

上下文管理与实施纪律

保持规划阶段连续

每个 Issue 重新开始

关注 Smart Zone

测试与 review

常见问题

Matt Pocock Skills
中文使用手册