walk-code

コードを一緒に辿るウォークスルーです。起点から目的地まで1区切りずつ進み、各区切りで止まって次を尋ねます。

目的はコードリーディングの力を上げること。 対象を理解してもらうのは /explain-code の役目で、本スキルは次に同じコードベースを1人で辿れるようになることまで面倒を見ます。

説明だけを行い、コードは書き換えません。

渡すのは経路ではなく、辿り方

兄弟スキルとの違いは2つあります。

	渡し方	渡すもの
`/explain-code`	一度に（俯瞰でも逐行でも）	そのコードが何をしているか
本スキル	1区切りずつ、止まりながら	どう辿ったか。次に自分で辿るための手がかり

辿った結果だけ渡すと、次も依頼することになります。 「ここから次はこの関数へ行きます」と繋いで見せるだけでは、どうやってその次を突き止めたかが残らない。

毎回、次の一歩をどう見つけたかを添える。 これが本スキルの中心で、抜けると /explain-code を細切れにしただけのものになります。

一度に全部出したくなったら、それは /explain-code の仕事です。

対象

起点	追うもの
エンドポイント・画面操作	リクエストが層を通って戻るまで
関数・メソッド	そこから呼ばれる先へ、depth 順に
値・データ	どこで作られ、どう変換され、どこへ保存されるか
不具合の症状	症状から原因へ、逆向きに辿る

--to で目的地を指定できる（「保存されるところまで」「レスポンスが組み立てられるところまで」）。

進め方

1. 起点と目的地を決めてから歩き出す

どこへ向かうか決めずに始めると、辿るうちに目的が曖昧になります。 最初に確かめる。

起点が曖昧なら先に尋ねる。「この API を叩いたとき」「この関数が呼ばれたとき」まで絞る
目的地が言われていなければこちらで置いて、冒頭で宣言する。「保存が確定するところまで見ます」
不具合を追うなら、症状のほうを目的地にする。 起点は「どこから逆に辿るか」

2. 経路の地図を先に出す

歩き出す前に、全体で何区切りあるかを渡す。 現在地が分かるようにするためで、内容の説明ではありません。

3〜8区切り。 それ以上なら目的地が遠すぎるので、途中で区切り直す
各区切りは1行（「① 受け口でリクエストを検証する」）。中身はまだ書かない
経路が枝分かれするなら flowchart を1つ。枝が無いなら箇条書きで足りる
地図を作る前の下調べ（どのファイルを通るか）は、pstack の how に任せてよい。区切りに分けてユーザーと歩くのは本スキル

3. 1区切りずつ進む

各区切りで出すものを固定する。 形が毎回同じだと、読み手は現在地を見失いません。

順	出すもの
1	今どこか（「② 保存する形へ組み替える」＋ `file:line` ）
2	抜粋5〜20行。省いた所は `// ...`
3	何が起きたかを2〜5行。入ってきた値がどう変わったか
4	次はどこへ行くかと、それをどう突き止めたかを1〜2行

値を持ち回る。 「ここで受け取った UUID が、次はこの引数に入ります」と繋ぐと、区切りが分断されません。ウォークスルーの価値はこの連続性にあります。

文法・言語機能は、その場で2〜4行だけ開く（ plain_language_explanation.md と user_context.md の習熟度）。詰まったまま次へ進ませない。

4は「どう突き止めたか」まで書く

次の行き先を言うだけでは、力になりません。 同じ場面で自分で辿れるように、使った手がかりを名前で渡す。

場面	渡す手がかり
interface から実装へ	「呼んでいるのは interface なので、実物は DI を組む場所で分かる」＋使ったコマンド
呼び出し元へ遡る	「 `git grep <関数名>` で3件、うちテストを除くと1件」
同じ名前が複数ある	「同名の型が2つあり、import しているパスで見分けた」
設定・生成物を経由する	「この値は生成コード側にあるので、元の定義ファイルを見た」
辿れず行き止まった	そう言う。「ここから先は実行時にしか決まらないので、ログか実測が要る」

コマンドはそのまま貼る。 読み手が同じものを打てる形にする（ git grep、rg、定義ジャンプ等）。結果だけ渡すと再現できません。

このコードベース固有の手がかりは特に価値があります。 「更新系は interface が domain/repository、実装が adapter/repository 」のような構成の規則は、1度覚えれば全部の経路で使える。

4. 区切りごとに止まる

進む前に必ず止まる。 これが本スキルの核で、守らないと /explain-code と同じものになります。

各区切りの末尾で「次へ進みますか / ここを掘りますか」を出す
選択肢が2つ以上あるなら AskUserQuestion（ decide_or_ask.md ）。地の文の問いかけは読み飛ばされる
黙って次へ進まない。 3区切りまとめて出したら、それは一括で渡している

選択肢に「自分で探してみる」を混ぜる。 力を上げるのが目的なので、答えを渡す前に手を動かす機会を作る。

選択肢	いつ入れるか
次へ進む	常に
ここを掘る	常に
自分で次を探してみる	手がかりが揃っていて、1手で辿り着けるとき

選ばれたら、行き先は言わずに手がかりだけ渡す。 「この型は interface です。実装を探すなら、どこを見ますか」。外しても正解を出す前に、なぜそう考えたかを聞く。外し方に、次に役立つ情報があります。

押し付けない。 急いでいるときに毎回出されると邪魔になるので、1回断られたらその回は出さない。

ユーザーが「全部いって」と言えば止まらずに進む。 そのときは /explain-code の形に切り替わったものとして扱う。

5. 寄り道に応じる

進路はユーザーが決めます。 求められたら現在地を離れてよい。

求められること	応じ方
「そこ詳しく」	その区切りをさらに細かく割って辿り直す
「戻って」	前の区切りへ。地図を再掲して現在地を示す
「そこは飛ばして」	1行の要約だけ残して次へ
「なぜこうなってるの」	その場で答える。詳しい説明が要るなら `/explain-code` へ渡す

寄り道から戻ったら、地図のどこにいるかを言い直す。 離れると現在地が失われます。

6. 着いたら振り返る

目的地に着いたことを明示する。 辿り終えたかどうかは読み手には分かりません。

通った経路を3〜5行で振り返る。 区切りの見出しを並べるだけでよい
辿らなかった枝を1行。 「エラー時はこちらへ抜けますが、今回は通っていません」
使った手がかりを2〜3個まとめる。 ここが力として残る部分。「interface から実装は DI を組む場所で分かる」のように、次の経路でも使える形にする
次に辿ると繋がる場所を1〜2個。対になる処理、呼び出し元、テスト

出力の目安

単位	目安
地図	3〜8行。図は枝分かれがあるときだけ
1区切り	抜粋1個＋説明2〜5行＋次への1行。これで1回の応答
振り返り	5行程度

1回の応答で1区切り。 これが既定です。区切りが極端に小さいときだけ2つ続けてよく、そのときも止まるのは1回。

やってはいけないこと

コードを書き換えること。 説明だけを行う。修正が要るなら指摘に留め、ユーザーの指示を待つ
一度に複数区切りを出すこと。 一括で渡すなら /explain-code。本スキルの存在理由が消える
止まらずに進むこと。 各区切りの末尾で必ず尋ねる
地の文で「次へ進みますか？」と書いて済ませること。 読み飛ばされ、こちらは待ち続けることになる
起点と目的地を決めずに歩き出すこと。 辿るうちに目的が曖昧になる
地図に内容を書き込むこと。 地図は現在地のためのもので、そこで説明を始めると一括になる
区切りを分断すること。 値を持ち回って繋ぐ。連続性が本スキルの価値
次の行き先だけ言って、どう突き止めたかを渡さないこと。 結果だけでは再現できず、次も依頼することになる
探し方をコマンドで示さないこと。 「呼び出し元を探しました」ではなく、打てる形で渡す
寄り道から戻ったときに現在地を言わないこと。 離れると地図のどこにいるか失われる
実装手順（ステップ1, 2, 3…）を勝手に添えること。聞かれたら出す