把程式碼庫變成可驗證的系統地圖：Archify 如何讓 AI 生成的架構圖不只好看

當團隊請 AI「畫一張系統架構圖」時，最常見的結果不是不能看，而是不能信：元件可能漏掉，箭頭可能只是視覺上的猜測，圖表更新後也很難知道到底改了什麼。tt-a1i/archify 選擇的路線不同。它不是另一個 Mermaid theme，也不是一般繪圖編輯器，而是一個讓 coding agent 產生 typed JSON intermediate representation（IR），再由 Node.js 工具鏈以可重現方式驗證、編譯成 HTML/SVG 的 Agent Skill。

本文以 GitHub 上的 Archify 原始碼與官方文件為查證基礎，拆解它的工作模型、驗證閘門、互動式閱讀方式，以及它適合放進日常開發流程的原因。文中的指令與功能描述以 2026 年 9 月 11 日查詢到的 main 分支與 README 所列的 v2.17.0-dev.1 為準；GitHub 星數會隨時間變動，當時約為 58,020 顆。

先說結論：Archify 解決的是「溝通可信度」

Archify 的核心價值不在於把方塊排得更漂亮，而在於把「圖上宣稱的關係」變成可檢查的資料。它的流程可以濃縮成五步：

Agent 根據描述或 repository source 產生 typed JSON IR。
Validator 檢查 schema、layout、HTML/SVG、route 與標籤和路線的間距。
通過檢查的 IR 被渲染成 self-contained HTML，並可匯出 PNG、SVG、WebM 或 1200×630 share card。
使用者在圖上搜尋節點、追蹤 authored upstream/downstream reach、檢查精確路線，或播放有限的 guided story。
下一次修改只替換通過驗證的產物；若候選版本失敗，預覽仍保留上一個 last-good artifact。

這個設計把 AI 的不確定性放在「產生候選 IR」階段，並把交付責任交給 deterministic checks。它不會讓 AI 自動知道線上系統的真實流量，也不會憑空推論風險；它只呈現已被寫入並通過規則檢查的拓撲。

安裝：把 Skill 接到 coding agent

Archify 的 README 提供最短安裝路徑：

npx skills add tt-a1i/archify -g

官方列出的整合對象包含 Cursor、Claude Code、Codex CLI 與 OpenCode。若只是想試用，也可以不先安裝到全域環境：

npx skills use tt-a1i/archify@archify --agent codex

安裝完成後，不需要先準備一個 repository 才能開始。直接在 Agent 對話中描述系統即可：

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

如果需要 source evidence，則先開啟 repository，再要求 Agent 分析原始碼並建立 high-level runtime architecture diagram。官方 quick start 建議限制核心元件數量、指定 primary path、外部依賴與 trust boundaries，並把支援細節放進 cards，而不是無限制增加連線。

五種圖表類型，對應五種問題

Archify 沒有把所有東西都塞進同一種 architecture diagram，而是把閱讀目的拆開：

Architecture：回答有哪些元件、服務、儲存與邊界。
Workflow：回答 CI/CD、審批、工具呼叫與 runbook 的順序、分支和例外。
Sequence：回答一次 API 呼叫、cache fallback、認證或非同步互動如何隨時間展開。
Data Flow：回答資料從哪裡來、如何轉換、存在哪裡，以及 PII 或其他敏感邊界在哪裡。
Lifecycle：回答狀態、等待、重試、取消與終止結果如何流動。

這個分法很實用。若把部署拓撲、請求時序、資料血緣與失敗重試全放在一張圖，讀者最後通常只剩下「看起來很複雜」的印象。先決定要回答的問題，再選 diagram type，才有機會把圖變成溝通工具。

驗證閘門：漂亮不是交付條件

Archify 的 README 把 validation 描述成 atomic validation before delivery。實際工作流不是「render 一次就完成」，而是候選結果必須依序通過規則，才會取代最後一個可信版本。常用指令如下：

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

失敗時，validate --json 與 deliver --json 回傳包含 stable rule code、subject、measured evidence 與 supported fixes 的診斷資料。這一點比直接看到 Node stack 或讓 Agent「再試一次」更重要：修復動作被限制在診斷明確支援的範圍內，而且官方文件也要求視覺檢查另外進行，不把自動規則當成設計審查的替代品。

Archify 也提供 preview 模式。它只在 loopback 介面監看單一 JSON 檔案，候選版本通過所有閘門後才重新載入；若儲存內容不完整或驗證失敗，畫面維持上一個 verified diagram。對正在修改架構圖的開發者來說，這比預覽畫面閃成半成品更適合長時間迭代。

Architecture Delta：把 PR 審查從「找差異」變成「讀變更」

架構圖最容易失效的時刻，往往不是第一次產生，而是系統改版之後。Archify 的 Architecture Delta 接受 validated Before、Delta、After snapshots，將變更整理為 added、removed、changed、moved 與 rerouted facts，並產出 machine receipt。

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

這不等於自動判斷「這個 PR 安全」或「這個改動一定會影響哪個服務」。Archify 明確把 impact、risk 與 merge safety 留在使用者判斷範圍內。它做的是把 authored facts 的差異整理乾淨，讓審查者先看變更本身，再決定要追哪些程式碼、測試與部署證據。

互動功能的關鍵：不虛構拓撲

靜態圖片只能展示結果，Archify 的互動 viewer 則把閱讀操作限制在已編寫的節點與關係上。README 列出的功能包含：搜尋 nodes、開啟 revision-verified source、追蹤 authored upstream/downstream reach、檢查 exact routes、比較 semantic roles，以及播放有限的 named chapters。

這裡的限定詞很重要：是 authored reach，不是 runtime impact；是 exact route，不是模型臨場補出來的可能路徑；是 revision-verified source，不是模糊地附上一個 repository 連結。當圖表缺少 deployment ownership、region placement、private database scope 或 named crossings 時，deployment-ownership profile 會 fail closed，而不是自行假設答案。

官方 Proof Lab 目前包含 11 個 checked-in scenarios、JSON source、named views 與 validation receipts。這些範例可以用來觀察同一份結構如何支援 guided story、route probe 和 semantic lens，而不必把每一種閱讀目的重新畫一張圖。

從 repository 取證：有邊界地使用 AI

如果要讓圖表包含原始碼證據，Archify 的設計是將 Architecture nodes 標記為 SRC n，再開啟固定在單一 public commit 的 Git-verified files 與 line ranges。這種做法適合 code review 或 onboarding，因為讀者可以從圖上的元件回到具體檔案與行號。

但它仍然不是 runtime observability。即使 source analysis 找到一條函式呼叫鏈，也不代表線上所有流量都會經過那條路；即使圖表通過 validator，也不代表部署環境的權限、網路政策或資料品質已經被驗證。比較穩妥的做法是把 Archify 當成 source-grounded communication artifact，並在文章、PR 或設計文件中清楚標示查證的 commit 和範圍。

一個適合團隊落地的最小流程

可以從一個不依賴真實 repository 的小案例開始：

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

接著採用以下節奏：

先用一句話定義圖表要回答的問題。
在對話中生成第一版 typed JSON IR。
用 validate --json 取得可機器處理的診斷。
只依 diagnostics[] 裡的 supported fixes 修復，並保留修復輪數上限。
以 deliver 產生與 JSON 同目錄的 HTML，提交 JSON 與 validation receipt。
讓 reviewer 進行獨立的視覺檢查與 source review。
下一次改動以前一版 validated snapshot 作為 Before，產生 Architecture Delta。

這套流程特別適合需要跨職能溝通的情境：後端工程師可以檢查 route，平台工程師可以檢查邊界，產品或管理者則可以用 guided story 先理解主流程，而不必先讀完整個 repository。

限制與採用前檢查

Archify 的限制同樣值得寫進評估報告：

它不是 general-purpose drawing editor，不能取代需要自由繪圖的工具。
它不會自動讀取 live infrastructure，也不應被當成 runtime topology 或 impact analysis 系統。
deployment-ownership 等嚴格 profile 可能因證據不足而拒絕交付；這是 fail closed 的預期行為，不是單純的 UI 錯誤。
圖表品質仍取決於 prompt、source 範圍與 authored IR；deterministic renderer 能穩定地呈現輸入，不能替團隊補上不存在的架構決策。
README 所列版本為 development version，導入正式流程前應鎖定版本，並在 CI 中保存 JSON、receipt 與輸出檔案。

結語：讓架構圖成為可審查的產物

AI 生成架構圖真正的問題，從來不只是排版。當圖上的箭頭會被誤讀、系統改動沒有可比較的基準、預覽會展示未完成的候選內容時，團隊需要的是一個對「哪些事可以宣稱」有明確邊界的工具鏈。

Archify 的答案是 typed JSON IR、deterministic rendering、atomic validation、last-good preview 與 source evidence。它沒有承諾替你理解所有線上行為，反而把這個限制說清楚。對正在使用 Cursor、Claude Code、Codex CLI 或 OpenCode 的團隊而言，這種「讓 Agent 產生候選、讓規則決定能否交付」的模式，比單純追求一張更華麗的圖更值得借鑑。