Archify 是什麼？Claude Skill 讀程式碼畫互動架構圖，實測每個方塊都對回原始碼行號

懶人包

• Archify 是 GitHub 上的開源 agent skill（tt-a1i/archify，Apache-2.0，2026-10-27 查約 8.97 萬星，最新 v3.2.0）。AI 讀程式碼寫出一份 JSON，Archify 再把它驗過、渲染成單檔互動 HTML 架構圖。
• 我拿自己的 LINE → 本機 Claude Code 管線 line-talk 實測：14 個元件、16 條連線、3 張說明卡，從 clone 到四道檢查全過約 4 分鐘，finalize 本身只跑 5 秒。
• 圖可以點：點一個方塊，相關的線亮起、其他變淡，側欄列出它對應的原始碼檔名和行號。另有 4 種風格、深淺色，能匯出 PNG、SVG、WebM 動畫。
• 它會擋錯：版面放錯邊界、沒附 repo 資訊、repo 的 origin 對不上，都會讓 finalize 直接失敗，不會默默出一張錯圖。
• 限制：它是一次性快照，程式碼改了要重畫；私有 repo 的圖會嵌入 repo 網址和 commit，公開前要另外去敏。

這篇的起點是 pinkjhs.life 在 Facebook 發的一支 Reel（我看到時 3.6 萬次觀看）。影片裡作者裝了一個叫 Archify 的 Claude Skill，只下一段指令叫它讀前端、後端兩個資料夾，三分鐘出一張系統架構圖，示範的是作者八月歐遊用的旅遊規劃網頁。

我想知道兩件事：這張圖是 AI 憑印象畫的，還是真的對得回程式碼？換成我自己的專案，要花多少功夫？所以我把 repo clone 下來，拿我每天在用的 line-talk 跑了一次。

影片版（YouTube Shorts）

〈AI 讀完程式碼，自己畫出可以點的架構圖〉

〈我用 Archify 畫出這支影片的製作流程〉

Archify 是什麼？

Archify 是一個給 AI coding agent 用的 skill，官方 README 寫支援 Claude Code、Codex CLI、Cursor、OpenCode。它不自己讀程式碼；讀程式碼的是你的 agent，Archify 負責規格、驗證和渲染。

1. agent 讀程式碼，寫出一份有型別的 JSON spec：元件、邊界、連線、說明卡，每個元件可以附 sources（檔名、起訖行號）。
2. 跑 node bin/archify.mjs finalize，依序過四關：validate（schema 和版面規則）→ deliver（產出 HTML）→ check（嚴格檢查）→ browser-check（用真的 Chrome 開起來量）。
3. 四關全過才算交付，產物是一個自包含的 HTML 檔，不需要伺服器。

怎麼安裝 Archify？

README 給的安裝指令是一行：

npx skills add tt-a1i/archify -g

-g 是裝到使用者層級，Claude Code 會放在 ~/.claude/skills/。不想用 npx skills 的話，README 的安裝表也寫了可以直接把 repo 裡的 archify/ 資料夾放到 ~/.claude/skills/ 或專案的 .claude/skills/。

我這次沒有裝成全域 skill，只把 repo clone 到工作目錄，直接跑裡面的 CLI。先確認環境：

git clone https://github.com/tt-a1i/archify.git
cd archify/archify
node bin/archify.mjs doctor

doctor 每一項都回 [ok]，最後一行是 Archify is ready.。我的環境是 Windows 11、Node v24.11.1、Chrome 裝在預設路徑。

實測：把 line-talk 讀成架構圖

line-talk 是我自己的服務：手機在 LINE 傳文字、網址、圖片或錄音，經 Cloudflare Tunnel 進到家裡的 Windows，本機用 Bun 收 webhook，分流給聊天 lane 或背景任務，背景任務再開 claude -p 子程序做事，最後把摘要推回 LINE。

我讓 Claude Code 讀了 server.ts、claude.ts、jobs.ts、line.ts、store.ts、ticker.ts、admin.ts 和安裝腳本，照 Archify 的 schema 寫出 candidate.json。下面是其中一個元件，sources 指到真正的函式範圍：

{
  "id": "jobs",
  "type": "messagebus",
  "label": "背景任務佇列",
  "sublabel": "jobs.ts 一次一件",
  "pos": [808, 560],
  "size": [150, 64],
  "sources": [
    { "path": "jobs.ts", "line": 78, "end_line": 91, "label": "pump" },
    { "path": "jobs.ts", "line": 150, "end_line": 193, "label": "runJob 收尾" }
  ]
}

整份 spec 是 14 個元件、1 個邊界（本機 Windows）、16 條連線、3 張說明卡。接著跑 finalize，--repo-root 指向被畫的 repo，讓它拿 sources 回去核對：

node bin/archify.mjs finalize architecture candidate.json line-talk-architecture.html \
  --repo-root ../line-talk --quality showcase --json

第一次被 validate 擋下來，第二次四關全過：

{
  "status": "pass",
  "gates": {
    "validate": "pass",
    "deliver": "pass",
    "check": "pass",
    "browser-check": "pass"
  },
  "diagnostics": [],
  "durationMs": 4944
}

時間上，從 clone Archify 到四關全過，檔案時間戳是 01:15 到 01:19，約 4 分鐘；大部分花在 agent 讀碼和寫 spec，finalize 只跑了 4.9 秒。產出的 HTML 是 862,706 bytes。

browser-check 用的是本機 chrome.exe，在 1440×900、1600×1000、1920×1080、2048×1320 四種視窗下檢查元件有沒有跑出邊界、深淺主題切換、文字可讀性和工具列。

圖上可以做什麼？

點「背景任務佇列」之後，跟它有關的 6 條線亮起來，其他元件變淡。左側面板寫著「已驗證來源」，列出 jobs.ts L78–91 和 L150–193，下面是上游 6、下游 4，以及每條出入向連線的名稱。

右上角的控制列有四組功能：

Archify 怎麼確保圖沒畫錯？

這是我覺得它跟「叫 AI 畫一張 Mermaid」差最多的地方。這兩次實測，它一共擋了我三次：

後兩個是溯源規則：只要元件宣稱自己對應到某段原始碼，spec 就得釘住是哪個 repo、哪個 commit（schema 規定 revision 必須是 40 碼十六進位），而且 finalize 會拿 --repo-root 那份 repo 實際比對。所以面板上那行「已驗證來源 jobs.ts L78–91」不是 AI 自己寫上去的標籤，是 CLI 對過的結果。

它沒擋的是語意本身：元件該不該存在、連線方向對不對，還是由寫 spec 的 agent 決定。checker 驗的是「這張圖跟它宣稱的來源一致、版面沒有騙人」，不是替你理解系統。

私有 repo 的架構圖可以公開嗎？

可以，但要多做一步。spec 裡的 link_mode: "local-only" 只是不產生可點的 GitHub 連結，HTML 裡還是會印出 repo 網址和 commit hash。line-talk 是私有 repo，圖上也有內部埠號。

這篇文章裡的圖，是我另外做的去敏版：

1. 複製一份 spec，把節點上的埠號改成「webhook」「只綁本機」這類描述。
2. meta.repository.url 改成 https://example.com/your-name/line-talk.git。
3. 另外 clone 一份 line-talk，checkout 同一個 commit，用 git remote set-url origin 把 origin 改成同一個佔位網址，讓 origin-mismatch 這關照樣驗得過。
4. 重跑 finalize，四關全過（5.8 秒），再截圖。

Archify 適合什麼、不適合什麼？

適合：

• 專案交接、盤點：每個方塊都對得回原始碼行號和 commit，接手的人可以順著點回去看。
• 教學和 demo：「AI 讀碼 → 被 validator 擋 → 修 → 出圖」整條鏈看得見，比直接給一張成品圖有說服力。
• README 和簡報的圖：PNG 3740 寬，SVG 有深淺兩版。

• 當即時監控或活文件：它是某個 commit 的快照，程式碼改了要重畫。
• 想要完全自動排版：座標由 agent 寫在 spec 裡。這次通過的版本還留一條可選提示，說 jobs → LINE 回覆那條線要轉 3 個彎；SKILL.md 寫明只跟彎數有關的提示可以不理。
• 給 AI 自己查程式碼：那是 CodeGraph 或 Graphify 的工作，它們把整個專案建成可查詢的圖；Archify 產的是給人看的、經過語意分層的圖。

自己跑一次的最短路徑

1. 裝 skill：npx skills add tt-a1i/archify -g，或把 archify/ 資料夾放進 ~/.claude/skills/。
2. 在要畫的 repo 根目錄，對 Claude Code 說：「用 archify 畫這個 repo 的 architecture，每個元件附原始碼行號」。
3. 讓它跑完 finalize，看 receipt 裡四個 gate 是不是都 pass；有失敗就讓它讀診斷修 spec，不要接受沒過關的 HTML。
4. 要公開的話，先照上一節去敏，再重跑一次 finalize。