Archify

npx skills add tt-a1i/archify -g

# Cursor へ非対話で入れる（明示指定）
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

# 試し打ち（永続インストールなし）
npx skills use tt-a1i/archify@archify --agent codex

--agent は cursor / codex / claude-code / opencode に対応する。エージェント別の正確なコマンドは クイックスタートの切替ページで確認できる。プロジェクトページは tt-a1i.github.io/archify。

1 枚でリポジトリ全体を説明しようとせず、見たい観点を 1 つ選ぶ。どれを選ぶか迷ったら、CLI に聞ける。

node bin/archify.mjs guide "Show an API request with Redis cache miss"
node bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

Mermaid 入力

貼られた Mermaid を機械パースして描画するのではなく、構造だけ読んで archify スタイルで置き直す。flowchart → workflow（またはコンポーネントなら architecture）、sequenceDiagram → sequence、stateDiagram → lifecycle。スタイル指定は捨て、トポロジと意味だけ残す。

5 モードとも同じループ。レンダラのソースを触らず、診断が指した箇所だけ JSON を直して再実行する。

flowchart TD
  A["Generate typed JSON IR"] --> B["validate --quality showcase --json"]
  B -->|diagnostics| E["診断された subject だけ直す"]
  E --> B
  B -->|pass| P["preview（任意 / last-good ループ）"]
  P --> D["deliver（原子的に置換 + 受領書）"]
  B -->|pass| D
  D --> V["visual-check（ブラウザ実測）"]
  V --> R["人による知覚レビュー"]
        

可読性は「全依存を矢印で描くこと」ではなく、1 本の物語が辿れる配置から来る。

1. 主経路は 1 本 — 枝は主経路の最近傍ノードから出す。ルーティング制御を足す前に、価値の低いエッジを削る。
2. ラベルは意味データ — 衝突したらまずラベルを移し、経路と間隔を調整し、最後に意味を保ったまま短くする。削除は幾何の修復ではない。両端点から完全に自明で、プロトコル・動作・方向・同期性・境界越えの情報を含まない場合だけ省く。
3. 間隔は「空き」で測る — 中心間距離ではなく実際のクリアランス。ラベルの空きは実測マスク幅を超えていること。
4. 自動経路は端点の面を所有する — 面は方向の契約で、最初と最後のセグメントはその面に垂直に出入りする。診断が求めるまで via / channelX / channelY / labelAt を書かない。1 回の修復で足す幾何制御は 1 つまで。
5. 詳細はカードへ — ポリシーや技術メモは summary cards に置き、矢印を増やさない。不透明な無関係ノードを横切るエッジ、曖昧な共有通路、他の経路を覆うラベルは受け入れない。

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
node bin/archify.mjs visual-check /tmp/workflow.html --json

コマンドの役割

生成 HTML の操作

設計レビューや PR レビューでは、検証済みの architecture スナップショット 2 つを比べる。compare は両方を独立に検証し、authored な安定 ID だけでコンポーネントと関係を対応付け、追加・削除・変更・移動・経路変更を分けて分類する。

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

• 削除されたノードと関係は元の座標を保ち、移動したノードは MOVE FROM のファントムを残す。端点が変わった関係は旧経路と新経路の両方を出す。
• + / ~ / − / ↔ と線種で意味を示すので、色やモーションに依存せず読める。
• 整形・キー順・要素順・wraps・sources の集合的な変更はセマンティックハッシュと成果物バイト列を変えない。失敗時は前の成果物が残る。
• リポジトリの不一致、共有コンポーネント ID がゼロ、関係 ID の欠落、境界キーの曖昧さは fail closed。
• 成果物は AUTHORED SNAPSHOTS と表示し、リポジトリ証拠のゲートを両方通ったときだけ REVISION-PINNED INPUTS になる。

リポジトリは必須ではない。Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback. のように説明だけでも描ける。ソースを根拠にしたいときはリポジトリを開いて次のように頼む。

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

フロー特化

Use archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->
Redis session lookup -> PostgreSQL fallback. Make the cache-miss path secondary.

データ系譜

Draw a data-flow diagram from Web and Mobile events through Consent Gate, Kafka,
Warehouse, and Feature Store to Dashboards and ML consumers. Mark the PII boundary.

チャットでの修正は JSON IR を残したまま「add Redis」「move auth to the left」のように局所変更する。

• GitHub: tt-a1i/archify — 本体リポジトリ
• プロジェクトページ
• Proof Lab — 検査済み 11 シナリオと JSON ソース、検証受領書
• シナリオガイド — 図タイプの選び方
• SKILL.md — エージェント向け手順
• schemas/README.md — JSON IR 契約
• authoring-cookbook.md — 作図クックブック
• CHANGELOG.md — v2.16.0 までの変更履歴
• Cocoon-AI/architecture-diagram-generator — フォーク元（MIT v1.0）
• vercel-labs/skills — インストールに使う skills CLI