vinvcn/mattpocock-skills-zh-CN

# 翻译 skill

使用这个 skill 把上游 `mattpocock/skills` 的内容翻译成简体中文，用于 `vinvcn/mattpocock-skills-zh-CN`。

这个 skill 用于**内容本地化**，不是 Git 同步。

## 操作原则

把用户可见的英文说明性文字翻译成自然的简体中文，同时原样保留所有行为关键内容。

目标仓库是一个独立的简体中文本地化版本。它应接收翻译后的内容，而不是上游的仓库元数据。

## 翻译哪些内容

# 问 Matt

你不需要记住每个 skill，所以直接问。

在断言某个 skill 做什么、或建议跳过某个步骤之前，先读那个 skill 的 SKILL.md：这里的摘要只用于定向。

**Flow** 是穿过 skills 的一条路径。大多数路径沿着一条 **main flow** 前进，两个 **on-ramps** 会并入它。其他内容要么是 standalone，要么是在下层运行的 vocabulary layer。

## 主流程：idea -> ship

这是大多数工作的路线：你有一个想法，并希望把它构建出来。

1. **`/grill-with-docs`** - 通过访谈打磨想法。在 **working directory** 中工作时从这里开始：它是 stateful 的，会把学到的内容保存在 `GLOSSARY.md` 和 ADRs 中。（没有 working directory？用 `/grill-me`，见「独立 skills」。两者都运行同一个 `/grilling` primitive；`grill-with-docs` 是会留下文档痕迹的版本，只要有 repo 可记录，它就是两者中更好的那个。）
2. **分支 - 能否在对话中解决所有问题？** 如果某个问题需要可运行的答案（state、business logic，或必须亲眼看到的 UI），就通过 prototype 绕行，并用 **`/handoff`** 在两个方向桥接（prototype 住在自己的目录里，这正是 `/handoff` 的用途，见「Phase 边界」）：

对用户提供的 fixed point 与 `HEAD` 之间的 diff 做双轴 review：

- **Standards**：代码是否符合这个 repo 记录下来的 coding standards？
- **Spec**：代码是否忠实实现来源 issue / spec？

两个轴线都作为**并行 sub-agents**运行，避免互相污染 context；然后这个 skill 聚合它们的 findings。

Issue tracker 应该已经提供给你；如果没有，请让用户运行 `/setup-matt-pocock-skills`。

## 流程

### 1. 确定 fixed point

用户说的任何内容都是 fixed point：commit SHA、branch name、tag、`main`、`HEAD~5` 等。如果用户没有指定，就询问。

# 代码库设计

设计 **deep modules**：把大量行为放在小 interface 之后，把 interface 放在清晰 seam 上，并通过该 interface 测试。凡是在设计或重构代码时，都使用这套语言和原则。目标是给 callers 带来 leverage，给 maintainers 带来 locality，并让每个人都更容易测试。

## 术语表

准确使用这些术语，不要替换成 "component"、"service"、"API" 或 "boundary"。一致语言就是重点。

**Module** - 任何拥有 interface 和 implementation 的东西。它故意不限定尺度：function、class、package，或跨层 slice 都可以。_Avoid_: unit, component, service.

**Interface** - caller 为了正确使用 module 必须知道的一切：type signature，以及 invariants、ordering constraints、error modes、required configuration 和 performance characteristics。_Avoid_: API, signature（太窄，只指 type-level surface）。

**Implementation** - module 内部的代码体。它不同于 **Adapter**：一个东西可以是小 adapter 但有大 implementation（Postgres repo），也可以是大 adapter 但 implementation 很小（in-memory fake）。讨论 seam 时说 adapter；其他时候说 implementation。

# 诊断缺陷

面向棘手 bugs 的纪律。只有在明确说明理由时才跳过阶段。

探索 codebase 时，先读取 `GLOSSARY.md`（如果存在），建立相关 modules 的清晰 mental model，并检查你将触碰区域的 ADRs。

## 脱敏

这个 skill 会要求你展示 commands、outputs 和捕获的 artifacts。**先 redact 掉每个 secret**：用 `<REDACTED>` 替换。Build loops 要针对 env vars 进行，让 credential 留在 environment 里而不是你展示的内容中。捕获的 artifacts 带有 auth headers：只引用携带 signal 的那些行。

如果 redact 后的 output 不足以诊断 bug，就说明情况并询问用户。

## Phase 1 - 构建 feedback loop

# 领域建模

在设计过程中主动构建并打磨项目的 domain model。这是 *active* discipline：挑战术语、发明 edge-case scenarios，并在概念成形的当下写入 glossary 和 decisions。

## 文件结构

多数 repos 只有一个 context：

```text
/
|- GLOSSARY.md
|- docs/
|  `- adr/
|     |- 0001-event-sourced-orders.md

调用两次 Skill 工具，分别指定 `grilling` 和 `domain-modeling`。

实现用户在 spec 或 tickets 中描述的工作。

如果用户传入 ticket reference，先从 issue tracker 获取它，并在开始前复述它的标题。如果 reference 有歧义，先询问。

尽可能在预先约定好的 seams 上调用 Skill 工具并指定 `tdd`。

定期运行 typechecking，定期运行单个测试文件，并在最后运行完整测试套件。

完成后，调用 Skill 工具并指定 `code-review` 来审查这次工作。

把工作提交到当前 branch。

你已经获得一份 spec。这份 spec 应该有与之关联的 tickets，说明如何实现它。

Issue tracker 应当已经提供给你。如果没有，就告诉用户运行 `/setup-matt-pocock-skills`。

目标是在单个 **integration branch** 上实现整个 spec，并按 issue tracker 关闭工作的方式解决每一个 ticket。

tickets 不是步骤清单，而是一个 **task graph**，其中包含 blocking relationships。这意味着始终存在一个由可领取 tickets 组成的 **frontier**。

与 subagents 的通信应当简洁。主要通过 **context pointers** 通信：指向 spec、tickets、research notes 和之前的 commits。不要重复 pointers 已经提供的信息。

在可能的情况下，**implementer subagents** 应当在 background 中运行，以获得最大并发度。

## 步骤

# 改进代码库架构

暴露 architectural friction，并提出 **deepening opportunities**：把 shallow modules 变成 deep modules 的 refactors。目标是 testability 和 AI-navigability。

这个命令由项目的 domain model 提供信息，并建立在共享 design vocabulary 上：

- 调用 Skill 工具并指定 `codebase-design`，获取 architecture vocabulary（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其 principles（deletion test、"the interface is the test surface"、"one adapter = hypothetical seam, two = real"）。每条建议都准确使用这些术语，不要漂移到 "component"、"service"、"API" 或 "boundary"。
- `GLOSSARY.md` 中的 domain language 会为好的 seams 命名；`docs/adr/` 中的 ADRs 记录这个命令不应重新争论的 decisions。

## 流程

### 1. 探索

**先划定扫描范围：YAGNI。** 深化 module 的收益在于让未来修改更容易，因此要更关注最近仍在变化的 codebase 区域。开始探索前先决定去哪里看：

使用以下模板撰写 PR 正文：

```markdown
## Summary

<diagram, diff-sketch, or tree>

## Evidence

- **Before:** <screenshot/output/failing test run>
  **After:** <screenshot/output/passing test run>

## Merge Danger

# 原型

Prototype 是**用来回答一个问题的 throwaway code**。问题决定形状。

## 选择分支

先识别正在回答哪个问题：来自用户 prompt、周围代码，或在用户在线时直接询问：

- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md)。构建一个单一、可分享的 HTML 文件（free-play buttons 加 tabbed guided walkthroughs），推动 state machine 跑过纸面上难以推理的 cases，而且非开发人员也能驱动它。
- **"What should this look like?"** → [UI.md](UI.md)。在单一路由上生成几种差异很大的 UI variations，并通过 URL search param 和浮动底栏切换。

这两个分支会产出非常不同的 artifacts；选错会浪费整个 prototype。如果问题确实模糊且用户不可达，默认选择更匹配周围代码的分支（backend module → logic；page 或 component → UI），并在 prototype 顶部说明假设。

## 两个分支通用的规则

启动一个 **background agent** 做 research，这样你可以在它阅读时继续工作。

它的工作：

1. 对照 **primary sources** 调研问题：official docs、source code、specs、first-party APIs，而不是二手解读。每个 claim 都要追溯到拥有该事实的 source。
2. 把 findings 写入一个 Markdown 文件，并为每个 claim 标注 source。
3. 保存到 repo 既有的 notes 位置；匹配现有 convention。如果没有 convention，就放在合理位置并说明路径。

用户要求做一次 **retrospective**。你要针对 coding agent 的 **environment** 提出改进建议，以改善未来的运行结果。

## 步骤

1. 调用 Skill 工具并指定 `writing-for-agents`，获取写作风格指南。

2. 阅读用户指定 session 的 primary sources。这可能意味着在本机搜索 session logs。如果用户没有指定 session，默认使用当前 session。

3. 在以下类别中寻找改进候选项。

- **Navigation**：agent 找到正确 files 有多容易？files 之间是否存在隐藏依赖？navigation pointer 能否让定位更容易？当 agent 花了很长时间才找到某段信息时使用。
- **Automated checks**：是否有 automated checks 可以捕获 agent 犯的错误？例如 linting、typing、tests 或 filesystem linters？先阅读 repo 自己的检查命令（`package.json`/build-tool 中的 `lint`/`check` scripts 以及 CI workflow），这样，如果某个检查已经存在但没有接入流程或悄悄失效，真正的发现就是这个问题，而不是重新发明一套检查。若 repo 完全没有 **guardrail**（没有 pre-commit hook，也没有运行 lint/typecheck/test command 的 CI job），这本身就是一项发现：未纳入 lint 的 repo 是长期存在的改进缺口，而不是理所当然的默认状态。当 agent 犯了本来可以被 automated check 捕获的错误，或 repo 完全没有 guardrail 时使用。
- **Coding standards**：是否应该给 **reviewer agent** 一条新规则来执行？是否应该删除或澄清现有规则？先对违规分类：**mechanical** 违规（固定的语法模式、被禁用的 API、import 形式、文件位置规则）必须交给 deterministic check 处理；根据 repo 使用的语言和现有 guardrail，选择成本最低的方式：在 repo 自己的 linter 中添加自定义规则、新增 pre-commit hook，或新增 CI job。默认优先构建检查，而不是编写规则。`CODING_STANDARDS.md` 只用于真正的 **judgement calls**（跨文件一致性、"matches the surrounding style"，以及任何 guardrail 都无法替代的判断）。当 reviewer agent 没有发现一个错误时使用。
- **Global AGENTS.md**：是否有 steering instructions 应该移到 coding standards 或 automated checks？当 repo 或用户 global scope 中的 AGENTS.md 特别庞大时使用。

# 配置 Matt Pocock 的 Skills

搭建 engineering skills 所假定的每仓库配置：

- **Issue tracker** - issues 存放在哪里（默认 GitHub；也原生支持 local markdown）
- **Triage labels** - 五个 canonical triage roles 使用的字符串
- **Domain docs** - `GLOSSARY.md` 与 ADRs 的位置，以及读取它们的 consumer rules

这是 prompt-driven skill，不是确定性脚本。先探索，展示发现，与用户确认，然后写入。

## 流程

### 1. 探索

# 测试驱动开发

TDD 是 red -> green loop。这个 skill 是让该 loop 产出值得保留的 tests 的 reference：什么是好 test、tests 应该放在哪里、anti-patterns，以及 loop 的规则。每个 cycle 前和 cycle 中都要参考这些内容，而不是事后才看。

探索 codebase 时，读取 `GLOSSARY.md`（如果存在），让 test names 和 interface vocabulary 与项目 domain language 对齐，并尊重你触碰区域的 ADRs。

## 什么是好 test

Tests 应通过 public interfaces 验证 behavior，而不是 implementation details。代码可以完全改变；tests 不该随之改变。一个好 test 读起来像 specification："user can checkout with valid cart" 能清楚说明存在什么能力；因为它不关心 internal structure，所以能承受 refactors。

示例见 [tests.md](tests.md)，mocking 规则见 [mocking.md](mocking.md)。

## Seams：tests 放在哪里

这个 skill 使用当前 conversation context 和 codebase understanding 产出 spec。**不要**访谈用户，只综合你已经知道的内容。

Issue tracker 和 triage label vocabulary 应该已经提供给你；如果没有，请让用户运行 `/setup-matt-pocock-skills`。

## 流程

1. 如果还没有探索 repo，先探索它以理解 codebase 当前状态。在 spec 中始终使用项目 domain glossary vocabulary，并遵守相关 ADRs。

2. 草拟你准备在哪些 seams 上测试这个 feature。优先使用现有 seams，而不是新增 seams。使用尽可能高层的 seam。如果确实需要新增 seams，尽可能在最高层提出。

Seams 越少越好，理想数量是一个。与用户确认这些 seams 是否符合预期。

3. 使用下面模板写 spec，并发布到项目 issue tracker。应用 `ready-for-agent` triage label；不需要额外 triage。

# 拆成 tickets

把 plan、spec 或 conversation 拆成一组 **tickets**：tracer-bullet vertical slices，每个 ticket 都声明 **block** 它的 tickets。

Issue tracker 和 triage label vocabulary 应该已经提供；如果没有，请让用户运行 `/setup-matt-pocock-skills`。

## 流程

### 1. 收集 context

使用 conversation context 中已经存在的内容。如果用户把 reference（spec path、issue number 或 URL）作为参数传入，获取并完整读取其 body 和 comments。

### 2. 探索 codebase（可选）

# Triage

通过一组小型 triage roles state machine，在项目 issue tracker 中移动 issues。

如果这个 repo 把 external pull requests 当作 request surface（见 issue-tracker 配置），triage 也覆盖它们：**PR 是带附加代码的 issue**，相同的 roles、相同的 states、相同的 machine，只有下面标记为 “for a PR” 的几处差异。按 tracker 配置把裸 `#42` 解析为 issue 或 PR。

Triage 期间发布到 issue tracker 的每条 comment 或 issue **必须**以此 disclaimer 开头：

```
> *This was generated by AI during triage.*
```

## 参考文档

一个松散想法出现了：它太大，单个 agent session 装不下，而且被 fog 包围；从这里到 **destination** 的路还看不见。Wayfinding 的目标是找到这条路，而不是朝 destination 猛冲。这个 skill 会把路径绘制成 repo issue tracker 上的 **shared map**，然后逐个处理 **decision tickets**（它们承载需要决策才能解决的问题，而不是要执行的 build slices），直到路线清晰。

不同 effort 的 destination 不同，而为它命名是 charting 的第一个动作；它塑造每个 ticket。它可能是一份要 hand off 并迭代的 spec、一个必须在 planning 前确定的 decision，或 data-structure migration 之类原地完成的 change。Map 与领域无关：engineering work、course content，或任何符合这个形状的事项都可以。

## 只规划，不动手

Wayfinder 默认用于 **planning**：每个 ticket 解决一个 decision；当别人动手前已经没有任何事情需要决定、路径完全清晰时，map 才算完成。想直接做工作的冲动通常表示你已经到达 map 边缘，该 hand off 了。Effort 可以在 **Notes** 中覆盖这个默认值，把 execution 纳入 map；否则只产出 decisions，不产出 deliverables。

## 用名称引用

每张 map 和每个 ticket 都是 issue，因此都有一个 **name**：它的 title。在所有给人看的内容里，包括叙述和 map 的 Decisions-so-far，都用 name 引用它，不要只写裸 id、number 或 slug。一堵 `#42, #43, #44` 很难读；name 一眼就能看懂。Id 和 URL 不会消失，它们被包在 name 的 link 里面，但不单独替代 name。

## 共享地图

# Wizard

**wizard** 是一个 bash 脚本，它一步一步引导人完成一项手动流程：这类流程手动做很繁琐，每次重新向 AI 解释一遍也很繁琐。它会打开每个 URL，准确说明该点什么、该复制什么，捕获这些值，把它们写到该去的地方（`.env`、GitHub secrets），在每个阶段确认，并显示还剩多少个阶段。它可能用于配置第三方服务、运行一次性 migration，或把项目从一种状态迁移到另一种状态。

出色的 UX 已经由 [template.sh](template.sh) 解决：逐阶段的进度、confirmation gates、跨平台 URL 打开（含 WSL）、隐藏的 secret 输入、幂等的 `.env` upserts、`gh secret`/`gh variable` 写入，以及收尾 summary。**你的工作只是确定流程范围并编写它的各个 stage。** `STAGES` 标记之上的 library 在每个 wizard 中都完全相同；这种一致性正是重点：永远不要手动编辑它。

Wizard 默认是临时的：为单次运行而构建，保存到 scratch 或 `scripts/` 路径，任务完成后删除。只有当用户想要一条应留在 repo 中的可重复 setup 路径时，才 commit 它。

## 流程

### 1. 界定流程范围

梳理出人必须执行的每一个手动步骤，以及沿途捕获的每一个值。先读 repo，不要凭空发问：

你是一名 chief of staff，负责协调 subagents 和 schedules，推进一个长期目标。这个 session 会运行很长时间，不断积累 tribal knowledge，帮助你做出长期战略决策。

你是这个目标的 Directly Responsible Individual。你有权想得比你习惯的更长远。你必须同时在两条轨道上思考：

- 战术：我如何完成眼下的任务？
- 战略：我如何改进环境，让 _下一个_ 任务取得更好的结果？

## Schedules

在 harness 允许的前提下，你要建议有助于达成目标的 recurring schedules。

## Subagents

所有工作都应在 subagents 中完成。保护你的 context window。

为当前对话写一份 handoff summary，让一个全新的 agent 可以继续工作。把它保存到用户操作系统的临时目录，然后启动一个以它作为 prompt 的 background agent：`claude --bg --name "<descriptive name>" -- "$(cat <summary file>)"`。传入文件可以避免 shell 执行 summary 中的反引号或展开其中的 `$`。它会在当前工作目录中启动并立即返回；用户用 `claude agents` 管理它。

始终带上 `-n`/`--name` 并给出描述性名称（例如 `--name "Fix login bug"`）；它设置显示名称，会出现在 job list、session picker 和 terminal title 中。

在 summary 中包含一个 "suggested skills" section，写明下一个 agent 应调用 Skill 工具并指定哪些 skills。

不要重复其它 artifacts（PRDs、plans、ADRs、issues、commits、diffs）中已经记录的内容，改为用 path 或 URL 引用它们。

删去任何敏感信息，例如 API keys、passwords 或个人身份信息：这份 summary 会成为 agent 的 prompt。

如果用户传入了 arguments，把它们当作对下一个 session 重点的描述，并据此调整 summary。

调用 Skill 工具并指定 `grilling`，运行一个 stateful session，唯一输出是 **workflow** specs。使用 grilling discipline：持续追问、一次一个问题、每个问题都附推荐答案。围绕下面的 vocabulary 和 goal 来访谈。随着 grilling 解决问题，创建、编辑、删除 specs。

## The loop lens

**Loop** 是用户生活中的重复模式：career、week、morning，或单个重复活动。把生活看成 loops within loops，会揭示活动到底有多 predictable，也因此揭示哪些值得 **delegating**。用这个 lens 找到值得写 spec 的 loops，并提出用户尚未注意到的 loops。

**Workflow** 是一个 loop 的 spec，并让它变得可执行。你在 loop 上运行 workflow；loop 是它的运行实例。Workflows 存在 `workflows/*.md` 中，并作为 source of truth。

## Vocabulary

只有当 workflow 需要时才使用 shared language；它不是 checklist。**不要强制任何结构**：除非 grilling 表明需要，否则 workflow 不需要 AI、不需要 checkpoint，也不需要 schedule。

- **Trigger** - 每次运行的触发物：一个 **event**（新 email、新 issue）或一个 **schedule**（每天早晨）。Event-triggering 通常更高效。
- **Checkpoint** - human-in-the-loop 点，用户在这里验证或决策。有些 workflows 没有 checkpoint，可自主运行；有些完全不使用 AI。

# Setup TS Deep Modules

让 repo 中每个 package 成为 **deep module**：用小 interface 隐藏大量 behaviour。Package 的 public surface 是其 **entry points**（package root 中的 files），所有 subfolders 都隐藏。这个 skill 会安装 [dependency-cruiser](https://github.com/sverweij/dependency-cruiser)，加入强制只能通过 entry points 访问的 rules，并证明这些 rules 确实会拦截违规。

Vocabulary（deep module、interface、seam、depth）来自调用 Skill 工具并指定 `codebase-design`；整个过程都使用它的语言。

## The shape this enforces

```
src/packages/
  <name>/
    index.ts        ← an entry point (public). Import this from outside.
    client.ts       ← another entry point. Packages may expose SEVERAL.
    lib/            ← implementation: hidden from outside, free to import each other.

<what-to-do>

用户已经传入（或将传入）一份 raw material markdown 文件。这是 **exploit**：探索已经完成，pile 已固定——承诺一条穿过它的路径，并挖掘 pile 来填充每个 beat。

如果用户没有说明文章保存路径，只询问一次并记住路径。

然后以自选路径（choose-your-own-adventure）风格运行 beat-by-beat journey：

1. **Establish the prerequisites.** 在任何 beat 之前，先与用户确定受众进场时已经知道什么——那些从一开始就已 **grounded** 的概念。其它一切都必须先被某个 beat grounded，之后的 beat 才能使用它。见 [Grounding](#grounding)。
2. 从 raw material 中写出 2-3 个候选 **starting beats**。每个都是进入文章的不同入口。每个都只能依赖已 grounded 的概念；记下每个 beat 新 grounded 了哪些概念。在写入文章文件之前先把这些 beats 展示给用户。用户选一个。预览选定这个 beat 后会解锁哪些 beats——就像让用户先看到路径前方一点点。
3. 用户选定 starting beat 后，只把**那个 beat**写入文章文件。一个 beat 可以是一句话，也可以是几段，按它自然需要的长度来。写完就停。
4. 从磁盘重新读取文章文件。然后提供 2-3 个候选 **next beats**——也就是从文章当前所在位置，journey 可以 pivot 的不同方向。每个都必须能从当前已 grounded 的集合到达；记下每个 beat grounded 了什么。
5. 循环步骤 3-5，直到文章自然结束。

<what-to-do>

这是纯粹的 **explore**：在不承诺任何结构的前提下，拓宽可写内容的空间——承诺结构是 _exploit_，是另一个 skill 的工作。运行一个产出 fragments 的 grilling session，围绕用户想写的任何主题持续访谈。在这里强加 phases、outlines 或文章结构都不在范围内。

当对话双方产生 fragments 时，把它们追加到单一 markdown 文件。

如果用户没有传入路径，只询问一次文档保存到哪里，然后在 session 剩余部分记住它。

从用户说的第一句话开始捕获 fragments，包括 initial prompt。

第一次写入时，在顶部放一个带 working title 的单一 H1（之后可以改），除此之外什么都不要放：不要 metadata、TOC 或 date。

</what-to-do>

<what-to-do>

用户已经传入（或将传入）一份 raw material markdown 文件。把它当作 input pile：它可以是整齐的 fragments 列表、无结构 prose 墙、transcript，任何格式都可以。先完整读完，再做其他事。

然后运行一个 shaping session，产出一份独立的 article document。这是 **exploit**：探索已经完成，pile 已固定——承诺一个结构，并挖掘 pile 来填充它。不要编辑 raw material 文件；对这个 skill 来说它是 read-only。

如果用户没有说明文章保存路径，只询问一次并记住路径。

</what-to-do>

<supporting-info>

## The loop

# 设置 Git Guardrails

设置一个 PreToolUse hook，在 Claude 执行危险 git commands 前拦截并阻止它们。

## 会被阻止的命令

- `git push`（包括 `--force` 在内的所有 variants）
- `git reset --hard`
- `git clean -f` / `git clean -fd`
- `git branch -D`
- `git checkout .` / `git restore .`

被阻止时，Claude 会看到一条 message，说明它无权访问这些 commands。

# 迁移到 Shoehorn

## 为什么用 shoehorn？

`shoehorn` 允许你在 tests 中传入 partial data，同时保持 TypeScript 满意。它用 type-safe alternatives 替换 `as` assertions。

**只用于 test code。** 永远不要在 production code 中使用 shoehorn。

Tests 中 `as` 的问题：

- 经过训练，不去使用它
- 必须手动指定 target type
- 对故意错误的数据需要 double-as（`as unknown as Type`）

# 搭建练习

创建能通过 `pnpm ai-hero-cli internal lint` 的 exercise directory structures，然后用 `git commit` 提交。

## 目录命名

- **Sections**：`exercises/` 下的 `XX-section-name/`（例如 `01-retrieval-skill-building`）
- **Exercises**：section 下的 `XX.YY-exercise-name/`（例如 `01.03-retrieval-with-bm25`）
- Section number = `XX`，exercise number = `XX.YY`
- Names 使用 dash-case（小写、连字符）

## Exercise 变体

每个 exercise 至少需要这些 subfolders 中的一个：

# 设置 Pre-Commit Hooks

## 这会配置什么

- **Husky** pre-commit hook
- **lint-staged** 对所有 staged files 运行 Prettier
- **Prettier** config（如果缺失）
- pre-commit hook 中的 **typecheck** 和 **test** scripts

## 步骤

### 1. 检测 package manager

检查 `package-lock.json` (npm)、`pnpm-lock.yaml` (pnpm)、`yarn.lock` (yarn)、`bun.lockb` (bun)。使用存在的那个。不清楚时默认 npm。

调用 Skill 工具并指定 `grilling`。

持续访谈用户，直到达成共同理解。把这件事映射成一棵 **design tree**：每个 decision 都分支到挂在它下面的那些 decisions。

按 **rounds** 逐轮处理这棵树。**frontier** 是那些 prerequisites 已经敲定的 decisions，也就是你现在就可以问、无需猜测还没听到的答案的那些问题。在一轮里问完整条 frontier：给每个问题编号并附上你的推荐答案。然后等用户回答，再进入下一轮。

每一轮的格式如下:

```
❓ **Q1** - **<问题标题>**：<问题正文，可能有多段，包括多个选项>

➡<U+FE0F> <你的推荐答案>

---

❓ **Q2** - **<问题标题>**：<问题正文，可能有多段，包括多个选项>

编写一份 handoff document，总结当前对话，让 fresh agent 能继续工作。保存到用户操作系统的临时目录（`$TMPDIR`，否则 `/tmp`；Windows 上是 `%TEMP%`），不要保存到当前 workspace。

在文档中包含 "suggested skills" section，写明下一个 agent 应调用 Skill 工具并指定哪些 skills。

不要重复已经被其他 artifacts 捕获的内容（specs、plans、ADRs、issues、commits、diffs）。改用 path 或 URL 引用它们。

删去任何敏感信息，例如 API keys、passwords 或 personally identifiable information。

如果用户传入了 arguments，把它们视为下一次 session 的关注点描述，并据此调整文档。

用户要求你教他们某件事。这是一个 stateful request：他们打算在多个 sessions 中学习这个 topic。

## 教学工作区

把当前目录视为 teaching workspace。Workspace 路径（`./lessons/` 及其余路径）都以运行 `/teach` 时所在的目录为基准解析；只有 `*-FORMAT.md` 链接以这个 skill 所在的 folder 为基准解析。他们的学习状态保存在这个目录中的几个文件里：

- `MISSION.md`：记录用户为什么对这个 topic 感兴趣。所有教学都应以它为 grounding。使用 [MISSION-FORMAT.md](./MISSION-FORMAT.md) 中的格式。
- `./reference/*.html`：reference materials 目录。这些是从 lessons 中压缩出的 learnings：cheat sheets、reference algorithms、syntax、yoga poses、glossaries。它们是原始学习单元。它们应该是漂亮的 documents，适合打印，并为 quick reference 设计。
- `RESOURCES.md`：可探索的 resources 列表，用来把教学建立在 context knowledge 上，或获取 knowledge 和 wisdom。使用 [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md) 中的格式。
- `./learning-records/*.md`：learning records 目录，记录用户已经学到的东西。它们大致相当于软件开发里的 architectural decision records：捕获非显而易见的 lessons 和 key insights，这些内容可能之后需要修订，或推动未来 sessions。它们应用来计算 zone of proximal development。标题格式为 `0001-<dash-case-name>.md`，数字每次递增。使用 [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md) 中的格式。
- `./lessons/*.html`：lessons 目录。一个 **lesson** 是一个单独、自包含的 HTML output，用来教授一个与 mission 绑定的 tightly-scoped 内容。这是此 workspace 中教学的主要单元。
- `./assets/*`：跨 lessons 共享的可复用 **components**。见 [Assets](#assets)。
- `NOTES.md`：scratchpad，用来记下用户偏好或 working notes。

把用户无法独自回答的事情转成一份 **questionnaire**：一份交给某个人异步填写，或在会议中一起填写的 Markdown document。Recipient 掌握用户缺少的知识；questionnaire 要把这些知识提取出来。

**Grill the send, not the subject。** 只围绕用户始终能够回答的 _send_ 进行访谈：发送给谁，以及需要对方返回什么。Document 中的问题再针对 recipient 所知与用户所需之间的 **gap**。

1. **发送给谁？** 在一次交流中询问 recipient 的 role、expertise 和与用户的关系。这会确定 questionnaire 的语气，以及需要携带多少 context。知道 recipient 是谁，以及对方掌握哪些用户不掌握的知识后，这一步完成。

2. **需要返回什么？** 在一次交流中询问用户无法独自解决、需要此人提供的具体 decisions 或 facts。当你得到一份具体清单，明确用户最终必须能做什么或决定什么时，这一步完成。

3. **编写 questionnaire。** 根据步骤 1–2 的 gap 起草问题，并遵循下面的 Document structure。把文件写到当前目录的 `to-questionnaire-<slug>.md`（slug 来自主题），然后报告路径。当文件存在，且步骤 2 中用户列出的每项内容都有问题覆盖时完成。

## 文档结构

把 document 定位为 **discovery questionnaire**：用户缺少 context，而 recipient 掌握它。按重要程度降序排列问题，异步沟通可能只有一次机会；问题超过少量时，按主题放在 `##` headings 下。使用以下 template。

等一下，我还没弄明白你到这里是怎么想的。重新表述一遍：给我一点 context 背景，遵循 ASD-STE100 简化技术英语的标准，用目前对话的语种，并使用 `GLOSSARY.md` 中的 ubiquitous language；如果仓库有 `GLOSSARY-MAP.md`，先按它指向的 context 读取正确的 `GLOSSARY.md`。

为 agent 消费的任何文档提供参考：一个 skill、一个 `AGENTS.md` / `CLAUDE.md`、一个经 pointer 触达的文档。包装方式不同；写作本身并无不同：同样的杠杆让每一份都变得可预测：agent 每次运行都采取相同的 _process_，而不是产出相同的 output。

当你写的文档是 skill 时，阅读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) 了解 frontmatter、invocation 选择以及 router skills。

## Context pointers

**context pointer** 是 agent context 中持有的一个 reference，它命名某个 context 之外的材料，并对触达它的条件进行编码。某个 skill 的 description 就是其一；`AGENTS.md` 中命名某个文档的一行是同一个对象。决定 agent 何时以及多可靠地触达材料的，是指针的 _措辞_，而不是它的目标。一个必须是目标的、却由措辞薄弱的 pointer 承载的内容，是一个 variance bug：先打磨措辞，只有打磨失败时才内联该材料。

一个 pointer 做两件事：说明材料是什么，并列出应触发触达它的 **branches**（一个 branch 是文档处理的一个独立情形，所以不同的 runs 会沿不同的路径穿过它）。一个始终加载的 pointer 的每个词都会在每一轮付出成本，所以它比正文更该被大力修剪：

- **把 leading word 放到最前面**：pointer 是它做触发工作的地方。
- **每个 branch 一个 trigger。** 如果同义词只是重命名单一 branch，那就是同一个 branch 写了两遍；合并它们，只保留真正不同的 branches。
- **删掉正文已经承载的 identity。**