グラレコ
はじめに
AI に構成図を描かせると、たいてい2つのどちらかになります。Mermaid の自動レイアウトそのままで、ノードが等間隔に並んだ味気ない図。あるいは、それっぽく作り込まれているのに、よく見ると矢印がノードを貫通していたりラベルが線と重なっていたりする図です。
この記事で紹介するのは、その両方を別々のやり方で改善している2つのプラグインです。
- diagram-design — 39種類の図を、編集デザインの規律に従って描かせる。削ることを最優先する設計
- archify — 型付き JSON から図を生成し、幾何的に検証してから納品する設計
どちらも AI エージェント（Claude Code、Cursor、Codex など）に導入して使うもので、無料・MIT ライセンスです。
この記事で扱う内容です。
- 🤔 AI の図が「なんか違う」ことの正体
- 📐 diagram-design の設計思想（削除・4px グリッド・複雑度予算）
- 🎨 セマンティックトークンによるブランド適用
- 🔍 archify の検証ループを実際に回した記録
- 🧾 SHA-256 レシートと Architecture Delta
- ⚖️ 2つの比較と、どちらをいつ使うか
- ⚠️ 日本語まわりの制限（正直に書きます）
⚠️ 本記事は 2026年8月27日時点の情報です。 検証はすべて筆者の macOS 環境（Node v26.7.0 / Python 3.14.6）で実際に実行し、出力をそのまま引用しています。diagram-design は v2.6.5、archify は v2.16 を使いました。
🤔 AI の図が「なんか違う」ことの正体
まず、何が起きているのかを整理します。
AI に「この構成を図にして」と頼んだとき、多くの場合 Mermaid が出てきます。Mermaid は手軽ですが、レイアウトはレンダラーが自動で決めます。つまり どのノードをどこに置くかという判断が、誰もしていないわけです。
結果として、こういうことが起きます。
より作り込んだ SVG を書かせると、今度は別の問題が出ます。AI は座標を計算しながら図を組み立てますが、出来上がったものが幾何的に正しいかを誰も検証していません。矢印が無関係なノードを横切っていても、ラベルが別の線と重なっていても、そのまま出てきます。
2つのプラグインは、この2つの問題にそれぞれ違う角度から手を入れています。
📐 diagram-design — 「最高の一手はたいてい削除」
diagram-design は Cathryn Lavery さんが公開している Claude Code プラグインです。作者の言葉を借りると「デザイナーが嫌がらない編集デザイン風の図」を目指しています。
導入
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
Codex、Factory Droid、Pi にも対応しています。実際、リポジトリには .claude-plugin/ .codex-plugin/ .factory-plugin/ .agents/ の4つの定義ディレクトリが入っていて、1つのリポジトリで複数のホストをカバーしています。
設計思想
同梱の SKILL.md の冒頭に、こう書いてあります。
The highest-quality move is usually deletion.
（最も質の高い一手は、たいてい削除である）
これが図に適用されると、次のようになります。
- 常に一緒に動く2つのノードは、1つのノードである
- レイアウトから関係が自明なら、線を消す
- アクセント色は editorial であって flag ではない。1つの図に1〜2要素まで
- 図は「すべてを足したとき」ではなく「何も削れなくなったとき」に完成する
目標密度は 4/10 と明記されています。技術的に完全であるには十分だが、説明書が要るほど濃くはない、というラインです。
複雑度予算という発想
面白いのは、これが精神論ではなく数値の上限になっていることです。
| 制限 | 値 |
|---|---|
| 最大ノード数 | 9 |
| 最大矢印数 | 12 |
| 最大アクセント要素 | 2 |
| 最大ライフライン（シーケンス） | 5 |
| 最大レーン（スイムレーン） | 5 |
| 最大エンティティ（ER） | 8 |
| ツリー最大深さ | 4 |
| ベン図の最大円 | 3 |
9ノードを超えたら、それはたぶん2つの図です — というのがルールです。上限を超えそうなときは、概要図と詳細図に分割することになります。
さらに 4px グリッドが課されます。
All values — font sizes, padding, node dimensions, gaps, x/y coords — divisible by 4. Non-negotiable.
| カテゴリ | 許可される値 |
|---|---|
| フォントサイズ | 8, 12, 16, 20, 24, 28, 32, 40 |
| ノード幅・高さ | 80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320 |
| 座標 | 4の倍数 |
| ノード間ギャップ | 20, 24, 32, 40, 48 |
| 角丸 | 4, 6, 8 |
チェック方法まで書かれています。「座標が 1, 2, 3, 5, 6, 7, 9 で終わっていたら直せ」。
例外は線幅（0.8 / 1 / 1.2）と不透明度、そして 22×22 のドットパターンだけです。
アンチパターンの明文化
個人的にいちばん実用的だと思ったのが、この表です。「どの図種であれ、AI スロップに見える特徴」として列挙されています。
| アンチパターン | なぜダメか |
|---|---|
| ダークモード + シアン/紫のグロー | デザイン判断なしに「技術的」に見せているだけ |
| JetBrains Mono を「開発者フォント」として全面採用 | モノスペースは技術的内容（ポート・コマンド・URL）専用。名前はサンセリフで |
| すべてのノードが同じ箱 | 階層が消える |
| 凡例が図の内側に浮いている | ノードと衝突する |
| 矢印ラベルにマスク矩形がない | 線が透けて読めなくなる |
| 矢印上の縦書きテキスト | 読めない |
| 等幅3枚のサマリーカードを既定にする | 汎用グリッドに見える。幅に変化をつける |
| 任意の要素へのシャドウ | シャドウは終わった。ボーダーを使う |
rounded-2xl |
角丸は最大6〜10px か、なし |
| 5つのノードにアクセント色 | アクセントは1〜2の editorial な焦点。シグナリング機構ではない |
| Mermaid のレンダラーレイアウトの再現 | 自動間隔・自動ルーティングをそのまま持ち込んでしまう |
心当たりがある項目がいくつかありました（特に「等幅3枚のカード」は、私が AI に作らせるスライドで毎回出てきます）。
39の図種
対応している図種の多さも特徴です。
アーキテクチャ図やフローチャートは想像どおりとして、Wardley マップ、特性要因図（フィッシュボーン）、メダリオンアーキテクチャ、DP security matrix あたりまで揃っているのは珍しいと思います。
セマンティックトークンとブランド適用
色は直接指定するのではなく、**役割（セマンティックロール）**で参照します。
| ロール | 用途 | 既定（ライト） | 既定（ダーク） |
|---|---|---|---|
paper |
背景・既定のノード塗り | #f5f5f5 |
#2d3142 |
ink |
主要テキスト・線 | #2d3142 |
#f5f5f5 |
muted |
副次テキスト・既定の矢印 | #4f5d75 |
#bfc0c0 |
soft |
サブラベル・境界ラベル | #7a8399 |
#8e98ac |
rule |
ヘアライン | rgba(45,49,66,0.12) |
rgba(245,245,245,0.12) |
accent |
焦点（1図に1〜2） | #eb6c36 |
#f08a59 |
link |
HTTP/API・外部矢印 | #2e5aa8 |
#6a95d8 |
型別のリファレンスは #f7591f ではなく accent と書きます。だから style-guide.md の1ファイルを差し替えるだけで、すべての図種の見た目が変わります。
ブランド適用はサイト URL から自動でできます。
あなた: 「diagram-design を https://yoursite.com に onboard して」
エージェント: → トップページを取得
→ 主要な配色とフォントスタックを抽出
→ paper / ink / muted / accent / link にマッピング
→ 差分を提示
→ references/style-guide.md に書き込む
複数のクライアントを持つ場合は、~/.diagram-design/profiles/ にプロファイルを保存して、プロジェクトルートの .diagram-design マーカーファイルで切り替えられます。
描く前に宣言させる
もう1つ、地味に効く仕組みがあります。レンダリング前に、選んだ図種・サイズ・複雑度予算で落とすものを1メッセージで宣言するというルールです。
ユーザーが反応できる状況なら、描き始める前に軌道修正できます。図を1枚作らせてから「違う」と言うより、はるかに速く終わります。
新規プロジェクトで最初の1枚を描く前には、スタイルガイドが既定のままかを確認して、ブランド適用するかどうかを聞いてきます。既定のオレンジ（atomic-tangerine）のまま社内資料に混ぜてしまう事故を防ぐためです。
実際に描いてみます
後で archify と並べて比べたいので、同じ「社内ナレッジ検索の構成」を描かせました。既定スキンのままです。
まず、描き始める前にこう宣言してきます。
型: Architecture / サイズ: doc-wide (1000x484)
予算: 6ノード（上限9）/ 5矢印（上限12）/ アクセント2要素（上限2）
落とすもの: なし（この内容は予算内に収まる）
そのうえで出てきたのがこちらです。
SKILL.md のルールがそのまま形になっているのが分かります。
-
アクセント（コーラル）は2要素だけ — 焦点の「検索API」と、主要フローの矢印。他はすべて
ink/muted - 凡例は図の外の横帯 — 中に浮かせない
-
矢印ラベルは白マスク付きで、線から離れている —
RESTや権限フィルタが線に乗っていません - ノードごとに塗りが違う — 外部は薄いスレート、フロントは白、ストアは2%のインク、セキュリティは破線
- 角丸は6px、シャドウなし
- ノード名は Geist サンセリフ、
Next.jsやpgvectorのような技術的な値だけ Geist Mono
このHTMLは同梱の検証スクリプトにも通しました。
python3 scripts/self_check.py dd-knowledge-search.html
# OK
python3 scripts/verify-geometry.py dd-knowledge-search.html
# Summary: 1 file(s) checked, 0 finding(s).
verify-geometry.py は「後から描かれるノードにラベルのマスクが重なっていないか」を検査するスクリプトです。SVG の描画順は「背景 → ゾーン → 矢印 → ラベル → ノード」に固定されているので、マスクがノードに飲み込まれると文字が欠けます。それを機械が拾います。
🔍 archify — 描いてから検証する
archify は tt-a1i さんが公開している Agent Skill です。アプローチがかなり違います。
導入
npx skills add tt-a1i/archify -g
Cursor 専用なら次のとおりです。
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes
インストールせずに試すこともできます。
npx skills use tt-a1i/archify@archify --agent codex
私の環境では ~/.agents/skills/archify/ に実体が入り、~/.claude/skills/archify からシンボリックリンクが張られていました。diagram-design がプラグインとして入るのに対し、archify はスキルとして入るという違いがあります。片方はプラグイン、片方はスキルなので、両方入れても衝突しません。
まず動作確認です。
node bin/archify.mjs doctor
実行結果です。
Archify doctor
[ok] Node.js v26.7.0 (requires >=18)
[ok] Core template
[ok] Example renderer
[ok] Live preview runtime
[ok] Visual-check runtime
[ok] Output path safety runtime
[ok] Scenario recipe guide
[ok] Progressive authoring references
[ok] Architecture compare runtime and proof fixtures
[ok] Standalone schema validators
[ok] architecture renderer, schema, and example
[ok] workflow renderer, schema, and example
[ok] sequence renderer, schema, and example
[ok] dataflow renderer, schema, and example
[ok] lifecycle renderer, schema, and example
Archify is ready.
Node.js 18 以上が要件で、それ以外の依存はありません。
5つの型
diagram-design が39種類あるのに対して、archify は5つに絞っています。
| type | 用途 |
|---|---|
architecture |
コンポーネント、サービス、クラウド/セキュリティ境界、インフラ |
workflow |
プロセス、承認ゲート、ツール呼び出し、ランブック、CI/CD |
sequence |
API 呼び出し連鎖、リクエストライフサイクル、非同期トレース |
dataflow |
パイプライン、ETL/ELT、リネージ、ガバナンス、コンシューマ |
lifecycle |
状態遷移、リトライ、待機・終端状態 |
迷ったときは guide コマンドが推薦してくれます。
Artifact first という規律
SKILL.md の作成手順に、変わった指示があります。
最初の候補を書く前に、
renderers/shared/geometry.mjs、レンダラーのソース、バリデータのソース、テスト、ベンチマークを読んではならない。
つまり AI に「調べてから描く」のを禁止しています。代わりにこうです。
Artifact first: 次のツール操作で候補を書くこと。レンダラー内部を調べる前に候補を書くこと。正確な座標を散文で計画しないこと。
読み込んでいいのは、該当する型のスキーマ1つと、該当する例1つだけ。しかも「例はフィールドの形を知るために読むのであって、事実をコピーするために読むのではない」と釘を刺されています。
AI に図を描かせたことがある人なら、この判断の意味がわかると思います。放っておくと AI は延々と内部実装を調べ、座標を文章で計画し、それでいて最初の1枚は結局ずれています。だったら先に1枚書いて、機械に検証させたほうが速い、という設計です。
実際に描いてみます
手で40行ほどの JSON を書きました。社内ナレッジ検索の構成図です。
{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "社内ナレッジ検索の構成",
"output": "demo.html",
"quality_profile": "showcase"
},
"components": [
{ "id": "user", "type": "external", "label": "社員", "sublabel": "Browser", "pos": [40, 300], "size": [120, 60] },
{ "id": "web", "type": "frontend", "label": "検索UI", "sublabel": "Next.js", "pos": [220, 300], "size": [140, 60] },
{ "id": "api", "type": "backend", "label": "検索API", "sublabel": "FastAPI", "pos": [420, 300], "size": [140, 60], "variant": "emphasis" },
{ "id": "auth", "type": "security", "label": "認証", "sublabel": "OIDC", "pos": [420, 160], "size": [140, 60] },
{ "id": "vector", "type": "database", "label": "ベクトルDB", "sublabel": "pgvector", "pos": [640, 380], "size": [140, 60] },
{ "id": "meta", "type": "database", "label": "メタデータDB", "sublabel": "PostgreSQL", "pos": [640, 220], "size": [140, 60] }
],
"boundaries": [
{ "kind": "region", "label": "社内VPC", "wraps": ["api", "auth", "vector", "meta"] }
],
"connections": [
{ "id": "c1", "from": "user", "to": "web", "label": "HTTPS", "variant": "emphasis" },
{ "id": "c2", "from": "web", "to": "api", "label": "REST" },
{ "id": "c3", "from": "api", "to": "auth", "label": "トークン検証" },
{ "id": "c4", "from": "api", "to": "vector", "label": "類似検索" },
{ "id": "c5", "from": "api", "to": "meta", "label": "権限フィルタ" }
],
"cards": [
{ "dot": "cyan", "title": "入口", "items": ["社員はブラウザからのみ到達", "UIは検索と結果表示だけを担当"] },
{ "dot": "emerald", "title": "検索", "items": ["APIがベクトル検索を実行", "メタデータで閲覧権限を絞る"] },
{ "dot": "rose", "title": "境界", "items": ["DBはVPC内に閉じる", "認証はOIDCで一元化"] }
]
}
検証します。
node bin/archify.mjs validate architecture demo.architecture.json --quality showcase --json
1回目は落ちました。
{
"ok": false,
"error": "architecture schema validation failed:\n /components/2 (id/label: \"api\") must NOT have additional properties {\"additionalProperty\":\"variant\"}",
"diagnostics": [{
"code": "schema/additionalProperties",
"severity": "error",
"subject": { "path": "/components/2", "identity": "api" },
"evidence": { "keyword": "additionalProperties", "additionalProperty": "variant" },
"supportedFixes": ["remove unsupported property \"variant\""]
}]
}
variant は connections には使えるのに components には使えませんでした。私の書き間違いです。
注目したいのは診断の中身です。どのパス（/components/2）の、どの要素（api）が、なぜ（additionalProperties）ダメで、どう直せばいいか（supportedFixes）まで返ってきます。 エラーメッセージを読んで原因を推測する作業が要りません。
variant を消して再実行すると、通りました。
single_svg ok
finite_svg ok
orthogonal_arrows ok
label_route_clearance ok
relationship_crossings ok
relationship_corridors ok
container_border_runs ok
route_rhythm ok
legend_clearance ok
composition: pass (errors: 0, warnings: 0)
minLabelRouteClearance: 30.5
9つのチェックすべてに合格し、ラベルと経路の最小クリアランスは 30.5px でした（要件は4px以上）。
--quality showcase は重要です。SKILL.md には「4つの artifact チェックだけのレシートは basic validation であって showcase 受理ではない」と書かれています。9つ全部が通って初めて合格です。
納品とレシート
node bin/archify.mjs deliver architecture demo.architecture.json demo.html --quality showcase --json
{
"ok": true,
"artifact": {
"sha256": "0341e51486f73a686ed0b8d82a7d136089351a42c0672add6f32e337fb8e476b",
"bytes": 700652
}
}
約688KB の単一 HTML が出てきました。仕様とアーティファクトの両方について SHA-256 とバイト数が返ります。「このHTMLはこの仕様から出た」ことが後から確認できるということです。
deliver は仕様のバイト列を同じディレクトリのスナップショットに凍結し、それをレンダリングして検証し、アトミックに HTML をコミットします。
画面サイズの検証
node bin/archify.mjs visual-check demo.html --json
1440×900 / 1600×1000 / 1920×1080 / 2048×1320 の4サイズで、はみ出しがないかを実際の Chrome で測ります。ライト・ダーク両方のスクリーンショット PNG とコンタクトシート HTML も生成されます。
{
"ok": true,
"status": "pass",
"visualReview": "pending",
"chrome": { "status": "available" },
"containment": { "status": "pass" }
}
ここが誠実だと思ったのですが、visualReview は必ず "pending" を返します。ドキュメントにはこう書かれています。
スクリーンショットは検査のための証拠であって、自動的な仕上がり保証ではない。
はみ出していないことは機械が保証しますが、「きれいかどうか」は人間が見るまで未確定、という立場です。
実際に生成された図がこちらです。
40行の JSON からこれが出ます。凡例、テーマ切り替え、プレゼンモード、エクスポートの UI は最初から入っていて、こちらでは何も指定していません。
このスクリーンショット自体、visual-check が 1440×900 で自動撮影したものをそのまま貼っています。手で撮り直していません。
🧾 Architecture Delta — 図の差分を機械が出す
archify で個人的にいちばん驚いたのがこの機能です。2つの構成図を比較して、何が変わったかを機械可読で返します。
先ほどの構成にキャッシュ（Redis）を1つ足した版を作って、比較してみます。
node bin/archify.mjs compare architecture demo.architecture.json demo-head.architecture.json --json
1回目 — ラベルが衝突
[composition/label-route-clearance] showcase architecture label "権限フィルタ" on
connections[4] id "c5" "api" -> "meta" is 0px from connections[5] id "c6"
"api" -> "cache" label "結果キャッシュ" segment 1 [600, 316] -> [600, 90]
(label rect [566, 270, 68, 14]; minimum 4px)
衝突相手の接続ID、セグメント番号、実座標、ラベル矩形の寸法、必要な最小クリアランスまで返ってきます。「ラベルが重なっています」ではなく「0px です、4px 必要です」です。
2回目 — ラベルをずらしたらノードに重なった
診断が挙げた labelDx を足してみたところ、今度は別の問題が出ました。
Label "権限フィルタ" overlaps component "meta"
label rect: [592, 270, 68, 14]
component "meta" rect: [640, 220, 140, 60]
Suggested fix: labelAt [626, 294] or labelDy +14 (below);
or labelAt [626, 216] or labelDy -64 (above)
具体的な代替座標を2案出してきます。
3回目 — ノードを動かしたら別の線を貫通
キャッシュを API の上に移したら、今度は接続線が認証ノードを突き抜けました。
[clean-flow/edge-through-node] architecture connections[5] id "c6" "api" -> "cache"
crosses component "auth" (unrelated to this relationship) on segment 0
[497, 300] -> [497, 210] (2px clearance)
「この関係とは無関係な auth を横切っている」と、無関係であることまで明示されます。
4回目 — 合格
キャッシュを API の下に置き、診断が提案した labelDy +24 をそのまま採用したところ通りました。
{
"ok": true,
"completeness": "complete",
"proofLevel": "authored",
"base": { "rawSha256": "82f11f...", "semanticSha256": "91a9e5...", "bytes": 2769 },
"head": { "rawSha256": "df5a5a...", "semanticSha256": "2de85b...", "bytes": 3169 },
"summary": {
"components": { "added": 1, "changed": 0, "removed": 0, "moved": 0 },
"connections": { "added": 1, "changed": 0, "removed": 0, "rerouted": 0 },
"boundaries": { "added": 0, "changed": 1, "removed": 0, "geometryChanged": 0 },
"presentationChanged": true,
"provenanceChanged": false
},
"changes": {
"components": [{ "id": "cache", "headLabel": "キャッシュ", "status": "added", "classifications": ["semantic"] }],
"connections": [{ "id": "c6", "status": "added", "classifications": ["topology"] }],
"boundaries": [{ "key": "region:社内VPC", "status": "changed", "classifications": ["scope"], "changedFields": ["/wraps"] }]
},
"limitations": [
"Authored Architecture IR only; no runtime impact, causality, risk, or mergeability is inferred.",
"Boundary identity is conservatively derived from kind + label."
],
"validation": { "checksPassed": 28, "checkCount": 28 }
}
実際に生成された図がこちらです。
3か所、注目したいところがあります。
① ハッシュが2種類ある — rawSha256 と semanticSha256 です。インデントを直しただけなら raw は変わっても semantic は変わりません。整形の差分と意味の差分を区別できます。
② 変更に分類が付く — キャッシュの追加は semantic、接続の追加は topology、VPC 範囲の変更は scope です。「境界の中身が変わった」ことが自動で scope として拾われるのは、レビューで効きそうです。
③ 自分から限界を書く — limitations に「これは記述された IR の比較であって、実行時の影響・因果・リスク・マージ可能性は推論していない」と明記されています。できないことを自分で宣言するツールは信用できます。
修正ループの停止条件も決まっています。
診断された対象だけを変え、証拠を確認し、
supportedFixesから選んで再実行する。客観的なエラー数が新しい最小値に達している間は修正を続ける。2回連続で最小値が改善しなければ止めて、未解決の診断を正直に報告する。
AI が「直りました」と言い続けて無限ループする、あの現象への対策です。
検証から納品、差分比較までの流れを1枚にすると上のようになります。
⚖️ 2つを比べる
同じ内容を、同じ条件で
ここまでで、まったく同じ「社内ナレッジ検索の構成」を両方に描かせました。並べるとこうなります。
diagram-design
archify
同じ6ノード、同じ5本の矢印です。それでも受ける印象がかなり違います。
| diagram-design | archify | |
|---|---|---|
| 入力 | 自然言語（エージェントが直接 SVG を書く） | 型付き JSON 仕様 |
| 図種 | 39 | 5 |
| 配布形式 | Claude Code プラグイン | Agent Skill |
| 実体の場所 | ~/.claude/plugins/ |
~/.agents/skills/ |
| 依存 | Python 3（PNG時のみ Playwright） | Node.js >= 18 |
| 検証 |
verify-*.py 群（幾何・面積保存・モーション） |
validate / deliver / visual-check の3段 |
| 差分比較 | なし | Architecture Delta |
| ブランド適用 | サイトURLから自動抽出＋プロファイル保存 |
brands コマンド（プリセット中心） |
| 対話性 | 静的（モーションはオプトイン） | 探索可能（検索・トレース・到達解析） |
| Mermaid |
import-mermaid で再描画 |
意味を読んで新規に書き起こす |
| 上限 | 最大9ノード | 主要ノード最大12 |
共通している思想
比較していて気づいたのですが、アプローチは正反対なのに、根っこの考え方はよく似ています。
① ノード数に上限がある — AI に好きなだけ描かせません。diagram-design は9、archify は主要ノード12です。
② 描く前に決めさせる — diagram-design はレンダリング前に計画を宣言させ、archify は候補を書く前にレンダラー内部を読むことを禁じます。方向は逆ですが、「あとで直す」を避ける点は同じです。
③ 失敗を機械可読にする — 人間が「なんか変」と言う代わりに、座標つきの診断を返します。
④ 正直さを強制する — archify の visualReview: "pending" と limitations、diagram-design の「複雑度予算で落とすものを宣言する」ルールがこれにあたります。
AI に任せる部分と、機械のルールで縛る部分の切り分けが、どちらもはっきりしています。
筆者はどう使い分けているか
私の場合はこうなりました。
-
記事・スライド・提案書に貼る1枚 → diagram-design
39種類あるので図種で困りませんし、ブランドトークンを適用すると資料全体のトーンが揃います。読ませる図です。 -
設計レビュー・PR 前の構成確認 → archify
検証レシートと差分比較があるので、「前回から何が変わったか」を人力で見比べる作業が消えます。確かめる図です。
冒頭に貼ったグラレコのような手描き風の絵は、どちらの守備範囲でもありません（あれは別の画像生成スキルで作っています）。この2つはあくまで構造を伝える図のためのものです。
⚠️ 正直に書いておく制限
使ってみて気づいた、事前に知っておきたい点です。
archify の日本語対応は限定的です
guide コマンドに日本語のシナリオを投げてみました。
node bin/archify.mjs guide "AIコーディングエージェントがMCPサーバー経由で社内DBを参照する構成" --json
返ってきたものです。
{
"ok": true,
"lang": "zh",
"confidence": "medium",
"matchedSignals": ["mcp"],
"recommendation": {
"id": "agent-tool-call",
"type": "workflow",
"title": "智能体工具调用",
"question": "智能体如何规划、获批、执行、恢复并汇报？"
}
}
日本語入力が "lang": "zh" と判定され、説明が中国語で返ってきました。 型の推薦（workflow）自体は妥当だったので実害は小さいのですが、驚きます。
SKILL.md にも、meta.locale が対応するのは "en" と "zh-CN" のみで、それ以外の言語では「固定の Viewer UI と <html lang> が英語にフォールバックすることを明示的に開示せよ」と書かれています。図の中身の日本語は問題なく描画されます（先ほどのスクリーンショットのとおりです）。UI 部分の話です。
archify の HTML は完全なオフラインではありません
生成された HTML の外部参照を確認しました。
grep -oE '<link[^>]*href="https?://[^"]*"' demo.html
<link rel="preconnect" href="https://fonts.gstatic.com">
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap">
Google Fonts への参照が残っています。 「自己完結 HTML」ではありますが、フォントだけは外から取ってきます。ネットワークのない環境ではフォールバックフォントで表示されます。
2つの美学は正面から食い違います
そして、上のフォント名を見て気づいた方もいると思います。archify が読み込んでいるのは JetBrains Mono です。
これは diagram-design が §4 のアンチパターン表で名指しで否定しているフォントです。
JetBrains Mono を「開発者フォント」として全面採用 → モノスペースは技術的内容専用。名前はサンセリフで。
どちらが正しいという話ではなく、美学が違うということです。同じ資料に両方の出力を混ぜると、フォントの印象が揃いません。使い分けるなら、章やドキュメントの単位で分けたほうがきれいだと思います。
その他
| 項目 | 内容 |
|---|---|
| diagram-design の PNG 出力 | Playwright + Chromium の別途インストールが必要（pip install playwright && playwright install chromium） |
| archify の修正ループ | 実測で3回のリペアが必要でした。1発で通るとは限りません |
| バージョン | どちらも活発に更新中です。本記事は 2026年8月27日時点 |
✅ まとめ
この記事で一番お伝えしたかったのは、「AI の図が微妙なのは、AI の絵心の問題ではなく、規律と検証がないから」ということです。
2つのプラグインは、まったく違う方向からそこに手を入れています。diagram-design は編集デザインの規律を先に課して、描く前に判断させます。archify は先に描かせてから、機械が幾何を検証します。どちらも「AI に自由に描かせる」ことをやめている点で共通しています。
実際に触ってみて印象的だったのは、archify の診断の細かさでした。「ラベルが重なっています」ではなく「0px です、4px 必要です、代わりにこの座標はどうですか」と返ってくると、修正が推測ではなく作業になります。AI に直させるときも同じで、曖昧な指摘より機械可読な診断のほうが、はるかに早く収束します。
次の一歩としては、この順で試すのが早いと思います。
- diagram-design を入れて、構成図を1枚描かせてみる（この記事の図は既定スキンのままです。それでも本文に馴染みます）
- 自社サイトの URL で onboard して、ブランドトークンを当ててみる（ここが刺さる人には刺さります）
-
archify で構成図を1枚
deliverまで持っていく（40行の JSON で終わります） -
その構成図を1か所だけ変えて
compareにかけてみる（差分が機械で出る体験は、一度やると戻れません）
そして、どちらを使うにしても、ノード数の上限は守ったほうがいいと思います。9個を超えたら2枚に分ける。この1つを守るだけで、AI が描く図はかなりまともになります。
参考
- cathrynlavery/diagram-design — 39の編集デザイン風図種。ギャラリーは cathrynlavery.github.io/diagram-design/
- tt-a1i/archify — 検証つきの探索可能な構成図
-
Agent Skills Specification — 両者が従う
SKILL.mdの形式 - Agent Plugins Specification 1.0.0 — プラグイン配布フォーマットの標準