本地 Markdown 文件全景图：谁创建、何时创建、何时被改

1. 为什么要按文件而不是按 skill 看

回忆 0001 课的系统地图：这组 skill 分成配置层（setup-matt-pocock-skills 跑一次）、 编排层（你手动输入斜杠命令启动的完整流程）和纪律层（被别的 skill 反复调用的基本功）。 那张图回答的是「我该启动哪个 skill」。但日常用久了你会遇到另一类问题，而那张图答不上来：

• 仓库里多了一个 .scratch/login-flow/issues/03-validate-token.md，这是谁写的？我该手改它吗？
• 我想把 GitHub Issues 换成本地文件工单，要改哪个文件、要不要重跑 setup？
• CONTEXT.md 里一个术语不对，直接编辑安全吗，还是有 skill 会覆盖我的修改？
• 哪些文件是「skill 的私有财产」，哪些是「人也可以随时手改的配置」？

这些问题的共同点是：它们都问文件的归属和生命周期。MISSION.md 里的目标说得明白—— 要「看见场景就知道每个 skill 会改仓库/tracker 里的什么」。这一课就是把这个能力一次性补齐： 先把全部本地 md 文件按「写它的那一层」分成四类，再逐类讲清创建时机和修改时机， 最后汇成一张可以随时回来查的大表。

2. 总览：四类文件 + 仓库之外

把所有本地 md 文件摆在一起，它们清楚地分成四堆。分类的标准是谁在什么时候写它：

还有第五类不在仓库里：handoff 的交接文档和 improve-codebase-architecture 的 HTML 报告都写进操作系统的临时目录，刻意不落在仓库里—— 因为它们是会话级的消耗品，不该污染版本历史。

把同一件事画成一张「仓库地图」会更直观。下面这棵树按四层配色， 每个文件后面跟着它的创建者和修改者——这就是本课大表的图形版：

your-repo/
├─ CLAUDE.md └「## Agent skills」区块 · setup 编辑已存在者 · 手改/重跑 setup
├─ docs/agents/
│  ├─ issue-tracker.md · setup 必写 · 手改（如 PR 旗标）
│  ├─ domain.md · setup 必写 · 重跑 setup 才变
│  └─ triage-labels.md · setup 条件写（装了 triage）· 手改
├─ CONTEXT.md · 第一个术语解决时才出生 · domain-modeling 持续内联更新
├─ CONTEXT-MAP.md · 多上下文布局专用 · 没人负责建，需手动补
├─ docs/adr/NNNN-*.md · 三重门槛懒创建 · 推翻不删，新 ADR 标取代
├─ .scratch/<feature>/spec.md · to-spec 写一次即冻结
├─ .scratch/<feature>/issues/NN-*.md · to-tickets 生 · triage 改状态 · prototype 追加指针
├─ .scratch/<effort>/map.md + issues/ · wayfinder 画地图 · 认领/解决/翻案时持续改
├─ .out-of-scope/<concept>.md · triage 拒绝 enhancement 才建 · 翻案时整文件删
├─ MISSION.md · RESOURCES.md · NOTES.md · GLOSSARY.md · teach 懒创建 · 持续维护
├─ learning-records/NNNN-*.md · teach 四类事件触发 · 推翻标 superseded 不删
└─ （仓库外）$TMPDIR/ · handoff 交接文档 · 架构评审 HTML 报告

分层图：0001 系统地图 · 领域语言：本仓库自己的 CONTEXT.md

3. 配置层：setup 写一次的文件

场景：你刚在一个新仓库装好这套 skill，跑 /setup-matt-pocock-skills。 它会问你三个问题——工单系统用哪家、triage 标签叫什么、领域文档放哪—— 然后在第四步把答案落成文件（setup-matt-pocock-skills/SKILL.md:72-112）：

3.1 CLAUDE.md 或 AGENTS.md 的 ## Agent skills 区块

这是编辑，不是新建：setup 先探测仓库根目录已有哪个文件—— 有 CLAUDE.md 就编辑它，没有再编辑 AGENTS.md，两个都没有才问你建哪个。 规则写得很死：「绝不在 CLAUDE.md 已存在时新建 AGENTS.md，反之亦然」 （SKILL.md:76-80）。如果文件里已有 ## Agent skills 区块， 就原地更新内容，不会追加重复段落（SKILL.md:82）。 这个区块是给 agent 的导航牌，里面用一句话概括工单系统、标签词汇、领域文档布局， 并各自指向 docs/agents/ 下的详细文件。

3.2 docs/agents/ 下的三份配置记录

• docs/agents/issue-tracker.md——必写。记录工单系统是 GitHub、GitLab 还是本地文件模式，内容由对应的种子模板（issue-tracker-github.md 等）复制而来 （SKILL.md:49）。里面有一面「PRs as a request surface」旗标，默认关， 想让外部 PR 进 triage 队列的人可以日后手改它。
• docs/agents/domain.md——必写。记录领域文档的布局是 single-context（单一上下文：根目录一个 CONTEXT.md 加 docs/adr/） 还是 multi-context（多上下文：根目录 CONTEXT-MAP.md 指向各上下文自己的 CONTEXT.md）。单上下文是默认，绝大多数仓库直接写不询问（SKILL.md:59-61）。
• docs/agents/triage-labels.md——条件写：只有安装了 triage skill 才创建（SKILL.md:102）。它把五个标准 triage role （needs-triage、needs-info、ready-for-agent、 ready-for-human、wontfix）映射到你工单系统里真实的标签字符串。

3.3 创建之后谁来改

答案干净利落：主要就是你的手。setup 在结尾明确说「之后可以直接编辑 docs/agents/*.md，只有想换工单系统或推倒重来时才需要重跑本 skill」 （SKILL.md:116）。除此之外，所有别的 skill 对这些文件只读： triage 读标签映射、wayfinder 读「Wayfinding operations」一节、to-spec/to-tickets 读发布位置—— 但没有任何 skill 会回头改它们。它们是「人拥有的配置」，不是「skill 拥有的状态」。

出处：setup-matt-pocock-skills/SKILL.md 第 49、59-61、72-116 行 · 详解课：0002

4. 领域模型层：CONTEXT.md、CONTEXT-MAP.md、ADR

场景：你在和 agent 讨论一个功能，对话里第五次出现「materialization cascade（实体化级联）」 这个行话。如果此时 grill-with-docs 在场，它会把术语钉进 CONTEXT.md——而这就是领域模型层文件被写入的典型瞬间。 这一层的写入者只有一个：domain-modeling，但它常被四个上层 skill 顺带调用。

4.1 CONTEXT.md：懒创建 + 内联更新

创建时机：「如果没有 CONTEXT.md，在第一个术语被解决时创建它」 （domain-modeling/SKILL.md:40）。不是会话开始时，不是 setup 时——是第一个 术语真正被钉下来的那一刻。单上下文布局就在仓库根目录；多上下文布局下， 写进 src/<context>/CONTEXT.md（由根目录的 CONTEXT-MAP.md 指路， 格式细节见 domain-modeling/CONTEXT-FORMAT.md:34-60）。

修改时机：每次有新术语被解决，就地更新——「不要攒着批量写」 （SKILL.md:62）。触发这些更新的入口有四个：

• grill-with-docs——它的全部实现就一行「用 domain-modeling 跑一场 grilling」，文件效果全部来自 domain-modeling；
• triage 第四步——打磨 issue 时并行跑 grilling 和 domain-modeling，决策落地就内联更新（triage/SKILL.md:76）；
• improve-codebase-architecture 第三步——给深化后的模块起名遇到新概念时加入 CONTEXT.md，并明说「不存在就懒创建」（improve-codebase-architecture/SKILL.md:68-69）；
• wayfinder——它的探路会话同样内嵌 grilling + domain-modeling（wayfinder/SKILL.md:111-112,124）。

4.2 CONTEXT-MAP.md：一个没有明确创建者的文件

这是本组 skill 里少有的文档空白。setup 只在 docs/agents/domain.md 里记录 「这个仓库用多上下文布局」，domain-modeling 只说「如果 CONTEXT-MAP.md 存在就读它」——没有任何一行原文规定谁来创建这张地图本身。 实际推断：选了多上下文布局后，由用户或 domain-modeling 在第二个上下文出现时补建。 如果你在真实仓库里遇到它缺失，手动创建是安全的——格式在 domain-modeling/CONTEXT-FORMAT.md 里。

4.3 docs/adr/NNNN-<slug>.md：三重门槛把关的懒创建

ADR（架构决策记录，记录一个难解释的技术决策）同样懒创建，但门槛高得多： 一个决策必须同时满足三个条件才配拥有一个文件——难逆转、出人意料、 有真实取舍（domain-modeling/SKILL.md:67-73）。文件名按序号递增 （NNNN-<slug>.md，模板见 ADR-FORMAT.md）。 多上下文仓库里，系统级 ADR 放根目录 docs/adr/，上下文专属 ADR 放 src/<context>/docs/adr/（SKILL.md:29-37）。

修改时机：ADR 文件本身基本不可变，但它有两个额外的创建入口和一个「软修改」机制——

• improve-codebase-architecture 会在你拒绝一个候选深化点、且拒绝理由有分量时，主动提议记成 ADR，原话是「要不要记成 ADR，免得以后的架构评审又把它翻出来？」（SKILL.md:70）；
• 旧 ADR 被推翻时不删不改，而是新写一份 ADR，在 frontmatter 的 Status 里标注取代关系——历史本身是信号。

出处：domain-modeling/SKILL.md 第 29-73 行 · 详解课：0004 domain-modeling、 0014 triage、 0017 improve-codebase-architecture

5. 流程产物层：.scratch/ 本地工单

场景：你 setup 时选了「本地文件工单」。此后每一次「发布到工单系统」的动作， 实际都变成「在 .scratch/ 下写一个 md 文件」。这套约定集中定义在 setup-matt-pocock-skills/issue-tracker-local.md——它是本节最重要的一手材料， 四个 skill 的写入行为都从它派生：

• spec 放 .scratch/<feature-slug>/spec.md（issue-tracker-local.md:8）；
• 工单放 .scratch/<feature-slug>/issues/<NN>-<slug>.md，从 01 编号，一单一文件，「绝不用单个合并文件」（第 9 行）；
• triage 状态是每份工单文件顶部的一行 Status:（第 10 行）；
• 评论和对话历史追加在文件末尾的 ## Comments 标题下（第 11 行）；
• 任何 skill 说「发布到工单系统」，在本地模式下就是「在 .scratch/<feature-slug>/ 下新建文件」（第 13-15 行）。

5.1 spec.md：to-spec 写一次，之后没人改

创建时机：to-spec 第三步「按模板写好 spec，发布到工单系统」 （to-spec/SKILL.md:19），本地模式下即 .scratch/<feature-slug>/spec.md， 同时写入 triage 状态行 Status: ready-for-agent。 修改时机：没有。spec 是写一次就冻结的快照—— 之后的 to-tickets、code-review、implement 都只读它。远端 tracker 模式下， 它变成一个 GitHub/GitLab issue，本地什么都不写。

5.2 issues/NN-*.md：to-tickets 创建，prototype 和 triage 追加

创建时机：to-tickets 第五步，一张工单一个文件，按依赖顺序从 01 编号， 使用本地工单模板（标题、Blocked by:、Status: ready-for-agent、 验收标准勾选项，to-tickets/SKILL.md:62-82）。注意它明确不碰父级： 「不要关闭或修改任何父 issue」（第 67 行）。

修改时机，按时间顺序：

• prototype——如果实现中做了原型验证，会在对应工单文件里追加一条「上下文指针」（原型分支的指向）和结论：「在实现工单上留下指向那个分支的上下文指针，把答案也记下来」（prototype/SKILL.md:26）。本地模式下这就是往 ## Comments 里追加。
• triage——本地模式下，「应用 triage 角色」就是改工单顶部的 Status: 行，「发 agent brief（给 agent 的执行简报）」就是往 ## Comments 追加内容。

5.3 wayfinder 的地图：.scratch/<effort>/map.md + 决策工单

wayfinder 在远端 tracker 下用 issue + 子 issue 表达一切；本地模式下才落文件， 且它有一条独立规则：「如果没有提供 tracker，默认用本地文件工单」（wayfinder/SKILL.md:25）。 它写两种文件：

• .scratch/<effort>/map.md——创建时机是「画地图」第三步 （SKILL.md:113），内容是目的地、笔记、已做决定、尚未明确、超出范围五节。
• .scratch/<effort>/issues/NN-*.md——决策工单（Decision ticket， 内容是问题而不是实现切片）。创建时机有两个： 画地图时一批（第 114 行），探路过程中新问题浮现时逐张新增（第 126 行）。

修改时机（本地模式的操作全部定义在 issue-tracker-local.md:23-30）：

• 认领：开始处理某张工单时，把它的 Status: 改成 claimed；
• 解决：答案写进工单文件的 ## Answer 下、状态改为 resolved，然后回头改 map.md——往「已做决定」一节追加一条上下文指针；
• 雾散与越界：模糊地带毕业了就从「尚未明确」里划掉；判定越界的工单关闭并在 map 里加一行；决定被推翻时更新或删除对应工单文件（SKILL.md:126）。

出处：issue-tracker-local.md 全文 · 详解课：0009 to-spec、0010 to-tickets、 0016 wayfinder

6. triage 的 .out-of-scope/ 与工单状态

triage 在远端 tracker 下几乎全落在远端（评论、标签、关闭）；本地仓库里它有一个专属文件和一个共享行为：

6.1 .out-of-scope/<concept>.md：拒绝增强提案时的档案

创建时机非常窄：一个增强提案（enhancement，不是 bug）被判定为 wontfix 时（triage/SKILL.md:85）。而且「因为已经实现了所以 wontfix」 的情况不写（triage/OUT-OF-SCOPE.md:86-88）—— 这个文件的用途是让未来的 agent 知道「这个方向我们已经拒绝过」，已实现的功能不需要这个档案。 一个概念一个文件，kebab-case 命名。

修改时机：同一个概念再次被提出时，往已有文件的「Prior requests（历史请求）」 列表里追加一行（OUT-OF-SCOPE.md:94）；维护者改变主意、重新考虑某个拒绝时， 整个文件被删除（OUT-OF-SCOPE.md:99-105）。

6.2 本地工单上的 triage 痕迹

第 5.2 节已说过：本地模式下 triage 的「应用角色」和「发简报」都落在工单文件里—— 改 Status: 行、往 ## Comments 追加。 所以本地模式下一份工单文件的一生是这样的（注意最后一棒是只读， implement 不会回头写它）：

出处：triage/OUT-OF-SCOPE.md 第 17、86-105 行 · 详解课：0014 triage

7. 一次性产物：research、handoff、prototype

这三个 skill 都写 md，但写的是「写完就不再碰」的一次性产物，只是落点完全不同：

三者对比着记：research 落仓库但不归任何目录惯例管；handoff 刻意落仓库外； prototype 的 README 跟着一次性代码生死。诊断 bug 时 diagnosing-bugs 也会产生大量东西，但全是脚本、日志和回归测试代码， 不是 md——它把复盘假设写进的是提交信息或 PR 描述（diagnosing-bugs/SKILL.md:132）。

详解课：0006 handoff、0007 research、 0008 prototype、0015 diagnosing-bugs

8. 教学工作区：teach 维护的 md

这层你最熟悉——本课程自己就是产物。teach 把当前目录当作有状态的 教学工作区，维护五份 md（0021 课有完整讲解，这里只列生命周期）：

注意一个和工程 skill 同构的设计：懒创建 + 序号文件 + 推翻不删除—— learning-records 之于 teach，就是 ADR 之于 domain-modeling。这不是巧合， SKILL.md 自己就说学习记录「大致相当于软件开发里的架构决策记录」。

详解课：0021 teach · 格式源：LEARNING-RECORD-FORMAT.md

9. 完全不写 md 的十个 skill

知道谁不写和知道谁写一样重要——当你在仓库里找不到某个文件时， 这张「沉默名单」能帮你排除一半嫌疑。以下 skill 在消费仓库里一个 md 都不写：

反过来，会写 md 的 skill 一共十二个：setup-matt-pocock-skills、domain-modeling、 grill-with-docs（借道 domain-modeling）、triage、improve-codebase-architecture、 wayfinder、to-spec、to-tickets、research、handoff、prototype、teach。 12 写 + 10 不写 = 22，与已发布集合对平。

10. 完整地图：文件 × 创建 × 修改

全课浓缩成一张表。打印出来贴在手边的就是它（速查表版见 reference/local-md-files-map.html）：

11. 三个容易踩的坑

11.1 CONTEXT-MAP.md 没有 owner

第 4.2 节说过：setup 只记录布局，domain-modeling 只读地图，没人负责建地图。 选了多上下文布局后记得手动补建这个文件，格式照 CONTEXT-FORMAT.md。 这也是「行为不对时该拧哪段文本」的实例——若想让 setup 顺手建它， 改的是 setup-matt-pocock-skills/SKILL.md 第四步的写入清单。

11.2 本地工单的 Status: 没人写「done」

本地模式下，工单从 to-tickets 创建起就是 Status: ready-for-agent， 而 implement 实现完不会更新这行状态—— 认领（claimed）和解决（resolved）的语义是 wayfinder 那套决策工单流程的， 普通实现工单在流程文本里没有对应的状态推进。如果你在意本地工单的状态闭环， 要么手改，要么在 implement/SKILL.md 里补一段「收尾时更新 Status」的指令。

11.3 docs/agents/*.md 是手改区，不是状态区

想调行为——换 tracker、改标签映射、打开 PR 旗标——直接编辑 docs/agents/ 下对应文件即可，不要重跑 setup。setup 自己明说重跑只用于换工单系统或推倒重来。 反过来，CONTEXT.md 和 ADR 是 skill 的内联更新区，你手改它们也安全， 但要预期 skill 会持续往里面写——它们更像「人机共写的活文档」。

12. 文件侦探：场景练手

大表查起来容易，难的是现场判断。下面五个「案情」都是真实使用中会遇到的场景—— 你在仓库里发现某个文件（或发现某个文件不在），能立刻说出它是谁写的、 什么时候写的吗？点一个选项，马上见分晓；答错可以重试，答对会展开解析。 先凭第 10 节大表的记忆作答，别往上翻。

13. 检索练习

先别往回翻表，凭记忆答。选项字数刻意对齐，不会从长度泄题。

14. 结课：速查表、一手材料

本课的压缩版已经放进 reference/local-md-files-map.html—— 一张打印友好的一页表，以后在仓库里遇到陌生 md 文件时翻它。 建议配对的复习路径：先回 0001 系统地图 把四层结构再过一遍，然后随便挑一个你自己的仓库，对着大表找出里面已有哪些文件、缺哪些。