Catchup

catchup

コードベースに追いつくための対話型ガイド。

「diffを並べる」のではなく「読者の理解を一段ずつ進める」ことを目的とする。各ステップで現状を要約し、次に見るべき場所を提示し、ユーザーの興味に従って深掘りしていく。

4つのモード

モード	想定シーン	起点
tour	新規参画。コード初見。	エントリポイント / README / 主要ディレクトリ
recent	エージェント実装を追う。	git log + sessions ログ
deepdive	特定領域を理解したい。	指定ファイル/シンボル/ディレクトリ
review	PR/ブランチをレビューする。	base...HEAD diff + コミット意図

詳細な進め方は references/modes.md を参照。

起動時の流れ

1. モードと範囲の確認 (必須)

AskUserQuestion でモードを選ばせる。発話から自明なら省略可:

• 「新規参画した」「全体像教えて」 → tour
• 「最近何が変わった」「先週のAI実装」 → recent
• 「認証周りを理解したい」「UserServiceを追いたい」 → deepdive
• 「このPR/ブランチをレビュー」 → review

範囲(期間・ディレクトリ・ブランチ)が曖昧なら追加で1問だけ聞く。

2. 環境チェック

git rev-parse --show-toplevel    # gitリポジトリか
git log -1 --format=%H 2>/dev/null
which sessions                   # session-index CLI の有無
gh auth status 2>/dev/null       # gh の有無 (review モード時)

失敗時の挙動 (必ず1ターン目で明示する)

検出事項	振る舞い
git rev-parse 失敗 (git リポでない)	1ターン目で「git リポではない」と明示。recent/review は実行不可と宣言。tour/deepdive は fd/lsd/Read で代替し、履歴・意図補完が出来ないことを注記
対象に走査可能なファイルが0件 (空ディレクトリ等)	1ターン目で「走査対象なし」と明示。架空の構造を捏造せず、git init / 別ディレクトリ指定 / 終了 の3択を提案して短絡終了
sessions CLI 無し	git のみで進行。pip install claude-session-index を1度だけ案内
gh 無し (review モード時)	PR文脈は取得不可と宣言。git diff <base>...HEAD のみで継続

提案した3択 (例: git init / 別ディレクトリ / 終了) にユーザーが該当しない応答を返した場合は、改めて事実 (走査対象なし等) を提示して再3択。素材不在のまま形骸的に走査を続けない (捏造誘発の主要因)。

ループ脱出: 同一3択を 2 回提示してもユーザーが該当しなければ、catchup 側から強制終了する (「押し付けない原則」と「捏造防止」のトレードオフは捏造防止を優先する)。

全成功時の圧縮: 上記の検出事項がすべて問題なし (git OK / 対象に走査可能ファイルあり / sessions あり / gh あり) の場合、環境チェック結果は 1 行に圧縮する (例: 環境: git/sessions/gh OK)。問題ありの時のみ詳細を展開する。

3. モード別の走査

各モードの具体的なコマンド・観点は references/modes.md を参照。共通原則:

• 一度に全部読まない。トップダウンで段階的に絞り込む。
• 走査結果は短く要約してから次の選択肢を提示する。
• ファイル参照は必ず path:line 形式で出す。

4. 対話で逐次ガイド

各ステップの末尾に「次にどこを見るか」の選択肢を 2〜4 個提示する。AskUserQuestion を使うか、明示的な番号付きリストを提示する。

進行中はユーザーの問い直し・寄り道に柔軟に応じる(レポート生成タスクではない)。

走査ソースの使い分け

ソース	何が分かるか	コマンド例
git log/diff	何が・いつ・どう変わったか	git log --since=..., git diff <base>...HEAD
git blame	各行の最終変更者・コミット	git blame -L <s>,<e> <file>
git show	特定コミットの全変更	git show <sha>
gh pr list/view	PR単位の文脈・レビューコメント	gh pr view <n> --json title,body,comments
sessions	実装時の対話履歴・意図	sessions find --project <name>, sessions context <id>
Read/Grep	コードそのもの	(built-in)

recent / review モードでは「git で変更を特定 → 該当時期の sessions で意図を補完」の二段構えが強い。

sessions CLI の活用

session-index (sessions CLI) が利用可能なとき:

# プロジェクト名でセッション特定 (worktreeも含む)
sessions find --project <repo-name>

# 期間で絞る
sessions find --project <name> --week
sessions find --project <name> --month

# 個別セッションの全体像
sessions context <session_id>

# キーワードで該当箇所を抽出
sessions context <session_id> "<keyword>"

# 横断要約
sessions synthesize "<topic>"

未インストール時は無理に勧めない(pip install claude-session-index を1回だけ案内)。git のみでも価値は出せる。

深掘りの起点となるシグナル

コードベース初見時、以下の順で起点を立てる:

1. エントリポイント: package.json#scripts, Cargo.toml#[bin], pyproject.toml, Makefile, mise.toml, Program.cs, main.*
2. README/CONTRIBUTING/CLAUDE.md/AGENTS.md: 設計判断・ローカル規約
3. 依存ファイル: package.json, Cargo.toml, requirements.txt, *.csproj
4. ディレクトリ最上位: src/, app/, internal/, Assets/, lib/ の命名
5. 設定の入口: *.config.*, .env.example, appsettings.json
6. テスト命名: tests/, *_test.go, *.spec.ts ─ 仕様の縮約
7. CI/CD: .github/workflows/, .gitlab-ci.yml ─ ビルド/デプロイ前提

出力の原則

• 各ターン400字以内を目安(上限)。素材が乏しいときは短文可、無理に下限を埋めない(捏造防止)。
• テンプレートを1ターンに全節詰めない。 1ターン目、およびモード切替直後の初回ターンも、要約節 + 選択肢のみ提示し、詳細節はユーザーが選んだら次ターンで出す(段階開示)。modes.md の出力テンプレートは「最終的に集まる構造」であって「1ターンの目標」ではない。
• ファイル参照は path:line 形式 (src/auth/service.ts:42)。ただし行番号が特定できない場面 (ディレクトリ全体走査、差分一覧、ファイル群サマリ等) では path/ (ディレクトリ) や path (line不明) を許容する。1セッションあたり最低1つは path:line 形式の参照を出すこと。
• 図解が有効なときのみASCII図(モジュール関係・呼び出しフロー)。常用しない。
• 推測には文末に半角スペース + ? を付けて読者判断を残す (例: これは設定ファイル ?)。文中の ? は使わない。
• ユーザーが寄り道したらそちらを優先する。元のフローに戻すかは聞いてから。

終了時のオプション

最後に以下を提案する(押し付けない):

• このセッションの要点を tasks/catchup-YYYY-MM-DD.md に保存しますか?
• /pr-brief でレビュー資料化しますか?(review モードの場合)
• /sync-knowledge で得た学びをナレッジに反映しますか?

類似スキルとの使い分け

スキル	役割	catchup との違い
pr-brief	レビュー前のブリーフィング資料(.md)を生成	catchup は対話、pr-brief は文書
diff-review	git diff を整形表示	catchup は意味づけ・読み方をガイド
session-recap	過去セッションをワークフロー文書化	catchup はコード理解、session-recap は作業ログ
claude-review 等	自動コードレビュー	catchup は理解支援、reviewは指摘

「読み方を案内する」のが catchup 固有の役割。