walkthrough

Name: walkthrough
Author: smallnest

github.com/smallnest開発29779 回インストール7 週間前に更新

リポジトリ

walkthrough について

walkthrough は、実装と検証の完了後に Markdown と HTML のレビュー資料を作成するスキルです。平易な変更概要、検証証拠、視覚的な証拠、マージ前の Git レビュー手順をまとめます。

主な機能

01平易な説明と技術的な詳細で変更を記述
02テストコマンド・出力・証拠の出所を記録
03ブラウザー検証と視覚的な証拠を掲載
04Git の変更を確認しマージレビューを準備
05Markdown を単体 HTML ファイルに変換

活用シーン

01マージ前の機能作業の記録
02レビュー担当者とのテスト結果・証拠の共有
03ステージング確認と PR 説明文の準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/smallnest/goal-workflow --skill walkthrough

インストール後、Claude Code で/walkthroughを入力して読み込まれたか確認します。

同梱ファイルscripts/md2html.py

詳細

walkthrough — フェーズ 2：ウォークスルー計画

エージェントが実装と検証を終えると、ウォークスルー用の成果物を出力します。これは、何が変更されたか、何が動作することを確認できたかをすばやく把握でき、マージ前に Git でステージングチェックを行える単一の Markdown ファイルです。

これは Google Antigravity のウォークスルー計画をモデルにしています。エージェントには、変更が動作することを証明し（ユニットテスト＋実際のブラウザーでの動作）、視覚的な証拠を記録し、レビューの判断ポイントを提示することが期待されます。差分をそのまま出力するだけではありません。

使用するタイミング

/goal（または任意の実装）とその検証が完了した後。例：/review-it／/verify／手動テストの後
/ship-it の前。コミット／PR／マージ前の最後のチェックポイントとして
ユーザーが「walkthrough」、「生成 walkthrough」、「生成走查文档」、「write the walkthrough」、「/walkthrough」、「Phase 2 walkthrough」と言ったとき

目的

変更の範囲を特定する — どの機能／Issue／ブランチをウォークスルーするのか、また対象となるリポジトリを特定します
平易な言葉で冒頭を書く — 変更前／変更後とその理由を、コードを見たことがない人にもわかるように説明します
変更の概要を書く — 次に差分を読む人向けに、技術的な詳細をまとめます
検証手順を実行して記録する — テストとコマンドを実行し、実際の出力を記録して、各主張の根拠を明記します
視覚的な証拠を記録する — 検証した UI の動作をスクリーンショットまたは録画で残します
レビューチェックポイントを作成する — Git で差分をステージングチェックし、PR の説明文を下書きし、デプロイ順序の前提条件を明記します
tasks/ に保存して提示する — walkthrough-[feature].md を作成し、HTML に変換して、ユーザー向けに要約します

セクションごとの説明

1. 平易な言葉で説明する / 冒頭（必読）

ファイルの最初に記載します。PM、QA、隣接チームのメンバー、または 3 か月後の自分が、このセクションだけを読んで、何が変わったのか、なぜ重要なのかを理解できなければなりません。

必須内容：

変更前／変更後を具体的に記載します。コードの動作ではなく、呼び出し元／ユーザーに見える内容を説明します。

変更前変更後
{ユーザー／呼び出し元に見える内容} {以前の動作} {新しい動作}
変更した理由 — 平易な言葉で 2～3 個の理由を挙げます。クラス名、フラグ名、テーブル名を使わずに理由を述べられない場合、このセクションを書くには変更を十分に理解できていません。
読み手が異なる対応をする必要があるかどうか（ある場合）。例：新しいエンドポイントを呼び出す、マイグレーションを実行する、クライアントを変更する。

ルール：

識別子から書き始めないでください。 dryRun、draft_id、PriorityResolver は説明ではありません。まず概念を平易な言葉で紹介し、次に名前を示してください。
*「X が『A』から『B』に変わった」*という文は、A と B の両方を平易な言葉で説明しない限り禁止です。
変更がユーザーに見える影響をもたらす場合は、ユーザーの視点から説明してください。

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

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

1b. 用語集 — ドキュメントに内部用語がある場合のみ

ドキュメントに次のいずれかが含まれる場合は、ドキュメント内の表現と平易な言葉での説明を対応させた 2 列の表を追加します。内部フラグ／フィールド名（dryRun）、数値のインターフェース ID（1001）、外部の人には意味がわからないドメイン用語（「归一化」「草稿」）、ファイルツリーから判断できないモジュール名が該当します。

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

標準的な用語（HTTP、SQL、PR）は説明しないでください。余計な記述に見えてしまいます。
似ているのに意味が異なる用語の組み合わせには特に注意してください。名前が似ていて混同しやすい概念が 2 つある場合は、表でその違いを明示してください。読者が実際につまずくのは、まさにそうした箇所です。

2. 変更の概要

差分をこれから開く読者向けの技術的な説明です。識別子を使うのはここからです。平易な言葉のセクションですでに説明しているためです。

差分（git diff、git log）と、その変更に対応する Issue／PRD を確認します
実装、リファクタリング、追加、削除した内容を 3～6 個の箇条書きでまとめます
主要なファイルとコンポーネント、および新しく追加されたものの構成（モジュール、ページ、API、データ構造）を列挙します
対応する要件を示し、該当する場合は Issue／PRD へのリンクを記載します

3. 検証手順

実装が実際に動作することを示す証拠です。主張ではなく、証拠を記録してください。実行した内容と、その出力を記録してください。

ターミナルコマンドとユニットテスト：テストスイート（または対象を絞ったテスト）、lint／ビルド、スモークテスト用コマンドを実行します。実行した正確なコマンドと、成功時の出力を貼り付けてください（不要な出力は省略し、成功件数は残してください）。
```
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 なしなど）は、その旨を明記してください。証拠を捏造しないでください。

すべての主張について、根拠を明記してください。 レベルは 3 段階です。どれに該当するかを記載してください。

ラベル	意味	例
已实测	実行し、出力を確認済み	`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 データ URI として埋め込む方法を推奨します。
```
![Task priority — set to High](data:image/png;base64,<base64>)
```
macOS では screencapture でウィンドウを撮影できます。Web ページの場合は、ブラウザ自動化ツールを使うことをおすすめします（例：Playwright で npx playwright screenshot <url> tasks/shot.png を実行し、PNG を読み込んで埋め込みます）。
録画：画面録画を撮影した場合は、パスを記載し、ファイル内でリンクしてください（![Demo](tasks/recording-demo.mov)）。
デモの操作手順を証明できる、要点を絞ったスクリーンショットを 2～4 枚使用してください（操作前 → 操作 → 操作後）。スクリーンショットを大量に並べるのは避けてください。
変更に視覚的な要素がない場合は、無理にスクリーンショットを用意するのではなく、「なし — 変更はバックエンド／CLI のみ」と記載してください。

5. レビューゲート

マージ前に、あなた（またはユーザー）が Git でコードをステージングチェックする際の最終的な diff／PR の説明です。

Diff の統計情報とファイル一覧：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，
> 即整个服务的任务查询全挂，而非仅新功能不可用。
```
「マイグレーションを実行してください」だけでは不十分です。読者が慎重にスケジュールを組むか、行き当たりばったりで進めるかを判断できるよう、影響範囲を示す必要があります。
PR の説明文案：すぐに貼り付けられる PR 本文（概要、テスト計画、Closes #N）。/ship-it と同じ内容にします
マージチェックリスト：テストがすべて成功していること、レビューが完了していること、git status に不要な成果物がないこと、コミットメッセージが Issue を参照していることを確認します

複数リポジトリにまたがる変更。 作業が複数のリポジトリにまたがる場合：

リポジトリごとにファイル一覧と検証セクションを用意し、それぞれのブランチ状態（ローカルとリモートが同じか、プッシュ済みか、PR がオープンか）を記載します
ブランチを必ずまとめてマージする必要があることと、片方だけマージされた場合に何が壊れるかを明記します
各リポジトリのチェックアウトを個別に検証します。開いていないリポジトリは、検証したリポジトリではありません — ひとつのチェックアウトだけを見て「もう片方は実装されていない」と結論づけないでください。同じリポジトリが、異なるパスやブランチで複数存在することがよくあります。

出力

同じベース名のファイルを 2 つ作成します：

ファイル	役割
`tasks/walkthrough-[feature-name].md`	ソース。作成・編集するファイルです。ケバブケースを使用します。例：`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 がないよりも悪い状態です。レビュアーは古い 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），若有
- [ ] 多仓时：每个仓各自的文件清单/证据/分支状态都齐了

機能名の決定方法

ユーザーが指定した場合（/walkthrough user-auth）は、その名前を使用します
feat/issue-42-*／feat/priority-system／fix/issue-42-* ブランチの場合は、ブランチ名から導き出します（feat/ プレフィックスと Issue 番号を削除します）
tasks/ に PRD／SPEC（prd-*.md、spec-*.md）がある場合は、その機能名を再利用します
それ以外の場合は、「walkthrough で使用する機能名は何ですか？」と尋ねます

エッジケース

シナリオ	対応
変更が検出されない（`git diff` が空で、新しい内容もない）	その旨を明確に伝え、ウォークスルーを捏造しない
テストが存在しない	「リポジトリに自動テストはありません」と記載し、手動／ブラウザーでの検証結果を根拠とする
変更に UI がない	Visual Proof = 「なし — バックエンド／CLI のみ」とし、ブラウザーテストのセクションを N/A とする
スクリーンショットの埋め込みに失敗した	`tasks/*.png` の相対パスに切り替え、これらのファイルも一緒にコミットする必要があると記載する
`tasks/` ディレクトリがない	自動的に作成する
この機能のウォークスルーがすでにある	既存の内容を更新するか、上書きするかを尋ねる。デフォルトは上書き（最新のスナップショット）
検証を完了できなかった	Review Gate にブロッカーとして記録する。未検証の作業を検証済みとして扱わない
より広範なテストスイートが失敗している	何かを書く前に、各失敗をコミットに紐付ける（base の先祖か？）。ハッシュのない「無関係」という説明は根拠にならない
変更が複数のリポジトリにまたがる	リポジトリごとにセクションを設け、「まとめてマージする必要がある」と明記する。各チェックアウトを確認する。開いていないリポジトリは検証済みではない
変更に DDL／マイグレーション／フラグが含まれる	影響範囲を含むデプロイ順序の前提条件を必ず記載する
変更の一部しかローカルでテストできない（DB／Redis／外部サービスがない）	この環境ではどのレイヤーが未検証なのかを記載する。根拠を誇張するドキュメントより、未解決の点を明示するドキュメントのほうがよい
ドキュメントに内部識別子が多い	平易な言葉での導入文と用語集を追加する。導入段落にフラグ名が含まれているなら、まだ書き終えていない
`markdown` パッケージがインストールされていない	スクリプトのインストール方法（`python3 -m pip install --user markdown`）を伝える。HTML の生成を黙って省略しない
レンダリング後に Markdown を編集した	レンダラーを再実行する。新しい `.md` の隣に古い `.html` を残さない
ドキュメントをチーム外／公開リポジトリで共有する	書き始める前に、リポジトリ固有の例（パス、クラス名／テーブル名／カラム名、コミットハッシュ、内部ホスト）をすべて一般的なものに置き換える

他のスキルとの関係

/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 — ウォークスルーを利用します。Review Gate のドラフト PR とチェックリストがそのまま引き継がれます

チェックリスト

保存する前に確認してください。

Markdown 対応

ログインしてコメント

基本情報

作者: smallnest
リポジトリ: smallnest/goal-workflow
カテゴリ: 開発
インストール数: 79
GitHub スター: 297

問題を報告