code-atlas

Code Atlas Skill

目的

コードの実態に基づき、網羅的で再生成可能なアーキテクチャアトラスを構築します。コードアトラスは、図、グラフ、一覧表から成る、生きたドキュメント群です。あらゆるコードベースをたどれるマップとして機能します。アトラスの構築は調査です。コードをグラフ形式で構造的に推論すると、直線的なコードレビューでは見逃される構造上のバグ、API コントラクトの不整合、アーキテクチャの乖離が明らかになります。

エンジニアがアトラスとバグ報告だけを手にして、ソースコードを開かずに実行経路全体をたどれるようになれば、アトラスは完成です。

レイヤーの概要

レイヤーの定義は LAYERS.yaml を唯一の情報源とします。以下のすべての参照では、このファイルのスラッグを使用します。

Slug	名前	説明	推奨する図の種類
repo-surface	リポジトリの全体像	すべてのソースファイル、プロジェクト構造、ビルドシステム	Mermaid flowchart TD
ast-lsp-bindings	AST+LSP シンボルのバインディング	ファイル間のシンボル参照、デッドコード、インターフェースの不整合	Mermaid flowchart LR または DOT digraph
compile-deps	コンパイル時の依存関係	パッケージのインポート、依存関係ツリー、循環依存	DOT digraph（大規模なツリーに適しています）
runtime-topology	ランタイムトポロジー	サービス、コンテナ、ポート、サービス間の接続	サブグラフクラスターを使う DOT digraph
api-contracts	API コントラクト	HTTP ルート、gRPC、GraphQL、ミドルウェアチェーン	Mermaid flowchart TD
data-flow	データフロー	DTO からストレージまでの経路、変換ステップ	Mermaid flowchart LR
service-components	サービスコンポーネントアーキテクチャ	サービスごとの内部モジュール／パッケージ構造	Mermaid graph TD（サービスごとに1つ）
user-journeys	ユーザージャーニーのシナリオ	エントリーポイントから結果までのエンドツーエンドの経路	Mermaid sequenceDiagram

レイヤーごとの対象範囲の指針

Slug	対象範囲
repo-surface	最上位のディレクトリとビルドエントリーポイント。すべてのファイルを列挙しないでください。
ast-lsp-bindings	エクスポートされたシンボルと、そのファイル間参照。パブリック API の範囲に焦点を当てます。
compile-deps	直接依存関係と、1段階の間接依存関係。バージョン制約を含めます。
runtime-topology	デプロイされているすべてのサービス、そのポート、サービス間プロトコル。
api-contracts	認証、DTO、ミドルウェアを含む、すべての HTTP／gRPC／GraphQL エンドポイント。
data-flow	サービスごとの主要な読み書き経路。関連がない限り、内部のキャッシュフローは省略します。
service-components	各サービス内の最上位パッケージ／モジュール。結合のエッジを示します。
user-journeys	api-contracts のルートとページ／CLI エントリーから導きます。主要なジャーニーを3〜8件たどります。

スキル委任アーキテクチャ

code-atlas (this skill)
  Responsibilities:
    - Atlas layer orchestration (all 8 layers)
    - Language-agnostic code exploration
    - Three-pass bug-hunting workflow
    - Staleness detection triggers
    - Density management (split, not prompt)
    - Publication workflow (GitHub Pages, mkdocs, SVG)

  Delegates to:
    code-visualizer skill       Python AST module analysis (compile-deps + service-components fallback)
    mermaid-diagram-generator   Mermaid syntax generation and formatting
    lsp-setup skill             Layer ast-lsp-bindings: LSP-assisted symbol queries (optional)
    visualization-architect     Complex DOT graph rendering and cross-layer layouts
    analyzer agent              Deep codebase investigation and dependency mapping
    reviewer agent              Contradiction hunting (Passes 1, 2, 3)

このスキルを使うタイミング

トリガー	ユースケース
未知のコードベースで作業を始めるとき	コーディング前にアトラス全体を構築する
新しいエンジニアをオンボーディングするとき	アトラスをナビゲーションガイドとして共有する
大規模なリファクタリングの前	現状をマッピングし、トポロジーに基づいて変更を計画する
バグ調査が行き詰まったとき	グラフを使ってパス1とパス2のバグ調査を行う
ドキュメントが古くなったと感じるとき	古さを確認し、対象を絞って再構築する
CI/CD の品質ゲートを追加するとき	アトラスの鮮度チェックを登録する
ドキュメントサイトを公開するとき	GitHub Pages / mkdocs の公開ワークフロー
未知の PR をレビューするとき	現在のアトラスとの差分を使って PR の影響を確認する

クイックスタート

# Build a full atlas
User: Build a complete code atlas for this repository

# Run bug hunting
User: Run code atlas bug hunting passes on this service

# Check freshness
User: Are our architecture diagrams still accurate?

# Publish
User: Publish our code atlas to GitHub Pages

Mermaid と Graphviz の両方を使う理由

このスキルでは、形式ごとに異なるバグが見つかるため、デフォルトで両方の形式のアトラス図を構築します。7 つのリポジトリを対象とした対照実験では、見つかったバグの重複は約 15％にとどまり、両方を使うと、いずれか一方だけの場合と比べて約 1.7 倍のバグが見つかりました。構文の違いによって、同じコードを異なる思考経路で捉えられます。根拠は PR #3221 に記載されています。

ユーザーは単一の形式に変更できます。

User: Build a code atlas using only Mermaid
User: Build a code atlas in DOT format only

図の密度に関する方針

ノード数やエッジ数に厳密な上限はありません。代わりに、次の方針を適用します。

図が読みにくくなるほど密になる場合は、パッケージまたはサービスの境界ごとにサブ図へ分割します。 バッチモードでは、ユーザーに確認せず自動的にグループ化します。各サブ図は、読みやすさを保つため、ノード数が 15～40 個程度になるようにします。

たとえば、80 個のサービスを含むランタイムトポロジー図は、ドメインごとのサブ図（例：runtime-topology-payments.mmd、runtime-topology-auth.mmd）と、ドメイン間の接続を示す概要図に分割します。

表は図の補助としてのみ作成し、図の代わりにはしません。

レシピ：12 フェーズのアトラス構築

アトラスの構築は、次のフェーズを順番に実行します。

1. 前提条件を検証する -- ツール（mmdc、dot、kuzu）を確認し、LSP モードを検出する
2. レイヤー 1～4 を構築する（構造） -- repo-surface、ast-lsp-bindings、compile-deps、runtime-topology
3. レイヤー 5～8 を構築する（振る舞い） -- api-contracts、data-flow、service-components、user-journeys
4. 8 つのレイヤーすべてを検証する -- 必須ゲート：すべての slug に .mmd、.dot、レンダリング済み .svg、および画像を埋め込んだ README があること
5. バグ調査（Mermaid 側） -- .mmd 図のみを使って 3 パスで調査する
6. バグ調査（Graphviz 側） -- .dot 図のみを使って 3 パスで調査する（手順 5 と並行して実行）
7. 調査結果を統合する -- 両側の重複を除去する
8. マルチエージェント検証 -- 3 人の専門家が個別に投票し、2/3 以上を確認のしきい値とする
9. Issue を作成する -- 検証済みのバグは GitHub Issue として登録する（アトラスには保存しない）
10. Kuzu への取り込み + OpenCypher -- グラフに取り込む（必須）+ 単独で使える .cypher ファイルを生成する
11. アトラスを公開する -- SVG をレンダリングし、インデックスを作成し、mkdocs のナビゲーションを更新する
12. 最終チェックリストをレビューする -- 独立したレビュアーがすべての成果物の完全性を検証する

各構築フェーズの後、図は docs/atlas/{slug}/ に書き出されます。内容は .mmd ソース、.dot ソース、レンダリング済みの *-mermaid.svg と *-dot.svg、および ![alt](file.svg) 構文で SVG をインライン表示する README.md です。

バグ検出ワークフローの概要

atlas は、調査を進めるためのツールです。3 回のパスで、atlas を単なるマップから高い信頼性を持つバグ検出エンジンへと変えていきます。アンカリングバイアスを防ぐため、各パスは新しいコンテキストウィンドウで実行します。

• パス 1（包括的な構築＋調査）：すべてのレイヤーを構築してから、レイヤー間の矛盾を体系的に調査します。ルートと DTO の不一致、孤立した環境変数、実行時に使われない経路、古いドキュメント参照などが対象です。
• パス 2（新鮮な視点でのクロスチェック）：新しいコンテキストウィンドウで atlas を独立して再調査します。パス 1 の調査結果を確認、覆す、または重大な問題として報告します。
• パス 3（シナリオの詳細調査）：すべてのユーザージャーニーを、api-contracts、data-flow、runtime-topology、service-components、ast-lsp-bindings を通じてエンドツーエンドで追跡します。各ジャーニーには、PASS、FAIL、NEEDS_ATTENTION のいずれかの判定を付けます。

完全なチェックリスト、テンプレート、出力形式：bug-hunt-guide.md

レイヤー 8：ast-lsp-bindings の動作モード

レイヤー ast-lsp-bindings は、2 つのモードのいずれかで動作し、README の 1 行目に必ずモードを記載します。

モード	トリガー	仕組み
lsp-assisted	lsp-setup がアクティブな LSP サーバーを報告	シンボルのクエリを LSP に委譲します
static-approximation	LSP を利用できない場合	ripgrep + code-visualizer AST

モードラベルを省略したり、暗黙的にデフォルト設定したりすることはありません。

出力構造

docs/atlas/
  index.md
  staleness-map.yaml
  {slug}/
    README.md          (embeds SVG diagrams inline with ![alt](file.svg))
    *-mermaid.svg      (rendered Mermaid diagrams)
    *-dot.svg          (rendered Graphviz diagrams)
    *.mmd              (Mermaid source)
    *.dot              (Graphviz source)
    inventory.md       (where applicable)
  cypher/
    schema.cypher      (CREATE NODE/REL TABLE statements)
    atlas-layers.cypher
    atlas-services.cypher
    atlas-bugs.cypher
    atlas-relationships.cypher
    queries.cypher     (ready-to-run example queries)

必ず守る 3 つの出力ルール：

1. バグ調査の結果をatlas に保存することはありません。すべての調査結果は、code-atlas-bughunt ラベルを付けて GitHub issue として登録します。
2. Kuzu への取り込みは必須であり、任意ではありません。Kuzu を利用できない場合は、エラーを明示して修正（kuzu パッケージのインストール）を試みます。黙ってスキップしてはいけません。
3. OpenCypher の .cypher ファイルは、あらゆるグラフデータベースで利用できるよう、Kuzu への取り込みと並行して必ず生成します。

古さの検出

古さを判定するトリガーは、LAYERS.yaml でレイヤーごとに glob パターンとして定義されています。git diff がトリガーパターンに一致すると、該当するレイヤーは古いものとしてマークされます。

完全なトリガーテーブル、再構築コマンド、段階的な再構築の方針： reference.md

CI 統合

次の 3 つの GitHub Actions パターンを利用できます。

1. 自動コミット付きのマージ後の古さチェックゲート
2. レイヤー注釈付きの PR 影響チェック
3. 失敗時に issue を作成する、週次の定期的な完全再構築

完全なワークフロー YAML と設定：publication-guide.md

公開

GitHub Pages 対応の docs/atlas/ 構造を出力します。mkdocs-material と通常の GitHub Pages に対応しています。SVG はコミットされるため、読み込み時にレンダリングする必要はありません。

SVG の生成コマンド、mkdocs との統合、デプロイのワークフロー： publication-guide.md

図の例

レイヤーごとの Mermaid および DOT の例と、推奨する図の種類： examples.md

セキュリティ制御

すべてのセキュリティ制御（SEC-01 から SEC-19）は SECURITY.md で定義されています。 主な制御：

• シークレットの値は出力しません（環境ファイルはキー名のみ解析します）
• realpath() による境界検証でパストラバーサルを防止します
• Mermaid/DOT/SVG のラベルをサニタイズします（XSS 防止）
• バグ報告に含まれるコード引用から、認証情報のパターンを削除します
• すべての file:line 参照で相対パスを使用します（SEC-16）

API コントラクト

すべてのスキル委譲とファイルシステムレイアウトの型付きコントラクト： API-CONTRACTS.md

リファレンス

エラーコード、Kuzu 取り込みスキーマ、古さのトリガーテーブル： reference.md

成功基準

完全なアトラスは、次の条件を満たします。

• 8 つのレイヤーすべてが、docs/atlas/{slug}/ に図とともに生成されている
• DOT と Mermaid のソースファイルが両方存在する（ユーザーが単一形式を指定した場合を除く）
• SVG がソースファイルとともに出力されている
• バグ調査で見つかった問題は GitHub の issue として登録されている（アトラスのドキュメントには保存しない）
• 登録したすべてのバグに、レイヤーの参照先、ファイルパス、行番号、コード上の根拠が含まれている
• 図に孤立ノードがない
• ast-lsp-bindings の README の 1 行目にモードが記載されている

制限事項

• 静的解析ツールではありません：grep、AST、設定の解析を使用します。コンパイラーではありません
• 古さの判定はヒューリスティックです：Git の差分パターンマッチングを使用し、意味解析は行いません
• Python AST への委譲：Python モジュールのグラフは code-visualizer に委譲されます（Python 専用）
• SVG のレンダリングには Graphviz／Mermaid CLI が必要です：CI 環境にはこれらをインストールする必要があります
• バグ調査は確率的です：登録前に人間によるレビューが必要です
• 単一リポジトリが対象です：リポジトリ間の依存関係には手動設定が必要です
• ランタイム計測は行いません：呼び出し頻度とレイテンシの測定には APM ツールが必要です

覚えておくこと

図の作成は調査であり、単なるドキュメント化ではありません。

コードアトラスの最も価値ある成果は、システムをグラフ形式で推論する過程で見つかるバグと矛盾です。

決して譲れない 5 つのルール：

1. 図から表への無断置き換えは禁止です。 密度が高い場合は、サブ図に分割してください。
2. モードは常に見えるようにします。 ast-lsp-bindings の README の 1 行目には、必ずモードを記載してください。
3. バグ調査は 3 パスで行います。 パス 1 で調査し、パス 2 で検証し、パス 3 でジャーニーごとに判定します。
4. バグは issue に登録し、アトラスには記載しません。 アトラスは継続的に更新されるアーキテクチャドキュメントであり、バグ報告ではありません。
5. Kuzu は必須であり、任意ではありません。 グラフの取り込みを黙ってスキップしてはいけません。エラーを明確にし、修正してください。

コードの真実に基づいて再構築し、矛盾を調査し、根拠に裏付けられたバグを登録してください。これを繰り返します。