diagramming-code

コードの図式化

Trailmark のコードグラフから Mermaid 図を生成します。あらかじめ用意されたスクリプトが Mermaid 構文の生成を処理し、Claude が図の種類とパラメーターを選択します。Trailmark 0.4.0 にはネイティブの trailmark diagram コマンドが含まれています。バージョンとコマンドを確認した後にのみ使用してください。それ以外の場合は、このスキルに同梱されたスクリプトを使用します。

使用する場面

• 関数間の呼び出し経路を可視化する
• クラスの継承階層を描く
• モジュールのインポート依存関係をマッピングする
• メンバーを含むクラス構造を示す
• 色分けによって複雑さのホットスポットを強調する
• エントリーポイントから機密性の高い関数までのデータフローを追跡する

使用しない場面

• 可視化せずにグラフをクエリする（trailmark スキルを使用してください）
• 変異テストのトリアージ（genotoxic スキルを使用してください）
• コードから導出されないアーキテクチャ図（手作業で描いてください）

前提条件

trailmark がインストールされている必要があります。uv run trailmark が失敗する場合は、次を実行してください。

uv tool install trailmark
# Python snippets: uv run --with trailmark python -   (a tool env is not importable)

ソースコードを読んで Mermaid を手書きする方法に絶対に切り替えないでください。このスクリプトは、正確性を確保するために Trailmark の解析済みグラフを使用します。インストールに失敗した場合は、エラーをユーザーに報告してください。

バージョンの確認

ネイティブの v0.4 図対応が利用できるか確認します。

trailmark diagram --help 2>/dev/null || uv run trailmark diagram --help 2>/dev/null

成功した場合は、trailmark diagram を使用できます。失敗した場合は、uv run {baseDir}/scripts/diagram.py を使用してください。これにより、従来のスキルのワークフローをそのまま利用できます。Trailmark 0.2.x にネイティブ CLI があると想定しないでください。

---

クイックスタート

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

# Trailmark 0.4.0+ equivalent after the Version Gate succeeds
uv run trailmark diagram \
    --target {targetDir} --language auto --type call-graph \
    --focus <function> --depth 2

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

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

---

図の種類

├─ "Who calls what?"               → --type call-graph
├─ "Class inheritance?"             → --type class-hierarchy
├─ "Module dependencies?"           → --type module-deps
├─ "Class members and structure?"   → --type containment
├─ "Where is complexity highest?"   → --type complexity
└─ "Path from input to function?"   → --type data-flow

各種類の詳しい例については、references/diagram-types.md を参照してください。

---

ワークフロー

Diagram Progress:
- [ ] Step 1: Verify trailmark is installed
- [ ] Step 2: Identify diagram type from user request
- [ ] Step 3: Determine focus node and parameters
- [ ] Step 4: Run diagram.py script (or native trailmark diagram on v0.4+)
- [ ] Step 5: Verify output is non-empty and well-formed
- [ ] Step 6: Embed diagram in response

ステップ 1： uv run trailmark analyze --language auto --summary {targetDir} を実行します。失敗した場合はインストールしてください。図の作成では engine.preanalysis() を実行しないでください。図のコマンドは独自のグラフを構築し、事前分析データを使用しないため、事前分析の有無によって図の種類が変わることはありません。data-flow では、Trailmark が解析時に記録したエントリーポイントを使用します。

対象の自動検出が誤っている場合は、python,rust のように、言語を明示するかカンマ区切りのリストを指定して再実行してください。

ステップ 2： 上記の判断ツリーを使って、ユーザーの依頼に対応する --type を選びます。

ステップ 3： call-graph と data-flow では、対象となる関数を特定します。--depth 2 がデフォルトです。依存関係のフローには --direction LR を使用してください。

ステップ 4： スクリプトを実行し、標準出力を取得します。 ネイティブの v0.4 CLI が利用できる場合は、どちらのコマンドを使ってもかまいません。このスキルのリファレンスと一貫した動作が必要な場合は、同梱スクリプトを優先してください。

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

ステップ 6： 出力を ```mermaid ``` のコードフェンスで囲みます。

---

スクリプトのリファレンス

uv run {baseDir}/scripts/diagram.py [OPTIONS]
# or, on Trailmark 0.4.0+:
uv run trailmark diagram [OPTIONS]

引数	短縮形	デフォルト	説明
--target	-t	required	解析するディレクトリ
--language	-l	python	ソース言語
--type	-T	required	図の種類（上記を参照）
--focus	-f	none	このノードを中心に図を配置
--depth	-d	2	BFS の走査深度
--direction		TB	レイアウト：TB（上から下）または LR（左から右）
--threshold		10	complexity タイプの最小複雑度

例

# Call graph centered on a function
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T call-graph -f parse_file

# Class hierarchy for a Rust project
uv run {baseDir}/scripts/diagram.py -t src/ -l rust -T class-hierarchy

# Module dependency map, left-to-right
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T module-deps --direction LR

# Class members
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T containment

# Complexity heatmap (threshold 5)
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -T complexity --threshold 5

# Data flow from entrypoints to a specific function
uv run {baseDir}/scripts/diagram.py -t src/ -l auto -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のサニタイズ、エスケープ、スタイル定義、よくある落とし穴