画像生成AIで作った図が編集しにくい、ブログごとに配色が変わる、Webページへ埋め込むたびに崩れる。
最短の解決策は、diagram-designをClaude CodeのAgent Skillとして使い、自包含HTMLを作成してから必要に応じてSVGやPNGへ書き出すことです。
この記事を読むべき人
Claude Codeに技術図表を直接作らせたい開発者、ブログや製品ドキュメントの見た目を統一したいコンテンツチーム、Agent Skillsの自動化能力を評価する技術責任者に向いています。リアルタイムの共同ホワイトボードや自由な手描き編集を求める場合は、別のツールを選ぶ方が適切です。
最終更新：2026年8月14日。プロジェクトのREADME、SKILL.md、referencesディレクトリ、最近のコミットを確認して整理しています。インストール方法や対応形式は更新される可能性があるため、導入前に公式リポジトリのREADMEも確認してください。
なぜ従来の図表ワークフローは途中で破綻するのか
技術記事でよくある失敗は、図表を「画像」として完成させてしまうことです。画像生成AIの出力は見栄えがよくても、ノード名の変更、矢印の追加、ブランドカラーの修正を行うたびに作り直しになります。
もう1つの問題は、形式と配置です。PNGだけを納品すると、Webでは解像度や余白を調整しにくく、印刷やスライドでは再利用しづらくなります。逆に、図表を手作業で作ると、以下のコストが積み上がります。
- サービス名や矢印の変更ごとにレイアウトを修正する必要がある
- 複数の記事でフォント、背景、アクセントカラーが揃わない
- 画像ファイル、外部スクリプト、フォント依存によって埋め込み時に崩れる
- 複雑な図では、AIが意味のないノードや過剰な装飾を追加する
- 自動生成した内容を人間が確認しないと、構成上の誤りを見落とす
diagram-designが解決するのは、絵を自由に描くことではありません。文章から、再利用しやすい構造化された図表を作り、HTMLやSVGとして管理することです。
diagram-designはどのような仕組みのツールなのか
diagram-designは、Claude CodeなどのAgent Skills対応環境に追加して使う図表生成スキルです。Claude Code公式ドキュメントでは、Skillが説明や手順を読み込み、必要な場面で起動する仕組みが説明されています。詳しくはClaude Codeの公式Skillsドキュメントを確認してください。
出力の中心は、外部ライブラリに依存しない自包含HTMLと、HTML内に含まれるインラインSVGです。公式READMEでは、アーキテクチャ図、フローチャート、シーケンス図、状態遷移図、ER図、タイムライン、スイムレーン、2軸図、ツリー、組織図、ベン図、レイヤー図などが案内されています。
この方式には、技術ドキュメント制作上の明確な利点があります。
- HTMLを直接開いて内容とレイアウトを確認できる
- SVGのテキストや図形をコードとして編集できる
- Webページへ埋め込みやすく、拡大しても輪郭がぼやけにくい
- 図表のソースをGitで管理し、記事更新と一緒に差分確認できる
- PNGはSNS、スライド、アイキャッチ用に後から生成できる
ただし、SVGが編集可能であることと、専門的なデザインソフトのファイル形式になることは別です。SVGはXMLベースの図形データなので、テキストエディターや対応するデザインツールで変更できますが、元のレイアウト規則や自動配置ロジックまで保存されるわけではありません。アクセシビリティを意識する場合は、SVGのタイトル、説明、役割なども確認してください。詳細はW3CのSVGアクセシビリティ資料で確認できます。
第一の用途：技術ブログと製品ドキュメント
技術ブログでは、文章の内容に合わせて「何を図解すべきか」を決めることが重要です。diagram-designに、対象システムの構成、読者の前提知識、図表の用途を渡すと、単なる画像ではなく、記事へ配置しやすい図表として出力できます。
例えば、APIの記事ならアーキテクチャ図、認証処理ならシーケンス図、障害対応なら状態遷移図、導入手順ならフローチャートが向いています。1枚にすべてを詰め込むのではなく、読者が1つの図から得る結論を決めてから生成してください。
技術ブログ向けの指示例
この認証フローを、技術ブログの本文に埋め込む図として作成してください。
対象読者は中級以上の開発者です。
登場要素はブラウザー、APIゲートウェイ、認証サービス、データベースに限定します。
正常系とトークン失効時の分岐を示し、HTMLとSVGを出力してください。
自包含HTMLは、外部のJavaScriptランタイムや画像素材を読み込まずに表示できる点が強みです。記事管理システムへHTMLを直接配置する場合でも、公開環境がどのタグやインラインSVGを許可しているかは事前に確認してください。
第二の用途：ソフトウェア構成と処理フロー
ソフトウェアアーキテクチャでは、図表の美しさよりも情報量の制御が重要です。ノードが増えるほど、AIは関連性の低いコンポーネントまで描き込みやすくなります。
実務では、次の順番で複雑度を抑えると安定します。
- 図表の読者を開発者、運用担当、経営層のいずれかに決める
- 図表で説明する経路を1本選ぶ
- 必須ノードと補足ノードを分ける
- 矢印の向きと通信内容を明示する
- 生成後に実際のコードや構成資料と照合する
- 読者が不要なノードを削除してから公開する
diagram-designのREADMEでは、インポート時に詳細度を分ける考え方も説明されています。複雑な元図をそのまま再現するのではなく、用途に応じて情報をまとめ、ブログ用、スライド用、役員向けなどに表現を変える設計です。
「最強のAI図表生成ツール」という表現は、すべての図表で性能が上という意味ではありません。コードや文章から、編集可能で埋め込みやすい技術図表を繰り返し作る場面で、強みが出るという意味に限定して考えるべきです。
第三の用途：ブランドに合わせたコンテンツ制作
初回設定では、プロジェクトのスタイルガイドを決めます。公式資料では、Webサイトの背景色、本文色、アクセント色、見出しフォント、本文フォントなどを意味的な役割へ割り当てる流れが示されています。
ここで注意したいのは、初期設定の配色を企業ブランドと誤認しないことです。デフォルト表示は動作確認には使えますが、継続的な記事制作に使うなら、以下を先に決めてください。
- 背景、本文、補助文字、強調線の色
- ノードの種類ごとの意味
- 危険、成功、外部サービスなどの色分け
- 日本語を含むフォントの表示可否
- モバイル幅での文字サイズと余白
- 背景色と文字色のコントラスト
一度スタイルガイドを整えれば、記事ごとに色を選び直す必要がなくなります。ただし、ブランドの自動抽出結果は必ず確認してください。サイト側のCSSが複雑な場合や、画像内の色が主要なブランド要素になっている場合、抽出結果だけでは十分でない可能性があります。
Claude Codeでdiagram-designを呼び出す手順
Claude Code公式ドキュメントでは、個人用のSkillを~/.claude/skills/に置く方法と、プロジェクト用の.claude/skills/に置く方法が説明されています。プラグインとして導入する場合は、名前空間付きのコマンドとして読み込まれます。
実際の導入は、次の流れで確認すると安全です。
第一歩：Claude Codeの実行環境を確認する
Claude Codeがインストール済みで、対象プロジェクトのディレクトリから起動できる状態にします。権限、Git管理、ファイル出力先を先に確認してください。
第二歩：diagram-designを導入する
公式READMEに掲載されているClaude Code向けのプラグイン手順を使います。手動で管理したい場合は、リポジトリを取得し、skills/diagram-design/をClaude CodeのSkillディレクトリへリンクする方法もあります。
第三歩：再読み込みと起動状態を確認する
導入後にプラグインを再読み込みし、Skillが一覧に表示されるか確認します。自動起動に任せる場合でも、最初は明示的にdiagram-designを指定して、意図したSkillが呼ばれているか確認するとトラブルを減らせます。
第四歩：入力資料と出力形式を指定する
対象の文章、コード、構成ファイル、参考図表を渡し、HTML、SVG、PNGのどれが必要かを明記します。「見栄えのよい図」だけではなく、読者、掲載場所、ノード数の上限、色の意味まで指定してください。
第五歩：HTMLをブラウザーで確認する
生成されたHTMLを開き、文字の切れ、矢印の重なり、スマートフォン幅での崩れ、背景とのコントラストを確認します。図表の内容が正しいかは、元のソースコードや設計資料と照合してください。
第六歩：SVGまたはPNGへ書き出す
公式READMEでは、SVG抽出とPNG書き出しのコマンドが用意されています。PNGのレンダリングにはPlaywrightとChromiumの準備が必要になる場合があります。Playwrightはブラウザーを操作して要素やページ全体のスクリーンショットを保存できるため、HTMLから画像を作る工程に向いています。詳しくはPlaywright公式のスクリーンショット資料を参照してください。
導入判断チェックリスト
次のチェック項目を使うと、diagram-design、Mermaid、Excalidrawのどれから試すべきかを決めやすくなります。diagram-designの項目が3つ以上当てはまるなら、まずClaude Codeへの導入を検討してください。
diagram-designを選ぶ場合
- [ ] Claude Codeから図表生成まで一連の流れを自動化したい
- [ ] 技術ブログや製品ドキュメントへHTMLを埋め込みたい
- [ ] SVGのテキストや図形を後から修正したい
- [ ] 同じ配色、フォント、意味付けを複数の記事で再利用したい
- [ ] HTML、SVG、PNGを用途ごとに使い分けたい
Mermaidを選ぶ場合
- [ ] 図表の定義を短いテキストとして管理したい
- [ ] Markdownやドキュメントのビルド処理へ組み込みたい
- [ ] レイアウトを細かく手直しするより、構造の差分管理を優先したい
- [ ] 既存のドキュメント基盤がMermaidに対応している
Mermaidはテキスト記法をレンダリングする設計なので、構造の変更を差分として扱いやすい点が強みです。公式のMermaid概要資料では、フローチャートやシーケンス図などをテキストから作る仕組みが説明されています。
Excalidrawを選ぶ場合
- [ ] 会議中に複数人でキャンバスを編集したい
- [ ] ペン入力や自由な手描きが中心になる
- [ ] 完成されたブランド図より、アイデア整理を優先したい
- [ ] ノードや矢印をマウスで自由に動かしたい
Excalidrawは、共同編集や手描き風のラフ作成を重視する場面に向いています。詳しくはExcalidraw公式ドキュメントを確認してください。
判断を迷ったときの戻し方
- HTMLへの埋め込みとSVG編集が必須なら、diagram-designを選びます。
- テキストによる差分管理とビルド連携が最優先なら、Mermaidへ戻します。
- 会議中の自由な配置と共同編集が最優先なら、Excalidrawへ戻します。
- どの条件にも当てはまらない場合は、1つの小さな図表で出力から公開までを試し、編集性と確認コストを比較してから決めます。
使わない方がよい場面と運用上の注意
次の条件に当てはまるなら、diagram-designを無理に採用しないでください。
- 複数人が同時にキャンバスを編集する必要がある
- ペン入力や自由な手描きが中心になる
- 特定のデザインソフト専用形式で納品する必要がある
- 図表の正確な座標やレイヤー構造を手作業で管理したい
- 生成物を確認せず、そのまま設計書として公開したい
また、Claude Codeに組み込まれている公式機能と、第三者が提供するdiagram-designのようなAgent Skillは区別してください。Skillは、導入したリポジトリ、プラグインの更新状態、参照ファイル、実行環境に影響されます。導入前にREADMEとSKILL.mdを確認し、社内コードや機密情報を外部へ渡す設定になっていないかも点検してください。
継続運用では、図表のソースを記事本文と同じリポジトリに保存し、生成日時、入力資料、確認者、出力形式を記録すると管理しやすくなります。PNGだけを残す運用にすると、次回の修正で再び手作業が発生します。
現在の環境からMac環境へ切り替える判断
ローカルのWindowsやLinux環境でもdiagram-designは試せますが、継続的なコンテンツ制作では、ブラウザー自動化、フォント、画面確認、ファイル共有が別々の設定になりやすい点が負担になります。特に、PlaywrightによるPNG書き出しでブラウザー依存が発生すること、GUI確認を自動化しにくいこと、チームごとに環境差が出ることは見落としやすい欠点です。
短期間だけClaude Codeとブラウザー書き出しを使うなら、Macを購入して環境を固定するより、必要な期間だけKvmzenのMac環境を借りる方が検証しやすい場合があります。Claude Codeの導入先やブラウザー書き出しの運用を整理したい場合は、KvmzenのMac利用ガイドを確認し、長期運用に向くか、短期の検証環境で十分かを切り分けてください。
なお、常時稼働する重い処理、物理ポートへの接続、特定の社内ネットワーク要件がある場合は、自社所有のMacや既存の開発環境の方が適しています。diagram-designを試す目的が一時的な記事制作、導入検証、ブラウザー書き出しの確認であれば、KvmzenのMacレンタル案内から利用条件を確認するのが現実的です。