Archify教學手冊
Archify 教學手冊 一句話定位:Archify 是一個給 AI Coding Agent 使用的 Agent Skill,讓 Agent 把「Repository 證據 / 架構描述」轉譯成一份經過 Schema 驗證、可互動探索、可分享的自包含 HTML 系統地圖——重點不是畫一張漂亮的圖,而是產出一份可驗證、可追溯來源的架構視圖。 官方 Repository:https://github.com/tt-a1i/archify(MIT License) 查證版本:2.15.0(最新正式版)/2.16.0-dev.0(開發中版本,CHANGELOG.md 的 [Unreleased] 區塊;與 archify/package.json 的 "version": "2.16.0-dev.0"、archify/SKILL.md frontmatter 的 metadata.version: "2.16" 三方一致) 查證日期:2026-08-28(同日完成第二輪深度複查,新增 ROADMAP.md、archify/schemas/README.md 兩份官方一手來源,並修正前一版三處判斷落差,詳見「改版與修正紀錄」) 適用對象:Software Architect、Solution Architect、Technical Lead、Backend/Frontend/Full Stack Developer、DevOps/DevSecOps Engineer、SRE、QA、System/Business Analyst、PM、AI Coding Agent Developer、AI Engineer、Legacy System 維運與 Framework Upgrade 團隊 目的:讓企業開發團隊知道「何時該用、怎麼用、怎麼驗證、怎麼治理」Archify,並將其嵌入 AI Agent 驅動的 Web Application 開發、Legacy System Reverse Engineering、Framework Upgrade、Architecture Review、Code Review、SSDLC 工作流程 技術堆疊:Node.js(engines.node >= 18)+ 零相依 CLI(archify/bin/archify.mjs)+ 5 份 JSON Schema(開發期由 ajv draft 2020-12 預先編譯為 standalone validator,執行期不需 npm install 或網路)+ 5 個 typed Renderer + 自包含 HTML/SVG Viewer(4 種 Visual Preset、深/淺色主題);供 Cursor、Claude Code、Codex CLI、opencode、Raven、Claude.ai、DeepSeek Harness 等 AI Agent 環境使用 重要聲明(請務必先讀) 範圍與翻譯聲明:本手冊以繁體中文撰寫,技術名詞(Agent Skill、Typed JSON IR、Reverse Engineering、Architecture Delta、Repository、Schema、Validation、Renderer、Viewer 等)保留英文原文,以避免翻譯造成語意漂移。所有官方文件原文引用皆標明出處。 核心定位聲明:Archify 不是「一個 Mermaid 轉 HTML 的小工具」。它的核心價值在於讓 AI Agent 產生的架構圖,經過型別化(typed)JSON IR 與 Schema 決定性驗證(deterministic validation) 這兩層把關,避免 AI 把「想像的拓撲」當成事實輸出成一張看起來很專業、實際上與程式碼不符的圖。本手冊會反覆強調這個定位。 查證方法論:本手冊所有與 Archify 官方功能相關的敘述,皆透過直接抓取官方 Repository 原始檔案(raw.githubusercontent.com,包含 README.md、CHANGELOG.md、package.json、archify/SKILL.md、archify/bin/archify.mjs、archify/delta/architecture-delta.mjs 等)並交叉比對而來,而非僅憑單一頁面摘要。凡是「僅有單一來源」或「多來源有落差」的內容,一律用 §符號約定 的 Provenance 標籤明確標示,不會偽裝成確定事實。 版本落差澄清:查證過程中發現兩處尚未解決的來源落差——(a) v2.15.0 的正式發布日期,官方 CHANGELOG.md 原文寫 2026-08-17,另一個第三方摘要頁面寫 2025-08-17,兩者差一年,本手冊採用 CHANGELOG 原始檔案文字但同時標注此落差;(b) GitHub Star 數,兩個獨立來源收斂在「約 25k」,但另一第三方聚合站回報「13k」,本手冊僅標示「約 25k(未完全確認)」,不作為技術判斷依據。第二輪複查已解決前一版的三處落差(Cursor 支援層級、Typed JSON IR 的官方地位、JPEG/WebP 匯出格式),詳見「改版與修正紀錄」。 虛構案例免責聲明:第 Part VII、Part XIII 中的「企業案例」「銀行系統案例」為教學示範用途之情境案例,其中的系統名稱、公司背景、數據均為虛構,僅用來示範 Archify 的使用方法,並非真實客戶專案。 License 免責聲明:Archify 採用 MIT License,本手冊之引用僅供教學說明,實際採用前請自行確認官方 Repository 當下的 LICENSE 檔案與版本條款。 完整參考來源請見「References」章節,內含所有直接查證用的官方 URL。 時效性聲明:Archify 目前處於高頻迭代狀態(CHANGELOG.md 顯示 2.11 至 2.16-dev 之間平均約 1~2 週一個 minor 版本)。本手冊標示 🟢 的內容為 2026-08-28 當下的官方事實,企業若要將本手冊轉為內部正式規範,建議設定每季複查一次的機制(見第 29 章維護章節)。 改版與修正紀錄 本手冊採「可稽核更新」原則:每一次改版都必須列出修正了什麼、為什麼修正、依據哪一份一手來源,而不是默默覆寫舊內容。 ...