walkthrough

walkthrough — 阶段 2：走查计划

Agent 完成执行和验证后，会输出一份走查文档：一个 Markdown 文件，让你快速了解改了什么、哪些内容已验证可用，并能在合并前使用 Git 执行暂存检查。

此计划参考了 Google Antigravity 的 walkthrough plan：预期 Agent 能证明改动有效（单元测试 + 真实浏览器行为）、收集视觉证据，并为你设置一个评审关卡，而不只是丢下一份差异。

适用时机

• /goal（或任何实现工作）及其验证环节完成后 — 例如完成 /review-it / /verify / 手动测试后
• /ship-it 之前，作为提交/PR/合并前的最后一个检查点
• 用户说“walkthrough”“生成 walkthrough”“生成走查文档”“write the walkthrough”“/walkthrough”或“Phase 2 walkthrough”时

工作内容

1. 确定改动范围 — 本次走查涉及哪个功能 / Issue / 分支，以及涵盖哪些仓库
2. 撰写通俗易懂的开篇 — 改动前后对比及原因，让从未看过代码的人也能读懂
3. 撰写改动摘要 — 为接下来查看差异的人提供技术细节
4. 运行并记录验证步骤 — 执行测试和命令，记录实际输出，并标明每项结论的来源
5. 收集视觉证据 — 截图 / 录制已验证的 UI 行为
6. 设置评审关卡 — 使用 Git 检查暂存区中的差异，起草 PR 描述，并明确部署顺序的前置条件
7. 保存到 tasks/ 并呈现 — 写入 walkthrough-[feature].md，将其渲染为 HTML，并为用户总结

逐节说明

1. 先说人话 / 通俗易懂的开篇（必读）

这是文件中的第一部分。PM、QA、相邻团队成员，或三个月后的你，都必须只读这一节就能了解改了什么，以及为什么值得关注。

必需内容：

• 改动前 / 改动后，具体说明 — 写用户 / 调用方看到什么，而不是代码做了什么：

  	改之前	改之后
  {用户/调用方看到什么}	{old behaviour}	{new behaviour}

• 改动原因 — 用通俗语言说明 2–3 个理由。如果不提类、标志或表就无法说明理由，说明你还不够了解这项改动，无法撰写本节。

• 读者需要采取哪些不同操作（如有），例如调用新的端点、运行迁移或更改客户端。

规则：

• 开篇绝不能使用标识符。 dryRun、draft_id、PriorityResolver 都不算解释。先用通俗语言介绍概念，再给出名称。
• 除非用通俗语言解释清楚 A 和 B，禁止写类似 “X 从「A」改为「B」” 的句子。
• 如果改动对用户可见，请从用户的角度描述。

BAD  (技术上没错，但读的人解不开)
> 把优先级的写入时机从「即时落库」改为「先返回 draft_id、确认后落库」

GOOD (同一件事)
> 用户改任务优先级时，以前客户端发一次就直接写进数据库；现在后端先把可选的优先级算出来
> 让用户挑一个，挑完才写。用户没挑就不写。

1b. 术语表 — 仅在文档使用内部术语时添加

如果文档使用了以下任何内容：内部标志 / 字段名（dryRun）、数字接口 ID（1001）、外部人员无法理解的领域术语（「归一化」「草稿」），或无法从文件树推断的模块名 — 请添加两列表格，将文档中的说法映射为通俗语言。

| 文中说法 | 说人话 |
|---|---|
| `dryRun` | 开关：`true` = 只算不写，不传 = 老行为 |
| 「草稿」 | 算出来、还没落库的中间结果 |

• 不要解释标准术语（HTTP、SQL、PR）— 那会显得是在凑内容。
• 特别注意名称相似但含义不同的概念。如果两个名称相似的概念容易混淆，请在表中明确指出 — 读者最容易在这里迷失。

2. 改动摘要

面向即将查看差异的读者，提供技术说明。标识符应放在这里 — 通俗语言部分已经介绍过它们。

• 阅读差异（git diff、git log）以及相关的 Issue / PRD
• 用 3–6 个要点总结构建、重构、添加或移除了哪些内容
• 列出关键文件和组件，并说明新增内容的组成形式（模块、页面、API、数据结构）
• 说明满足了什么需求；如果有 Issue / PRD，请附上链接

3. 验证步骤

证明实现确实可用的证据，而非断言。记录运行了什么，以及输出了什么。

• 终端命令和单元测试：运行测试套件（或目标测试）、lint/build 以及任何冒烟测试命令。粘贴准确的命令及其成功输出（删减无关内容，但保留通过数量）。

  go test ./... -run TestPriority
  

  ok  	github.com/example/app 0.042s
  

• 自动化浏览器测试结果（如果改动涉及 UI）：在沙盒/无头浏览器中打开应用，按演示路径逐步操作，并记录结果。对每种场景，记录执行的操作、观察到的结果，以及通过/失败。

  Scenario: user sets a task's priority
    1. open /tasks — renders list
    2. click priority select on task #3 → pick "High"
    3. reload — task still shows High  ✓
  

• 如果跳过了某个步骤（没有测试、没有 UI），请明确说明，不要编造证据。

为每条声明标注来源。 分为三个级别，并说明适用哪一级：

标签	含义	示例
已实测	你运行过，并且有输出	95 PASSED / 0 FAILED
代码推断	从代码或单元测试中读取，但未执行	「没有优先级时回落 normal」（PriorityResolverTest 里有对应测试用例，但没运行）
未验证	两者都不是——必须明确说明	「本机没有数据库/缓存/外部服务，本环境未验证服务级行为」

绝不要把代码推断或未验证说成已实测。夸大证据的演练说明比存在缺漏的说明更糟，因为读者会去核查那些缺漏。

记录你如何让命令成功运行。 如果需要变通方法——离线模式、配置覆盖、初始化脚本、缩小测试筛选范围——请记录下来，否则读者无法复现你的证据。

./gradlew test --offline --rerun -I /tmp/no-failfast.gradle \
  --tests "com.example.tasks.*" --console=plain
# 依赖仓库在本机不可达，必须加 --offline；构建脚本设了 failFast=true，
# 不覆盖的话第一条失败就停，看不到完整清单

如果运行器的默认设置会造成误导，也要记录基线注意事项：例如 failFast 隐藏后续失败、测试缓存重放旧结果（--rerun），或者测试套件在你改动前就已失败。

如果更大范围的测试套件有失败，必须逐一追溯每个失败——不要写「无关」。 对每个失败，请说明：

• 文件/类、最近一次修改它的提交及日期
• 该提交是否是你基线的祖先（→ 已存在的问题）
• 该提交是否位于你自己的提交范围内（→ 由你引入）

| 失败用例 | 所属类最后修改提交 | 是 base 祖先？ | 在本分支提交内？ |
|---|---|---|---|
| `PriorityResolverTest > defaultsToNormal()` | `1a2b3c4d` 2026-01-15 | 是 | 否 |

可追溯到你基线之前提交的失败属于已存在的问题——请注明哈希值，让读者可以重新核查。你提交范围内的失败就是你的问题，无论看起来多么无关。

4. 视觉证据

在浏览器测试期间截取的截图或短屏幕录制，直接嵌入文件中，确保在任何地方（GitHub、VS Code、浏览器）都能显示。

• 截图：在上述浏览器演练期间截取。使用 base64 data URI 嵌入，使文件完全自包含（推荐）：

  ![Task priority — set to High](data:image/png;base64,<base64>)
  

  在 macOS 上可以使用 screencapture 截取窗口；对于网页，优先使用浏览器自动化工具（例如 Playwright：npx playwright screenshot <url> tasks/shot.png，然后读取 PNG 并嵌入）。
• 录屏：如果录制了屏幕视频，请注明其路径，并在文件中添加链接（![Demo](tasks/recording-demo.mov)）。
• 优先提供 2–4 张能证明演示路径的重点截图（之前 → 操作 → 之后），而不是堆砌截图。
• 如果改动没有可视界面，请写明「无——改动仅涉及后端/CLI」，不要为了截图而强行截图。

5. 审查关卡

合并前，你（或用户）使用 Git 对代码进行暂存检查时查看的最终差异 / PR 描述。

• 差异统计 + 文件列表：git status、git diff --stat HEAD、git diff --name-status

• 高风险说明：指出强制推送的历史记录、迁移、配置变更、大范围重构、子模块指针更新

• 部署顺序前置条件（只要变更包含 DDL / 迁移 / 配置键 / 功能标志，就必须说明）——明确指出 (a) 必须应用的内容，(b) 如何应用（手动还是自动），(c) 顺序错误时的故障模式：

  > `0042-add-priority-to-tasks.sql` 给 `tasks` 表加 `priority` 列。
  > **不会被任何 compose 自动执行**（唯一挂载的 initdb 目录指向的是另一个路径），
  > 必须手工应用到所有环境。实体已映射该列且 ddl-auto=none →
  > 代码先上线会让**每一次** Task 查询抛 SQLGrammarException，
  > 即整个服务的任务查询全挂，而非仅新功能不可用。
  

仅仅说“记得跑一下 migration”是不够的。读者需要了解影响范围，因为这决定了他们是谨慎安排，还是冒险操作。

• PR 描述草稿：可直接粘贴的 PR 正文（摘要、测试计划、Closes #N），与 /ship-it 保持一致
• 合并检查清单：确认测试通过、审查完成、git status 中没有多余文件，提交消息中引用了 Issue

多仓库变更。 如果工作涉及多个仓库：

• 每个仓库都提供一份文件列表和验证部分，并分别说明分支状态（本地与远程是否一致？是否已推送？PR 是否已创建？）
• 明确说明这些分支必须一起合并，并指出如果只合并其中一个会导致什么问题
• 分别验证每个仓库的检出状态。你没有打开过的仓库，就不能算已验证——不要仅凭单个检出就断定“另一部分尚未实现”；同一仓库常常会在不同路径下、处于不同分支。

输出

两个文件，基名相同：

文件	用途
tasks/walkthrough-[feature-name].md	**源文件。**你编写和编辑的内容。使用 kebab-case，例如 walkthrough-priority-system.md
tasks/walkthrough-[feature-name].html	**交付物。**交给审查者的文件。由 .md 生成，绝不手动编辑

HTML 不可省略——这是人们实际阅读的产物。它采用浅色主题 （暖白色背景、衬线标题、赤陶色点缀），完全自包含（无 CDN、无外部 资源），并带有左侧的固定目录侧栏，由文档中的 h2 / h3 构建。

使用此技能附带的脚本渲染：

python3 scripts/md2html.py tasks/walkthrough-[feature-name].md
# or, once installed:
python3 ~/.claude/skills/walkthrough/scripts/md2html.py tasks/walkthrough-[feature-name].md

• 在输入文件旁写入 walkthrough-[feature-name].html；传入第二个路径可覆盖默认路径。
• --title "…" 可覆盖页面标题（默认使用文档的 # H1）。
• 需要 markdown 包：python3 -m pip install --user markdown。如果缺少该包，脚本会显示这条安装说明后退出——请转达此信息，不要悄悄跳过 HTML。
• 内嵌的 data: 图片 URI 会原样保留，因此 Visual Proof 截图不会丢失。
• 每次编辑 .md 后都要重新渲染。更新后的 Markdown 旁边放着过期 HTML，比没有 HTML 更糟：审查者会读到过期内容。

如果用户提供了名称（/walkthrough user-auth）或 Issue 编号（/walkthrough #42），就使用该名称或编号。如果当前分支是 feat/issue-42-* 或 feat/priority-system，则从分支名中推导功能名称。否则请询问。

模板

# Walkthrough — {Feature / Issue Title}

> Phase 2 walkthrough artifact · generated {date} · {author}
> {跨哪几个仓 / 分支名，若只有一仓则省略}

## Change Summary

### 先说人话：这次到底改了什么

{2–4 句，不含任何标识符。改之前什么样、改之后什么样。}

| | 改之前 | 改之后 |
|---|---|---|
| {用户/调用方看到什么} | {old behaviour} | {new behaviour} |

{为什么改，2–3 条大白话。}
{读的人需要做什么不同的事吗？}

### 术语表

| 文中说法 | 说人话 |
|---|---|
| {identifier / 数字接口号 / 领域词} | {plain meaning} |

### 技术摘要

{2–4 sentence high-level description — 到这里才允许出现标识符}

- {bullet: what was built/refactored/added/removed}
- {key files, components, pages, APIs}
- {requirement satisfied — link Issue/PRD}

## Verification Steps

### Terminal commands & unit tests

```bash
{exact command, including any workaround needed to make it run}
```
```
{actual output — pass counts, ok lines}
```

**provenance:** {已实测 / 代码推断 / 未验证} — {对每条重要结论标注}
{若跑不了：本机缺什么（DB/Redis/外部服务），因此哪一层未被验证}

{若更宽的测试面是红的，逐条列表并给出「是 base 祖先吗 / 在本分支内吗」}

### Automated browser testing

| # | Scenario | Action | Observed result | Status |
|---|----------|--------|-----------------|--------|
| 1 | {demo step} | {clicks / inputs} | {what happened} | ✅ / ❌ |

## Visual Proof

![{caption}](data:image/png;base64,{base64})

_{or: None — change is backend/CLI only}_

## Review Gate

```bash
git status
git diff --stat HEAD
git diff --name-status
```
{output}

### High-risk notes

{force-pushed history / migrations / config / submodule bumps}

**部署顺序前置** {仅当涉及 DDL / migration / 配置项 / 开关}
- 要应用什么：{文件路径}
- 怎么应用：{手工 / 自动；若「不会被任何东西自动执行」就直说}
- **顺序错了会怎样**：{blast radius，不是「功能不可用」而是「什么会一起挂」}

### Draft PR

{ready-to-paste PR body — Summary / Test plan / Closes #N}

### Merge checklist

- [ ] Unit tests / build pass (evidence in Verification Steps)
- [ ] Browser testing done where UI changed (evidence in Visual Proof)
- [ ] Review pass complete (/review-it)
- [ ] No stray artifacts in `git status`
- [ ] Commit messages reference the Issue
- [ ] 每条结论都标了 provenance（已实测 / 代码推断 / 未验证）
- [ ] 若有更宽测试面的红，逐条追溯到 commit 并说明是否在本次范围内
- [ ] 部署顺序前置已写清（含 blast radius），若有
- [ ] 多仓时：每个仓各自的文件清单/证据/分支状态都齐了

确定功能名称

1. 如果用户提供了名称（/walkthrough user-auth），就使用该名称
2. 如果当前分支是 feat/issue-42-* / feat/priority-system / fix/issue-42-*，则从分支名中推导（去掉 feat/ 前缀和 Issue 编号）
3. 如果 tasks/ 中存在 PRD / SPEC（prd-*.md、spec-*.md），则沿用其中的功能名称
4. 否则询问：“walkthrough 应使用什么功能名称？”

边缘情况

场景	处理方式
未检测到更改（git diff 为空，没有新增内容）	明确说明；不要编造操作说明
不存在测试	注明“仓库中没有自动化测试”，并依据手动／浏览器验证证据
更改没有 UI	视觉证明 = “无 — 仅后端／命令行”；将浏览器测试部分标记为不适用
截图嵌入失败	改用 tasks/*.png 相对路径，并注明这些文件需要一并提交
缺少 tasks/ 目录	自动创建
此功能已有操作说明	询问：原位更新还是覆盖？默认 = 覆盖（生成全新快照）
无法完成验证	在评审门禁中将其记录为阻碍项——绝不要把未经验证的工作标记为已证实
更大范围的测试套件未通过	撰写任何内容前，先将每项失败追溯到某个提交（是否为 base 的祖先？）。“无关”若没有哈希作为依据，就不算证据
更改涉及多个仓库	每个仓库单设一节，并明确注明“必须一并合并”；检查每个工作副本——没有打开的仓库就不能算已验证
更改包含 DDL／迁移／标志	必须注明部署顺序前置条件及影响范围
只有部分更改能在本地测试（没有数据库／Redis／外部服务）	说明在此环境中哪些层未经验证；夸大证据的文档不如明确说明不足之处的文档
文档充斥内部标识符	添加通俗易懂的开篇和术语表。如果开篇段落包含标志名称，就说明尚未写好
未安装 markdown 包	转达脚本的安装提示（python3 -m pip install --user markdown）；不要悄悄跳过 HTML
渲染后又编辑了 Markdown	重新运行渲染器。不要让过时的 .html 与更新后的 .md 并存
文档将分享给团队外部人员／发布到公开仓库	撰写前，将所有特定于仓库的示例（路径、类／表／列名称、提交哈希、内部主机）替换为通用内容

与其他技能的关系

/goal → /review-it → /note-it → /walkthrough → /ship-it
   │         │           │           │             │
 execute   find/fix   rationale   proven +      commit + PR
                                  review gate

• /review-it — 修复问题并确认更改可靠；操作说明假设此技能（或等效流程）已运行
• /note-it — 按 Issue 记录设计依据；操作说明记录证明和摘要，两者互为补充
• /understand — 解释新增代码的作用；操作说明是交给评审者的正式材料
• /ship-it — 使用操作说明：评审门禁中的 PR 草稿和检查清单会直接用于此流程

检查清单

保存前：

• 已写好通俗易懂的开篇，且不含标识符——非工程人员也能独立读懂
• 说明更改前后的情况，以及更改原因
• 文档使用内部 ID／标志／领域术语时，附上术语表；指出容易混淆的概念对
• 更改摘要面向初次阅读者撰写（不是 diff 内容转储）
• 每个验证步骤都展示实际命令和实际输出
• 如果命令需要变通方法才能运行，已记录该方法
• 每条声明均标记为“已实测”／“代码推断”／“未验证”
• 将更大范围测试套件中的失败追溯到提交（哈希 + 是否早于 base），而不是含糊地称为“无关”
• 存在 UI 时，记录浏览器测试场景及通过／失败结果
• 已嵌入视觉证明（base64），或明确注明“无”
• 评审门禁中包含 git status／git diff --stat、PR 草稿和合并检查清单
• 如果更改包含迁移／配置／标志，已注明部署顺序前置条件及影响范围
• 多仓库更改：每个仓库都有自己的文件列表、证据和分支状态
• 未验证的声明均已标明为未验证——没有编造内容
• 已保存至 tasks/walkthrough-[feature-name].md
• 已渲染为 .html，并在最后一次 Markdown 编辑后重新渲染（保留目录侧边栏）
• 如果此文档将用于共享／公开场合，示例中没有泄露仓库内部专有信息