リポジトリの構成図が、コードの変更に追いつかず古びていく問題に悩んでいるチームは少なくないはずです。手動で描いた構成図は、サービス名の変更や責務の移動が起きるたびにずれていき、誰も更新しないまま放置されがちです。この記事は、Claude CodeやCursorといったコーディングエージェント（コードを読み書きできるAIアシスタント）を使っている開発者に向けて、構成図自動生成ツール「Archify」を導入すべきかどうかの判断材料を整理します。
Archifyは、Claude Code・Cursor・Codex・OpenCode向けのエージェントスキル（AIエージェントに追加機能を与える拡張）として提供されています。仕組みはシンプルで、コーディングエージェントがリポジトリを解析し、型付きJSON（構造が決まったJSON形式のデータ）でアーキテクチャを表現します。そのJSONをArchifyが検証し、インタラクティブに操作できるHTML/SVG形式の図として出力します。対応する図の種類は、アーキテクチャ図・ワークフロー図・シーケンス図・データフロー図・ライフサイクル図の5種類です。
ここで押さえておきたいのは、リポジトリを「解釈」するのはコーディングエージェントであり、Archify自身がやっているのはJSONの「検証と描画」だという役割分担です。壊れたデータや不正な参照、レイアウトの破綻は検出できますが、エージェントがコードの意味を正しく理解したかどうかまでは保証しません。つまり出力をそのまま信じるのではなく、レビューする前提のツールです。
どんな場面で導入を検討するか
構成図の陳腐化に困る場面は主に3つあります。ひとつは、初めて触るリポジトリの全体像を短時間で把握したいとき。ふたつめは、コードレビューやオンボーディング資料として、常に最新の構成図を用意したいとき。三つめは、設計変更のたびに手動で図を描き直す作業をやめたいときです。逆に、構成がほぼ固定されていて変更頻度が低いプロジェクトでは、恩恵は限定的です。
判断軸1: 検証可能性（Source Evidence）の有無
Archifyには「evidence-backed architecture mode（証拠付きアーキテクチャモード）」という機能があります。これは、図の各コンポーネントが、特定のコミットに紐づくリポジトリ内のファイルや行範囲を参照できる仕組みです。
これが重要なのは、AIが生成した図を「見た目が整っているから信じる」状態から抜け出せる点です。コンポーネントを選択すれば、その裏付けとなるコードを直接確認できます。もしコンポーネントが図から漏れていれば、エージェントが見落としたのか、実際にコードが存在しないのかを自分で切り分けられます。
ただし、この証拠参照はリポジトリの条件によってはオプション扱いになり、常に付与されるとは限りません。検証機能があっても、ハルシネーション（AIが事実に基づかない内容を生成する現象）自体がなくなるわけではない点は理解しておく必要があります。
判断軸2: 再生成コストの低さ
手動で作った構成図は、ある時点までは正確でも、サービス名の変更や責務の移動が起きた瞬間に古くなります。Archifyの図はリポジトリと自動同期するわけではなく、コードが変わるたびにエージェントを再実行する必要があります。
ただし、その再生成コストは手描きの修正コストよりはるかに低いという点が評価ポイントです。古い図を信頼してよいか悩む代わりに、現在のリポジトリから再生成して差分を見る、という運用に切り替えられます。構成図がドキュメントというより「ビルド成果物」に近い性質を持つようになる、という捉え方ができます。
判断軸3: プロンプトのスコープ設計
大規模なリポジトリをスコープなしで解析させると、技術的には詳細でも人間には読みにくい図が出力されます。これを避けるには、プロンプトで粒度を明示的に指定する必要があります。
公式に紹介されているプロンプト例は次のようなものです。
Analyze this repository, then use Archify to create a high-level runtime architecture diagram. Show 8–12 core components, the primary request path, external dependencies, storage, and trust boundaries. Include source evidence where it is supported. Put secondary details in cards instead of adding more edges.「8〜12個のコアコンポーネントに絞る」という制約が肝心な部分です。この制約がないと、エッジ（コンポーネント間の関係線）が増えすぎて可読性が落ちます。まだコードが存在しない設計段階のシステムであれば、自然言語だけで図を描かせることも可能です。
Use Archify to draw this system: Browser -> API gateway -> authentication service -> application API -> Redis cache -> PostgreSQL fallback. Show the trust boundary around the private services and database.判断軸4: 導入コストと動作要件
ArchifyはNode.js 18以降が動作要件です。インストールはグローバルにスキルを追加する形で行います。
npx skills add tt-a1i/archify -g導入自体は数分で終わるため、コストの中心は「対応エージェントを既に使っているか」に集約されます。Claude Code・Cursor・Codex・OpenCodeのいずれかを日常的に使っていれば、追加の学習コストはほぼありません。
選択肢の比較
構成図の作成方法として、手動作図ツール（Draw.ioやMiroなど）、コードから静的解析で図を生成する既存ツール、Archifyのようなエージェント駆動型ツールの3系統を比べると、次のような整理になります。
| 方式 | 最新性の維持 | 検証のしやすさ |
|---|---|---|
| 手動作図ツール | 更新を忘れると即座に陳腐化 | 人間が描いた分だけ意図は明確 |
| 静的解析ベースの自動生成 | コードと機械的に同期しやすい | 解析ロジックが固定的で柔軟性は低い |
| Archify（エージェント駆動） | 再実行すれば追従、自動同期ではない | 証拠付きモードで裏付け確認が可能 |
ケース別の推奨
初見のリポジトリの全体像を素早く掴みたいエンジニアには、対応エージェントを使っているという条件付きで導入をすすめられます。8〜12個という粒度指定を守れば、レビュー資料やオンボーディング資料としても実用に足る図が作れます。
設計変更が頻繁に起きるマイクロサービス構成のプロジェクトでは、構成図が手動運用だと確実に陳腐化します。再生成コストの低さが効いてくる典型的なケースなので、evidence-backed modeを併用した導入が向いています。
まだコードが存在しない設計フェーズでも、自然言語プロンプトから構成図の叩き台を作れるため、設計レビューの初期段階での利用価値もあります。
あえて見送るべき条件
対応エージェント（Claude Code・Cursor・Codex・OpenCode）をチームで使っていない場合、導入のハードルが上がります。エージェントなしでは核となる解析処理が動かないためです。
また、構成がほぼ変化しない小規模な単一サービスや、既に静的解析ベースの構成図生成が業務フローに組み込まれているプロジェクトでは、乗り換える利点は小さいと考えられます。加えて、生成された図を検証する体制がなく「見た目が整っているから正しい」と鵜呑みにしてしまう運用では、ハルシネーションのリスクをそのまま抱え込むことになるため注意が必要です。
導入前に確認すること
Archifyを試す前に、次の3点を確認しておくとスムーズです。
- 使っているコーディングエージェントがClaude Code・Cursor・Codex・OpenCodeのいずれかに該当するか
- Node.js 18以降が動作環境に用意できるか
- 生成後に「主要ノードが実在のフォルダやサービスに対応しているか」「重要なエッジが実際の呼び出しやデータの流れを表しているか」「外部依存関係が図に反映されているか」を確認する運用を組めるか
この3つ目のチェックリストは、evidence-backed modeで各コンポーネントの根拠となるファイルや行範囲を実際に開いて照合する作業とセットで運用すると効果的です。構成図を「一度作って終わり」にせず、コードと突き合わせて検証する習慣を持てるかどうかが、このツールを使いこなせるかの分かれ目になります。