grok-repo

grok-repo

まず目的、構造、仕組みを読み、次に「なぜ」を知るために履歴を確認します。証拠を確認してから、設計の良し悪しを判断します。 質問に応じてモードを1つ選びます。すべての主張にファイルパスまたはコミットを引用します。

• 範囲を絞った質問（「Xはどう動く？」「Yはどこから来る？」）→ データフロートレース。
• 変更に関する質問（「なぜXが追加された？」「この機能はどう進化した？」）→ 変更の経緯調査。
• リポジトリ全体に関する質問（「このコードベースを説明して」「全体を案内して」）→ 全体ブリーフィング。

データフロートレース（範囲を絞ったモード）

リクエスト、メッセージ、設定値、ファイルなど、1つのデータを入口から影響が及ぶところまで追跡します。このトレースが回答になります。

• ホップの連鎖を1行で示し、各ホップに引用を付けます。 POST /jobs (api/handler.go:41) → validate → Job{} (job.go:12) → enqueue (redis) → worker.Run (worker.go:88) → status written (store.go:130)
• 各ホップで、そのデータを保持するもの（型／構造体／スキーマ）、変換内容、形状の変化や名前の変更（JSON→構造体、フィールド名の変更、列挙値の対応付け）をすべて示します。
• 通過する境界に印を付けます。シリアライズ、キュー、プロセス／ネットワーク境界、ゴルーチン／スレッド間の受け渡しなどです。
• 省略した副次的なフロー、追加で調査する価値のあるエラー／エッジケースの経路、意外な点を最後にまとめます。
• あるホップの「なぜ」が不自然な場合は、履歴を確認します。git log -S '<symbol>' を実行するか、該当行の blame を調べます。

変更の経緯調査（履歴モード）

リポジトリ全体の年代記ではなく、1つの機能または判断を再構成します。

1. 現在の概念を起点にする — 現在のシンボル、パス、設定名、テスト、ユーザー向けの用語を見つけます。どのように現在の形になったかを説明する前に、今の動作を述べます。
2. 導入時点を探す — 出現／消失には git log -S '<literal>'、変更行の一致には git log -G '<regex>' を使い、名前変更されたファイルには --follow を使います。以前の名前も試します。
3. コミットを読む。件名だけで済ませない — 導入時のコミットとその親コミットを git show で確認します。本文、テスト、削除されたコード、近接する修正も証拠になります。差分だけでは推測にすぎません。
4. レビューのやり取りをたどる — 変更の根拠は、通常、コミットメッセージよりもPR内に詳しく残っています。そのコミットを取り込んだマージコミットから番号を特定し、説明だけでなく議論を読みます。

   git log --merges --ancestry-path --oneline <sha>..HEAD | tail -1
   gh pr view <n> --comments        # gh issue view <n> --comments for a linked issue
   

5. 変遷を追う — 後続の修正、リファクタリング、リバート、現存する行の blame を調べます。

変更前 → 圧力／証拠 → 導入 → 修正／撤回 → 現在の形の順に説明します。 各段階に SHA とパスを引用します。裏付けのある根拠、却下された代替案、未解決の文脈、履歴から分かる範囲の限界を最後にまとめます。コミットの順序を因果関係と見なしたり、動機を捏造したりしてはいけません。

読み進める順序（全体ブリーフィング）

上から順に進めます。大規模なリポジトリでは、代表的なコンポーネントを抽出して読み、何を調べたかを明記します。

1. 全体像をつかむ — README、docs/、トップレベルの構成、マニフェスト（go.mod/package.json/Cargo.toml）、Makefile／CI設定を確認します。エントリーポイント（main、CLIコマンド、サーバーの起動処理、エクスポートされたAPI）を探します。ビルドやテストを手軽に実行できるなら、実行します。テストスイートが通り、実際の呼び出しを1つ確認できれば、以降の分析の足掛かりになります。
2. 実際のフローを1つ、端から端まで追跡する（リクエスト、コマンド、ビルドなど）。一般化する前に追跡します。トレースなしのアーキテクチャに関する主張は、たいてい間違っています。
3. コンポーネントと境界を把握する — モジュールが接する箇所を確認します。インターフェース、ワイヤープロトコル、DBスキーマ、キュー、プラグインポイント、プロセス境界などです。各境界について、なぜここなのかを考えます。テスト容易性、差し替えやすさ、デプロイ境界、チームの境界、あるいは偶然によるものか。型を所有する側も記録します。
4. Git履歴を調べて根拠を探す（以下のコマンドを参照）。まず、履歴が浅いか、スカッシュされているか、インポートされたものか、生成物やベンダーコードが多いかを確認します。履歴が弱い場合は、根拠ではなく手掛かりしか得られません。
5. 設計の良し悪しを判断し、注目点を選ぶのは最後です。それまでに集めた証拠に基づいて行います。

Git の考古学

scripts/archaeology.sh [repo-dir]         # digest first, then drill into what it surfaces
git show --stat <sha>                     # read the big commits' messages in full
git log --follow --oneline -- <hot-file>  # evolution of a load-bearing file
git log -S '<symbol>' --oneline           # when/why a concept appeared or died

• 最近かどうかではなく、規模とメッセージから「重要な変更」を見つけます。書き直し、「refactor」「redesign」、バージョン更新のコミット、トレードオフを説明しているコミットメッセージを探します。良いプロジェクトでは、コミットメッセージに設計ドキュメントが隠れていることがあります。引用しましょう。
• 頻繁に変更されたファイル × 修正で変更されたファイルを照合し、詳しく読むファイルを選びます。これは手掛かりであって、脆弱性の証明ではありません。フォーマット変更、生成コード、長期間使われているファイルが件数の大部分を占めることがあります。
• リバートは、否定的な根拠になり得ます。代替案が採用されなかった理由の説明に使う前に、ロールバックが現在の設計に関するものか確認します。
• 両側で git shortlog -sn -- <dir> を実行し、「チーム境界」に関する仮説を検証します。作者が重複していなければ仮説を支持しますが、確証にはなりません。同じ名前が並んでいれば、仮説の確度は下がります。
• 気になる行を問題点と呼ぶ前に、git blame で確認します。多くの場合、修正コミットの経緯がわかります。

ブリーフィングの要件

ブリーフィングは、読者が自分でコードを理解するための地図であり、コードを読む代わりではありません。すべての概念について、その概念を解説しているファイルを示してください。以下のセクションを、記載順に作成し、全体を通して path:line または短い SHA を引用してください。

0. 課題とユーザー — どのような問題を誰のために解決するのか、またプロジェクトが意図的に行わないことは何か（非目標は、README／ドキュメントや初期のコミットに記されていることがよくあります）。
1. アーキテクチャ — 主なコンポーネント 3～7 個と、それらをつなぐ構造（パイプライン、ハブ＆スポーク、レイヤー構造、プラグインホストなど）。1 段落にまとめ、簡潔な図またはリストを添えます。
2. 設計の傾向 — 一貫して見られる作者の選択を、それぞれ 2 つ以上の例で裏付けます。依存関係の方針、エラー処理のスタイル、抽象化の深さ、命名、テストの方針、並行処理モデルなどが該当します。繰り返し現れるものが傾向です。1 例だけでは偶然かもしれません。
3. コンポーネントと境界 — コンポーネントごとに、責務、入出力の境界、その境界がそこにある理由を示します。境界を越えて誤った方向にインポートしているなど、漏れのある境界に注意を促します。
4. 履歴と理由 — 重要なコミット／時期を 3～6 件挙げ、それぞれから、現在の設計に至った理由を読み取ります（例：「X の後、コミット でインターフェースの背後にストレージを置き換えた」）。
5. 優れたコード — 根拠がある場合は、独創的、簡潔で明快、または少ないコードで多くを実現している箇所を 1～3 件紹介します。短い抜粋を引用し、優れている理由を具体的に述べます。守っている不変条件、まとめて扱えるケース、または誠実さを保っている API などを説明してください。調査したコードに目立つ箇所がなければ、無理に称賛せず、その旨を伝えます。
6. 好奇心を深める手掛かり — プロジェクト独自の用語（専門用語を 5～10 個挙げ、それぞれを定義するファイルを示す）、データフロートレースに適したフローを 2～3 件、分析では解決できなかった未解決の疑問（説明されていない境界、疑わしいコード、文書化されていない判断）を挙げます。

注意事項

• 観察と推測を分けます。「X は Y を Z 経由で呼び出す」はコードから読み取れる事実です。「おそらくテスト容易性のため」は推測なので、推測と明記します。
• ドキュメントとコードの内容が食い違う場合、コードを正とし、その食い違い自体を調査結果として扱います。
• 調査時間に上限を設けます。10 万行を超えるリポジトリでは、エントリーポイント、追跡したフロー 1 つ、履歴をもとにブリーフィングを作成し、未読の領域を列挙します。
• 充実したブリーフィングの最後には、調査範囲を記します。確認した範囲、サンプル調査またはスキップした範囲、推測に依存する主張、テストまたは実際の呼び出しを実行したかどうかを記載します。