Archifyは、システムの説明文や既存のMermaidから、機械検証を通した構成図を単一HTMLで生成するAgent Skillだ。本記事はv2.16.0時点の使い方と、手元で動かして数えた検証の中身をまとめる。エージェント基盤そのものの選び方は AIエージェントフレームワーク比較2026|LangGraph・CrewAI・Dify等9種をStar数・実コードで検証 をご覧ください。
30秒でわかるArchify
- ・導入は
npx skills add tt-a1i/archify -gの1行。Claude Code・Codex CLI・Cursor・OpenCodeに同時対応するAgent Skill - ・エージェントは型付きJSON(JSON IR)を書くだけ。描画と検証はNode.js CLIが決定論的に行う
- ・
showcase品質では9項目の幾何チェックを全通過しないと出力されない - ・Architecture Deltaで2つのスナップショットを Before / Delta / After で差分表示できる
- ・依存パッケージはゼロ(Node.js 18以上だけ)。MIT。2026-09-04時点で45,821★
Archifyとは:Claude専用のzipスキルから4エージェント対応へ
Archifyが生成するのは「アーキテクチャ図」「ワークフロー図」「シーケンス図」「データフロー図」「ライフサイクル図」の5種類。リポジトリはtt-a1i/archifyにある(archify github で辿り着きたい場合もこのURLが正)。
初出時点(2026年5月)は213スターの小さなプロジェクトだったが、2026年9月4日 09:55 JST にGitHub APIで実測した時点で45,821スター・2,937フォークまで拡大していた。増加が集中したのは2026年8月末で、README冒頭のTrendshiftのバッジからGitHub Trendingに乗ったことも確認できる。日次の増加数は認証なしのAPIでは遡れないため、途中のペースは断定しない。
THEN AND NOW初出時からの変化
初出時(v2.4)の理解は、v2.16.0 ではほぼ入れ替わった
初出時(2026年5月)
2026-09-04 の実測
初出時(2026年5月): Claude.ai に zip を上げる専用スキル
2026-09-04 の実測: npx skills add で4エージェントに配置
初出時(2026年5月): Claude が SVG を直接組み立てる
2026-09-04 の実測: JSON IR を CLI がコンパイル
初出時(2026年5月): JSON IR は v3.0 のロードマップ
2026-09-04 の実測: 実装済み・9項目の検証つき
初出時(2026年5月): 内包される JS は約3KB
2026-09-04 の実測: JS 479KB の対話アプリ
現在の公式READMEはArchifyを「Cursor・Claude Code・Codex CLI・OpenCode向けのNode.jsレンダリング/検証システム」と定義している。topicsにもcodex・opencode・deepseek-harness・mermaid-alternativeが並ぶ。「Claude Skill」の枠で理解していると、対応範囲を実際より狭く見積もることになる。
より本質的な変化は内部設計だ。初期版は「Claudeが直接SVGを組み立てる」構成で、図の品質はモデルの推論に依存していた。いまは二層に分かれている。
AGENT WRITES JSON二層の構成
エージェントは描かない。JSONを書き、CLIが検証して描く
-
説明文・Mermaid
ユーザーの入力
-
エージェント
型付きJSON IRを書く
-
validate
9項目の幾何チェック。不合格は診断つきで差し戻し
-
render
決定論的にコンパイル
-
単一HTML
PNG / SVG / WebM / 共有カードも
同じJSONからは同じ図が出るので、モデルの機嫌で配置が変わらない。生成物をリポジトリに置いて差分を取ることに意味が出て、後述のArchitecture Deltaもこの性質の上に成り立っている。
Archifyの使い方:インストールから最初の図まで
現在の推奨は次の1行だ。-gはグローバル導入で、リポジトリローカルに入れたい場合は外す。
npx skills add tt-a1i/archify -g
skillsはVercel Labsが公開しているnpmパッケージ(”The open agent skills ecosystem”、執筆時点の最新は1.5.23)。この配布経路自体はArchify固有ではなく、Googleが公式Agent Skillsリポジトリを公開した流れの中で標準化が進んでいる(Skillは標準仕様になる|Googleが公式Agent Skillsリポジトリを公開、npx skillsで何が変わるか)。
本記事での検証範囲
- ・
npx skills addそのものは、実行環境のネットワーク制限で未実行 - ・かわりに、npmレジストリで
skillsの実在と版(1.5.23)を確認し、リポジトリをgit cloneして配置されるスキル本体(archify/)とCLIの動作を実測した。後述の数値はすべて後者の結果
| エージェント | 配置先 | 対応範囲 |
|---|---|---|
| Claude Code | ~/.claude/skills/ または .claude/skills/ |
レンダラ+検証の全機能 |
| Codex CLI | ~/.agents/skills/ または .agents/skills/ |
全機能。v2.13.0で第一級サポートと明記 |
| opencode | ~/.config/opencode/skills/、.opencode/skills/、.agents/skills/ |
全機能 |
| Cursor | skills CLIが出すグローバル/プロジェクト別コマンドに従う |
全機能。v2.13.0で「First-class Cursor onboarding」 |
| Claude.ai | Settings → Capabilities → Skills からarchify.zipをアップロード |
サンドボックスのNode.js実行可否に依存 |
| Project Knowledge | プロジェクトにarchify.zipをアップロード |
プロンプト駆動のフォールバック |
検証とレンダリングは node bin/archify.mjs という実プロセスが担う。Claude CodeやCodex CLIはローカルでNode.jsを起動できるので全機能が使えるが、Claude.aiはサンドボックス次第だ。検証機能を目当てにするならCLI系エージェントを選ぶのが確実だ。公式は「one portable archify/SKILL.md」を保つ方針で、エージェントごとに増えているのは配置先と導入コマンドだけ。v2.15.0ではDeepSeek Harness向けの任意統合(dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0)も入ったが、公式は「DeepSeekの公式製品ではない」「開発者プレビュー版 @deepseek-ai/dsh@0.1.0-rc.6 向けのコミュニティ統合」と明示している。1つのスキルを多数のエージェントへ配る設計は、Agent Skill全体の潮流でもある(Agent Skill Creator解説|スキルを自動生成し17プラットフォームへ配るOSSの品質ゲートを実測)。
READMEは「No repository is required」と明言している。チャットで構成を説明するだけでよい。
Reactフロントエンド、Node.js API、PostgreSQL、Redisキャッシュ、AWSでホスト。
この構成のアーキテクチャ図を archify で作って。
直すときも「Redisを左へ」「認証サービスをマゼンタに」「Kafkaを追加」と伝えれば、エージェントがJSONを書き換えて再検証する。SVGではなくJSONを編集するので、修正のたびに検証がやり直される。SKILL.md の description は入力として「pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input」も受け付けると書いており、Mermaidの図資産は貼るだけで移せる。
実測:依存ゼロ・9項目の検証・出力HTMLの中身
検証環境は macOS(Darwin 23.5.0、Apple Silicon)/Node.js v22.13.1/git clone --depth 1 した v2.17.0-dev.1(安定版最新は v2.16.0)/2026-09-04。npm install を一切せず、node_modules が無い状態で始めた。
node bin/archify.mjs doctor
node bin/archify.mjs validate architecture examples/checkout-platform.head.architecture.json --quality showcase --json
node bin/archify.mjs compare architecture examples/checkout-platform.base.architecture.json examples/checkout-platform.head.architecture.json out.html --json
MEASURED実機で数えた
依存ゼロのまま、9項目の検証を通った図だけが出る
16/16
doctor の [ok]
node_modules 無しで実行
9項目
showcase の幾何チェック
errors 0 / warnings 0
694KB
出力の単一HTML
外部参照は Google Fonts のみ
doctor は16項目すべて[ok]。archify/package.json の dependencies は実際に空で、ajv などは devDependencies 側にある。validate が返した9つのチェックは次のとおり。
| チェック名 | 何を見ているか |
|---|---|
single_svg / finite_svg |
<svg> がちょうど1つか/座標に有限でない値が無いか |
orthogonal_arrows |
矢印が直交しているか |
label_route_clearance |
ラベルと経路が十分離れているか |
relationship_crossings / relationship_corridors |
関係線が不要に交差していないか/通り道が曖昧でないか |
container_border_runs |
線がコンテナの枠に沿って走っていないか |
route_rhythm |
折れ・伸び・線分長のリズムが崩れていないか |
legend_clearance |
凡例が他要素と干渉していないか |
composition は status: "pass"、errors: 0、warnings: 0、properCrossings: 0、maxBends: 2、minLabelRouteClearance: 55、minSegmentPx: 20。SKILL.mdは「4項目しか報告されない受領書は基本検証であってshowcase合格ではない」と警告している。スキルの品質を外から測る試みにはMicrosoftの評価フレームワークもあるが(Microsoft Waza|Agent Skillsの品質を測るGo製評価フレームワークを解説)、Archifyはスキル自身が出力ゲートを内蔵している。
render の出力HTMLは次のとおり。
| 実測項目 | 値 |
|---|---|
| 出力サイズ | 710,931バイト(約694KB、単一ファイル) |
| 内訳 | JavaScript 479,162B / CSS 186,015B / インラインSVG 18,875B |
<script> / 外部<img> / @import |
4個(すべてインライン)/ 0件 / 0件 |
| 外部ホストへの参照 | fonts.googleapis.com・fonts.gstatic.com のみ |
prefers-color-scheme の出現 |
7箇所 |
| レンダリング所要時間 | 約0.3秒(ウォームアップ後・N=3の中央値) |
clone直後の初回だけは4〜6秒かかったが、これはNode起動とモジュール初回ロードのコストだ。ウォームアップ後に standard と showcase を交互に3回ずつ回すと中央値は375msと291msで、ばらつき(262〜413ms)に埋もれる差だった。出力バイト数は全6回で一致した。品質プロファイルはレンダリング時間を実質変えない(単一入力・N=3の範囲での結論)。初出時に書いた「内包されるJSは約3KB」は現在は誤りで、ノード検索・経路プローブ・ガイド付きストーリー・共有カード生成が入った結果、単一ファイルで動く小さなアプリになっている。
compare(Architecture Delta、v2.13.0)はウォームアップ後N=3の中央値0.96秒。受領書には両スナップショットのrawSha256とsemanticSha256、components: added 1 / changed 1 / removed 1 / moved 1、completeness: "complete"、proofLevel: "authored"が並んだ。
+ / ~ / − / ↔と線種で示され、色や動きに依存せず読める。出典: tt-a1i/archify(MIT)CHANGELOGはこの機能について「リスク・影響範囲・安全性・マージ可否・検証済みPR影響を主張しない(never claims risk, blast radius, safety, mergeability, or verified PR impact)」と書く。出すのは作者が書いた事実の変化だけだ。v2.13.0の「Revision-verified Repository Evidence Passport」を使えば、各コンポーネントをリポジトリURL・完全なコミットSHA・1〜3個の相対パスで実ソースへ結び付けられる(--repo-root を渡すと、origin・コミット・blob・行範囲を検証してからリンクを出す)。未固定の証跡とプライベートリポジトリは意図的に対象外だ。
5種類の図の使い分けと対話機能
| 種類 | 向いている対象 | プロンプトに含めるとよい情報 |
|---|---|---|
| Architecture | コンポーネント・サービス・ストレージ・境界 | スコープ、主要コンポーネント、主経路 |
| Workflow | CI/CD、承認フロー、ツール呼び出し、運用手順 | 参加者、順序、分岐、例外 |
| Sequence | API呼び出し、キャッシュフォールバック、認証、非同期トレース | 呼び出し元、呼び出し先、戻り、タイミング |
| Data Flow | パイプライン、データリネージ、個人情報、利用先 | ソース、変換、保存先、境界 |
| Lifecycle | 状態、リトライ、待機、終了状態 | 状態、イベント、リトライ・キャンセル経路 |
迷ったら node bin/archify.mjs guide "Show an API request with Redis cache miss" のようにCLIに聞ける。出力HTMLの479KBのJSは、v2.12.0〜v2.16.0で入った読解支援を担っている。
・Node Finder — ノード名で検索して絞り込む
・Authored Reachability — 上流/下流を推移的にたどり、ノード数・リンク数・最大ホップ数を出す。#focus=<id>&reach=upstream でURL共有もできる
・Semantic Passport — ノードの役割・種別・検証済みソースへのリンク
・ガイド付きストーリー — 作者が定義した章を順に再生する
・Reach Share Card — 探索結果から1200×630のPNGを書き出す
Reachabilityの説明にも「作者が書いた到達可能性であって、影響範囲・破壊・リポジトリへの影響・実行時の因果ではない」とある。図が語るのはJSONに書かれた事実までで、そこから先は推測しない。
Mermaid・diagrams.netとの比較と、いまの制約
| 観点 | Archify | Mermaid | diagrams.net | Lucidchart | PlantUML |
|---|---|---|---|---|---|
| 入力 | 自然言語/既存Mermaid(JSON IR経由) | 独自構文 | GUI操作 | GUI操作+AI | 独自構文 |
| 出力の検証 | 9項目の幾何チェック(showcase) | なし | なし | なし | なし |
| 決定論性 | 同じJSONから同じ出力 | 高い | 手作業依存 | 手作業依存 | 高い |
| 差分比較 | Architecture Delta(受領書つき) | テキストdiff | ファイル比較 | 版履歴 | テキストdiff |
| 成果物 | 単一HTML(約694KB)+PNG/SVG/WebM/共有カード | SVG(レンダラ必要) | 各種 | 各種 | 各種 |
| 依存 | Node.js 18以上のみ | JS実行環境 | アプリ/Web | SaaS | Java |
| ライセンス | MIT | MIT | Apache 2.0 | 商用 | GPL |
mermaid-alternative というtopicは付いているが、実際には併用が自然だ。MermaidはREADMEやIssueに数行で埋め込める手軽さと可搬性で勝るが、線が交差しても凡例が重なっても止まらない。Archifyが向くのは、何度もレビューされ、更新され、他人に説明される図だ。「Mermaidで下書きして、清書と検証をArchifyに任せる」流れも成立する。diagrams.netやLucidchartは表現力で上回るが、テキストから起こす・差分を機械的に取る・CIに載せるといった自動化はしにくい。Archifyは作図ツールというより、構成情報をコードとして扱うためのコンパイラに近い。
初出記事はv2.4(2026-04-18)を対象にしていた。最新はv2.16.0(2026-08-30)、開発版は v2.17.0-dev.1 だ。
| バージョン | 日付 | 主な追加 |
|---|---|---|
| v2.12.0 | 2026-07-23 | Last-Good Live Preview(preview)。実リポジトリを題材にした検証済み事例 |
| v2.13.0 | 2026-08-03 | Architecture Delta、リポジトリ証跡パスポート、Cursor第一級対応、構造化された修復受領書 |
| v2.14.0 | 2026-08-11 | visual-check によるファーストスクリーン検証、ビューアUIの整理 |
| v2.15.0 | 2026-08-17 | 107個の出所付きブランドマーク、DeepSeek Harness配布 |
| v2.16.0 | 2026-08-30 | Workflow schema v2の制約駆動コンパイラ、ビューアUIの多言語化(en / zh-CN)、更新通知のみのバージョン確認 |
いま押さえておきたい制約は次のとおり。
・Claude.aiアップロード版は全機能を保証しない(Node.jsプロセスに依存)
・ビューアUIの多言語化はen / zh-CNのみ。meta.locale を指定しなければ英語UI。図の中のラベルは日本語でよい
・出力HTMLは約694KB。静的サイトに多数を埋め込むなら転送量を意識する
・Architecture Deltaは危険度を判定しない。マージ可否の判断材料にはならない
・開発版と安定版が並走。READMEは v2.17.0-dev.1、Releasesの最新安定版はv2.16.0。どちらが入るかを確かめる
来歴は、Cocoon AI社のarchitecture-diagram-generator v1.0(MIT)を出発点とするfork rewriteで、SKILL.md にも based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0) とある。THIRD_PARTY_NOTICES.md も同梱。2026年8月時点でスポンサーが付いており、READMEにはAPINEBULA(アフィリエイトリンクと割引コード付き)とEverMindの記載がある。OSS自体はMITのままだが、READMEに商用リンクが混在している点は認識しておきたい。
参照ソース
- tt-a1i/archify — GitHubリポジトリ(README / CHANGELOG / SKILL.md、MIT、2026-09-04時点で45,821★)
- Archify プロジェクトページ(公式サイト・シナリオガイド・Proof Lab)
- skills — npmパッケージ(vercel-labs、v1.5.23、
npx skills addの提供元) - Cocoon-AI/architecture-diagram-generator(Archifyのfork元、MIT v1.0)





