graph-easy

Graph-Easy 図表スキル

graph-easy を使用して、任意の GitHub Flavored Markdown ファイル用に ASCII アーキテクチャ図を作成します。自動レイアウトによるテキストのみの出力で、画像のレンダリングは必要ありません。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある場合、パラメーターが変わっている場合、または回避策が必要だった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合に限り、更新してください。

このスキルを使用する場面

• README ファイルに図を追加する場合
• 設計仕様のドキュメント
• アーキテクチャの可視化が必要な GFM Markdown ファイル
• フローチャート、パイプライン、システム図の作成
• ユーザーが「diagram」、「ASCII diagram」、「graph-easy」、「architecture chart」と言及した場合

ADR には使用しないでください — Architecture Decision Records には adr-graph-easy-architect を使用してください（ADR 固有のパターンである、2 図の必須要件や変更前／変更後のテンプレートが含まれています）。

事前確認

レンダリングの前に、graph-easy がインストールされ、正常に動作することを確認してください。階層型インストールガイド（mise 優先の手順、macOS + Linux）については、事前確認を参照してください。

簡単な確認：

echo "[Test] -> [OK]" | graph-easy &>/dev/null && echo "✓ graph-easy ready"

---

DSL クイックリファレンス

構文の全リファレンス：DSL 構文

基本事項

[Node] -> [Node]              # Basic edge
[A] -- label --> [B]          # Labeled edge
[A] <-> [B]                   # Bidirectional
( Group: [Node A] [Node B] )  # Container
[n] { label: "Display Name"; }  # Custom label

必須のグラフ属性

graph { label: "Title"; flow: south; }   # Top-to-bottom
graph { label: "Title"; flow: east; }    # Left-to-right

• すべての図に、意味を表す絵文字 + タイトルを含む label: が必須です
• すべての図に、明示的な flow: 方向の指定が必須です

文字の安全性

場所	グラフィカルな絵文字	Unicode 記号	ASCII マーカー
ノード内	絶対に使用しない	使用可	常に安全
グラフラベル	安全	使用可	使用可

ASCII マーカー：[x] [+] [!] [OK] [>] [*] [~] [?] [=]

ノードとエッジのスタイル

スタイル	構文	用途
角丸	{ shape: rounded; }	開始／終了ノード
二重枠	{ border: double; }	重要／強調
太枠	{ border: bold; }	重要なノード
点線の枠	{ border: dotted; }	オプション（GH の注意）
実線の矢印	-> / <->	通常／想定どおりの経路
点線の矢印	..>	条件付き／代替経路
太い矢印	==>	クリティカルパス

---

よく使われるパターン

詳しい例（パイプライン、複数コンポーネント、判断、グループ化、双方向、階層型アーキテクチャ）については、図のパターンを参照してください。

簡単なテンプレート：

# Pipeline (left-to-right)
graph { label: "Pipeline"; flow: east; }
[Input] -> [Process] -> [Output]

# Multi-component (top-down)
graph { label: "System"; flow: south; }
[Gateway] -> [Service A]
[Gateway] -> [Service B]
[Service A] -> [Database]
[Service B] -> [Database]

---

レンダリング

コマンド（プラットフォーム対応）

# For GitHub markdown (RECOMMENDED) - renders as solid lines
graph-easy --as=ascii << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

# For terminal/local viewing - prettier Unicode lines
graph-easy --as=boxart << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

出力モード

モード	コマンド	使用場面
ascii	--as=ascii	GitHub Markdown - +--+ はどこでも実線としてレンダリングされます
boxart	--as=boxart	ターミナルのみ - ┌──┐ はローカルでは見栄えがよく、GitHub では点線になります

GitHub ではなぜ ASCII なのですか？ GitHub では Unicode の罫線文字（┌─┐│└─┘）が点線としてレンダリングされます。純粋な ASCII（+---+、|）はどこでも正しくレンダリングされます。

生成後の配置検証（推奨）

埋め込み後、次を使用して検証してください：Skill(doc-tools:ascii-diagram-validator)

• コピー＆ペーストによる配置のずれや、フォントのレンダリングに関する問題を検出します
• 図を生成したばかりで、手動編集していない場合は省略してください

---

Markdown への埋め込み

GFM の折りたたみ可能なセクション構文を含む完全なガイド：埋め込みガイド

重要：すべての図に <details> のソースブロックを含める必要があります。これは必須です。

## Architecture

```
+----------+     +----------+     +----------+
|  Input   | --> | Process  | --> |  Output  |
+----------+     +----------+     +----------+
```

<details>
<summary>graph-easy source</summary>

```
graph { flow: east; }
[Input] -> [Process] -> [Output]
```

</details>

---

等幅フォントで安全な記号

全リファレンス：等幅フォント用の記号

主なマーカー：[+] 追加 | [x] 削除 | [*] 変更 | [!] 警告 | [>] アクティブ

---

グラフラベル（必須：すべての図に絵文字とタイトルを付ける）

警告：これは最もよく忘れられる要件です。ラベルのない図は無効です。

正しい例

graph { label: "Deployment Pipeline"; flow: east; }
[Build] -> [Test] -> [Deploy]

アンチパターン（無効・絶対に行わないでください）

graph { flow: east; }
[Build] -> [Test] -> [Deploy]

これが誤りである理由：絵文字を含む label: がありません。すべての図に、ひと目でわかるコンテキストが必要です。

---

必須チェックリスト（レンダリング前）

グラフレベル（必須）

• graph { label: "Title"; } - 意味を表す絵文字とタイトル（最も忘れられやすい項目です。最初に確認してください！）
• graph { flow: south; } または graph { flow: east; } - 明示的な方向
• GitHub Markdown ではコマンドに --as=ascii を使用（ターミナルのみの場合は --as=boxart）

埋め込み（必須・妥協不可）

• ソースを含む <details> ブロック - すべての図に、折りたたみ可能なソースコードブロックが必須です
• 再現可能なソースなしで図をコミットしないでください

埋め込み後の検証（推奨）

• 図を埋め込んだ後、ファイルに対して ascii-diagram-validator を実行します
• 生成後に手動で図を編集した場合は、特に重要です

ノードとエッジのスタイル

• 開始／終了：{ shape: rounded; } | 重要：{ border: double; } | 任意：{ border: dotted; }
• メインパス：-> | 条件付き：..> | 重要：==> | ラベル：1～3語
• ノード内に図形の絵文字を使用しないでください。絵文字は graph { label: "..."; } 内でのみ使用します

構造

• 関連するノードが4つ以上ある場合はグループ ( Name: ... ) を使用します
• ノード ID は短く、ラベルは説明的にします：[db] { label: "PostgreSQL"; }
• 図あたりのノード数は最大7～10個にします（多い場合は分割します）

成功基準

正確性

1. エラーなしで解析できる - graph-easy が DSL を受け付ける
2. きれいにレンダリングされる - ボックスのずれや線の途切れがない
3. 内容と一致する - 説明にある重要な要素がすべて表現されている
4. ソースが保持されている（必須） - すべての図に graph-easy DSL のソースを含む <details> ブロックが必須です

見た目

1. プラットフォームに適した出力 - GitHub では --as=ascii、ターミナルでは --as=boxart
2. 読みやすいラベル - \n を使った複数行とし、省略されないようにします
3. 明確な流れ - 自然な読み方（上から下、または左から右）に合った方向
4. 一貫したスタイル - 同じボーダースタイルは、全体を通して同じ意味を表します

網羅性

1. エッジの意味 - 実線＝通常、点線＝条件付き、太線＝重要
2. 論理的なグループ化 - 関連するノードを ( Group: ... ) コンテナにまとめます

トラブルシューティング

問題	原因	解決策
command not found	graph-easy が未インストール	事前チェックを実行します
GH で点線になる	--as=boxart を使用した	GitHub Markdown では --as=ascii を使用します
ボックスの枠が崩れる	ノードに図形の絵文字がある	絵文字を削除し、ASCII マーカー [x][+] を使用します
ノードが重なる	複雑すぎる	複数の図に分割します（最大7～10ノード）
エッジラベルが切れる	ラベルが長すぎる	1～3語に短縮します
タイトルが表示されない	構文が正しくない	graph { label: "Title"; flow: south; } を使用します
レイアウトがおかしい	flow の方向が指定されていない	graph { flow: south; } または flow: east を追加します
解析エラー	ノード内の特殊文字	ノード名をエスケープするか、簡潔にします

リソース

• CPAN の Graph::Easy
• Graph::Easy マニュアル
• GitHub の Graph::Easy

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功していない場合は、失敗の原因となった手順またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して一致させます。
3. 回避策が必要でしたか？ — 別のフラグや追加手順など、その場で工夫する必要があった場合は、次回の実行で同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測で更新しないでください。