dev-context-code-graph

Code Graph

単一のリポジトリを対象に、決定的で機械可読なコードグラフを構築します。このグラフは、ターミナル専用のレポートではなく、LLM が保守するリポジトリ Wiki やコンテキストハブのための機械可読な基盤として扱います。このスキルは dev-context-multi-repo のアーティファクトワークフローを踏襲しつつ、ポートフォリオレベルではなく、ファイルとシンボルのレベルで動作します。

次の用途でこのスキルを使用します。

• コミット可能な graphs/code-graph.json アーティファクトが必要な場合
• 1 つのリポジトリのファイルマップとシンボルマップが必要な場合
• インポート、呼び出し、継承、テストリンクの分析
• 関節点、橋、サイクル、トポロジカル順序、代替経路などのグラフ理論に基づくレビューシグナル
• 変更されたファイルやシンボルの影響範囲と、レビューに必要な最小限のコンテキスト
• パーソナライズド PageRank を使った、1〜3 個の注目シンボル周辺の予算上限付きコンテキスト取得
• 場当たり的なコードベースの説明文ではなく、グラフデータに基づいて生成する、根拠のあるリポジトリ説明やモジュール説明

次の用途にはこのスキルを使用しないでください。

• ポートフォリオ全体にわたるリポジトリの探索や、リポジトリ横断のシステムマップ
• 多数のリポジトリにまたがるアーキテクチャや移行の計画
• グラフを生成しない説明文ドキュメントの整理

代わりに、関連する次のスキルを使用してください。

• リポジトリのポートフォリオやハブレベルのナレッジグラフには dev-context-multi-repo
• コードグラフ、コンテキストグラフ、リポジトリグラフのどれが適切なアーティファクトか判断するには dev-context-engineering
• コードグラフの仕様と受け入れ基準には docs-ai-prd
• グラフに基づくドキュメントやレポートの公開には docs-codebase

クイックリファレンス

必要なこと	ここから始める
基本のアーティファクト一式を生成する	## Workflow
スキーマとグラフの整合性を検証する	### Phase 3: Validate
影響範囲やシンボルの近傍を照会する	### Phase 4: Query
グラフ構造上のリスクを明らかにする	query_code_graph.py --articulation-points、--bridges、--cycles、--topo-sort、--from ... --to ... --k N
注目シンボルの PPR による取得を実行する	query_code_graph.py --ppr --seed <id> [--seed <id> ...] --top N
コミュニティを使ってモジュールを検出する	query_code_graph.py --communities [--resolution γ] [--community-seed N]
レビューに適したクエリを選ぶ	references/query-recipes.md
スクリプト、スキーマ、レポートを読み込む	## Navigation

標準出力

すべての実行で、同じ出力モデルを使用してください。

• code-profiles/<repo>.json schemas/code-profile.schema.json に準拠した機械可読なコードプロファイルです。
• graphs/code-graph.json 主要な機械可読アーティファクトです。schemas/code-graph.schema.json に準拠した、照会可能なシンボルグラフです。
• reports/code-graph-validation.json (任意ですが推奨) scripts/validate_code_graph.py --output ... の出力です。
• reports/code-graph-report.md (任意ですが推奨) グラフから生成される、人が読めるサマリーレポートです。
• reports/query-*.md (任意ですが推奨) リポジトリのナレッジベースに記録する価値のある、影響範囲、近傍、関係性に関する回答を保存したものです。
• reports/code-graph-report.html (任意) ローカルでのレビュー用の静的 HTML レポートです。
• reports/code-graph.mmd (任意) グラフの近傍や影響範囲ビューをエクスポートした Mermaid 図です。

ワークフロー

フェーズ 1：スキャン

1. 生成物やベンダー提供のビルドツリーをスキップしながら、拡張子を使って対応するソースファイルを特定します。
2. ファイルを source、test、config、unknown に分類します。
3. 利用可能な最善の決定的な方法で各ファイルを解析します。
4. 解析ステータスを parsed、heuristic、unsupported、error、skipped のいずれかとして明示的に記録します。

主なヘルパー：scripts/scan_code_repo.py

ASCII フロー

single-repo code graph request
  -> scan files and classify source, test, config, or unknown
  -> parse symbols with deterministic or heuristic parser
  -> build nodes and edges into graphs/code-graph.json
  -> validate schema, references, duplicates, orphans, and parse confidence
  -> query neighborhoods, impact, paths, PPR, communities, or structural risk
  -> persist useful reports back into repo context
  -> use findings for review, docs, onboarding, or blast-radius planning

フェーズ 2：ビルド

1. 1 つ以上の code-profiles/*.json ファイルを読み込みます。
2. 正規ノードとエッジを graphs/code-graph.json に具体化します。
3. リポジトリからファイルへの構造エッジと、親シンボルまたはファイルから子シンボルへの構造エッジを追加します。
4. 解決できないインポート先や呼び出し先、またはサードパーティのインポート先や呼び出し先に対して、external_symbol ノードを合成します。

主なヘルパー：scripts/build_code_graph.py

フェーズ 3：検証

ビルドのたびに検証を実行します。

python3 scripts/validate_code_graph.py graphs/code-graph.json \
  --output reports/code-graph-validation.json

検証ツールは以下をチェックします。

• スキーマと列挙型への準拠
• 存在しない参照
• 孤立ノード
• 重複 ID
• 包含関係と親エッジの整合性
• 循環インポート
• 古い検証メタデータ
• 解析ステータスと信頼度の範囲

フェーズ 4：クエリ

一般的なクエリパターン：

# Neighborhood around a file or symbol
python3 scripts/query_code_graph.py graphs/code-graph.json --node <id> --hops 1

# Blast radius from a file or symbol
python3 scripts/query_code_graph.py graphs/code-graph.json --impact <id> --hops 2

# Path between two nodes
python3 scripts/query_code_graph.py graphs/code-graph.json --from <id> --to <id>

# Up to three node-disjoint shortest paths
python3 scripts/query_code_graph.py graphs/code-graph.json --from <id> --to <id> --k 3

# Personalized PageRank from one or more hot symbols
python3 scripts/query_code_graph.py graphs/code-graph.json --ppr --seed <id> --top 30

# Module detection via Louvain communities (γ=1 default; >1 = smaller modules, <1 = larger)
python3 scripts/query_code_graph.py graphs/code-graph.json --communities --format table
python3 scripts/query_code_graph.py graphs/code-graph.json --communities --resolution 1.4 --top 25

# Search by label, path, summary, or tags
python3 scripts/query_code_graph.py graphs/code-graph.json --search "invoice service"

# Structural risk
python3 scripts/query_code_graph.py graphs/code-graph.json --articulation-points --relations imports --top 20
python3 scripts/query_code_graph.py graphs/code-graph.json --bridges --relations imports --top 20
python3 scripts/query_code_graph.py graphs/code-graph.json --cycles --relations imports,inherits,calls
python3 scripts/query_code_graph.py graphs/code-graph.json --topo-sort imports

# Mermaid diagram export
python3 scripts/query_code_graph.py graphs/code-graph.json --diagram --output reports/code-graph.mmd

主なヘルパー：scripts/query_code_graph.py

クエリから長期的に役立つ知見が得られた場合は、チャット出力にだけ残さず、Markdown または Mermaid に記録します。

クエリ出力を使って、以下を生成します。

• リポジトリ領域の説明
• モジュールの概要
• 変更の影響に関するメモ
• リスクの高いシンボルやサブシステムのレビュー資料

フェーズ 5：公開

人が確認できる静的レポートを生成します。

python3 scripts/export_code_graph_report.py graphs/code-graph.json \
  --output-dir reports/

Obsidian でレビューしたり、より広範なコンテキストハブに保存したりできる Markdown、Mermaid、または HTML 形式の出力を推奨します。

フェーズ 6：強化

グラフに基づくナレッジに対して、軽量なヘルスチェックを実行します。

1. 検証結果を確認し、不足しているエッジ、解析の欠落、説明が必要な未対応領域を特定します。
2. 密結合または接続の弱いグラフ領域に基づいて、再利用可能なレポート、概念ページ、フォローアップの質問を LLM に提案させます。
3. 同じ調査を後で繰り返さずに済むよう、長期的に役立つ知見を reports/ または上位レベルのリポジトリナレッジベースに記録します。

グラフをリポジトリの説明に使う場合は、生成の範囲を限定します。

• グラフが裏付けられる内容だけを要約します
• 解析の欠落を明示します
• シンボル名だけを根拠に、所有権、実行時の動作、アーキテクチャ上の役割を作り上げないでください

V1 の対応範囲

v1 のパーサーパイプラインは、決定論的かつ保守的です。

• フルパーサー：ast を使った Python
• ヒューリスティックパーサー：JavaScript、TypeScript、TSX、C#、Swift
• 未対応の言語：ファイルノードのみを出力し、明示的に未対応とマークします

Swift の v1 対応は、意図的にヒューリスティックなものです。スキャナーは .swift ファイルからトップレベルの型シンボルと関数シンボルを抽出し、imports および継承／プロトコルのエッジを保守的に記録します。また、.build、DerivedData、Pods、Carthage、SourcePackages など、Apple の生成ビルド出力を対象外にします。

グラフが対象とするもの：

• repo、file、class、function、method、test、external_symbol ノード
• contains、defines、imports、calls、inherits、references、tests エッジ

以下は対象としません。

• セマンティック埋め込み
• 監視モードまたは IDE 同期
• SQLite による永続化
• プログラム全体の型推論
• 動的コードにおける完全な呼び出し解決の保証

小規模から中規模のリポジトリでは、グラフへの直接クエリと簡潔な Markdown レポートで十分なことがよくあります。グラフの JSON と要約だけでは運用上不十分になるまでは、より複雑な検索やインデックスのレイヤーを追加しないでください。

コマンドパターン

次のいずれかの指示から始めます。

• 「dev-context-code-graph を使って、このリポジトリのコードグラフを構築してください。」
• 「dev-context-code-graph を使って、<file-or-symbol> の影響範囲を特定してください。」
• 「dev-context-code-graph を使って、<module> をカバーするテストをマッピングしてください。」
• 「dev-context-code-graph を使って、このコードベースの領域の Mermaid 図をエクスポートしてください。」
• 「dev-context-code-graph を使って、グラフの根拠に基づくリポジトリ領域の説明を生成してください。」

推奨レイアウト

code-hub/
├── AGENTS.md
├── code-profiles/
├── graphs/
├── reports/
├── schemas/
└── scripts/

生成されたグラフデータは code-profiles/、graphs/、reports/ に保存します。インベントリや生のシンボル一覧をルートの指示ファイルに貼り付けないでください。

安定した型

このスキルでは、次の標準的なコントラクトを前提とします。

• schemas/code-profile.schema.json
• schemas/code-graph.schema.json

下流システムで変換レイヤーが必要な場合を除き、別のデータ形状を独自に作成しないでください。

検証チェックリスト

• スキャン対象の各リポジトリから、code-profiles/<repo>.json が1つ生成される。
• すべてのノードに、正規化された安定した ID がある。
• parent_id を持つすべてのノードに、対応する contains または defines エッジがある。
• サポートされていない解析や失敗した解析が、すべて明示的に記録されている。
• graphs/code-graph.json の検証が問題なく完了する。
• 影響範囲やパスのクエリから、範囲が限定され、読みやすい結果が返される。
• 外部の参照先は、宙に浮いたエッジではなく external_symbol ノードとして表現されている。
• 再利用する価値のある調査結果は、チャット履歴だけに残さず、Markdown または図のファイルに書き出されている。
• リポジトリやモジュールの説明を生成する場合は、グラフの根拠に基づいており、解析上の不足も明示されている。

既知の落とし穴

• ファイル形式や言語のサポートが部分的な場合に、ヒューリスティックなパーサーの出力を意味的な真実として扱う。
• 解析ステータスや確信度のフィールドを明示せず、下流の要約がグラフで裏付けられる以上に確実なものに見えてしまう。
• プロファイルとスキーマのコントラクトを通じて正規化せず、場当たり的なスクリプトや LLM の要約から直接グラフのエッジを構築する。
• サポートされていない言語を、影響範囲の回答に影響するカバレッジ不足として記録せず、暗黙のうちに無視してよいと考える。
• 範囲が限定された近傍クエリや影響範囲クエリで十分で、検証もはるかに容易な場合に、すべての質問に対して巨大なグラフクエリを1つ実行する。
• コードグラフをソースファイルの読み込みに代わるものとして扱う。コードグラフは、動作を最終的に判断する根拠ではなく、参照先を特定し影響範囲を調べるための基盤です。
• 必要なコンテキストだけをその都度得るためにグラフのノード ID、パス、範囲を限定したクエリを使わず、リポジトリ全体のグラフ出力を LLM のプロンプトに取り込む。

よくあるアンチパターン

• グラフを文章中心のレポート生成器に変えてしまい、信頼性を支えていた機械可読な基盤を失う。
• 安定したスキーマを維持し、必要に応じて変換レイヤーを追加する代わりに、場当たり的に新しいノード型やエッジ型を作成する。
• 外部ライブラリや解決できないシンボルを external_symbol ノードとして表現せず、欠損データとして扱う。
• 解析上の不足、ヒューリスティック、サポート対象外の領域に触れずに、グラフ出力からリポジトリやモジュールの説明を公開する。
• 決定論的なグラフとクエリのワークフローだけで運用上十分な状態になる前に、より重い検索や埋め込みを追加する。
• 生成された要約を、あたかもソースの根拠であるかのように、グラフの抽出処理に再度入力する。
• リポジトリごとのシンボルノードをポートフォリオのナレッジグラフに混入させず、リンク付きのコードグラフレポートや選定した要約を公開する。

ナビゲーション

リファレンス

• references/code-graph-patterns.md
• references/parser-support-matrix.md
• references/query-recipes.md

スキーマ

• schemas/code-profile.schema.json
• schemas/code-graph.schema.json

スクリプト

• scripts/scan_code_repo.py
• scripts/build_code_graph.py
• scripts/validate_code_graph.py
• scripts/query_code_graph.py
• scripts/export_code_graph_report.py
• scripts/test_code_graph_regressions.py

例

• examples/python-mini-repo.md
• examples/typescript-mini-repo.md

ファクトチェック

• 既知のバグ、リグレッション、フレームワーク／コンパイラー／ランタイムの落とし穴、バージョン固有のクラッシュや回避策に関する情報は、現在も有効な事実として扱う前に、最新の一次情報をウェブで確認してください。
• 実装が変更された場合は、ユーザー向けの回答を行う前に、パーサーのサポートに関する情報を再確認してください。
• パーサーのランタイム、AST の動作、JSON Schema のセマンティクスについては、一次資料を優先してください。
• 厳選されたソースマップとして data/sources.json を使用してください。