なぜあなたのAIが作成するダイアグラムは嘘をつくのか
AIエージェントは、コードベースをマッピングする際にしばしば嘘をつきます。コーディングエージェントにリポジトリのダイアグラム作成を依頼すると、実際には存在しないKafka、Redis、またはAPIゲートウェイが表示されることがあります。これらのダイアグラムは一見もっともらしく見えますが、コンポーネントをハルシネーション（幻覚）で作り出しており、視覚情報全体が信頼できず、実際の開発には役に立ちません。フィクションから生まれたビジュアルを信頼することはできません。
Archifyはこの問題に真っ向から取り組みます。そのAIエージェントは何も描画せず、代わりにシステムを構造化された「typed JSON」として記述します。この根本的な転換により、システムの正確な記述と視覚的表現が分離されます。Archifyは、ダイアグラムが表示される前にこのJSONを厳密に検証し、根本からの正確性を保証します。
Archifyを「システムマップのためのLLVM」と考えてください。AIコーディングエージェントはフロントエンドとして機能し、初期のシステム記述を生成します。その記述は、厳格なスキーマに従う必要がある、検証済みの「JSON Intermediate Representation (IR)」となります。これらのチェックを通過した後にのみ、ローカルコンパイラがIRを最終的なインタラクティブなHTMLに変換し、推測ではなく多段階の検証可能な出力を保証します。
JSONから信頼へ：検証パイプライン
ArchifyはAIにダイアグラムを「描かせる」だけではありません。代わりに、AIエージェントに対して構造化された「typed JSON Intermediate Representation (IR)」を出力するよう要求します。このIRは、厳密で決定論的な検証パイプラインに入ります。Archifyは、厳格なスキーマと整合性のためのアトミックゲートに対してチェックを行い、システム記述が正しいことを保証します。
重要なのは、不正なJSONが魔法のように欠陥のあるダイアグラムになることはないという点です。グラフが無効な場合、Archifyはプロセスを停止し、明確な診断とルールコードを提供します。つまり、黙って間違っている視覚的表現を信頼するのではなく、対処可能なエラーメッセージを受け取ることができます。この「フェイルクローズ」のアプローチが、根本的な信頼性を構築します。
次に、Archifyは「Repo Evidence」機能により、検証可能な証明の強力なレイヤーを追加します。ダイアグラム内のノードには「SRC」バッジを表示できます。それをクリックすると、そのコンポーネントの存在を証明する特定のリポジトリ内のコード、コミット、さらには正確な行範囲に直接ジャンプできます。したがって、アーキテクチャは単にもっともらしいだけでなく、証明可能な真実となります。
Mermaidのようなツールを考えてみてください。構文的に正しいダイアグラムコードを書くことはできますが、論理的に欠陥があったり、実際のコードベースには存在しないコンポーネントが含まれていたりするダイアグラムが生成される可能性があります。Archifyの包括的な検証レイヤーは、直接的なコードリンクの証拠と組み合わさることで、他のツールにはない「セマンティックな信頼」という重要な次元を追加します。
単なる画像を超えて：インタラクティブなシステムマップ
ArchifyのコンパイラがJSONを検証した後、それは「自己完結型のHTMLファイル」を生成します。これは静的な画像ではなく、真の有用性を提供するインタラクティブなシステムマップです。任意のサービスを検索し、そのアップストリームおよびダウンストリームの依存関係を即座に明らかにできます。次に、静的なダイアグラムを眺めるだけでなく、システム全体を通じた「キャッシュミス」パスをたどるように、複雑なフローをステップバイステップでインタラクティブに追跡できます。
プルリクエストにおいて、「アーキテクチャの差分表示（architecture diffing）」機能は決定的な利点をもたらします。Archifyはシステムの2つの検証済みスナップショットを比較し、視覚的な「変更前、差分、変更後」の比較を生成します。これにより、どのコンポーネントが追加、削除、または再ルーティングされたかというすべてのアーキテクチャ変更が明確に強調され、コードレビューがより堅牢になり、意図しない変更を防ぐことができます。
インタラクティブなHTMLファイルがArchifyの主要な成果物であり最大の強みですが、堅牢なエクスポート機能も備えています。PNG、JPEG、WebP、SVG、WebMなどの形式で静止画像を簡単に生成できるほか、迅速なコミュニケーションに役立つ1200x630の共有カードも作成可能です。ただし、これらのエクスポートはあくまで二次的なものであり、真の価値は動的で探索可能なHTMLにあります。Archifyの機能の詳細については、GitHubリポジトリをご覧ください: tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. - GitHub
この記事が気に入ったら、毎朝同じようなものをメールで受け取れます。
1日1通 · 2クリックで解除 · サードパーティのトラッキングなし
Archifyの習得：プロンプト、落とし穴、そしてPR
Archifyは、具体的かつ限定的な質問をしたときに最も優れたパフォーマンスを発揮します。「このリポジトリをマップして」といった曖昧な指示は避けてください。通常、役に立たない結果が返ってきます。代わりに、「キャッシュミス時のユーザー認証フローを図解して」といった正確な質問をし、明確さと焦点を保つためにノード数を8〜12個程度に制限することをお勧めします。このターゲットを絞ったアプローチにより、意味のある検証済みの出力が保証されます。
ただし、Archifyは万能なソリューションではありません。GitHubはインタラクティブなHTML出力をレンダリングしないため、GitHubのREADMEに直接埋め込む単純な図には適していません。また、このツールはスタンドアロンのアプリではなく、Claude CodeやCursorなどのプラットフォームを使用した既存の「AIエージェントワークフロー」にエージェントスキルとして統合する必要があります。
重要な局面において、Archifyは真価を発揮します。その検証済みでインタラクティブな出力は、開発の重要な段階における「検証可能な成果物」となります。主な用途は以下の通りです：
- PRレビュー用のアーキテクチャ図を生成し、変更の差分を明確にする。
- 設計ドキュメント内で新機能を設計する。
- リポジトリ内のシステムコンポーネントに対する、信頼性が高くコミット可能な「信頼できる唯一の情報源（source of truth）」を確立する。
このアプローチにより、図は静止画像から信頼できる編集可能なシステムマップへと進化し、エンジニアリングプロセスに欠かせない要素となります。
よくある質問
Archifyとは何ですか？
Archifyは、ClaudeのようなAIコーディングエージェントが検証可能でインタラクティブなアーキテクチャ図を生成できるようにするオープンソースのエージェントスキルです。エージェントがシステムの構造化されたJSON表現を作成し、Archifyがそれを検証して自己完結型のHTMLファイルにコンパイルする仕組みで動作します。
Archifyはどのようにして不正確な図を防いでいますか？
AIに画像を「描かせる」のではなく、Archifyは厳格な検証パイプラインを強制します。AIはスキーマに準拠した型付きのJSONグラフを出力しなければなりません。JSONが無効であったり、不可能な状態を記述していたりする場合、プロセスは明確な診断メッセージとともに失敗し、誤解を招く図の作成を防ぎます。
Archifyと連携できるAIエージェントは何ですか？
Archifyはエージェントスキルとして設計されており、Claude Code、Cursor、Codex CLI、OpenCode、DeepSeek Harnessなど、いくつかの人気のあるコーディングアシスタントと統合できます。
ArchifyはMermaidの代わりになりますか？
PRや設計レビューで使用される、AI生成のインタラクティブで検証可能な図に関しては、Archifyの方が優れた機能を提供します。しかし、GitHubのREADMEに直接埋め込む単純な図の場合、MermaidはGitHubによってネイティブにレンダリングされるため、より手軽な選択肢となることが多いです。