why

why

リポジトリにすでに残されている記録をたどり、既存コードの背景にある判断を再構成します。コード行の履歴、コミットメッセージ、PR の議論、関連する issue を掘り起こします。出力するのは、証拠に基づくストーリーであり、リンクの羅列ではありません。推測は決してしません。

唯一の絶対ルール：根拠をでっち上げないこと。 調査していないコードについて、もっともらしい説明をするのは、「記録には書かれていません」と伝えるよりも悪いことです。誤った理解を植え付けてしまいます。意図について述べる場合は、必ず出典（コメント、コミット、PR、issue）を示すか、推論であることを明確にしてください。

調査 — 層を追い、答えが見つかったら止める

質問に必要な深さまで調べます。ほとんどの質問には git log -L で答えられます。重要な謎を解く場合にのみ、徹底的に調べます。

レイヤー 0 — コードそのもの

近くにあるコメント、docstring、プロジェクトのドキュメントに、すでに答えが書かれていないか確認します。書かれていれば、その箇所を引用して終了します。それがコードベース本来のあるべき姿です。

レイヤー 1 — コミット履歴

対象のコードを形作ったコミットを探します。

git log -L <start>,<end>:<file>          # full evolution of a line range
git log -L :<funcname>:<file>            # or of a function
git blame -w -C -M <file> -L <start>,<end>   # last-touch view, ignoring whitespace/moves

• blame が示すのは最後に変更したコミットであり、起点ではありません。git log -L の出力をさかのぼり、判断が導入されたコミットを探します。
• 表面的なコミット（整形、一括リネーム）は飛ばします。リポジトリに .git-blame-ignore-revs があれば、--ignore-revs-file で指定して適用します。
• ファイル名が変更されている場合は、ファイルに対する通常の git log に --follow を追加します。

関連するコミットメッセージを全文で読みます（git show -s <sha>）。良いメッセージであれば、ここで調査を終えられることもあります。

レイヤー 2 — プルリクエスト

関連する各コミットを取り込んだ PR を探し、その前後にある人間同士の議論を読みます。

gh api repos/{owner}/{repo}/commits/<sha>/pulls   # commit → PRs
gh pr view <number> --comments                    # body + discussion

PR の本文には意図が説明されています。レビューのスレッドには、却下された代替案とその理由が正確に記録されていることがよくあります。対象のファイルや行について、スレッドを検索します。リモートが GitHub でない場合、または gh が利用できない場合は、PR レイヤーを調査できないことを伝え、git だけで分かる範囲を調べ続けます。

レイヤー 3 — issue

PR の本文やコミットメッセージにある参照（fixes #N、closes #N、チケット ID）をたどり、元の問題報告を確認します。「実際に何が壊れていたのか」はここに書かれています。「なぜこの防御的なコードがあるのか」という問いへの、本当の答えが見つかることもよくあります。

レイヤー 4 — 人

記録が尽きたら、誰に聞けば分かるかを特定します。導入コミットの作成者や PR のレビュアーです。今も活動しているか確認します（git log --author で最近の履歴を調べます）。調査で分かったことをもとに、相手に尋ねるための質問を具体的に作ります（「PR #123 でリトライが追加されましたが、3 回という上限は後から説明なしに導入されています。実測に基づく値だったのでしょうか、それとも任意の値だったのでしょうか？」）。

報告

• 判断の順序に沿って、問題 → 選択 → 置き換えたもの、または却下した案 → その後の変遷、というストーリーにします。主張のそばに出典（sha、PR/issue 番号）を示します。
• 記録と推論を明確に分けます。「PR には X と書かれています」と「差分を見ると Y のように思えますが、記録には書かれていません」を区別します。
• 記録が途絶えていることも調査結果です。失敗ではありません。記録がどこで途絶えたかを正確に報告します（「'' でメッセージ 'fix' とともに導入されましたが、PR での議論はありません」）。

調査後 — 答えを、最も長く残る場所に記録する

• 記録は途絶えているが、理由は判明した（推論によって、または誰かに尋ねて判明した）場合：要となる箇所に簡潔なコメントを追加する案を提案します。その背景情報はすでに一度失われています。コメントを残せば、二度失われずに済みます。提案にとどめ、黙って適用しないでください。
• 見つかったが、埋もれていた（レビューのスレッドを三層たどった先にあった）場合：十分に重要なら、同様にコメントへ移す案を提案します。それ以外は、ユーザーがこのパックのセッションループを使っている場合、ドシエに一行の参照（「X の背景情報：PR #123」）を残す価値があるかもしれません。セッションループを使っていないユーザーには、これは一切提案しません。

ガードレール

• デフォルトでは読み取り専用です。書き込みが行われるのはユーザーが承認した昇格提案のみで、通常の成果物として扱います。リポジトリに反映されるものには、このスキルパックや個人用ストアについて決して記載しないでください。
• 質問に応じて調査の深さを調整してください。レイヤー1で答えが見つかったなら、4つのレイヤーまで調べる必要はありません。
• 推測を記録された事実として示してはいけません。「わかりません。リポジトリにも記載がありません」は、正直で妥当な回答です。