Lesson 0002 · 深课 · 配置层

setup-matt-pocock-skills

你刚 clone 了一个仓库，想让 AI 用这套工程流程帮你干活。正式开工前，要先在这个仓库里跑一次 /setup-matt-pocock-skills： 它会一边翻你的仓库、一边问你几组问题，把「issue（工作票）放在哪个系统、分拣标签叫什么、领域文档怎么摆」这三件事定下来， 写成 docs/agents/ 下的几个配置文件，并在 CLAUDE.md 或 AGENTS.md 里加一段指路说明。 这节课把它的 SKILL.md 和自带的模板文件逐段拆开：它会看什么、问什么、写什么、写出来的东西被谁读。 学完你应当能预判它会写出的每个文件，并且分得清什么时候直接手改文件、什么时候才值得重跑它。

1. 它在整个系统里站在哪、谁能启动它

在 Lesson 0001 的三层地图里， setup-matt-pocock-skills 独占配置层——0001 打的比方是「开店前的装修」： 它在你的每个目标仓库里跑一次，把约定写成文件。 它自己不写业务代码、不发工单、不做分拣状态机； 它只产出其它工程 skill 假定已经存在的那些配置。

这个仓库里还有一份写给人看的说明（agent 干活时以 SKILL.md 为准，这份只是同一内容的通俗版，别拿它当行为依据）： docs/engineering/setup-matt-pocock-skills.md · 发布后的 URL 长这样：https://aihero.dev/skills-setup-matt-pocock-skills

2. 什么时候必须跑、什么时候别跑

它的 description 原文只有一句： Run once before first use of the other engineering skills.（在第一次使用其它工程 skill 之前跑一次。） 写给人看的文档说得更明确：每个目标仓库一次，在第一次用任何其它工程 skill 之前。

2.1 为什么说它是必须先跑的前提，而不是「可选项」

好几个只能人启动的工程 skill，在正文第一屏就写明「我依赖 setup 产出的配置」；缺了配置，它们会反过来要求你先跑 setup：

写给人看的文档里有一段「It's working if」（怎么算配置成功），可以直接当验收标准用： docs/agents/ 下出现 issue-tracker.md 和 domain.md（装了 triage 的话还有 triage-labels.md）， 且 CLAUDE.md 或 AGENTS.md 里出现 ## Agent skills 这一段； 之后 triage / to-tickets 能直接作用在正确的位置、打正确的标签，而不是靠猜或反复问你。

2.2 什么时候不要重跑它

• 只是想改标签字符串、改 CLI 习惯、打开「外部 PR 也进分拣队列」的开关 → 直接编辑 docs/agents/*.md 就行（怎么改见第 10 节）。
• 配置已经在了，只想开始干活 → 跳过 setup，直接 grill / to-spec / triage……
• SKILL.md 的收尾段只给重跑留了两个正当理由：换工单系统，或者推倒重来。

3. 五步流程总览（探索 → 完成）

SKILL.md 的流程是固定骨架，五步必须按顺序推进。提问节奏是「一组一问」——一次只问一组问题，你答完才进下一组，不会一口气甩给你一张大表单。

整个流程贯穿三条原则： 推荐答案写在最前面（你回一个词，比如 yes，就算接受）； 探索阶段已经有答案的问题整组跳过（没装 triage 就不问 B；仓库不是 monorepo，C 就直接按默认布局写、不问你）； 先确认再写（第 3 步的草稿你可以改，改完它才落笔）。

4. 第 1 步：探索阶段它翻哪些东西

SKILL.md 列了一张「看现状、不假设」的信号清单。下表把每个信号对应到它影响的后续决定：

5. 第 2 步：汇报 + A·B·C 三组提问，何时整组跳过

汇报完仓库现状，就按顺序一组一组地问：一次一组、你答完再进下一组。 每组都先把推荐答案摆在最前面；只有真正需要你做决定的分叉点，才附一行解释。

5.1 A 组 —— 工单系统（几乎总会问）

SKILL 原文的意思是这样的：「issue tracker」就是这个仓库的 issue（工作项）放在哪里。 to-tickets、triage、to-spec、qa 这些 skill 都要读写它——所以得让它们知道： 是调 gh issue create，还是往 .scratch/ 写 markdown 文件，还是按你描述的其它流程。 选你实际用来跟踪工作的那个地方。

默认怎么推荐：这套 skill 是为 GitHub 设计的。remote 指向 GitHub，就推荐 GitHub；指向 GitLab（gitlab.com 或自建实例），就推荐 GitLab；其它情况（或你有自己的偏好），端出四个选项。所谓模板（skill 里叫 seed），就是 skill 自带的成品文件，setup 时照抄或按你的回答微调后写进你的仓库：

选择会记录在 docs/agents/issue-tracker.md。 GitHub / GitLab 模板里有一个开关叫「PRs / MRs as a request surface」——意思是「把外部人提的 PR 也当作需要分拣的请求入口」，默认是关的（off）；setup 过程中不会主动提这个开关。 你如果想让外部 PR 进分拣队列，事后自己在文件里把它改成 yes。

5.2 B 组 —— 分拣标签词汇（有条件才问）

如果 triage 已安装，只问一个问题：

Do you want to keep the default triage labels?（要保留默认的分拣标签吗？推荐回答：yes）

默认有五个角色，标签字符串就等于角色名本身： needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。 答 yes → 照模板 triage-labels.md 原样写入。 答 no（常见原因：你的 tracker 上已经有 bug:triage 这类标签）→ setup 会收集一份一一对应的替换表（overrides），让 triage 去打你已有的标签，而不是新建一套重复标签。

这张映射表的意思是：左列是这套 skills 内部统一使用的标准角色名（canonical name，skill 之间约定好的叫法）；右列是你的 tracker 上真实存在的标签字符串； skill 说到某个角色时，查右列。以后要改，只改右列就行，不用动 skill 源码。

5.3 C 组 —— 领域文档（几乎总是不问，直接按默认写）

• 默认 single-context（单份术语表）：根目录一个 CONTEXT.md，加上 docs/adr/。几乎所有仓库都适合这样 → 不提问，直接按此写。
• 只有当探索阶段发现 monorepo 信号时，才提供 multi-context（多份术语表）这个选项：根目录放一个 CONTEXT-MAP.md 当目录，指向每个 context 各自的 CONTEXT.md，并跟你确认要哪种布局。

注意：setup 写的是 docs/agents/domain.md 里的使用规则和布局说明， 它不会顺手创建 CONTEXT.md 本体。 domain 模板写得很明白：文件不存在就静默继续，不建议你「先建一个空的 CONTEXT」。 真正负责创建术语表和 ADR 的是 /domain-modeling（由 /grill-with-docs、/improve-codebase-architecture 等在需要时才调用它来创建）。

6. 四种工单系统的模板有什么差别

三份内置模板结构差不多：先约定常规操作（创建 / 读取 / 列表 / 评论 / 打标签 / 关闭）， 再约定「发布 / 拉取」各是什么意思，最后附一节给 /wayfinder 专用的 Wayfinding operations（寻路操作集）。 选 Other 则完全依赖你写的那段自然语言描述——wayfinder / to-tickets 能不能顺利干活，取决于你那段描述有没有覆盖同样的操作。

6.1 常规操作对照

6.2 Local markdown 的目录约定（to-tickets / triage 都靠它）

• 一个 feature 一个目录：.scratch/<feature-slug>/
• 需求文档：.scratch/<feature-slug>/spec.md
• 实现票：.scratch/<feature-slug>/issues/<NN>-<slug>.md，从 01 开始编号——禁止把所有票合并成一个文件
• 分拣状态：写在 issue 文件顶部的 Status: 行
• 讨论历史：写在文件底部的 ## Comments 小节

6.3 Wayfinding operations（wayfinder 专门读这一节）

三份模板都定义了六件事：map（决策地图）、child ticket（子票）、blocking（谁挡谁）、frontier（没被挡住、现在就能开工的票）、claim（认领）、resolve（解决）。 这就是 wayfinder 敢说自己「不挑工单系统」（tracker-agnostic）的真正底气：它的正文只讲概念，具体物理操作以 setup 写进你仓库的这一节为准。

7. 第 3、4 步：先给你看草稿，再精确写文件

7.1 给你看的草稿清单

写入任何文件之前，setup 必须把下面这些东西完整亮出来，而且你可以改：

1. 将写进 CLAUDE.md 或 AGENTS.md 的 ## Agent skills 整段全文
2. docs/agents/issue-tracker.md 全文
3. docs/agents/domain.md 全文
4. docs/agents/triage-labels.md 全文——仅当 triage 已安装且 B 组问过

7.2 实际写出哪些文件

7.3 domain.md 模板里实际写了什么（就是「怎么用」的规则）

AI 在探索代码库之前应该先读：

• 根目录的 CONTEXT.md；如果根目录有 CONTEXT-MAP.md，先读它，再读相关 context 的 CONTEXT
• docs/adr/ 里和手头工作相关的 ADR；multi-context 布局还要查 src/<context>/docs/adr/

缺这些文件就静默继续——不报警，也不逼你先建空文件。

给领域概念起名字时：用术语表里的词，不要漂移到「术语表明确说不要用」的同义词。想用的概念不在表里，只有两种可能：要么你在发明这个项目根本不用的叫法，要么它该交给 /domain-modeling 补进术语表。

输出和已有 ADR 冲突时：必须明确说出来，禁止悄悄覆盖。

8. ## Agent skills 这段写进哪个文件、怎么写

8.1 选哪个根文件——三条规则

1. 已经有 CLAUDE.md → 只编辑它
2. 没有 CLAUDE.md、但有 AGENTS.md → 编辑它
3. 两个都没有 → 问你要创建哪一个；不替你选

8.2 这一段的模板（来自 SKILL.md）

## Agent skills

### Issue tracker

[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.

### Triage labels

[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.

### Triage labels 小段和 triage-labels.md 同一个条件：只有 triage 已安装且 B 组问过才出现。 每行 one-line summary 要写你确认后的真实选择（比如「GitHub Issues via gh」），不要留个空壳占位。

历史上，其它 skill 是通过这一段来找到 tracker 文档位置的——先看指路说明再去找文件，而不是把路径写死在 skill 里。 wayfinder 等 skill 就曾从「写死 docs/agents/issue-tracker.md」改成跟着同一个指路走，免得文档挪了位置之后悄悄退回本地 tracker 的行为。 作者级排错经验：如果 AI 找错了工单系统，先看 ## Agent skills 指的对不对，再看被指的那个文件的内容。

9. 第 5 步：收尾，以及写出的文件被谁读

收尾时 AI 应该：宣布 setup 完成；点名哪些工程 skill 会读这些文件； 提醒以后可以直接手改 docs/agents/*.md；只有换工单系统或推倒重来才需要重跑这个 skill。

9.1 谁读哪个文件（一张表）

另：implement 流程收尾会调 code-review，所以也间接依赖 tracker 文档； grill-with-docs 通过 domain-modeling 写 CONTEXT/ADR，布局要和 domain.md 声明的 single / multi 一致。

10. 之后想改配置：手改文件还是重跑

SKILL.md 的收尾段是权威分界，原文： edit docs/agents/*.md directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch. 翻译过来：以后直接改 docs/agents/*.md 就行；只有换工单系统、或者想推倒重来，才需要重跑这个 skill。

11. 合理的灵活用法与常见错误

11.1 这些「偏离」是合法的

• remote 是 GitHub，却选 Local：一个人单干、或暂时不想用 Issues 时完全合法；汇报阶段应当讲清代价（协作时别人看不到、wayfinder 的地图没有可分享的 URL 等）。
• 装了 triage，但答 no 并填自己的映射：这正是适配已有标签体系的正确姿势。
• 没装 triage 所以跳过 B：setup 仍然是完整的，会写出 issue-tracker + domain；以后若装了 triage，记得补上 B 的产物（手写 labels 文件 + Agent skills 小段，或者干脆重跑）。
• 选 Other 并写足细节的描述：Linear / Jira 都支持；效果好坏取决于你有没有写清与内置模板同等覆盖面的操作。
• Monorepo 仍选 single-context：探索阶段发现信号只是「有资格问你」；你完全可以坚持 single（比如工作其实只动一个包）。

11.2 常见错误

12. 检索练习

先尽量不回看上文。每题选项长度对齐。核对后回到对应章节补洞。

13. 一手材料与下一课

本课主一手材料（请打开原文读，不要只背本页）：

• skills/engineering/setup-matt-pocock-skills/SKILL.md —— 流程、A/B/C 三组提问、写入规则、收尾段的分界（agent 干活时以它为准）
• issue-tracker-github.md · issue-tracker-gitlab.md · issue-tracker-local.md —— 三种工单系统的操作约定和 Wayfinding operations
• triage-labels.md · domain.md —— 标签映射表模板和 domain「怎么用」规则模板
• agents/openai.yaml —— Codex 一侧的显示名 + allow_implicit_invocation: false
• docs/engineering/setup-matt-pocock-skills.md —— 写给人看的版本（什么时候跑、要做哪三个决定、怎么算配置成功）
• 下游 skill 的依赖原文： to-spec · to-tickets · triage · wayfinder · code-review
• .agents/invocation.md —— 两种启动方式的约定；只能人启动的 skill 不能被别的 skill 调用
• ask-matt —— 地图里 setup 的位置

建议下一课（0003）： grilling 一族——grilling 这套基本功（面试纪律的全文所在），加上 grill-me / grill-with-docs 两个写得很薄的入口（正文只有几行，实际纪律都在被调用的文件里）。 配置层就绪后，主流程通常从「把模糊想法问清楚」开始；深课会拆「一次只问一个问题」的纪律，以及它和 domain-modeling 的分工边界。