adr-graph-easy-architect

ADR Graph-Easy アーキテクト

graph-easy を使って、Architecture Decision Record（ADR）用の包括的な ASCII アーキテクチャ図を作成します。自動レイアウトによるテキストのみの出力で、画像のレンダリングは不要です。

自己進化型スキル：このスキルは使用を通じて改善されます。指示が間違っている場合、パラメーターにずれが生じている場合、または回避策が必要だった場合は、後回しにせず、すぐにこのファイルを修正してください。実際に再現可能な問題がある場合にのみ更新してください。

このスキルを使う場面

• アーキテクチャの変更を伴う新しい ADR を作成するとき
• ADR で移行、統合、またはシステムの変更について説明するとき
• ユーザーが決定の視覚的な表現を求めているとき
• 既存の ADR 図をレビューまたは更新するとき

事前確認

図をレンダリングする前に、graph-easy がインストールされ、正常に動作することを確認してください。

セットアップ手順の全文：事前確認セットアップ

簡易確認：

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

---

DSL クイックリファレンス

ノードのスタイル、エッジのスタイル、絵文字のルールを含む構文の全文と例：DSL 構文リファレンス

基本構文

[Node]                          # Node
[A] -> [B]                      # Edge
[A] -- label --> [B]            # Labeled edge
[A] <-> [B]                     # Bidirectional
( Group: [Node A] [Node B] )    # Group/container
[id] { label: "Display"; }     # Custom label

フローの方向（必須）

graph { flow: south; }   # Top-to-bottom (architecture, decisions)
graph { flow: east; }    # Left-to-right (pipelines, sequences)

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

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

正しい例：

graph { label: "🔄 Database Migration"; flow: south; }
[Old DB] -> [New DB]

アンチパターン（無効）：

graph { flow: south; }
[Old DB] -> [New DB]

絵文字付きの label: がありません。事前確認バリデーターは、graph { label: "emoji ..."; } がない図を含む ADR をブロックします。

絵文字の選択（グラフラベル専用。ノード内では使用しないでください）

図の種類	絵文字	図の種類	絵文字
移行／変更	🔄	アーキテクチャ	🏗️
デプロイ／リリース	🚀	ネットワーク／API	🌐
データフロー	📊	ストレージ／データベース	💾
セキュリティ／認証	🔐	モニタリング	📡
エラー／障害	⚠️	フック／イベント	🪝
判断／分岐	🔀	変更前／変更後	⏮️/⏭️

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

スタイル	構文	用途
角丸	{ shape: rounded; }	開始／終了ノード
二重枠	{ border: double; }	重要／強調
太枠	{ border: bold; }	重要なノード
点線の枠	{ border: dotted; }	任意／スキップ可能
実線の矢印	->	メインフロー／正常系
点線の矢印	..>	条件付き／代替
太い矢印	==>	強調／重要
ラベル付きエッジ	-- label -->	注釈付きの接続

文字の安全性

• ノード内のグラフィカルな絵文字：絶対に使用しない（ボックスの位置がずれます）
• ノード内の Unicode 記号（チェックマーク、バツ印、警告）：使用可能（半角幅）
• ノード内の ASCII マーカー（[x] [+] [!]）：常に安全
• graph { label: } 内のグラフィカルな絵文字：使用可能

記号の一覧：等幅フォントで安全な記号

---

よく使われる図のパターン

移行（変更前 -> 変更後）

graph { flow: south; }
[Before] -- migrate --> [After]

複数コンポーネントのシステム

graph { flow: south; }
[A] -> [B] -> [C]
[B] -> [D]

パイプライン（左から右）

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

選択肢のある判断

graph { flow: south; }
[Decision] -> [Option A]
[Decision] -> [Option B]

グループ化されたコンポーネント

( Group:
  [Component 1]
  [Component 2]
)
[External] -> [Component 1]

双方向フロー

[Client] <-> [Server]
[Server] -> [Database]

ADR の種類別の追加パターン：図の例

---

レンダリング

コマンド（必須：常に boxart を使うこと）

graph-easy --as=boxart << 'EOF'
graph { flow: south; }
[A] -> [B] -> [C]
EOF

--as=ascii は使わないでください。きれいな ┌──┐ の線ではなく、見栄えの悪い +--+ のボックスが生成されます。

検証ワークフロー

# 1. Write DSL to heredoc
# 2. Render with boxart
# 3. Review output
# 4. Iterate if needed
# 5. Copy final ASCII to ADR

---

ADR への埋め込み

レンダリングした図にはすべて、graph-easy のソースを含む折りたたみ可能な <details> ブロックを必ず含めてください。書式ガイドの全文と GFM 構文ルール：ADR 埋め込みガイド

必須の形式：

```
┌───────┐     ┌──────┐
│ Build │ --> │ Test │
└───────┘     └──────┘
```

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

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

</details>

<details> ブロックは必須です。ソースなしで図を埋め込まないでください。

---

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

グラフレベル（必須）

• graph { label: "🚀 Title"; } - 意味を表す絵文字＋タイトル（最も忘れられがちです。最初に確認してください！）
• graph { flow: south; } または graph { flow: east; } - 方向を明示
• コマンドでは --as=boxart を使用します。--as=ascii は絶対に使用しないでください

埋め込み（必須・必須条件）

• ソースを含む <details> ブロック - すべての図に、折りたたみ可能なソースコードブロックが必要です
• 形式：レンダリング済みの図を ``` ブロックに記述し、その後にソースを含む <details><summary>graph-easy source</summary> を記述します
• 再現可能なソースを含めずに図をコミットしないでください

ノードのスタイル（視覚的な階層）

• 開始／終了ノード：{ shape: rounded; } - 入り口／出口となるポイント
• 重要／優先度の高いノード：{ border: double; } または { border: bold; }
• 任意／スキップ可能なノード：{ border: dotted; }
• 長いラベルには複数行にするため \n を使用します - 1 行あたり最大約 15 文字

エッジのスタイル（意味）

• メイン／正常系の経路：-> 実線の矢印
• 条件付き／代替の経路：..> 点線の矢印
• 強調／重要な経路：==> 太線の矢印
• エッジラベルは短くします（1～3 語）：-- YES -->、-- error -->

文字の安全性（位置合わせ）

• ノード内に図形絵文字を使用しないでください（位置合わせが崩れます）
• ノード内では Unicode 記号を使用できます（半角幅のもの）
• ASCII マーカーは常に安全です（[x] [+] [!] [OK]）
• 図形絵文字を使用できるのは graph { label: "..."; } のタイトルのみです

構造（整理）

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

成功基準

正確性

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

見た目

1. boxart を使用する - ASCII の +--+ ではなく、きれいな Unicode の線を使用する
2. 視覚的な階層 - 開始／終了は角丸、重要な要素は太線／二重線、任意の要素は点線
3. 一貫したスタイル - 同じ境界線のスタイルは全体を通して同じ意味にする
4. 読みやすいラベル - \n で複数行にし、省略されないようにする
5. 明確な流れ - 自然な読み順（上から下、または左から右）に方向を合わせる

網羅性

1. タイトルに意味を表す絵文字を使用する - 図の目的に合った絵文字を選ぶ
2. 必要に応じて凡例を付ける - 複雑な図では、タイトルを \n で複数行にする
3. エッジの意味 - 実線＝通常、点線＝条件付き、太線＝重要
4. 論理的にグループ化する - 関連するノードを ( Group: ... ) コンテナにまとめる

トラブルシューティング

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

リソース

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

実行後の振り返り

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

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

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