codespaces

Codespaces -- Belief Map アーキテクチャの調査

ソースファイルを読む前に、.belief_map.sexp をクエリしてモジュール、境界、依存関係を確認してください。コードをむやみに読むのは避け、まずグラフをクエリしてください。

スクリプト

このスキルには Python スクリプトが含まれています。実行する前にスキルと対象のルートを特定し、スキャン対象のプロジェクトを必ず明示してください。

• scripts/belief_search.py -- Belief Map グラフをクエリします
• scripts/build_belief_map.py -- ソースから Belief Map を生成します
• scripts/build_infra_topology.py -- Kustomize、Helm、Terraform のトポロジー情報を抽出します
• scripts/git_descendants.py -- HEAD（または指定した参照）から派生したすべてのコミットを見つけます

プロジェクト内にあるこれらのスクリプトのコピーは使用しないでください。古くなっている可能性があり、sexp ではなく JSON を出力することがあります。

前提条件

Belief Map の場所を確認してください。存在しない場合は、生成します。

ls .belief_map.sexp belief_map.sexp 2>/dev/null
SKILL_ROOT="$(pwd -P)"
TARGET_ROOT="$(cd /absolute/path/to/project && pwd -P)"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT" --full

Python のインデックス作成には、外部パーサーへの依存はありません。検出されたその他の言語では、パーサーが存在しないか、バージョンが異なる場合、最初のビルドは公開前に失敗し、言語ごとに実行すべき正確なコマンドを表示します。たとえば、次のようになります。

python3 -m pip install -r "$SKILL_ROOT/requirements/typescript.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/csharp.txt"
python3 -m pip install -r "$SKILL_ROOT/requirements/ruby.txt"

ビルダーが指定した要件ファイルのみをインストールしてから、再度実行してください。 requirements.txt は、インフラストラクチャトポロジーの依存関係専用です。

必須のワークフロー：コードを読む前にクエリする

重要なコード作業では、rg、find、sed、cat、nl を実行したり、ディレクトリを開いたり、ソースファイルを読んだりする前に、Belief Map のクエリを実行してください。このスキルは、ソースを確認した後の裏付けとしてではなく、最初の範囲特定ステップとして使うことで効果を発揮します。

タスクのキーワードが明確な場合の、最初の簡易確認：

python3 scripts/belief_search.py quick "keyword"

quick は最初に一致したモジュールを検索し、ただちに analyze を実行します。境界ファイル、依存関係、逆依存関係、レイヤー、違反を一度に確認するために使ってください。quick が誤ったモジュールを返した場合、または一致するものがない場合は、以下の明示的な search → analyze の流れを使ってください。

ステップ 1 -- モジュール ID を見つける：

python3 scripts/belief_search.py search "keyword"
python3 scripts/belief_search.py entity EntityName

search または entity を使ってモジュール ID を特定します。モジュール ID は pki-service/src/modules/ca/ca.service のような相対パス全体であり、ps34 のような短いコードではありません。Belief Map 内部には短いパスマップ ID が含まれる場合がありますが、自動的に解決されます。常に人が読めるパス形式の文字列を渡してください。モジュール ID を推測したり、作り出したりしないでください。必ず先に search で確認してください。

ステップ 2 -- モジュールを分析する（任意ではなく、必ずすぐに実行）：

python3 scripts/belief_search.py analyze <module-id>

analyze は主要なコマンドです。境界ファイル、依存関係、逆依存関係、アーキテクチャレイヤー、違反など、全コンテキストを返します。ソースを読む前に、必ず実行してください。

ステップ 3 -- analyze の出力に示された境界ファイルのみを読む。

ステップ 4 -- ディレクトリ全体を読まない。 境界に関連ファイルが 2～3 個示されている場合は、そのファイルのみを読んでください。ディレクトリ内のその他のファイルは無視してください。

コマンドリファレンス

コマンド	目的	例
search "<pattern>"	グラフを安全にリテラル／.* 検索します	search "operative.*service"
analyze <id>	モジュールを完全に分析します（主要コマンド）	analyze drive/modules/drive/drive_schema
quick <keyword>	検索して最初の一致を分析します（ショートカット）	quick operatives
boundary <id>	変更時に読み込むファイルを表示します	boundary operatives.service
boundary <id> --files-only	ファイルパスのみを表示します（コンパクト）	boundary operatives.service --files-only
entity <Name>	定義と参照を検索します	entity DrivePath
deps <id> [depth]	出力依存関係ツリーを表示します	deps operatives.service 3
rdeps <id> [depth]	影響範囲を表示します（これに依存するもの）	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 <name>	関数／メソッドの定義を検索します	find_function createOrder
find_type <name>	型／クラス／モジュール／インターフェース／列挙型の定義を検索します	find_type DriveDbCommitResponse
find_callchain <src> <tgt> [depth]	関数間の呼び出し経路を追跡します	find_callchain createOrder processPayment
find_callers <fn> [depth]	この関数を呼び出す関数を表示します	find_callers handleRequest 3
find_calls <fn> [depth]	この関数が呼び出す関数を表示します	find_calls createOrder 2
grep_functions <pattern>	ソース内の関数本体を検索します	grep_functions "validate.*input"
diff_functions [ref]	git diffで変更された関数を表示します	diff_functions HEAD~3
query '<sexp>'	Schemeクエリを組み合わせて実行します	query '(count (boundary "X"))'
repl	対話型Scheme REPL	repl

クイックリファレンス：rgクエリ

Pythonスクリプトを実行せずに、すばやく対象を絞って検索するには、rgでbelief mapを直接検索します。同梱のビルダーは.belief_map.sexpを書き込みます。リポジトリで従来のbelief_map.sexpを使用している場合は、以下のコマンドでファイル名を置き換えてください。

# All facts about a module
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# Who imports a module
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# What does a module import
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# All references to an entity
rg 'DriveDbCommitResponse' .belief_map.sexp

# All classes in a repo
rg '^\(cls drive/' .belief_map.sexp

# Data flow edges
rg 'data-flow' .belief_map.sexp

これらのワンライナーは簡単な確認に便利です。構造化された出力と完全な分析には、Pythonスクリプトのコマンドを使用してください。

出力表記

すべての出力はS式のファクトで、1行につき1つです。形式の詳細はreferences/sexp-notation.mdを参照してください。

主なパターン：

(boundary <mod> :lang py :file <path> :purpose "<desc>")
(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> <Name> <line> :lang py :file <path>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<reason>")
(result <module-or-path>)
(result-count 42)

:langの値：py = Python（snake_case）、ts = TypeScript（camelCase）、tsx = TSX（PascalCase）、rs = Rust（snake_case）、cs = C#、java = Java、go = Go、rb = Ruby/Railsです。

Schemeクエリ言語

複雑な分析のためにクエリを組み合わせます。詳細なリファレンスはreferences/scheme-queries.mdを参照してください。

基本：

(boundary "id")                ; target + deps + rdeps (change boundary)
(entity "Name")                ; modules defining entity
(deps "id" depth)              ; outgoing dependencies
(rdeps "id" depth)             ; reverse dependencies
(find-function "name")         ; modules with matching function defs
(find-type "name")             ; modules with matching type defs
(find-callers "fn" depth)      ; modules calling a function
(find-calls "fn" depth)        ; modules a function calls
(intersect A B)                ; set intersection
(filter SET "pattern")         ; safe literal/.* filter
(files SET)                    ; resolve to file paths
(count SET)                    ; count members
(violations)                   ; modules with boundary violations
(layer "id")                   ; architecture layer of a module

分析計画のパターン

コードを変更する前に、クエリから計画を組み立てます。

; 1. Scope
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. Architecture constraints
(violations "operatives.service")
(layer "operatives.service")

; 3. Cross-language boundaries
(filter (refs-to "DrivePath") "app-service")

; 4. Narrow to actionable files
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. After changes: verify
(violations "operatives.service")

使用例

次の内容をソースから読み取る前に、このスキルを使用してください。

• サービス、API、ジョブ、イベント、UIフロー、または不具合のある動作に言及する根本原因の調査。
• 「XはどのようにYを呼び出すのか？」「これはどこに保存されているのか？」など、サービス間またはモジュール間に関する質問。
• 回答がコードの動作に左右されるRedmineでの確認。
• アーキテクチャレビュー、影響分析、公開コントラクトの変更、または影響範囲の確認。
• 依存関係の方向やモジュールの所有権が重要となる、複雑なステージ済み変更のレビュー。

コミットのみのタスク、git-logの要約、手動でのデモ／サーバー実行、ブラウザーのみのテスト、またはセッションログの分析には、無理に使用しないでください。

エラーからの復旧

コマンドが(error no-match ...)を返した場合：

1. 同じIDで再試行したり、別のIDを推測したりしないでください
2. より広いキーワードでsearchを実行し、正しいモジュールIDを見つけてください
3. :suggestionsフィールドがある場合は使用してください。類似するモジュールIDが一覧表示されます

# Wrong: guessing IDs
python3 scripts/belief_search.py analyze ps34        # fails: ps34 is a short path-map ID
python3 scripts/belief_search.py analyze ca.service  # fails: incomplete path

# Right: search first, then use the full path from results
python3 scripts/belief_search.py search "ca.*service"
# Output shows: 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 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT" --full
python3 "$SKILL_ROOT/scripts/build_belief_map.py" --root "$TARGET_ROOT" --lsp
python3 "$SKILL_ROOT/scripts/build_belief_map.py" \
  --root "$TARGET_ROOT" --output "$TARGET_ROOT/custom-map.sexp"
python3 "$SKILL_ROOT/scripts/build_belief_map.py" \
  --root "$TARGET_ROOT" --exclude-dir review-bundles

追跡対象のスナップショット、生成されたフィクスチャ、その他、稼働中の製品ではないソース形式のツリーには、--exclude-dir NAME オプションを繰り返し指定してください。各値はディレクトリのベース名で、深さを問わず適用されます。除外設定を変更すると増分キャッシュは無効になり、以前のビルドで除外対象のファイルが混入することはありません。

Git ワークツリー内のターゲットには、Git のリポジトリ除外ルールも適用されます。同じ解決済みポリシーで、ソースファイル、TypeScript のエイリアスとパッケージ、Go と Rust のパッケージマニフェスト、Ruby のプロジェクト設定、LSP のプロジェクト検出がフィルタリングされます。Git のインデックスチェックを無効にして呼び出すため、.gitignore に一致する追跡対象のスナップショットパスは、信念マップから引き続き除外されます。

構造を変更した後（ファイルの追加・削除、インポートの変更、クラスの追加など）は再構築してください。検索パターンでは、リテラル、.*、境界アンカー ^／$、バックスラッシュによるエスケープをサポートします。それ以外の正規表現演算子は拒否されます。

TypeScript AST の契約では、TS／TSX のインポートと再エクスポート、リテラル形式の import()／require()、import = require()、リテラルのテンプレートインポート、出力される .js／.jsx の指定子、プロジェクトスコープのパスエイリアス、慣例的な完全一致の自己インポートを対象としています。継承した tsconfig のエイリアス、baseUrl のみの解決、パッケージの source／exports、自己パッケージのエクスポートサブパスは保証されません。

C# のインデックス作成では、名前空間と参照されるローカル型を追跡します。Java のインデックス作成では、パッケージ、明示的なインポート、参照されるワイルドカード型を追跡します。使用されていない名前空間やワイルドカードのインポートから、推測によるエッジが作成されることはありません。Go のインデックス作成では、ローカルモジュールのインポートを、インポートされたパッケージを構成するソースファイルに解決します。標準的な .NET の bin／obj 出力と Go の vendor 依存関係は除外されます。

Ruby のインデックス作成では、.rb と .rake ファイルを検出し、明示的な require、ローカル定数、Rails アプリケーションのルート、静的に設定された autoload ルート、プロジェクトの略語、concerns、関連付け、コールバック、ジョブ、メーラー、spec 参照を解決します。Rails を起動することはありません。再オープンされた定数や、その他の曖昧な定数、多態的な関連付けは、推測によるエッジを作成せず、リンクされないままになります。Rails のリレーションフラグは、生成されるマップ内で :association、:concern、:callback、:job、:mailer、:spec として保持されます。

Pascal のインデックス作成では、.pas、.pp、.lpr、.inc ファイルを検出します。unit、program、uses／contains／requires 句、include ディレクティブ、クラス、レコード、インターフェース、継承、メソッド、ルーチンを抽出します。unit 名とパスは大文字と小文字を区別せずに解決されます。明示的な UnitName in 'path.pas' パスが優先され、次にインポート元ファイルのディレクトリ内にある一意の unit が使用されます。それ以外の曖昧な unit 名はリンクされないままになります。条件付きコンパイラ分岐は保守的にインデックス化されます。Pascal はまだ LSP の補完に対応していません。慣例的な Lazarus の backup/ ディレクトリ内にある Pascal ファイルは除外されますが、その名前のディレクトリにある他の対応言語はインデックス化できます。

インフラストラクチャのトポロジー

Kustomize、Helm、Terraform ファイルからサービスのトポロジーを抽出します。このスクリプトには PyYAML が必要です（pip3 install pyyaml）。

python3 scripts/build_infra_topology.py                    # auto-detect all IaC
python3 scripts/build_infra_topology.py --kustomize .      # kustomize only
python3 scripts/build_infra_topology.py --helm ./charts    # helm charts only
python3 scripts/build_infra_topology.py --terraform ./infra # terraform only
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # merge into graph

infra-node、k8s-depends、k8s-service、helm-depends、tf-depends、infra-maps のエッジを出力します。次のようにクエリします。

rg 'infra-node' .belief_map.sexp                  # all services
rg 'k8s-depends' .belief_map.sexp                 # service dependencies
rg 'infra-node.*:component database' .belief_map.sexp  # all databases
rg 'infra-maps.*app-service' .belief_map.sexp     # infra -> source code mapping