devcxl/mattpocock-skills-zh

# Ask Matt

你不必记住每一个技能，所以来问。

在说明某个技能的作用或建议跳过某一步之前，先阅读该技能的 `SKILL.md`：这里的摘要仅用于定位。

**流程（flow）**是穿过技能的一条路径。大多数路径沿一条**主干流程**行进，两条**入口匝道**汇入其中。其余的都是独立技能，或者是在底层运行的词汇层。

## 主干流程：想法 → 交付

大多数工作走的路线。你有一个想法，想把它建出来。

1. **`/grill-with-docs`**：通过盘问打磨想法。只要你在**工作目录**里就从这里开始：它是有状态的，会把学到的东西保存在 `GLOSSARY.md` 和 ADR 中。（没有工作目录？用 `/grill-me`，见"独立技能"。两者跑的是同一个 `/grilling` 原语；`grill-with-docs` 是会留下书面痕迹的那个，所以只要有仓库可以留痕迹，它就是更好的选择。）
2. **分支：所有问题都能在对话中解决吗？** 如果某个问题需要一个可运行的答案（状态、业务逻辑、必须亲眼看到的 UI），就绕道原型，由 **`/handoff`** 双向桥接（原型住在自己的目录里，这正是 `/handoff` 的用武之地，见"阶段边界"）：

# 审查

对 `HEAD` 与用户指定的固定点之间的 diff 进行双轴审查：

- **规范**——代码是否符合本仓库文档化的编码规范？
- **规格**——代码是否忠实地实现了原始 issue / PRD / 规格？

两条轴线作为**并行子 agent** 运行，互不污染彼此的上下文，然后由本技能汇总双方的发现。启动每个子 agent 时，都使用全新的上下文窗口。

Issue 跟踪器应该已经提供给你了。如果没有，请告诉用户运行 `/setup-matt-pocock-skills`。

## 流程

### 1. 确定固定点

# Codebase Design

设计 **深度模块（deep modules）**：一个小接口背后承载大量行为，放置在干净的 seam 处，通过该接口可测试。在设计和重构代码的任何地方，都使用这套语言和原则。目标是：对调用者而言是杠杆效应（leverage），对维护者而言是局部性（locality），对所有人而言是可测试性。

## 词汇表

精确使用以下术语 —— 不要替换为"组件"、"服务"、"API"或"边界"。使用一致的语言正是关键所在。

**Module（模块）** —— 任何具有接口和实现的东西。特意与规模无关：一个函数、类、包或跨层级切片。_避免使用_：单元、组件、服务。

**Interface（接口）** —— 调用者正确使用该模块所需知道的一切：类型签名，还包括不变性约束、顺序约束、错误模式、所需配置和性能特征。_避免使用_：API、签名（过于狭隘 —— 它们仅指类型层面的表面）。

**Implementation（实现）** —— 模块内部的内容，它的代码主体。与 **Adapter（适配器）** 不同：某个东西可以是一个小型适配器配大型实现（如 Postgres 仓库），也可以是一个大型适配器配小型实现（如内存中的假实现）。当讨论重点是 seam 时使用"adapter"；否则使用"implementation"。

# 诊断 Bug

针对棘手 bug 的一条纪律：只有显式说明正当理由时才能跳过某个阶段。

在探索代码库时，读取 `GLOSSARY.md`（如果存在）以获得相关模块的清晰心智模型，并查看你所触及区域的 ADR。

## 脱敏

本技能会让你展示命令、输出和捕获的产物。**先脱敏所有秘密**：用 `<REDACTED>` 替换。针对环境变量构建循环，这样凭证留在环境中而不是出现在你展示的内容里。捕获的产物可能携带认证头：只引用携带信号的若干行。

如果脱敏后的输出不足以诊断 bug，要明确说明，并请用户提供更多材料。

## Phase 1：构建反馈循环

# Domain Modeling（领域建模）

在设计过程中主动构建和完善项目的领域模型。这是一门**主动**的学科——质疑术语、创造边界场景、在术语和决策形成的瞬间将其记录在案。（仅仅*阅读* `GLOSSARY.md` 来获取词汇不是此 skill 的用途——那是任何 skill 都能做的单行习惯。此 skill 用于你在*修改*模型，而非仅仅消费它。）

## 文件结构

大多数 repo 只有一个 context：

```
/
├── GLOSSARY.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md

调用 Skill 工具两次，分别传入 "grilling" 和 "domain-modeling"。

根据用户在 spec 或 tickets 中描述的内容实现工作。

如果用户传入 ticket 引用，先从 issue 跟踪器获取该 ticket，并在开始前说明标题。引用含糊时先询问。

尽可能在预先约定的 seam 处调用 Skill 工具并传入 "tdd"。

定期运行类型检查，定期运行单个测试文件，最后运行一次完整测试套件。

完成后，调用 Skill 工具并传入 "code-review" 来审查工作。

将你的工作提交到当前分支。

你已被提供一份 spec。该 spec 应关联若干 ticket，用以描述如何实现该 spec。

应该已经为你提供了 issue 跟踪器。如果没有，请告诉用户运行 `/setup-matt-pocock-skills`。

目标是整份 spec 在一条**集成分支**上实现完成，每张 ticket 都按 issue 跟踪器关闭工作的方式解决。

这些 ticket 不是一份步骤清单。它们是一张**任务图**，彼此之间存在阻塞关系。这意味着始终存在一个**前沿（frontier）**：可立即被领走的 ticket。

每个子智能体都应从一个全新的上下文窗口开始。

与子智能体之间的通信应保持精简。通信主要通过**上下文指针**：指向 spec、ticket、研究笔记与历史 commit。无需重复指针已经能触达的信息。

**实施者子智能体**应尽可能在后台运行，以获得最大并发。

# 改进代码库架构

揭示架构摩擦点并提出**深化机会**——将浅层 module 转变为深层 module 的重构。目标是可测试性和 AI 可导航性。

本命令**参考**项目的领域模型，并基于共享的设计词汇：

- 调用 Skill 工具并传入 "codebase-design" 获取架构词汇（**module**、**interface**、**depth**、**seam**、**adapter**、**leverage**、**locality**）及其原则（deletion test、"interface 就是 test surface"、"一个 adapter = 假设性 seam，两个 = 真实的"）。在每个建议中严格使用这些术语——不要偏离到 "component"、"service"、"API" 或 "boundary"。
- `GLOSSARY.md` 中的领域语言为好的 seam 提供了命名；`docs/adr/` 中的 ADR 记录了本命令不应重新讨论的决策。

## 流程

### 1. 探索

**先确定范围再扫描——YAGNI。** 加深一个模块的回报在于使未来对该模块的修改更容易，因此对最近变更的代码区域给予额外权重。在查看之前先决定*看哪里*：

写 PR body 时用这个模板：

```markdown
## Summary（摘要）

<图表、diff 草图，或树>

## Evidence（证据）

- **Before:** <截图 / 输出 / 失败中的测试运行>
  **After:** <截图 / 输出 / 通过了的测试运行>

## Merge Danger（合并风险）

# 原型（Prototype）

原型是**回答某个问题的一次性代码**。问题决定了它的形态。

## 选择分支

判断要回答的是哪个问题——从用户的提示、周围的代码判断，或者如果用户在场就直接问：

- **"这套逻辑 / 状态模型感觉对吗？"** → [LOGIC.md](LOGIC.md)。构建一个可分享的 HTML 文件——自由试玩按钮加上带标签页的引导式演练——把状态机推过那些在纸面上难以推理的用例，而且非开发者也能上手操作。
- **"它应该长什么样？"** → [UI.md](UI.md)。在单一路由上生成几个截然不同的 UI 变体，通过 URL 查询参数和一个底部悬浮栏切换。

两个分支产出截然不同的产物——选错了分支，整个原型就白做了。如果问题确实模棱两可、用户又联系不上，就默认选择更贴合周围代码的分支（后端模块 → 逻辑；页面或组件 → UI），并在原型顶部注明这个假设。

## 两者都适用的规则

启动一个**后台 agent** 来做研究，这样它阅读时你可以继续干活。在启动它时使用全新的上下文窗口。

它的任务：

1. 对照**一手来源**（官方文档、源码、规范、第一方 API）调查问题，而不是它们的二手转述。把每一条声明追溯回拥有它的那份来源。
2. 把发现写入单个 Markdown 文件，每条声明都标注来源。
3. 文件保存到仓库中已有的同类笔记位置——遵循既有约定；若没有，放到一个合理位置并说明在哪里。

用户请求了**回顾**。你正在为编码 agent 的**环境**提出改进建议，以提升后续运行的体验。

## 步骤

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

2. 读取用户指定的会话的主源资料。这可能意味着在本机上的会话日志中检索。如果用户没有指定会话，则默认为当前这个。

3. 在以下类别中寻找可改进的候选：

- **导航**：agent 找到正确文件的难易程度如何？文件之间是否存在隐藏依赖？一个**导航指针**会让事情更简单吗？当会话花很长时间才找到某条信息时使用。
- **自动化检查**：是否存在能捕捉 agent 所犯错误的自动化检查？linting、类型检查、测试、文件系统 linter？先读仓库自己的检查命令（它的 `package.json`/构建工具的 `lint`/`check` 脚本、它的 CI workflow），这样发现就落在"已经存在、但没接线或悄悄坏掉"的检查上，而不是重新发明一个。没有任何**护栏**（没有 pre-commit hook，也没有跑 lint/typecheck/test 的 CI job）的仓库本身就是一条发现：未 lint 的仓库是一个长期错失的机会，而不是中性的默认状态。当 agent 犯了一个本可被自动化检查捕获的错误，或仓库完全没有护栏时使用。
- **编码规范**：是否应给**评审 agent** 一条新规则去执行？是否应删除或澄清已有规则？先给违规分类：**机械性**违规（固定的语法模式、被禁用的 API、某种 import 形态、文件位置规则）一律走确定性检查：在仓库自己的 linter 里加自定义规则、加一个新的 pre-commit hook、或加一个新的 CI job，哪个在仓库的语言和现有护栏下最便宜就用哪个。默认优先构建检查，而不是写规则。把 `CODING_STANDARDS.md` 留给真正的**判断题**（跨文件一致性、"与周围风格一致"、任何护栏永远无法替代的东西）。当评审 agent 没抓住错误时使用。
- **全局 AGENTS.md**：是否有些引导指令应当改为编码规范（或自动化检查）？当 AGENTS.md 文件特别庞大时：无论是在仓库还是用户的全局作用域：使用。

# 设置 Matt Pocock 技能

搭建工程技能所依赖的逐仓库配置：

- **Issue 跟踪器** — issue 放在哪里（默认 GitHub；本地 markdown 也开箱即用）
- **分类标签** — 五个规范分类角色所用的标签字符串
- **领域文档** — `GLOSSARY.md` 和 ADR 放在哪里，以及读取它们的消费规则

这是一个提示驱动的技能，不是确定性的脚本。探索、呈现你的发现、与用户确认，然后写入。

## 流程

### 1. 探索

# 测试驱动开发（Test-Driven Development）

TDD 是红 → 绿的循环。本技能是让这个循环产出值得保留的测试的参考：好测试是什么、测试放在哪里、反模式有哪些、循环的规则是什么。每一节在每一个循环中都适用——在循环之前和之中查阅它们，而不是之后。

探索代码库时，读 `GLOSSARY.md`（如果存在），让测试名称和接口词汇与项目的领域语言一致，并尊重你正在触碰的区域的 ADR。

## 好测试是什么

测试通过公共接口验证行为，而不是实现细节。代码可以彻底改变；测试不应该。好测试读起来像一份规格——"用户可以用有效购物车结账"精确地告诉你存在什么能力——而且因为它不关心内部结构，能在重构中存活。

示例见 [tests.md](tests.md)，mocking 指南见 [mocking.md](mocking.md)。

## 接缝——测试放在哪里

本技能获取当前的对话上下文和对代码库的理解，产出一份 spec。不要盘问用户——只综合你已经知道的内容。

issue 跟踪器和分类标签词汇应该已经提供给你了——如果没有，告诉用户运行 `/setup-matt-pocock-skills`。

## 流程

1. 如果还没探索过，先探索仓库，了解代码库的当前状态。整个 spec 都使用项目的领域词汇表术语，并尊重你正在触碰的区域的任何 ADR。

2. 勾勒出你将测试该功能的接缝。已有接缝应优先于新接缝。用尽可能高的接缝。如果需要新接缝，在你能达到的最高点提出。代码库中的接缝越少越好——理想数量是一个。

   与用户确认这些接缝符合他们的预期。

3. 用下面的模板写 spec，然后发布到项目的 issue 跟踪器。打上 `ready-for-agent` 分类标签——不需要再做分类。

# 拆分为 Ticket

将计划、规范或对话拆分为一组 **ticket**——tracer-bullet 垂直切片，每个都声明阻塞它的其他 ticket。

Issue 跟踪器和分类标签词汇表应已提供给你——如果没有，请告诉用户运行 `/setup-matt-pocock-skills`。

## 流程

### 1. 收集上下文

从对话上下文中已有的内容开始。如果用户传入引用（规范路径、Issue 编号或 URL）作为参数，获取它并读取其完整正文和评论。

### 2. 探索代码库（可选）

# 分类（Triage）

让项目问题跟踪器上的 issue 走一遍由分类角色组成的小型状态机。

如果本仓库把外部拉取请求（PR）也当作请求入口（见 issue-tracker 配置），分类也覆盖它们：**PR 就是带着代码的 issue**——同样的角色、同样的状态、同样的状态机，只有少数几处下面标注了"仅限 PR"的差异。根据跟踪器配置，把裸的 `#42` 解析为 issue 或 PR。

分类期间发布到问题跟踪器的每条评论或 issue **必须**以这段免责声明开头：

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

## 参考文档

一个模糊的想法来了——大到一个 agent 会话装不下，而且笼罩在迷雾之中：从当前位置到**目的地**的路线还不 visible。Wayfinding 就是寻找那条路线，而不是冲向目的地。本技能将其绘制为 Issue 跟踪器上的**共享地图**，然后逐个处理其**决策 ticket**——问题本身，其答案是一个决策，而非构建中的可交付物切片——直到路线清晰。

每个项目的目标各不相同，命名目标是绘图的第一个行为——它塑造了每一个 ticket。它可能是一份要交付并迭代的规格说明、一个在规划开始前要锁定的决策、或者一个原地进行的变更（如数据结构迁移）。地图是领域无关的——工程工作、课程内容，无论什么形态都适用。

## 规划，而非动手

Wayfinder 默认是**规划**工具：每个 ticket 解决一个决策，地图在路线清晰时完成——不再有任何需要决定的事情，就可以交给别人去动手了。想要直接动手做的冲动，通常是你已经抵达地图边缘的信号，是时候交接了。项目可以在其**笔记**中覆盖这一设定——将执行任务也纳入地图——但默认情况下，产出的是决策，而非可交付物。

## 用名称来引用

每个地图和 ticket 都是一个 issue，因此它有一个**名称**——它的标题。在人读取的一切内容中——叙述、地图的"已有决策"部分——都通过名称来引用，绝不使用原始 ID、编号或短横线标识。一堵 `#42, #43, #44` 组成的墙难以阅读；名称则一目了然。ID 和 URL 不会消失——但名称包裹着链接——它们只是活在名称*内部*，而不是替代它。

## 地图

# 向导

**向导（Wizard）** 是一个 bash 脚本，逐步引导人类完成手动流程——这些流程手动做很繁琐，每次重新向 AI 解释也很麻烦。它会打开每个 URL，精确说明要点击什么和复制什么，捕获值，将其写入正确的位置（`.env`、GitHub secrets），在每个阶段确认，并显示剩余阶段数。它可能配置第三方服务、运行一次性迁移、或把项目从一个状态迁移到另一个状态。

便捷的 UX 已经由 [template.sh](template.sh) 解决——分阶段显示进度、确认关卡、跨平台 URL 打开（含 WSL）、隐藏密文输入、幂等的 `.env` 写入、`gh secret`/`gh variable` 写入，以及一个结束汇总。**你的工作只是界定流程范围并编写其阶段。** 每个向导中 `STAGES` 标记上方的库代码都是相同的——这种一致性正是关键所在，永远不要手动编辑它。

向导默认是临时的——为一次运行而创建，保存在 scratch 或 `scripts/` 路径下，任务完成后删除。仅当用户希望创建一个可重复的设置路径（应留在仓库中）时才提交它。

## 流程

### 1. 界定流程范围

找出人类必须执行的每一个手动步骤以及沿途捕获的每一个值。先阅读仓库——不要凭空提问：

你是一名 chief of staff，通过协调子智能体和日程安排来推进一项长期目标。本次会话将持续很长时间，逐步积累团队内部的隐性知识（tribal knowledge），并帮助你做出长期战略决策。

你是这个目标的 Directly Responsible Individual（直接责任人）。你被赋予了比以往更长远地思考的权限。你必须同时沿两条轨道思考：

- Tactical（战术）：如何完成眼前的任务？
- Strategic（战略）：如何改进环境，让_下一项_任务取得更好的结果？

## 日程安排

在 harness 允许的情况下，你会提出有助于实现目标的周期性日程安排。

## 子智能体

所有工作都应交由子智能体完成。保护好你的上下文窗口。

为当前对话撰写一份交接摘要，让一个全新的 agent 能够继续工作。先将摘要保存到用户操作系统的临时目录，再以该文件内容作为提示启动后台 agent：`claude --bg --name "<描述性名称>" -- "$(cat <summary file>)"`。通过文件传入摘要可避免 shell 执行其中的反引号或展开 `$`。它会在当前工作目录启动并立刻返回；用户通过 `claude agents` 来管理它。

务必传 `-n`/`--name` 并配以描述性名称（例如 `--name "修复登录 bug"`）：它会被设置为任务列表、会话选择器以及终端标题中所显示的标签。

在摘要里加一个 "suggested skills" 部分，建议下一个 agent 调用哪些技能。

不要重复已经被记录在其他产物（规格、计划、ADR、issue、commit、diff）中的内容。引用时用路径或 URL。

抹去任何敏感信息，例如 API 密钥、密码或可识别个人身份的信息：摘要会成为 agent 的提示词。

如果用户传入了参数，把它们当作对下一个会话关注点的描述，并据此裁剪摘要。

运行一个有状态的 `/grilling` 会话，其唯一输出是**工作流**规格。沿用 grilling 纪律：无休无止、一轮接一轮的问题、每题配一个推荐答案：对准下面的词汇表和目标。在 grilling 解决事情的过程中，规格会被创建、编辑、删除。

## 循环透镜

一个**循环（loop）**是用户生活中反复出现的模式：他们的职业、他们的一周、他们的早晨、一个反复出现的活动。把生活看成循环套循环，能揭示这些活动实际上有多么可预测：而这正是它们值得**委托**的原因。用这个透镜去发现值得规格化的循环，并提出用户还没注意到的循环。

一个**工作流（workflow）**是一个循环的规格，使之落地。你在一个循环上运行工作流：循环是它的运行实例。工作流存放在 `workflows/*.md`，是事实的来源。

## 词汇表

一套共享语言，只在工作流需要时才拿出来：绝不是清单。**不要强加任何结构性内容**：一个工作流不需要 AI、检查点或时间表，除非 grilling 表明它确实需要。

- **Trigger（触发器）**：每次运行的触发条件：一个**事件**（新邮件、新 issue）或一个**时间表**（每天早上）。事件触发通常更高效。
- **Checkpoint（检查点）**：一个人工介入点，在此处要求用户验证或决策。有些工作流没有检查点，完全自主；有些根本不用 AI。

# 设置 TS 深度模块

让此仓库中的每个 package 都成为一个**深度模块**：小接口背后隐藏大量行为。一个 package 的公开表面是其**入口点**：package 根目录下的文件：而其子文件夹中的所有内容都是隐藏的。本技能安装 [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) 与让入口点成为唯一通路的规则，然后验证规则确实起作用。

关于相关词汇（深度模块、接口、接缝、depth），请调用 Skill 工具并传入 "codebase-design"：在后续内容中使用它的术语。

## 它强制形成的结构

```
src/packages/
  <name>/
    index.ts        ← 一个入口点（公开）。外部从这里导入。
    client.ts       ← 另一个入口点。Package 可以暴露多个。
    lib/            ← 实现：对外部隐藏，内部可以自由相互导入。

**software factory** 是一种由 agents 组成的系统，它会把 tickets、PRs 和日程安排转化为已合并的代码，并部署到用户选择的远程基础设施上。本技能为设计 factory 提供一套语言。讨论或白板梳理 factory 时，只使用以下术语；如果用户用了 _Avoid_ 下的词，就指出对应的规范术语。

## Tasks and runs

**Task**：
一种由 factory 执行的工作，只需定义一次，就可以反复运行：review、explore、implement、ratchet。Task 可以处理一个 ticket、一个 PR，或整个 codebase。
_Avoid_：job、workflow、action

**Trigger**：
启动一个 run 的事件：ticket tracker 或 git host 中的变更、orchestrator 上的时钟，或另一个 run。

**Run**：
一个 task 在一个 runner 上从触发到结束的一次执行，作为黑盒处理。一个 run 可以直接触发后续 runs、通过 orchestrator 中的逻辑触发，也可以通过更改 ticket tracker 或 git host 触发。run 绝不会等待人类：它会结束，而人类之后对 ticket tracker 或 git host 所做的更改会触发一个新的 run。
_Avoid_：session

<what-to-do>

用户已经传入（或即将传入）一份 markdown 格式的原始素材文件。这是 **exploit（利用）**：探索已经完成，素材堆已经固定：承诺一条路径穿行其中，然后开采素材堆来填充每个节拍。

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

然后进行逐拍推进的自选冒险式旅程：

1. **设定先决条件。** 在任何节拍之前，先与用户确定读者进入时已经知道什么：那些从一开始就被**夯实（grounded）**的概念。其他所有概念必须被某个节拍夯实后，后续节拍才能使用它。参见[夯实（Grounding）](#夯实grounding)。
2. 从原始素材中提炼 2–3 个候选**起始节拍**。每个节拍是文章的一个不同入口。每个节拍只能依赖于已夯实的概念；注意每个节拍夯实了什么新概念。在写入文章文件之前先将节拍展示给用户看。用户选取一个。预览该节拍解锁了哪些后续节拍：让用户仿佛能看得到前方的一小段路。
3. 用户选定起始节拍后，将**仅这一拍**写入文章文件。一个节拍可以是一句话，也可以是若干段：取决于该节拍自然需要多少篇幅。到此为止。
4. 从磁盘重新读取文章文件。然后提供 2–3 个候选**下一节拍**：从文章当前所在位置可以转向的不同方向。每个候选节拍必须能从当前已夯实的集合中触及；注意每个节拍夯实了什么。
5. 循环步骤 3–5，直到文章自然收尾。

<what-to-do>

这是纯粹的 **explore（探索）**：拓宽可被写作的空间，不承诺任何结构：承诺结构是 _exploit（利用）_ 的任务，由另一个技能负责。进行一次产生碎片的盘问，就用户想写的任何话题不断追问。强加阶段、大纲或文章结构在此不在范围内。

当对话双方的碎片浮现时，将它们追加到一份 markdown 文件中。

如果用户没有传入保存路径，询问一次文档保存到哪里，然后在整个对话中记住它。

从用户说的第一件事（包括初始 prompt）开始就捕捉碎片。

首次写入时，在顶部放一个 H1 的工作标题（以后可以改），除此之外什么都不放：没有元数据、没有目录、没有日期。

</what-to-do>

<what-to-do>

用户已经传入（或即将传入）一份 markdown 格式的原始素材文件。将其视为输入材料堆：可以是从整洁的碎片列表到一团无结构的文字墙再到一份转录稿的任何形式。格式不重要。在做任何其他事情之前从头读到尾。

然后进行一次塑造环节，生成一份独立的文章文档。这是 **exploit（利用）**：探索已经完成，素材堆已经固定：承诺一个结构，然后开采素材堆来填充它。不要编辑原始素材文件：它对本技能而言是只读的。

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

</what-to-do>

<supporting-info>

## 循环流程

# 设置 Git 护栏

设置一个 PreToolUse 钩子，在 Claude 执行危险 Git 命令之前拦截并阻止它们。

## 会被阻止的命令

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

当命令被阻止时，Claude 会看到一条消息，告知它没有权限访问这些命令。

# 迁移到 Shoehorn

## 为什么使用 shoehorn？

`shoehorn` 让你在测试中传递部分数据，同时保持 TypeScript 类型正确。它用类型安全的替代方案取代了 `as` 断言。

**仅限测试代码。** 切勿在生产代码中使用 shoehorn。

`as` 在测试中的问题：

- 习惯上被训练不要使用它
- 必须手动指定目标类型
- 双重 `as`（`as unknown as Type`）用于传递故意错误的数据

# 搭建练习框架

创建能通过 `pnpm ai-hero-cli internal lint` 检查的练习目录结构，然后使用 `git commit` 提交。

## 目录命名规则

- **章节（Sections）**：位于 `exercises/` 下的 `XX-section-name/` 格式（例如 `01-retrieval-skill-building`）
- **练习（Exercises）**：位于章节内的 `XX.YY-exercise-name/` 格式（例如 `01.03-retrieval-with-bm25`）
- 章节编号 = `XX`，练习编号 = `XX.YY`
- 名称使用短横线命名法（小写字母、连字符）

## 练习变体

每个练习至少需要以下子文件夹之一：

# 设置 Pre-Commit 钩子

## 将要设置的内容

- **Husky** pre-commit 钩子
- **lint-staged** 对所有暂存文件运行 Prettier
- **Prettier** 配置（如果缺失）
- **typecheck** 和 **test** 脚本在 pre-commit 钩子中运行

## 步骤

### 1. 检测包管理器

检查 `package-lock.json`（npm）、`pnpm-lock.yaml`（pnpm）、`yarn.lock`（yarn）、`bun.lockb`（bun）。使用已存在的那个。如果不确定，默认使用 npm。

调用 Skill 工具并传入 "grilling"。

持续盘问用户，直到你们达成共识。将讨论映射为一棵**设计树（design tree）**：每个决策都会分支出一系列依赖它的子决策。

以**轮次（rounds）**推进这棵树。**前沿（frontier）**是所有前提已确定的决策：即你现在*可以*问的问题，无需猜测尚未听到的答案。每一轮问完整个前沿：为每个问题编号，并给出你的推荐答案。然后等待用户的回答，再进行下一轮。

每个问题格式如下：

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

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

---

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

将当前对话总结为一份交接文档，方便一个全新的智能体继续工作。保存到用户操作系统的临时目录（`$TMPDIR`，否则为 `/tmp`；Windows 上为 `%TEMP%`），而不是当前工作区。

文档中需要包含"建议技能"部分，指明下一个 agent 应该为哪些技能调用 Skill 工具。

不要重复复制已经记录在其他产物中的内容（spec、计划、ADR、Issue、commit、diff）。用路径或 URL 引用它们。

隐去所有敏感信息，如 API 密钥、密码或个人身份信息。

如果用户传入了参数，将其视为对下一个会话关注点的描述，据此调整文档内容。

用户让你教他们一些东西。这是一个有状态的请求：他们打算通过多个会话来学习这个主题。

## 教学工作区

将当前目录视为教学工作区。`./lessons/` 等工作区路径相对于运行 `/teach` 的目录解析；只有 `*-FORMAT.md` 链接相对于此技能文件夹解析。他们的学习状态通过以下几个文件记录在此目录中：

- `MISSION.md`：记录用户对这个主题**感兴趣的原因**的文档。所有教学都应以此为基准。使用 [MISSION-FORMAT.md](./MISSION-FORMAT.md) 中的格式。
- `./reference/*.html`：参考资料目录。这些是课程的压缩学习成果：速查表、参考算法、语法、瑜伽体式、词汇表。它们是学习的原始单元。应该是排版精美的文档，适合打印，并且为快速查阅而设计。
- `RESOURCES.md`：一份资源列表，可以探索以将你的教学建立在情境化知识上，或获取知识和智慧。使用 [RESOURCES-FORMAT.md](./RESOURCES-FORMAT.md) 中的格式。
- `./learning-records/*.md`：学习记录目录，记录用户已经学会了什么。这大致相当于软件开发中的架构决策记录：它们捕获那些非显而易见的教训和关键见解，后续可能需要修正，或用于驱动未来的课程。这些应用于计算最近发展区。文件命名格式为 `0001-<dash-case-name>.md`，编号每次递增。使用 [LEARNING-RECORD-FORMAT.md](./LEARNING-RECORD-FORMAT.md) 中的格式。
- `./lessons/*.html`：课程目录。**课程**是一个独立、自包含的 HTML 输出，教授一个与使命紧密相关的、范围狭窄的内容。这是本工作区教学的主要单元。
- `./assets/*`：跨课程共享的可复用**组件**。参见 [Assets（资源）](#assets)。
- `NOTES.md`：供你记录用户偏好或工作笔记的草稿本。

# 转化为问卷

将用户无法独自回答的问题转化为一份**问卷**：一份 Markdown 文档，交给某个人异步填写，或在会议中共同填写。接收者拥有用户缺乏的知识；问卷负责把这些知识挖掘出来。

**审问"发送"而非"主题"。** 只询问用户关于"发送"的问题：这是他们总能回答的：发给谁，以及需要什么回来。文档中的问题则针对**接收者所知与用户所需之间的差距**。

1. **发给谁？** 用一个来回问清楚接收者的角色、专长，以及和用户的关系。这决定了问卷的语气和需要携带多少上下文。完成条件：你知道了接收者是谁，以及他们知道什么用户不知道的东西。

2. **你需要什么回来？** 用一个来回问清楚用户无法独自解决、需要从这个人那里获得的具体决策或事实。完成条件：你有了一个具体的清单，列出用户必须能据此做出或决定的事情。

3. **撰写问卷。** 针对步骤 1-2 中确定的差距起草问题，遵循下面的文档结构。将问卷写入当前目录下的 `to-questionnaire-<slug>.md` 文件（slug 来自主题），并报告文件路径。完成条件：文件存在，且用户在步骤 2 中提到的每一个项目都有对应的问题覆盖。

## 文档结构

等等：我不太明白你讲到哪了。重新解释一下：给我一点上下文，使用 ASD-STE100 简化技术英语，并用 `GLOSSARY.md` 中的通用语言（如果仓库有多个，按 `GLOSSARY-MAP.md` 找到正确的那个）。

一份用于编写智能体所阅读的任何文档的参考：一个技能、一份 `AGENTS.md` / `CLAUDE.md`、一份通过指针触达的文档。包装方式各异，但写作规则是一致的：同样的杠杆让每份文档都变得可预测，因为智能体每次运行采取的是同一个*流程*，而不是产出同一个输出。

当你正在编写的文档是一个技能时，请阅读 [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md)，了解前置元数据、调用方式的选择，以及路由技能。

## 上下文指针

**上下文指针（context pointer）** 是智能体上下文中持有的一条引用，它指向一份"上下文之外"的资料，并编码了触达该资料的条件。技能的 `description` 就是一条；`AGENTS.md` 中指向某份文档的一行也是同一回事。决定智能体何时、以多高的可靠性触达这份资料的，是这条指针的*措辞*，不是它的指向。一个本应被触达的指向目标，却藏在一段措辞含糊的指针背后：这是一个方差 bug：先打磨措辞；只有当打磨失败时，才把资料直接内联进去。

一条指针承担两件事：说明这份资料是什么，以及列出应当触发触达它的**分支**（branch 是这份文档所处理的一种独立情形，所以不同次运行会走不同的路径）。每一条始终加载的指针里的每一个词，在每一次轮次中都在付代价，所以它需要比正文更严格的精简：

- **把"引导词"前移**：指针是触发工作真正发生的地方。
- **一个分支对应一个触发词。** 同义词把同一个分支换了个说法写两遍，本质上是一个分支；把它们合并，只保留真正不同的分支。
- **去掉正文已经承载的身份信息。**