コードのダイアグラミング

Trailmark のコードグラフから Mermaid ダイアグラムを生成します。事前に用意されたスクリプトが Mermaid 構文の生成を処理し、Claude がダイアグラムタイプとパラメータを選択します。

使用場面

• 関数間のコールパスを可視化する
• クラス継承階層を描画する
• モジュール import の依存関係をマッピングする
• メンバーを含むクラス構造を表示する
• 色分けで複雑性のホットスポットを強調する
• エントリーポイントから機密関数へのデータフローをトレースする

使用してはいけない場面

• 可視化なしでグラフにクエリを実行する（trailmark スキルを使用してください）
• ミューテーションテストのトリアージ（genotoxic スキルを使用してください）
• コードから導出されないアーキテクチャダイアグラム（手描きしてください）

前提条件

trailmark がインストールされていることが必須です。uv run trailmark が失敗する場合は、以下を実行してください：

uv pip install trailmark

絶対に ソースコード読み込みから Mermaid を手書きしないでください。スクリプトは Trailmark のパースされたグラフを精度のために使用します。インストールが失敗した場合は、 エラーをユーザーに報告してください。

---

クイックスタート

uv run {baseDir}/scripts/diagram.py \
    --target {targetDir} --language auto --type call-graph \
    --focus main --depth 2

出力は生の Mermaid テキストです。フェンス付きコードブロックでラップしてください：

```mermaid
flowchart TB
    ...
```

---

ダイアグラムタイプ

├─ "何が何を呼び出すか？"           → --type call-graph
├─ "クラス継承？"                   → --type class-hierarchy
├─ "モジュール依存関係？"           → --type module-deps
├─ "クラスメンバーと構造？"         → --type containment
├─ "複雑性が最も高いのはどこ？"     → --type complexity
└─ "入力から関数へのパス？"         → --type data-flow

各タイプの詳細な例については、 references/diagram-types.md を参照してください。

---

ワークフロー

ダイアグラム進捗：
- [ ] ステップ 1: trailmark がインストールされていることを確認
- [ ] ステップ 2: ユーザーリクエストからダイアグラムタイプを特定
- [ ] ステップ 3: フォーカスノードとパラメータを決定
- [ ] ステップ 4: diagram.py スクリプトを実行
- [ ] ステップ 5: 出力が空でなく、形式が正しいことを確認
- [ ] ステップ 6: レスポンスにダイアグラムを埋め込む

ステップ 1: uv run trailmark analyze --language auto --summary {targetDir} を実行してください。失敗した場合はインストールしてください。その後、プログラミング API 経由で事前分析を実行します：

from trailmark.query.api import QueryEngine

engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine.preanalysis()

事前分析は、グラフに blast radius、taint 伝播、および data-flow ダイアグラムで使用される 特権境界データを追加します。

ターゲットに対して自動検出が間違っている場合は、明示的な言語または python,rust などの コンマ区切りリストを使用して再実行してください。

ステップ 2: ユーザーのリクエストを上記のデシジョンツリーを使用して --type にマッチさせます。

ステップ 3: call-graph と data-flow については、フォーカス関数を特定してください。 デフォルト --depth 2。依存関係フローに --direction LR を使用してください。

ステップ 4: スクリプトを実行し、標準出力をキャプチャします。

ステップ 5: 確認：出力は flowchart または classDiagram で始まり、 少なくとも 1 つのノードを含みます。空または形式が違う場合は、 references/mermaid-syntax.md を参照してください。

ステップ 6: 出力を ```mermaid ``` コードフェンスでラップします。

---

スクリプトリファレンス

uv run {baseDir}/scripts/diagram.py [OPTIONS]

引数	短形	デフォルト	説明
--target	-t	必須	分析するディレクトリ
--language	-l	python	ソース言語
--type	-T	必須	ダイアグラムタイプ（上記参照）
--focus	-f	なし	このノードを中心にダイアグラムを作成
--depth	-d	2	BFS トラバーサルの深さ
--direction		TB	レイアウト：TB（上下）または LR（左右）
--threshold		10	complexity タイプの最小複雑性

例

# 関数を中心にしたコールグラフ
uv run {baseDir}/scripts/diagram.py -t src/ -T call-graph -f parse_file

# Rust プロジェクトのクラス階層
uv run {baseDir}/scripts/diagram.py -t src/ -l rust -T class-hierarchy

# モジュール依存マップ、左から右へ
uv run {baseDir}/scripts/diagram.py -t src/ -T module-deps --direction LR

# クラスメンバー
uv run {baseDir}/scripts/diagram.py -t src/ -T containment

# 複雑性ヒートマップ（閾値 5）
uv run {baseDir}/scripts/diagram.py -t src/ -T complexity --threshold 5

# エントリーポイントから特定の関数へのデータフロー
uv run {baseDir}/scripts/diagram.py -t src/ -T data-flow -f execute_query

---

カスタマイズ

方向: 階層ビューには TB（デフォルト）を、依存関係チェーンなどの 左から右へのフローには LR を使用してください。

深さ: --depth を増やすと、より多くのコールグラフが表示されます。 減らすと、クラッタを減らせます。ダイアグラムが 100 ノードを超える場合、 スクリプトは警告を出します。

フォーカス: 重要でないコードベースではない場合は、call-graph に対して 常に --focus を使用してください。data-flow の場合、フォーカスを省略すると 上位 10 の複雑性ホットスポットが自動的にターゲットになります。

言語: ポリグロット または未知のリポジトリでは --language auto を優先してください。 ターゲットが単一言語であることが確実な場合、または関連のないコンポーネントを除外する必要がある場合は、 明示的な言語のみを使用してください。

---

サポートドキュメント

• references/diagram-types.md - 各ダイアグラムタイプの詳細ドキュメントと Mermaid 例
• references/mermaid-syntax.md - ID サニタイゼーション、エスケープ、スタイル定義、および一般的な落とし穴