Claude Codeで構成図を作るArchifyを調べてみた

Archifyについて調べてみた

Claude Codeで構成図を作れるという Archify が気になり、公開資料を読んでみました。

コードを読ませた結果が図になるなら、引き継いだシステムを理解するときに使えそうだと感じたためです。

先に触れておくと、今回は調査メモです。インストールやClaude Code経由の図生成は実行していません。

導入手順と依頼文は、次に試すためのものとして記載します。

Archifyとは

最初に確認したのは、Claude Code本体の機能なのかという点でした。

今回調べたのは、GitHubの tt-a1i/archify です。

Claude Codeに追加して使う外部のAgent Skillで、Anthropicが提供する組み込み機能ではありません。構成の説明やコードの分析結果をもとに、単一のHTMLファイルとして図を生成します。

ArchifyのREADME に、配布元と仕組みが記載されています。

Claude Code側のSkillsは、指示やスクリプトをまとめて追加できる仕組みです。プロジェクト内の .claude/skills/ などに配置して読み込ませます。

Archifyもこの仕組みを使っています。Claude CodeのSkillsドキュメント を読むと、本体との役割の違いが分かりやすくなりました。

調査中に少し迷ったのが、バージョンです。

検索結果には 2.13 や 2.15、開発版の説明が混在していました。

2026年8月31日に確認したREADMEと CHANGELOG では、8月30日公開の v2.16.0 が安定版です。

HTMLの前に、図の元になるJSONを作ります

仕組みを読んで引っかかったのは、図になるまでの工程でした。

Claude Codeなどのエージェントが、構成要素や接続関係を型付きのJSONに整理します。Archifyは、そのJSONを検証してHTMLやSVGへ変換します。

READMEでは、この中間の表現を JSON IR と呼んでいます。

構成の説明・コードの分析結果
  ↓
エージェントが図の仕様をJSONで作成
  ↓
Archifyが形式やレイアウトを検証
  ↓
HTMLとして出力

JSONが残るので、後から図を修正するときも元の仕様に戻れます。

同じ入力を描画する工程と、AIが構成を解釈する工程が分かれている、と理解しています。

図の種類は5つあります。Skillの定義 にある分類を、自分が使う場面に置き換えると次のようになります。

たとえば、Lambdaとデータベースの位置関係を見たいなら architecture です。

タイムアウト後の処理を追いたいなら、sequence や lifecycle に分けたほうが確認しやすそうです。

導入するなら、まずプロジェクト内に置きます

公開手順をもとに、Claude Codeだけを対象にしたコマンドを整理しました。

以下は未実行の手順例です。Node.jsと npx を使える環境を前提にしています。

対象リポジトリのルートで実行します。

npx skills add tt-a1i/archify --skill archify --agent claude-code --copy

skills は、外部のSkillを導入するためのCLIです。

--agent でClaude Codeを指定し、--copy でシンボリックリンクではなくファイルをコピーします。--global を付けなければ、プロジェクト単位の導入になります。

skills CLIのオプション で確認しました。

私なら、最初は全プロジェクトに適用しません。どんな指示とスクリプトが入るのかを、検証用リポジトリで確認したいためです。

実行前に、配布元の SKILL.md と同梱スクリプトも読んでおきます。

配置後は、次のパスを確認します。

.claude/skills/archify/SKILL.md

環境確認には、同梱CLIの doctor が案内されています。

node .claude/skills/archify/bin/archify.mjs doctor

現行のSkillでは、配布パッケージ内で追加の npm install は不要とされています。

古い説明にある依存パッケージの導入手順を、そのまま足さないようにします。Setup and fallback が確認先です。

最初の依頼は、AWSの小さな構成に絞ります

最初から業務リポジトリ全体を描かせると、図の出来とコードの読み取り精度を同時に確認することになります。

まずは正解が分かっている、小さな仮想構成で試したいと思いました。

次の内容は、実在するシステムの構成ではありません。Archifyへの依頼例です。

Archifyを使って、次の仮想構成をarchitecture図にしてください。

利用者がAPI Gatewayへリクエストし、API GatewayがLambdaを呼び出します。
LambdaはDynamoDBへデータを保存します。

図のタイトルと説明は日本語にしてください。
指定していないサービス、認証方式、VPC構成は追加しないでください。
アニメーションは不要です。
図の元になるJSONとHTMLを、docs/architecture/に保存してください。
検証結果と、表示を実際に確認したかどうかも報告してください。

VPCや認証方式まで追加しないようにしたのは、描画の確認に設計の提案が混ざるのを避けたいためです。

業務の構成図でも、確認できた事実と「こうしたほうがよい」という提案は分けておきたいです。

リポジトリを読ませる段階では、依頼を次のように変えます。

このリポジトリのAPI入口、永続化処理、デプロイ設定を確認してください。
確認できた構成要素と接続関係だけを、Archifyで図にしてください。
主経路は一つに絞り、主要な構成要素は8個以内を目安にしてください。

根拠にしたファイルと行番号は、別のMarkdownに記録してください。
コードだけでは分からない設定は推測で補わず、未確認事項として残してください。
アプリケーションのコードは変更しないでください。

Archifyの 作図ルール にも、実コードを扱う場合は入口や保存先、デプロイ設定を確認する方針があります。

検証済みの図でも、構成の確認は残ります

Archifyの検証が扱うのは、JSONの形式や、図の配置、線とラベルの干渉などです。

出力時の仕様 では、自動チェックと目視確認も分けられています。

スクリーンショットを取得できたことだけで、見た目の確認が完了したとは扱いません。

ここは、使う前に整理しておきたい点でした。

きれいにつながった矢印でも、そもそもコードの読み取りを間違えていれば、違う構成を表してしまいます。

私が確認するなら、入口から保存先までの経路を一つ選びます。矢印ごとに呼び出し元と呼び出し先をたどり、図と一致するかを見ます。

8個以内という依頼も、その確認を自分でできる範囲に収めるためです。

変更前後の図を比較する Architecture Delta も用意されています。

ただし、比較するのは検証済みのスナップショットです。影響範囲やマージの安全性を自動判定するものではないと、READMEの説明 でも明示されています。

PRレビューで使うなら、変更点を探す補助として見たいです。図に差分がないことを、影響がない根拠にはしないと思います。

日本語で共有するときに確認しておきたいこと

図のラベルと、操作画面の言語は別です。

v2.16.0 のViewer UIが対応する言語は、英語と簡体字中国語です。

日本語のタイトルや説明は作成できますが、固定の操作UIは英語へフォールバックします。言語設定の仕様 に記載されています。

日本語で依頼すれば、画面全体が日本語になると思い込まないほうがよさそうです。

社内で共有する場合は、まずラベルの長さと読みやすさを確認したいです。

生成されたHTMLには、検索や拡大縮小などの操作が含まれます。画像として書き出すこともできますが、どの形式を渡すかは用途で分けるつもりです。

Viewerの仕様 も確認しました。

どちらの場合も、内部ホスト名や顧客名を残していないかは共有前に確認します。

次は小さな図を一つ作って確認します

調べてみて、私が試したいのは、引き継ぎ資料の最初の一枚を作る用途です。

図の元になるJSONと、コードを読んだ根拠を残せるなら、後から修正するときにも使いやすそうだと感じました。

まだ生成結果は評価できていません。

ここまで読んでいただき、ありがとうございます。もしこの記事の技術や考え方に少しでも興味を持っていただけたら、ネクストのエンジニアと気軽に話してみませんか。

• 選考ではありません
• 履歴書不要
• 技術の話が中心
• 所要時間30分程度
• オンラインOK

エンジニアと話してみる