Archifyでアーキテクチャ図を生成する方法｜検証付きHTML出力

システムの構成は頭の中で説明できるのに、設計レビューや引き継ぎのたびに構成図を描き直している。そんな状態に心当たりのある方は少なくないはずです。図は描いた瞬間から実装との乖離が始まり、次に必要になった時にはもう作り直しになっています。

かといって AI に図を描かせても、別の悩みが生まれます。生成された図は見た目こそ整っていても、「本当にこの構成で合っているのか」「勝手に存在しないコンポーネントを足していないか」を人間が目視で確かめるしかありません。レビュー資料として提出するには、その確認コスト自体が負担になります。

こうした「AI が描いた図の正しさをどう担保するか」という問題に、仕組みのレベルで答えようとしているのが Archify です。Archify はエージェントに型付きの JSON を書かせ、その JSON がスキーマ・レイアウト・経路の検証をすべて通過した場合にだけ成果物を出力する、という設計を採っています。

本記事は、Archify の README・公式プロジェクトページなど公開されているドキュメントに基づく整理です。動作検証やインストールは行っておらず、記述はすべて公式ドキュメントの内容に基づいています。

本記事では、Archify の位置づけと基本情報、対応する 5 つの図種の使い分け、インストールから図の更新までの使い方、検証ゲートの仕組み、d2 や Mermaid など類似ツールとの違い、そして導入前に確認しておきたい制約までを順に解説します。

Archifyとは｜AIエージェントに図を描かせるスキル

Archify は、Cursor / Claude Code / Codex CLI / OpenCode といった AI コーディングエージェント向けに提供される、Node.js 製のレンダリング・検証システムです。GitHub リポジトリは tt-a1i/archify で公開されています。

役割分担がはっきりしているのが特徴です。README の説明によれば、図の内容を考えるのはエージェント側で、エージェントは自然言語の説明やコードベースの解析結果から「型付き JSON IR（中間表現）」を生成します。Archify はその JSON を受け取り、決定的に HTML / SVG へコンパイルします。つまり Archify 自体は「絵を描く AI」ではなく、「エージェントが書いた設計データを、検証してから図に変換するコンパイラ」に近い位置づけです。

README には「Archify は汎用の作図エディタでも Mermaid のテーマでもない」（原文: Archify is not a general-purpose drawing editor or a Mermaid theme.）と明記されています。この一文が、後述する他ツールとの棲み分けを理解する上で重要な手がかりになります。

リポジトリの基本情報は次のとおりです（いずれも 2026 年 9 月 3 日時点）。

スター数 43,742 に対して直近の push が 2026 年 9 月 2 日と、更新が止まっていない点は「メンテナンス状況が健全か」を判断する材料になります。また、このリポジトリはアーカイブされておらず、他リポジトリのフォークでもありません。ライセンスは MIT で、商用利用を含めて扱いやすい部類です。

より視覚的な紹介や生成例は Archify 公式プロジェクトページ にまとまっています。公式ページでは、プレーンな英語の説明からインタラクティブな技術図を生成できること、PNG / JPEG / WebP / SVG / WebM への書き出しに対応すること、依存ゼロの自己完結 HTML としてオフラインでも閲覧できることが紹介されています。

Archifyが対応する5つの図種と選び方

Archify が対応するのは 5 種類の図です。汎用作図ツールのように「何でも描ける」わけではなく、対象を絞ることで検証ロジックを作り込む方針が採られています。README の「Choose the right diagram」表を整理すると、次のようになります。

実務での使い分けは、扱いたい対象が「静的な構造」なのか「時間軸のある動き」なのかで大きく分かれます。サービス間の依存関係や信頼境界を示したいなら Architecture、リリースや承認の流れを示したいなら Workflow、障害調査で「どの呼び出しがどの順で失敗したか」を追いたいなら Sequence が適します。データ基盤で個人情報の流通経路を棚卸ししたい場合は Data Flow、注文やジョブの状態遷移を整理したい場合は Lifecycle という選択になります。

Architecture 図には任意の deployment-ownership プロファイルが用意されています。README によれば、オーナー・リージョン配置・プライベート DB スコープ・名前付き越境のいずれかが記述されていない場合、Archify は暗黙の補完をせずに fail closed（失敗として止まる）挙動を取ります。また、稼働中インフラを検査して情報を埋めることはしません。「書かれていないことは描かない」という方針が、図種のレベルで徹底されているわけです。

どの図種を選ぶべきか迷う場合は、公式の シナリオガイド にユースケース別の例が掲載されています。後述する CLI の guide コマンドでも、目的を文章で伝えると適した図種の案内が得られます。

Archifyの使い方｜インストールから図の更新まで

ここからは、Archify を導入して図を出力するまでの流れを、README の記載に沿って整理します。

インストール

README の「Quick start」では、次のコマンドでグローバルインストールする方法が示されています。

npx skills add tt-a1i/archify -g

出典: https://github.com/tt-a1i/archify

対話プロンプトを挟まずに、対象エージェントを明示して入れる場合の例も README に記載されています。

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

出典: https://github.com/tt-a1i/archify

インストールせずに試す方法も用意されています。

npx skills use tt-a1i/archify@archify --agent codex

出典: https://github.com/tt-a1i/archify

導入判断で気になるのは「自分たちが使っているエージェントに入るのか」という点でしょう。README の「Installation options」では、サーフェスごとのインストール先が示されています。

Claude.ai 上での利用はサンドボックス環境で Node.js が使えるかどうかに依存する、と README に注記されています。ローカルの CLI エージェントで使う場合は Node.js が動く環境であれば前提条件は少なく、導入コストは 1 コマンド程度に収まる構成です。エージェント別の初期設定手順は エージェント別クイックスタート に整理されています。

説明から図を描かせる

Archify を使う上で押さえておきたいのは、リポジトリがなくても図を描けるという点です。README には「No repository is required: describe the system in any agent chat.」と記載されており、エージェントのチャットにシステムを説明するだけで図が生成されます。

最小の例として、README には次のプロンプトが挙げられています。

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

出典: https://github.com/tt-a1i/archify

既存のコードベースを根拠に図を起こす場合の例も示されています。

Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

出典: https://github.com/tt-a1i/archify

後者のプロンプトは、そのまま図の設計指針にもなっています。コンポーネント数を 8〜12 に絞り、主要経路を 1 本に限定し、補足情報はエッジを増やすのではなくカードに逃がす。この指定があることで、リポジトリ解析の結果が「線だらけで読めない図」になるのを防いでいます。

会話で反復し、CLIで検証する

生成後の修正は、図を直接編集するのではなく会話で行います。README では add Redis、move auth to the left、highlight the rollback path といった短い指示で反復でき、その間も型付きのソースは保持されると説明されています。図そのものではなく設計データを更新していく形なので、無関係な箇所のレイアウトが崩れにくい仕組みです。

エージェント経由ではなくリポジトリのコマンドを直接叩く場合、README には次のコマンド群が記載されています。

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

出典: https://github.com/tt-a1i/archify

それぞれの役割は、doctor が環境診断、demo がサンプル生成、guide が目的からの図種案内、validate が JSON の検証、preview がライブプレビュー、deliver が成果物の出力です。CI に組み込むなら validate --json が起点になり、日常の作図では preview と deliver が中心になります。

型付きJSONと検証ゲート｜Archifyが「検証付き」と言える理由

Archify の中核は、図を出力する前に置かれた検証ゲートです。README の「How it works」では、処理が次の 5 段階に分かれると説明されています。

ここで効いてくるのが Deliver の「アトミックな差し替え」です。README によれば、スキーマ・レイアウト・HTML/SVG・経路・ラベルと経路のクリアランス検査がすべて通過しない限り、showcase 成果物は直前の検証済み版（last-good）を置き換えません。プレビューについても、保存が不完全だったり不正だったりする間は直前の検証済み図を表示し続けると説明されています。「壊れた図が一瞬でも出回る」状態を構造的に避ける設計になっているわけです。

検証に失敗した場合の戻り値も特徴的です。validate --json / deliver --json は、安定したルールコード・対象・実測エビデンス・サポートされる修復操作のみを返すと README に記載されています。Node のスタックトレースを投げ返したり、当てずっぽうのリトライをしたりはしません。エージェントが機械的に読み取って修正できる「修復レシート」を返す、という設計です。この仕様は自動化との相性がよく、CI で図の破損を検知する用途にも使えます。

もう一点、レビュー資料として信用できるかを左右するのが「捏造しない」方針です。README では、フォーカス・上流/下流リーチ・経路・ロール比較・ストーリーといった対話機能はいずれも「作者が記述したノードと関係」を再利用するだけで、トポロジを捏造したりランタイム影響を主張したりしないと明記されています。加えて、Evidence-backed な Architecture ノードは SRC n を表示し、単一の公開コミットに固定された Git 検証済みのファイル・行範囲を開けます（通常の成果物にはソース参照が付きません）。

生成とビューアの契約、およびスキーマの詳細は SKILL.md と スキーマリファレンス に記載されています。自社のフォーマットや CI に組み込めるかを見極めるなら、この 2 つを先に読むのが近道です。

生成したアーキテクチャ図を共有・レビューに使う

図は作った後に共有されて初めて価値が出ます。Archify の成果物は依存ゼロの自己完結 HTML 1 ファイルで、オフラインでも開けます。社内 Wiki に添付する、Pull Request に成果物を置く、といった運用がしやすい形式です。

エクスポート面では、Export メニューから PNG をクリップボードにコピーしたり、静止・モーション形式でダウンロードしたりできます。Copy Share Card は 1200×630 の共有用画像を生成し、経路トレース後の Route Share Card、リーチトレース後の Reach Share Card も同じサイズの PNG として出力されます。README には、エクスポートは常に図全体を対象とし、一時的なビューア状態を含まないと記載されています。レビューに貼る画像が「たまたま拡大していた状態」に引きずられない、という点は地味ながら実務では効きます。

レビュー時に視点を揃えたい場合は、安定リンクが使えます。#focus=<id>、#focus=<id>&reach=upstream|downstream、#relation=<id>、#route=<source>~<target>、#lens=<kind>~<kind>、#view=<view-id> といったフラグメントで表示状態を復元できるため、「この経路を見てほしい」という指定を URL のまま渡せます。モーションは有限で prefers-reduced-motion を尊重し、正規のエクスポートには含まれません。

設計変更のレビューで役立つのが Architecture Delta です。検証済みの Before / Delta / After スナップショットを比較し、追加・削除・変更・移動・再ルートの事実をマシンレシート付きで提示します。比較は次のコマンドで実行できると README に記載されています。

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

出典: https://github.com/tt-a1i/archify

ここでも「事実だけを出す」姿勢が徹底されており、README は影響・リスク・マージ安全性は推論しないと明記しています。つまり Delta が示すのは「何がどう変わったか」までで、「その変更が安全か」の判断は人間の側に残ります。レビューを自動化しきるツールではなく、レビューの前提を機械的に揃えるツールと捉えるのが実態に近いでしょう。

生成物の実例は、公式の Proof Lab で確認できます。公式ページによれば、掲載されている成果物には 9 項目の検証チェックを通過した旨が示されています。

類似OSS・エージェントスキルとの違い

図を生成する OSS は数多くあります。採用判断で重要なのは「Archify がどの領域を担い、どこは他ツールの方が向くか」を把握することです。2026 年 9 月 3 日時点の主要な選択肢と比較すると、次のように整理できます（スター数はいずれも同日時点）。

選び方の指針としては、リポジトリ内のドキュメントにそのまま埋め込みたいなら Mermaid、手書きの DSL で細かく図を管理したいなら d2、URL を渡すだけで全体像を掴みたいなら gitdiagram が向きます。Archify が優位に立つのは、図の内容を機械的に検証したい場合、設計変更の差分を追跡したい場合、そして生成した図をそのままレビュー資料として配布したい場合です。

diagram-design との棲み分けは特に迷いやすいポイントです。図種の幅と編集デザイン性を重視する汎用図解であれば diagram-design、構成図に絞って検証と差分追跡を重視するなら Archify、という整理になります。diagram-design 側の詳細はClaude Codeの図解にdiagram-designが選ばれる理由で解説しています。用途が DB スキーマの設計に寄っている場合は、ER 図と SQL 生成に特化した ER図・SQL生成にdrawDBが選ばれる理由 も比較対象になります。

導入前に確認したいArchifyの制約

採用判断には、できることと同じくらい「できないこと」の把握が必要です。README の「Reference and scope」では、次の 4 つが意図的にスコープ外とされています。

• Mermaid の自動パース
• 汎用オートレイアウト
• ホスティング共有
• WYSIWYG 編集

既存の Mermaid 資産を自動で移行したい、GUI で図を直接ドラッグして整えたい、生成した図を URL で社外共有したい、といった要件がある場合は、この時点で要件との不一致が判明します。

言語面では、設定で指定できるロケールが en と zh-CN の 2 種類です。README の設定例は次のとおりです。

{
  "meta": {
    "locale": "en",
    "animation": "trace",
    "visual_preset": "signal-flow"
  }
}

出典: https://github.com/tt-a1i/archify

meta.locale はページタイトル・凡例・状態やエラー表示・アクセシビリティ属性・HTML/SVG の lang をローカライズしますが、記述した内容そのものは翻訳されません。README 上に日本語ロケールの選択肢は記載がないため、UI 周りが英語表記になる点は事前に想定しておく必要があります。図中のラベルは入力した文言がそのまま使われるので、日本語で書けば日本語で表示されます。

ネットワーク面では、Archify が固定の manifest に GET リクエストを送り、任意の更新リマインダーを表示することがあると README に記載されています。更新のダウンロードやインストールは行わず、成功時は約 72 時間（±20%）待機、失敗時は 6 時間 → 24 時間の間隔で再試行します。サーバーが受け取るのは通常の HTTP メタデータ（IP と時刻）のみで、バージョン・エージェント・プロジェクトデータ・プロンプト・アカウントやデバイスの ID・ETag は送信されないとされています。外部通信を許容できない環境では、ARCHIFY_UPDATE_CHECK_DISABLED=1 を設定することで通信とリマインダー状態の書き込みを無効化できます。

バージョンについては、README に記載されている開発版が v2.17.0-dev.1 です。最終 push が 2026 年 9 月 2 日であることと合わせると、開発は活発に続いている状況といえます。一方で、活発な更新は仕様変更の可能性とセットでもあるため、CI に組み込む場合はバージョンを固定する運用を検討する価値があります。ライセンスは MIT で、2026 年 9 月 3 日時点でアーカイブ済みでもフォークでもありません。

Archifyが向くチーム・向かないチーム

ここまでの内容を、採用判断のチェックリストとして整理します。

Archify が向くケース

• Cursor / Claude Code / Codex CLI / OpenCode などの AI エージェントを既に日常的に使っている
• 設計レビューや引き継ぎで構成図を共有する機会が多く、図の鮮度を保ちたい
• AI が生成した図をそのままレビュー資料に使いたいが、正しさを機械的に担保したい
• 設計変更の前後で構成図の差分を追跡したい
• 生成物をオフラインでも開ける単一ファイルとして扱いたい

別の選択肢を検討した方がよいケース

• リポジトリの Markdown にそのまま埋め込みたい → Mermaid
• 描ける図種の幅とデザイン性を優先したい → diagram-design
• URL を渡すだけで手軽に全体像を掴みたい → gitdiagram
• DB スキーマの設計・SQL 生成が主目的 → drawDB
• GUI で図を直接編集したい、既存の Mermaid 資産を自動移行したい → Archify のスコープ外

導入コスト自体は 1 コマンドで、npx skills use を使えばインストールせずに挙動を確認できます。判断に迷う場合は、まず自チームの図が 5 つの図種に収まるかを確認し、次に UI が英語表記になる点とスコープ外の 4 項目が要件と衝突しないかを見るのが効率的です。

なお、構成図をどう描くかの前提として、アーキテクチャそのものの整理が必要になる場合もあります。基本的な考え方はシステムアーキテクチャとはで解説しています。

関連情報

既存システムの構成整理や設計ドキュメントの再構築でお困りの場合は、お問い合わせフォーム からご相談いただけます。要件が固まる前の段階からのご相談にも対応しています。