cursor-walkthrough

name	cursor-walkthrough
description	コードリーディング支援。差分（PR・ブランチ・ローカル未コミット）と既存コード（ファイル・ディレクトリ・自然文領域）を横断的に受け取り、冒頭で「全体像 + 読む順序 + 詳細化メニュー」を提示 → ユーザー指定箇所のみ深掘り → docs/walkthrough/ にキャッシュ保存する。AI が書いた実装のレビュー、他人の PR 理解、既存コード読解を1本でまかなう。「コードリーディングがきつい」「PR の差分が追えない」「このコード何してる？」「ウォークスルーして」「読み解くの手伝って」といった要望に使う。/cursor-pir2 の直後に追いがけで呼ぶこともできる。ユーザーが /cursor-walkthrough と入力したら必ずこのスキルを使う。
argument-hint	[target（PR番号 / ブランチ名 / ファイルパス / ディレクトリパス / 自然文領域、省略時はローカル未コミット差分）] [--team] [--no-save] [--fresh]

Walkthrough — コードリーディング支援

差分または既存コードを対象に、全体像・読む順序・詳細化メニューを段階提示する。毎回 docs/walkthrough/ に保存し、同一対象への再起動時はキャッシュとして再利用する。

target: $ARGUMENTS（省略時はローカル未コミット差分）

スキル本体（メインエージェント）がオーケストレーターとして全エージェントの起動権限を持つ。subagent同士の相互起動は行わない。

---

ステップ 0: 環境確認と引数解析

echo "PROJECT_ROOT=$(pwd)"
echo "TODAY=$(date +%Y-%m-%d)"
echo "NOW=$(date -Iseconds)"

$ARGUMENTS から以下を解析する:

• --team: チームモード強制フラグ
• --no-save: 保存スキップフラグ
• --fresh: キャッシュ無視フラグ
• 残りの文字列: target（空なら省略扱い）

フラグを除いた target を TARGET として保持する。

---

ステップ 1: target 判定

以下を上から順に評価し、最初にマッチしたものを採用する:

1. TARGET が空 → local-diff モード（git diff HEAD で出力が空でないことを確認）
2. #123 / 数字のみ / GitHub PR URL → pr モード
3. 実在するファイルパス → file モード
4. 実在するディレクトリパス → directory モード
5. git show-ref --verify refs/heads/<TARGET> もしくは refs/remotes/<TARGET> で実在 → branch モード
6. 上記どれにもマッチしない → topic モード（自然文領域）

判定が複数解釈可能な場合（例: auth が実在ブランチかつ自然文にもなりうる）、推測せず1メッセージ1質問でユーザーに確認する。

判定結果を MODE と TARGET_ID として保持する。

---

ステップ 2: キャッシュヒット判定

--fresh フラグがある場合はこのステップをスキップして新規扱いで進む。

docs/walkthrough/ を走査し、MODE と TARGET_ID から決まるファイル名（命名規則はステップ6参照）が存在するか確認する。存在すればフロントマターを読み、以下の鮮度判定を行う:

MODE	判定	完全ヒット	部分変化	陳腐化
pr / branch	head_sha 比較	sha 一致 → 再利用	sha 不一致 → 差分のみ再調査	base 消滅 → 再調査
file / directory	mtime + hash	全一致 → 再利用	一部変化 → 変化箇所のみ再調査	全変化 or 構造変化 → 再調査推奨
topic	文字列マッチ	一致確認で再利用	—	ユーザー判断で新規
local-diff	現在 diff のハッシュ比較	一致 → 再利用	不一致 → 差分のみ再調査	—

created_at から30日以上経過していれば「30日前の調査です」と1行添える（強制無効化はしない）。

対象ファイル削除の検出

file / directory / local-diff モードで cache_key.files に記録されているパスのうち現時点で存在しないものを抽出し「削除済みファイル」として扱う。差分再調査の対象から除外し、ウォークスルー本文冒頭に「削除されたファイル: <path>」と注記する。モジュール全体削除レベル（対象ディレクトリ自体の消失、記録されたファイルの過半数が削除）なら「[3] 完全に再調査」を推奨する旨を提示に添える。

ヒット時の提示

前回のウォークスルーが見つかりました: docs/walkthrough/<file>
- 作成: YYYY-MM-DD HH:MM
- 鮮度: [完全一致 / 部分変化 / 古い可能性]
- [変化箇所があれば: 差分 N ファイル]
- [削除済みファイルがあれば: 削除 M 件]

どうしますか？
[1] そのまま表示（+ 詳細化ループへ）
[2] 変化箇所のみ再調査して更新（推奨）
[3] 完全に再調査（`--fresh` 相当。既存は `-2` などの連番で履歴保持）

ユーザーの選択に応じて分岐する:

• [1]: キャッシュ本文をそのまま表示し、ステップ 7（詳細化ループ）へ
• [2]: 変化箇所のみステップ 3 以降を実行し、該当パートを追記更新してからステップ 7 へ
• [3]: 既存ファイルを <file>-2.md（以降 -3, -4 と連番）にリネーム、新規作成扱いでステップ 3 へ

ヒットしなかった場合はそのままステップ 3 へ。

---

ステップ 3: 対象取得

MODE ごとに以下の方法で対象を取得する:

MODE	取得手段
local-diff	git status + git diff HEAD
pr	gh pr view <n> --json title,body,files,headRefOid,baseRefOid + gh pr diff <n>
file	直接 Read（単一ファイルのピンポイント確認として許容）
directory	explorer に委譲（直接 ls/find はしない）
branch	BASE=$(git merge-base <base> <TARGET>) して git diff $BASE...<TARGET>
topic	explorer に「<TARGET_ID> に関連するファイル群を洗い出し、責務・エントリポイント・データフローを要約」と指示

差分が大規模（2000 行超または 50 ファイル超）の場合、ステップ 5 で「読む順序のみ先に提示し詳細化は指定箇所のみ」縮退モードに入る旨をユーザーに予告する。

取得した diff / ファイル内容 / 構造情報を CONTENT として保持する。

---

ステップ 4: 構造把握（explorer 起動）

.cursor/skills/cursor-pir2/SKILL.md の「ステップ3: 探索フェーズ」で規定しているモデル別探索ポリシーに準拠する:

• coding-fast: 広く浅い調査（構造列挙、grep 相当）。最大3体並列
• coding: 深く読み解く調査（既存ロジックの意味理解、設計意図の把握）。最大1体
• coding: coding フォールバック（間接参照追跡・メタプログラミング・複雑な状態遷移）。最大1体、他層と並列起動しない

Task subagentの model パラメータで起動時に明示指定する。coding-fast + coding は同ターン並列起動可。coding は単独起動。coding → coding のフォールバック経路は「意図を推測で補う気配がある」「間接参照が途中で切れる」「DSL / メタプログラミングで表層 grep が効かない」の兆候で発動する。

MODE ごとの推奨構成:

シナリオ	推奨構成
小規模差分（数ファイル）	coding-fast 1体
大規模差分 / 複数レイヤー跨ぎ	coding-fast 2〜3体（レイヤー別並列）+ 必要なら coding 1体
単一ファイル読解	coding-fast 1体（呼び出し元・被呼び出し調査）+ 必要なら coding 1体
ディレクトリ読解	coding-fast 1〜2体（構造・外部依存）+ coding 1体（主要ロジック）
自然文領域	coding-fast 1体（候補ファイル洗い出し）→ coding 1体（意味把握）
間接参照 / DSL 壁	coding → coding フォールバック

各 explorer への指示には以下の観点を必須で含める:

1. 対象コードの責務（ひと言で何をするコードか）
2. 同一ドメイン・同一レイヤーの既存実装パターン
3. 再利用可能な既存ユーティリティ・ヘルパー関数
4. 呼び出し経路と呼び出され経路
5. 外部依存（ライブラリ・DB・API）
6. 非自明な分岐・条件・状態遷移の洗い出し
7. 読むときに注意すべき落とし穴

ライブラリ / フレームワーク API 仕様に関わる場合は公式 doc を WebFetch / WebSearch で裏取りし参照 URL をレポートに含めるよう指示する。

初回レポートで不明点が残っていれば、疑問が解消するまで回数制限なしで追加 explorer を起動する。推測で埋めない。

探索結果を REPORT として保持する。

---

ステップ 5: 複雑度判定とチーム化判断

--team フラグがある場合は無条件でチームモードへ昇格する。それ以外は REPORT と CONTENT を見て以下のいずれかに該当したら昇格する:

• 単一関数内で独立した分岐経路が3以上、または入れ子3段以上
• ステートマシン / イベント駆動 / 複数状態を持つクラスや enum による状態管理
• 1つの変更が3モジュール以上に波及、または複数の呼び出し起点がある
• DSL / メタプログラミング / 動的ディスパッチ / 高度な型パズルで単純 grep が効かない
• ユーザーが「全分岐を網羅して」「全経路を説明して」等を明示要求

判定タイミングは初回 explorer レポート受信直後と、ステップ 7 の詳細化フェーズで新対象領域を扱うたびの2つ。

昇格時はユーザーに「対象が複雑なためチームモードで調査します」と1行告知し、Task subagent workflows ツールで以下の構成を起動する:

役割	モデル	責務
調査リード	coding	全体像を把握し分岐点・経路を特定、各メンバーに調査範囲を配分
分岐調査員 × N	coding-fast または coding	割り当てられた経路を深掘り、共有コンテキストに事実を投入

統合役はスキル本体（メインエージェント）。調査リードは指示のみで、メンバー起動はスキル本体が行う。subagent同士の相互起動はしない。

チームのレポートを受け取り REPORT にマージする。

昇格しなかった場合は単体モードのまま進む。選択結果を WORK_MODE（single or team）として保持する。

---

ステップ 6: 冒頭ウォークスルー生成とドキュメント作成

冒頭ウォークスルーは 読み手が最初の1回で全体像を掴めるだけの密度 を目指す。サマリー版ではなく、詳細化に入る前でも独立して読み物として成立するレベルの情報量を出す。詳細化メニューは「さらに深掘りしたい人向け」の入口であって、冒頭自体が薄くていい理由ではない。

原則:

• 省略よりも構造化で読みやすくする。情報量を削って短くするのではなく、セクション分け・表・コードブロックで読みやすくする
• 「何が起きたか」だけでなく「なぜこうなっているか」も冒頭で触れる。設計判断・トレードオフ・非自明な制約を把握できるようにする
• コード引用を恐れない。関数シグネチャ・重要な定数・分岐の核心部分は引用する。1引用あたり 10〜30 行程度を目安とし、合計で冒頭全体の1/3を超えない範囲で
• 表を使って情報を圧縮する。影響範囲・API 変更・層ごとの差分など、縦横に並ぶ情報は箇条書きより表のほうが速く読める
• 非自明な判断・落とし穴を必ず書く。「この context だけ context.Background() なのはなぜか」「この定数がこの値の理由」など、後から罠にならないポイントを予め潰す
• 各セクションの見出しに数字や具体を入れる（「読む順序（推奨5ステップ）」など）。何が書いてあるか目次だけで予測できるように

生成するセクション（必須。target 規模に関わらず出す）:

# <target 名> ウォークスルー

_作成: YYYY-MM-DD | target: <target_id> | モード: <mode> | 複雑度: <work_mode>_
_規模: N ファイル、+X / -Y 行 / コミット M 本_（pr/branch/local-diff のみ。file/directory は対象サイズ）

## 変更の全体像

[2〜3段落で書く。1段落目は「何の機能が / 何のために / 何をするのか」を広めに、2段落目以降で「設計上の主要判断」「副次的変更」「なぜこの形か」を押さえる。合計 400〜800 字程度を目安にする。単発の3〜4文では足りない]

## コミット構成（読み解きヒント） ※ pr/branch のみ

[主要コミットを一覧で並べ、★印で設計上の転換点を示す。差分を筋道立てて読むためのロードマップ]

## 読む順序（推奨 N ステップ）

[3〜6ステップ。各ステップで以下を書く]
### N. <ファイル/関数> — <1行見出し>

<なぜこの順で読むべきか 1〜2文>

```<lang>
<重要シグネチャ / 定数 / 分岐の核心 10〜20 行程度>

<引用コードの読み方ガイド 1〜3文>

データフロー図（任意）

[該当すれば Mermaid 図を1つ。sequenceDiagram / flowchart / stateDiagram から適切なものを選ぶ]

影響範囲サマリ

[層（controller/usecase/gateway/domain/...）× 変更内容 の表。PR 全体の差分を1表で俯瞰できるようにする]

設計上の注意点・落とし穴

[非自明な判断・契約・制約を箇条書きで5〜10項目。「なぜこの context が Background か」「この定数がこの値の理由」「既存パターンから逸脱している点」「外部互換を壊す点」など]

詳細化メニュー（番号か自然文で指定してください）

[8〜12 件程度。各項目は「テーマ名 — 深掘ると何がわかるか 1〜2文」の形式。冒頭で触れきれなかった分岐・経路・外部依存から抽出]

• [A] <テーマ1> — <深掘り内容> ...
• [Z] その他、気になる箇所を自然文で

### 分量の目安

- 小規模差分（数ファイル, 数百行以下）: 全体で 300〜500 行の md
- 中規模差分（10〜30 ファイル, 1000〜3000 行）: 全体で 500〜800 行の md
- 大規模差分（30 ファイル以上、3000 行以上）: 全体で 800〜1500 行の md

この目安を下回る場合、情報が足りない可能性が高い。探索レポートに立ち戻って「冒頭で触れるべきだが書けていない事実」がないか点検する。**ユーザーから「もっと薄く」と明示要求されたときだけ削る**。

### Mermaid 図

以下のいずれかに該当するときは積極的に添える（1つに限定しない。必要なら2つまで）:

- データフローが3ステップ以上で文章より図のほうが明らかに速い
- 呼び出し関係が複数モジュール間で交錯している
- ステートマシンがある
- ライフサイクル（開始→中間→終了 など）を時系列で見せたい

### 保存処理

`--no-save` フラグがある場合は保存せずチャット内のみに表示し、ステップ 7 へ。

それ以外はファイル命名規則に従って保存する:

| MODE | ファイル名 |
|-----|-----------|
| pr | `pr-<番号>.md` |
| branch | `branch-<名ケバブ>.md` |
| file | `file-<パスのケバブ>.md` |
| directory | `dir-<パスのケバブ>.md` |
| topic | `topic-<要約ケバブ>.md` |
| local-diff | `local-diff.md` |

ケバブ変換後に衝突が発生する場合は末尾にパスハッシュ4桁（sha256 の先頭4桁）を付与する。

ディレクトリが無ければ `mkdir -p docs/walkthrough` で作成する。

フロントマター形式:

```yaml
---
target_type: pr | branch | file | directory | topic | local-diff
target_id: <識別子そのもの>
cache_key:
  base_sha: <比較元 SHA>          # pr/branch のみ
  head_sha: <比較先 SHA>          # pr/branch のみ
  files:                          # file/directory/local-diff 対象
    - path: <相対パス>
      mtime: <ISO8601>
      hash: <sha256 先頭8桁>
created_at: <ISO8601>
updated_at: <ISO8601>
mode: single | team
---

ファイルのひな形（フロントマターに続けて）:

# <target 名> ウォークスルー

_作成: <YYYY-MM-DD> | target: <TARGET_ID> | モード: <MODE> | 複雑度: <WORK_MODE>_

## 変更の全体像
<生成内容>

## 読む順序
<生成内容>

## 詳細化メニュー
<生成内容>

## Mermaid 図（任意）
<生成した場合のみ>

---

## 詳細化ログ

ユーザーに保存完了を提示する:

冒頭ウォークスルーを保存しました: docs/walkthrough/<file>.md

詳細化したい箇所があればメニューの番号（[A], [B] など）か自然文で指定してください。
終わるときは「終わり」「OK」「完了」など何かしらの終了合図をお願いします。

---

ステップ 7: 詳細化ループ

ユーザーの応答を以下のパターンで解釈する:

応答パターン	分類	処理
A / [A] など英字ラベル単体	メニュー選択	該当テーマを詳細化
A, C など複数指定	複数選択	順に詳細化ループ
自然文指定（「authの分岐詳しく」）	自由入力	対象推定 → 必要なら追加 explorer 起動 → 詳細化
疑問文（「この関数は何？」）	Q&A	簡潔に回答（保存しない）
「終わり」「OK」「完了」等	終了	ステップ 8 へ
意図不明	確認	「詳細化か質問か」を1質問で確認

詳細化として保存するのは構造化された説明（テーマ名 + 対象コード引用 + 解説数段落）になるもの。短文 Q&A は保存しない。ユーザーが「これも記録しといて」と明示した場合は Q&A でも詳細化扱いで保存する。

追加 explorer 起動判断:

• 初回 REPORT で回答可能 → そのまま詳細化を書く
• 情報不足 → 追加 explorer を起動（モデル選択はステップ 4 のポリシーに従う）
• coding でも意図が掴めない → coding にフォールバック
• 新対象領域に複雑度判定条件がマッチ → ステップ 5 のチーム化判定を再適用
• --team 指定時は詳細化ループでも常にチーム構成を維持する。--team 未指定時は新対象領域ごとに独立に複雑度条件で再判定する

--no-save フラグがある場合は追記処理をスキップし、詳細化はチャット内のみで提示する（ステップ6のひな形保存も既にスキップされているため、対応するファイルが存在しない）。

--no-save がない場合、詳細化パートは docs/walkthrough/<file>.md の ## 詳細化ログ セクションに追記する:

### <YYYY-MM-DD HH:MM> — <テーマ名>
_要求: "<ユーザー入力そのまま>"_

#### 対象コード
```<言語>
<核心コード引用（最大20〜30行、必要なら複数箇所）>

解説

<何をしているか / なぜこうなっているか / 読むときの注意点>

非自明な判断（あれば）

<代替案や落とし穴>

追記時にフロントマターの `updated_at` を現在時刻に更新する。

範囲が広い詳細化要求（「全部詳しく」等）を受けた場合、1ターン最大3テーマまでを原則とし「続きを出しますか？」と確認する。

応答を受け取るたびにこのループを継続する。

---

## ステップ 8: 終了

ユーザーから終了合図を受け取ったら以下を実行する:

1. フロントマターの `updated_at` を現在時刻に更新
2. `## 詳細化ログ` 末尾に `---` 区切りを入れて将来の追記位置を明示
3. 最終サマリーを提示

ウォークスルー完了

保存先: docs/walkthrough/.md

• モード: <WORK_MODE>
• 初回作成: YYYY-MM-DD
• 最終更新: YYYY-MM-DD HH:MM
• 詳細化テーマ数: N 件

後日同じ対象で /cursor-walkthrough <target> を呼ぶと、このキャッシュを元に [1] そのまま表示 / [2] 変化箇所のみ再調査 / [3] 完全再調査 を選べます。

`--no-save` 指定時は保存処理をスキップし簡略メッセージのみ表示する。

スキル終了後もユーザーは通常チャットでメインエージェント に質問し続けられる。メインエージェント は最後に作成/更新したウォークスルーファイルをコンテキストに保持しているためそのまま Q&A に応答できる。再度スキル起動したい場合はユーザーが `/cursor-walkthrough` を呼び直す。

---

## 既存スキルとの棲み分け

- `/cursor-pir2` のサマリー版ウォークスルー: 自分が走らせた実装直後の1発ウォークスルー。スキル本体（メインエージェント）が `/cursor-pir2` ステップ9で生成する
- `/cursor-walkthrough`: 独立したコードリーディング支援。対話的な深掘り、キャッシュ再利用、既存コード対応、PR レビュー補助に使う。`/cursor-pir2` 完了後に「サマリーだけでは足りない」と感じたら追いがけで起動する
- `/cursor-reviewer` `/cursor-review-pr`: 問題検出特化で PASS/FAIL 判定と問題一覧を出す。説明支援はしない

## ディレクトリ運用

`docs/walkthrough/` はキャッシュ領域として運用する。プロジェクト特性により共有資産として commit したい場合もあるため、デフォルトは `.gitignore` 追加推奨とするが強制はしない。