explain-repo

Explain Repo

このスキルは、リポジトリをアトラスに変換します。開発者がコードベースを理解して開発を続けられるよう、ナビゲーション可能な HTML の章を集めたものです。さらに、将来のエージェントセッションを立ち上げるために要点をまとめた SUMMARY.md も作成します。

アトラスの内容はすべて根拠に基づいています。主張には必ず、その根拠となったファイル、コミット、または Issue を引用します。引用できない主張は削除します。これがこのスキルの基本原則、引用するか削除するかです。この種のコードが「通常」どう動くかというパラメトリックな推測で、リポジトリを説明してはいけません。実際に読み、引用してください。創作が特に起こりやすい History と Strengths/Weaknesses の 2 章では、この原則を徹底するため、対抗的な反証パス（ステップ 5）を実施します。

アトラスは対象リポジトリ内の .repo-atlas/ に置きます。Git で無視されるため、作業ツリーに変更が加わることはありません。また、作成時のコミットを基準時点として記録し、コードの変化に応じて更新できるようにします。

各ステップは順番に進めてください。それぞれに完了条件があります。条件を満たすまでは次に進まないでください。

アトラスのワークスペース

領域と、それを表す地図に対応する 2 つのレイヤーで構成されます。

プレゼンテーションレイヤー — 開発者が開くもの（HTML）、.repo-atlas/ 内。

• index.html：ダッシュボード。開発者が開く唯一のページです。章、参照資料、基礎資料を並べた左メニューに、鮮度を示す行があり、コンテンツ領域には現在の章が表示されます。サイドバー全体は、ファイル内の NAV オブジェクトによって制御されます（ダッシュボードを参照）。templates/dashboard.html から作成します。
• assets/：共通の style.css と md.js（オフラインの Markdown レンダラー）。セットアップ時にこのスキルの assets/ から一度コピーします。アトラスごとに手作業で編集してはいけません。
• brief.html、glossary.html、sources.html：基礎資料。templates/doc.html から作成し、BRIEF-FORMAT.md、GLOSSARY-FORMAT.md、SOURCES-FORMAT.md に沿った Markdown を内容として記述します。
• chapters/*.html：アトラス本体。リポジトリの各領域につき、CHAPTERS.md に示された骨格に従って、自己完結した章を 1 つ作成します。templates/chapter.html から作成します。ファイル名は 0001-<dash-case-name>.html とし、番号を順に増やします。
• reference/*.html：密度が高く、ざっと確認できるチートシート（ディレクトリマップ、コマンドリファレンス、重要ファイルの索引）。templates/reference.html から作成します。

状態レイヤー — 開発者には開かない作業メモリ（Markdown）、.repo-atlas/ 内。

• findings/*.md：リポジトリについて確認済みの事実と、各章の背景にある未解決の疑問を記録した、根拠の台帳です。ファイル名は 0001-<slug>.md とします。FINDING-FORMAT.md を使用してください。
• SUMMARY.md：要点をまとめたエージェント起動用ファイルです。SUMMARY-FORMAT.md に従います。
• .atlas-meta.json：{ asOf, repoRemote, chapters }。更新を制御する基準時点の記録です。
• NOTES.md：好みや作業メモを記録するためのスクラッチパッドです。

Markdown を唯一の情報源とする

基礎資料（brief、glossary、sources）では、Markdown は HTML 内の <script type="text/markdown"> ブロックに記述します（templates/doc.html を参照）。編集時はそのブロックだけを変更し、資料の状態を確認するときもそのブロックだけを読み取ってください。md.js がレンダリングするため、別個の .md ファイルはなく、二重管理も発生しません。状態資料（findings/、SUMMARY.md、NOTES.md）は通常の .md のままにします。開発者が開くことはないため、HTML でラップしてはいけません。

ステップ 1 — ワークスペースをセットアップする

対象リポジトリを特定します（デフォルトは現在のリポジトリです。それ以外の場合はパスを尋ねます）。次に、リポジトリのルートから以下を行います。

1. .repo-atlas/ を作成し、無視対象になっていることを確認します。.gitignore に .repo-atlas/ を追加します（.gitignore がない場合は作成します）。対象が Git リポジトリでない場合は、その旨を伝えます。履歴と鮮度を確認できないことを説明し、続行するか尋ねます。
2. このスキルの assets/ を .repo-atlas/assets/ にコピーします。
3. templates/dashboard.html を .repo-atlas/index.html にコピーし、templates/doc.html をもとに brief.html、glossary.html、sources.html を作成します。
4. chapters/、reference/、findings/ は、それぞれに最初のファイルを書き込むときに作成します。

完了条件： .repo-atlas/ が存在し、Git の無視対象になっていて、assets/ とダッシュボードを含み、3 つの基礎ドキュメントが存在すること（空でも構いません）。

ステップ 2 — 偵察してブリーフを作成する

コストを抑えた広範な調査を行います。まだ深く読み込まないでください。

• 構成：ディレクトリツリー（深さを制限）、エントリーポイント、README、CONTRIBUTING。
• スタック：マニフェスト／ロックファイル、Dockerfile、CI 設定ファイル（存在とファイル名）。
• Git：git log --reverse | head、タグ、git shortlog -sne（Git リポジトリでない場合は省略）。
• オリジン：git remote get-url origin。URL と、リポジトリが public かどうかを記録します（Contributing 章の要否はこれによって決まります。gh と public なリモートを利用できる場合は対象に含め、それ以外の場合は対象外とします）。

偵察をもとに、次の 2 つを行います。

1. ブリーフのためにヒアリングする — 開発者がこのリポジトリを調査する 理由 と、何をする予定か（オンボーディング、バグ修正、機能追加、監査、引き継ぎなど）を尋ねます。さらに、説明の深さを調整するため、使用するスタックへの習熟度も確認します。質問は数問にとどめます。BRIEF-FORMAT.md に従って brief.html を作成します。ブリーフによって、どの章を掘り下げるかが決まります。
2. 機能ブロックを列挙する — 詳しく調査する価値のある重要なサブシステムを特定します。大規模なリポジトリでは、規模と変更頻度に基づいて、深掘りする対象を主要なブロックに絞ります。調査対象から外したものは必ず NOTES.md とブリーフに記録し、決して黙って省略しないでください。

完了条件： brief.html が作成され、public／private が確認され、調査対象のブロックと対象外にしたブロックが記録されていること。

ステップ 3 — 調査する

ここで CHAPTERS.md を読みます。章立てと、章ごとの調査手順（読むべきもの、引用すべきもの）が記載されています。ブリーフで指定された章を選びます。

作業を分担する： 章ごと（または機能ブロックごと）にサブエージェントを 1 つ起動します。それぞれ担当範囲のみを調査し、構造化された 調査結果（FINDING-FORMAT.md）と、章の Markdown 草案を返します。これにより、膨大な読み込みをメインのコンテキストから切り離せます。サブエージェントには、章ごとの手順に加えて 引用するか、記載しないか という指示を与えます。すべての主張に path:line、コミット SHA、または issue／PR 番号を付け、直接確認した（observed）か、推論した（inferred）かを示します。

完了条件： 対象となるすべての章について、各主張に出典が引用され、observed／inferred のタグが付いた調査結果があること。

ステップ 4 — 組み立て

調査結果をアトラスにまとめます。

• templates/chapter.html をひな形として chapters/NNNN-*.html を作成し、引用を実際のソースへのリンクとして記載します。表示テキストは src/foo.ts:42 とし、相対パスの <a href="../../src/foo.ts"> でもあるようにします（章とリファレンスドキュメントはリポジトリルートから 2 階層下にあり、ルート直下の基盤ドキュメントでは代わりに ../ を使用します）。リモートが Web URL の場合はコミットを <remote>/commit/<sha> にリンクし、それ以外の場合は SHA のみを記載します。
• glossary.html（リポジトリおよびドメイン用語。GLOSSARY-FORMAT.md に従います）と、sources.html（リポジトリ、そのドキュメント、スタックのドキュメント、さらに公開リポジトリの場合はトラッカーとコミュニティ。SOURCES-FORMAT.md に従います）を整備します。
• 各章とリファレンスを index.html の NAV に追加します（「ダッシュボード」を参照）。

完了条件： 対象範囲内のすべての章が、機能するソースリンク付きでダッシュボードに表示され、用語集とソース一覧が作成されていること。

ステップ 5 — 反証

創作が入り込みやすい 2 つの章、History と Strengths/Weaknesses について、敵対的な観点で見直します。懐疑的なサブエージェントを起動し、実際のコードと Git に照らして各主張を反証させます。証拠が薄い場合は、既定で「裏付けなし」と判断させます。根拠を示せない主張は削除するか、推論に格下げします。引用による証拠のない弱点は掲載しません。

完了条件： History と Strengths/Weaknesses のすべての主張に、反証担当者が認めた引用による根拠があるか、削除されていること。

ステップ 6 — 要約して確定

1. SUMMARY-FORMAT.md に従って SUMMARY.md を作成します。将来のエージェントが初期情報を得るために読む、高密度で解析しやすいファイルです。これは調査結果を要約したものであり、新たな調査を追加するものではありません。
2. .atlas-meta.json に as-of コミット（git rev-parse HEAD）、リモート、章の一覧を記録します。ダッシュボードの鮮度表示に as-of を表示します。
3. SUMMARY.md をリポジトリの CLAUDE.md にコピーすることを提案します（追記または新規作成）。提案にとどめ、自動では実行しません。
4. CLI の open コマンドが利用できる場合は、開発者のためにダッシュボード（.repo-atlas/index.html）を開きます。

完了条件： SUMMARY.md と .atlas-meta.json が存在し、ダッシュボードに as-of コミットが表示され、開発者にダッシュボードの場所が案内されていること。

アトラスの更新

アトラスがすでに存在する場合、再実行は再構築ではなく、対象を絞って行います。.atlas-meta.json の as-of コミットを読み取り、git diff <asOf>..HEAD --stat を実行して、変更されたパスを章に対応付けます。NAV では該当する章だけを古い状態としてマークします（ダッシュボードにはその件数が表示されます）。その章だけを再調査し（該当範囲についてステップ 3～5 を実施）、.atlas-meta.json を更新します。変更されていない章はそのままにします。

ダッシュボード

ダッシュボードは開発者のホームです。サイドバーと鮮度表示は、index.html 内の NAV オブジェクトだけを使って制御します。サイドバーのマークアップを手作業で編集してはいけません。何かを作成または更新したら、NAV を更新します。

• 新しい章 → { n, href, title, stale: false } を NAV.chapters に追加し、NAV.current がその章を指すようにします。
• 新しいリファレンス → { href, title } を NAV.reference に追加します。
• 更新時に章が古くなった → stale: true に設定します。再調査後に解除します。
• as-of が変更された → NAV.asOf を更新します。

図

既定では、フェンス付きコードブロック内に ASCII のボックス図を使用します。依存関係がなく、きれいに印刷でき、オフラインの file:// アトラスとも一貫性があります。作成する価値のある図は、アーキテクチャ（モジュールマップ）、CI/CD（パイプライン）、エンドツーエンドのフロー 1 つです。開発者から依頼があった場合に限り、mermaid などのレンダラーを組み込みます。