walkthrough

ウォークスルー

ローカルで実行中の Command Center を使ってコードのウォークスルーを生成し、開きます。

呼び出すタイミング

ユーザーが現在のブランチ、プルリクエスト、コミット範囲のウォークスルー、または「差分の説明」を求めた場合に使います。例：

• 「このブランチのウォークスルーを作成してください。」
• 「main 以降の変更を順に説明してください。」
• 「HEAD~5..HEAD のウォークスルーを生成してください。」

このエージェントが Command Center 内から実行されている場合は、別のウォークスルーツールまたはスキルが利用できます。このスキルと混同しないでください。このスキルは差分全体のウォークスルーを生成するためのものです。もう一方は、差分、バグのデータフロー、サインインのフロー、コードベース内の特定のメソッドのすべての使用箇所など、任意のコード部分を対象にウォークスルーを生成するためのものです。

呼び出し方法

run.mjs を実行します。これはこの SKILL.md と同じディレクトリにあります。ランナーがすべての処理（インストールの検出、バックエンドの起動、認証／モデル／ワークスペースの確認、ウォークスルーの生成、ブラウザーでの表示）を行います。

node <SKILL_DIR>/run.mjs [from..to] [--files=PATTERN[,PATTERN...]]

<SKILL_DIR> は、skills CLI がこのスキルをインストールした場所です。一般的な場所は次のとおりです。

環境	パス
Claude Code、プロジェクトローカル	./.claude/skills/walkthrough
Claude Code、グローバル（-g）	~/.claude/skills/walkthrough
その他のエージェント	./.agents/skills/walkthrough

この SKILL.md をディスクから読み込んだ場合、ランナーは同じ階層にあります。そのディレクトリに置き換えてください。

どちらの引数も省略できます。デフォルトでは、解決された範囲の差分全体がウォークスルーの対象になります。

参照範囲 — [from..to]：

• 省略時 → merge-base(HEAD, <base>)..HEAD がデフォルトです。<base> は origin/HEAD のシンボリック参照で、見つからない場合は origin/main / origin/master / main / master の順に使用します。
• git が解釈できる値を指定できます。SHA、ブランチ、HEAD~3..HEAD などです。
• 特別なトークン：WORKING_TREE（未コミットの変更）および STAGED（インデックス）。例：HEAD..WORKING_TREE。

便利なフラグ（上記の参照範囲トークンと同等）：

• --working-tree → ベースに対する merge-base から現在のワーキングツリーまでの差分（未コミットの編集を含む）。
• --staged → HEAD..STAGED（git add した内容のみ）。
• --port=<port> → 特定の Command Center バックエンドポートに接続します。複数の CC インスタンスが稼働している場合（開発環境など）や、ランナーが適切なインスタンスを自動検出できない場合に便利です。

ファイルフィルター — --files=PATTERN[,PATTERN...]：

• カンマ区切りの、リポジトリ相対の glob パターンです。* はスラッシュ以外の文字に一致し、** はディレクトリをまたいで一致します。
• 除外するには、パターンの先頭に ! を付けます。除外のみを指定した場合、暗黙の対象パターンは **（「すべて。ただし除外対象を除く」）です。
• ランナーはローカルで git diff --name-only from..to に対してパターンを展開し、具体的なファイル一覧をバックエンドに送信します。

例 — ユーザーの意図に合うものを選びます。

ユーザーの意図	コマンド
ベースとの差分でブランチ全体（デフォルト）	（引数なし）
昨日のコミット	$(git log --since="2 days ago" --until="1 day ago" --format=%H | tail -1)..HEAD
直近 3 件のコミット	HEAD~3..HEAD
ブランチ全体。ただしテストは除外	--files=!**/*.test.*,!**/*.spec.*,!**/__tests__/**
src/ 内の TS ファイルのみ	--files=src/**/*.ts
昨日のコミット。テストは除外	<sha>..HEAD --files=!**/*.test.*
未コミットの編集	--working-tree
未コミットの編集。src/ のみ	--working-tree --files=src/**/*.ts
ステージ済みの内容のみ	--staged

出力の解釈

ランナーは、標準出力に1行ごとに1つのJSONオブジェクトを出力します。各行にはkindフィールドがあります。

• kind: "status" — 進捗状況の更新です。ユーザーに簡潔な1行のメッセージを表示します。
• kind: "result" — 正常終了です。ランナーがウォークスルーを開いています。開いたことをユーザーに伝え、urlのURLを含めます。
• kind: "error" — エラー終了です。codeフィールドとmessageフィールドを使って、何が問題だったかをユーザーに伝えます。コードは固定の列挙値です（not-installed、not-running、not-logged-in、no-model、quota、no-workspace、backend-too-old、generation-failedなど）。messageはすでにユーザーの言語で記述されています。
• kind: "action-required" — 再実行する前にユーザーが何かを行う必要があります（例：アプリのインストール、サインイン、モデルの設定）。messageと、存在する場合はurlを表示します。

ランナーのmessageは、常にそのまま表示してください。言い換えてはいけません。ランナーはユーザー向けの文字列を英語で出力します。バックエンド由来の文字列は、すでにローカライズされています。

0以外の終了コード

ランナーは成功時に0を返し、失敗時には固定された少数の整数を返します（失敗の種類ごとに1つのコードがあり、プロジェクトのREADMEに記載されています）。終了コードを解析してはいけません。上記の構造化されたkind／codeフィールドに基づいて分岐してください。