codebase-study-guide

コードベース学習ガイド

エビデンスに基づく学習手法を用いて、コードベースへの持続的な理解を築く学習ガイドを生成します。このガイドは、コードが何をするのかだけでなく、なぜ存在するのか、また各部分がどのように関連しているのかを読者が把握できるようにします。

指導の基本方針

以下の原則が、ガイドのすべてのセクションを形作ります。研究の根拠については、references/pedagogy.md を参照してください。

• 構造より目的を先に。 ファイルツリーではなく、解決する課題から始めます。「なぜ」を理解した読者は、「どのように」を理解するためのより強固なスキーマを形成します（Ausubel の有意味学習）。
• しきい値概念を最初に。 ひとたび理解すれば、ほかのすべてが腑に落ちるようになる2〜3個のアイデアを特定し、最初に提示します（Meyer & Land）。
• 段階的な開示。 概要 -> システム -> インターフェース -> 内部構造の順に、複雑さを段階的に重ねます。なじみのないサブシステムを一度に複数紹介してはいけません（認知負荷理論）。
• 受動的学習より能動的学習を。 説明だけでなく、予測を促す問い、詳細な検討を促す質問、探索タスクを含めます。能動的な手法は、受動的な読書より高い効果を示します（d = 0.5〜0.7、Dunlosky ほか）。
• 二重符号化。 文章による説明には、必ず図、マップ、フローなどのビジュアルを組み合わせます。二重チャネルによる符号化で、想起率はおよそ2倍になります（Paivio）。
• パターンに名前を付ける。 アーキテクチャパターンを明示し、参考資料にリンクします。パターン認識は、熟練者がコードを理解するためのメカニズムです（Brooks、Soloway）。

ワークフロー

ステップ 1：ガイドの範囲を定める

AskUserQuestion を使用して、対象読者と重点項目を把握します。

question: "Who is the primary audience for this study guide?"
header: "Audience"
options:
  - label: "New team member"
    description: "Developer joining this team, needs full onboarding"
  - label: "Experienced dev, new codebase"
    description: "Senior engineer who knows the stack but not this project"
  - label: "Cross-team collaborator"
    description: "Someone who needs to interface with this system, not own it"
  - label: "Future me"
    description: "Personal reference for a codebase I'm exploring now"

次に、詳しさを確認します。

question: "What depth should the guide cover?"
header: "Depth"
options:
  - label: "Full guide (Recommended)"
    description: "Purpose, architecture, systems, patterns, interfaces, and exploration tasks"
  - label: "Architecture overview"
    description: "Purpose and high-level systems only, no deep dives"
  - label: "Specific subsystem"
    description: "Deep dive into one area of the codebase"

ステップ 2：コードベースを調査する

Explore エージェントまたは直接ツールを使って、体系的に調査します。次の順序で確認します。

1. エントリーポイント — 実行はどこから始まるか（main、ルートハンドラー、CLI エントリー、イベントリスナー）
2. 設定 — 動作を左右するものは何か（環境変数、設定ファイル、機能フラグ）
3. ドメインモデル — 中核となるエンティティとその関係は何か
4. 主要なフロー — 代表的な操作を2〜3個選び、最初から最後まで追跡する
5. システム境界 — このコードはどこで外部システムと連携するか
6. テスト構成 — テストから、意図された動作やエッジケースについて何がわかるか
7. 既存のドキュメント — README、CLAUDE.md、アーキテクチャドキュメント、ADR、インラインコメント

次の点も確認します。

• 命名規則とコード構成のパターン
• エラー処理の方針
• 主要な依存関係と、それぞれの役割

ステップ 3：しきい値概念を特定する

調査内容をもとに、コードベース固有のしきい値概念を2〜3個特定します。しきい値概念とは、次の特性を持つアイデアです。

• 変革的：理解すると、システム全体の見方が変わる
• 統合的：それまで無関係に見えた部分を結び付ける
• 自明でない：新規参入者が何気なく読むだけでは気付けない

例：「すべてはイベントである」「所有権がライフサイクルを決める」「設定が信頼できる唯一の情報源である」「読み取りと書き込みは別のモデルである」

ステップ 4：概念マップを作成する

執筆する前に、システムのメンタルモデルを概念マップとして作成します。

• ノード：主要なシステム／モジュールを5〜8個
• エッジ：それらがどのように通信するか（関数呼び出し、イベント、共有状態、HTTP、キュー）
• 方向：データ／制御がどちらに流れるか

これがガイドの「システムマップ」セクションとなり、それ以降の内容の順序を決める基礎になります。

ステップ 5：ガイドを作成する

references/guide-template.md のテンプレート構成に従ってください。作成時の主な原則：

各システム／モジュールのセクションについて：

• 仕組み（「どのように機能するのか」）より先に、目的（「なぜ存在するのか」）から説明を始めます
• 読者に設計上のトレードオフについて考えさせる「なぜ」という問い、つまり掘り下げて考えるための質問を含めます
• 使用しているアーキテクチャパターンを明示し、標準的なリソースへのリンクを付けます
• 代表的なコードスニペットを、構文だけでなく理由も注釈で説明しながら、実例として示します
• 読者が独力で取り組める探索課題で締めくくります

Mermaid 図について：

• システムアーキテクチャとデータフローには graph TD を使用します
• リクエストのフローとやり取りには sequenceDiagram を使用します
• 関係性を含むドメインモデルには classDiagram を使用します
• 図は要点を絞り、すべてを一度に詰め込まず、1 つの図につき 1 つの概念を扱います

探索課題について：

• PRIMM の進行に従います：予測 -> 実行 -> 調査 -> 変更
• 「コードを見る前に、〜の場合に何が起きると思いますか？」という予測から始めます
• 調べる具体的なファイルパスと関数名を含めます
• ガイド付きの探索から、独力で行う調査へと段階的に進めます

ステップ 6：レビューして提出する

ガイドを提出する前に、以下を確認してください。

1. 「木を見て森を見ず」になっていないか確認します — ガイドを読み終えた読者は、なぜこの仕組みが存在するのか、またユーザーにとってどのような問題を解決するのかを理解できるでしょうか？目的のセクションで説得力をもって説明できていない場合は、修正してください。
2. 段階的な情報開示を確認します — セクション 2 まで読んだ時点でも、有用な理解を得られるでしょうか？セクション 3 までではどうでしょうか？各セクションは、それ単独でも価値のある内容にしてください。
3. 能動的な要素を確認します — 主要な各セクションに、少なくとも 1 つの質問または課題が含まれていますか？能動的な学習を促す要素がなく、説明だけに終始しているセクションは削除してください。
4. パターンへのリンクを確認します — 名前を挙げたすべてのパターンに、学習用リソースへのリンクが付いていますか？

ガイドは単一の Markdown ファイルとして、適切な場所（.claude/docs/study-guide.md、またはユーザーの指定した場所）に作成します。ガイドは自己完結型にしてください。コードベースとガイドを利用できる読者が、それ以外に何も必要としない内容にします。