コードスペース — 信念マップ・アーキテクチャ発見 は何をしますか？
ソースファイルを読む前に、.belief_map.sexp をクエリしてモジュール、境界、依存関係を発見します。コードを盲目的に読まず、最初にグラフをクエリしてください。
スクリプト
このスキルには Python スクリプトがバンドルされています。スキルのベースディレクトリから実行してください。
scripts/belief_search.py— 信念マップグラフへのクエリscripts/build_belief_map.py— ソースから信念マップを生成scripts/build_infra_topology.py— Kustomize、Helm、Terraform のトポロジーファクトを抽出scripts/git_descendants.py— HEAD（または指定された ref）から派生するすべてのコミットを検索
プロジェクトローカルのスクリプトコピーは使用しないでください。それらは古く、JSON（sexp ではない）を出力する可能性があります。
前提条件
信念マップを見つけてください。なければビルドします。
ls .belief_map.sexp belief_map.sexp 2>/dev/null
# ビルド: pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py # 差分ビルド ~5秒
python3 scripts/build_belief_map.py --full # フルビルド ~30秒
必須ワークフロー: コードの前にクエリ
非自明なコード作業では、rg、find、sed、cat、nl、ディレクトリを開く、またはソースファイルを読む前に、信念マップクエリを実行してください。このスキルは、ソースを確認した後の確認としてではなく、最初のスコープ設定ステップとして使用された場合にのみ役立ちます。
タスクに明確なキーワードがある場合の高速な最初のパス:
python3 scripts/belief_search.py quick "キーワード"
quick は最初に一致するモジュールを検索し、すぐに analyze を実行します。境界ファイル、依存関係、逆依存関係、レイヤー、違反を一度に取得するために使用します。quick が間違ったモジュールを返した場合や一致しなかった場合は、以下の明示的な search -> analyze フローを使用してください。
ステップ 1 — モジュール ID を見つける:
python3 scripts/belief_search.py search "キーワード"
python3 scripts/belief_search.py entity エンティティ名
search または entity を使用してモジュール ID を見つけてください。モジュール ID は pki-service/src/modules/ca/ca.service のような完全な相対パスであり、ps34 のような短いコードではありません。信念マップは内部で短いパスマップ ID を持つことがありますが、自動的に解決されます — 常に人間が読めるパス形式の文字列を渡してください。モジュール ID を推測したり、でっち上げたりしないでください。常に最初に search で確認してください。
ステップ 2 — モジュールを分析する（必須、オプションではありません）:
python3 scripts/belief_search.py analyze <モジュールID>
analyze は主要コマンドです。境界ファイル、依存関係、逆依存関係、アーキテクチャレイヤー、違反など、完全なコンテキストを返します。ソースを読む前に必ず実行してください。
ステップ 3 — analyze 出力にリストされた境界ファイルのみを読んでください。
ステップ 4 — ディレクトリ全体は読まないでください。 境界が 2〜3 の関連ファイルを示している場合は、それらのファイルのみを読んでください。ディレクトリ内の他のすべては無視します。
コマンドリファレンス
| コマンド | 目的 | 例 |
|---|---|---|
search "<パターン>" | グラフに対する正規表現検索（モジュール ID を探す） | search "operative.*service" |
analyze <id> | モジュールの完全分析（主要コマンド） | analyze drive/modules/drive/drive_schema |
quick <キーワード> | 検索 + 最初の一致を分析（ショートカット） | quick operatives |
boundary <id> | 変更に必要なファイル | boundary operatives.service |
boundary <id> --files-only | ファイルパスのみ（コンパクト） | boundary operatives.service --files-only |
entity <名前> | 定義と参照を検索 | entity DrivePath |
deps <id> [深さ] | 出力依存関係ツリー | deps operatives.service 3 |
rdeps <id> [深さ] | ブラスト半径（これに依存するもの） | rdeps drive_schema 2 |
flow <id> <fn> | 呼び出し/データフローのトレース | flow drive_api fetchFiles |
module <id> | エッジ情報付きの単一モジュール | module operatives.controller |
boundaries [id|all] | アーキテクチャ違反のチェック | boundaries all |
invariants [id|all] | 命名規則違反のチェック | invariants all |
layers | レイヤー別に全モジュールを表示 | layers |
find_function <名前> | 関数/メソッド定義を検索 | find_function createOrder |
find_type <名前> | 型/クラス/インターフェース/列挙型定義を検索 | find_type DriveDbCommitResponse |
find_callchain <src> <tgt> [深さ] | 関数間の呼び出しパスをトレース | find_callchain createOrder processPayment |
find_callers <fn> [深さ] | この関数を呼び出すもの | find_callers handleRequest 3 |
find_calls <fn> [深さ] | この関数が呼び出すもの | find_calls createOrder 2 |
grep_functions <パターン> | ソース内の関数本体を検索 | grep_functions "validate.*input" |
diff_functions [ref] | git 差分で変更された関数 | diff_functions HEAD~3 |
query '<性表現>' | 合成可能な Scheme クエリ | query '(count (boundary "X"))' |
repl | インタラクティブな Scheme REPL | repl |
クイックリファレンス: rg クエリ
高速で対象を絞った検索が必要な場合、Python スクリプトを呼び出さずに、rg で信念マップを直接クエリできます。バンドルされたビルダーは .belief_map.sexp を書き込みます。リポジトリがまだレガシーな belief_map.sexp を使用している場合は、以下のコマンドでそのファイル名に置き換えてください。
# モジュールに関するすべてのファクト
rg 'drive/modules/drive_db/api ' .belief_map.sexp
# モジュールをインポートするもの
rg 'imports .* drive/modules/commons/result' .belief_map.sexp
# モジュールがインポートするもの
rg 'imports drive/modules/drive_db/api' .belief_map.sexp
# エンティティへのすべての参照
rg 'DriveDbCommitResponse' .belief_map.sexp
# リポジトリ内のすべてのクラス
rg '^\(cls drive/' .belief_map.sexp
# データフローエッジ
rg 'data-flow' .belief_map.sexp
これらのワンライナーはクイックチェックに便利です。構造化された出力と完全な分析には、Python スクリプトコマンドを使用してください。
出力記法
すべての出力は、1行に1つの S 式ファクトです。完全なフォーマットは references/sexp-notation.md を参照してください。
主要なパターン:
(boundary <mod> :lang py :file <path> :purpose "<説明>")
(boundary-dep <mod> <dep> :lang ts :file <path> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <path> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <名前> <行> :lang py :file <path>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<理由>")
(result <モジュールまたはパス>)
(result-count 42)
:lang の値: py = Python（snake_case）、ts = TypeScript（camelCase）、tsx = TSX（PascalCase）。
Scheme クエリ言語
複雑な分析のためにクエリを合成します。完全なリファレンスは references/scheme-queries.md を参照してください。
基本:
(boundary "id") ; ターゲット + deps + rdeps（変更境界）
(entity "名前") ; エンティティを定義するモジュール
(deps "id" 深さ) ; 出力依存関係
(rdeps "id" 深さ) ; 逆依存関係
(find-function "名前") ; 一致する関数定義があるモジュール
(find-type "名前") ; 一致する型定義があるモジュール
(find-callers "fn" 深さ) ; 関数を呼び出すモジュール
(find-calls "fn" 深さ) ; 関数が呼び出すモジュール
(intersect A B) ; 集合の積集合
(filter SET "パターン") ; 正規表現フィルター
(files SET) ; ファイルパスに解決
(count SET) ; メンバー数をカウント
(violations) ; 境界違反のあるモジュール
(layer "id") ; モジュールのアーキテクチャレイヤー
分析計画パターン
コードを変更する前に、クエリから計画を構成します:
; 1. スコープ
(boundary "operatives.service")
(count (boundary "operatives.service"))
; 2. アーキテクチャ制約
(violations "operatives.service")
(layer "operatives.service")
; 3. 言語をまたぐ境界
(filter (refs-to "DrivePath") "app-service")
; 4. アクション可能なファイルに絞り込む
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))
; 5. 変更後: 確認
(violations "operatives.service")
トリガー例
以下の場合に、ソースを読む前にこのスキルを使用してください:
- サービス、API、ジョブ、イベント、UI フロー、または障害動作に言及する根本原因調査。
- サービス間またはモジュール間の質問、「X は Y をどのように呼び出すのか？」や「これはどこに保存されているのか？」を含むもの。
- 回答がコード動作に依存する場合の Redmine の明確化。
- アーキテクチャレビュー、影響分析、公開契約の変更、またはブラスト半径チェック。
- 依存関係の方向やモジュールの所有権が重要な、非自明なステージングされた変更のレビュー。
コミットのみのタスク、git-log の要約、手動のデモ/サーバー実行、純粋なブラウザテスト、またはセッションログ分析には使用しないでください。
エラー復旧
コマンドが (error no-match ...) を返した場合:
- 同じ ID で再試行したり、別の ID を推測したりしないでください。
- より広いキーワードで
searchを実行し、正しいモジュール ID を見つけてください。 - 存在する場合は
:suggestionsフィールドを使用してください。類似したモジュール ID がリストされています。
# 間違い: ID を推測する
python3 scripts/belief_search.py analyze ps34 # 失敗: ps34 は短いパスマップ ID
python3 scripts/belief_search.py analyze ca.service # 失敗: 不完全なパス
# 正しい: 最初に検索し、結果から完全なパスを使用する
python3 scripts/belief_search.py search "ca.*service"
# 出力に表示される: pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service
アンチパターン
- モジュール ID を推測すること。 モジュール ID は完全な相対パスです（例：
pki-service/src/modules/ca/ca.service）。ps34のような短いコードは内部的なパスマップ ID であり、直接使用してはいけません。必ず最初にsearchしてください。 - ビルドはするがクエリはしないこと。 信念マップをビルドしても、
search、analyze、boundaryを実行しなければゼロ価値です。 - ソースを読んだ後にクエリすること。 最初のソースコード読み取りは、
analyze出力のboundary-file行から取得する必要があります。 .belief_map.sexpをファイル全体として読むこと。search、analyze、またはrgを使用して特定のファクトをクエリしてください。- モジュール間タスクで信念マップをスキップすること。 ソースファイルを読む前に、常にグラフをクエリして境界を理解してください。
- ディレクトリ内のすべてのファイルを読むこと。 境界が 2〜3 のファイルを示している場合は、それらのファイルのみを読んでください。
- プロジェクトローカルスクリプトを使用すること。 常にこのスキルにバンドルされたスクリプトを使用してください。プロジェクトのコピーは sexp ではなく JSON を出力する可能性があります。
グラフの再ビルド
python3 scripts/build_belief_map.py # 差分ビルド (~5秒)
python3 scripts/build_belief_map.py --full # フルビルド (~30秒)
python3 scripts/build_belief_map.py ./drive # 単一サブリポジトリ
python3 scripts/build_belief_map.py --lsp # LSP 呼び出し階層付き (~1-5分)
構造的な変更（ファイルの追加/削除、インポートの変更、クラスの追加）の後に再ビルドしてください。
インフラストラクチャトポロジー
Kustomize、Helm、Terraform ファイルからサービス・トポロジーを抽出します。このスクリプトには PyYAML が必要です（pip3 install pyyaml）。
python3 scripts/build_infra_topology.py # すべての IaC を自動検出
python3 scripts/build_infra_topology.py --kustomize . # kustomize のみ
python3 scripts/build_infra_topology.py --helm ./charts # helm チャートのみ
python3 scripts/build_infra_topology.py --terraform ./infra # terraform のみ
python3 scripts/build_infra_topology.py --append .belief_map.sexp # グラフにマージ
infra-node、k8s-depends、k8s-service、helm-depends、tf-depends、infra-maps エッジを出力します。以下のようにクエリします:
rg 'infra-node' .belief_map.sexp # すべてのサービス
rg 'k8s-depends' .belief_map.sexp # サービス依存関係
rg 'infra-node.*:component database' .belief_map.sexp # すべてのデータベース
rg 'infra-maps.*app-service' .belief_map.sexp # インフラ -> ソースコードマッピング