返回列表
2026年10月13日 上午01:00

Archify：把架構討論變成可驗證的系統地圖｜GitHub雷達

原始影片

學習筆記：Archify：把架構討論變成可驗證的系統地圖｜GitHub雷達

TL;DR

Archify 透過將系統描述轉化為可驗證的 Typed JSON IR，並結合 Renderer、Validator 及可追溯的交付流程，將架構討論從模糊的圖片進化為可互動、可驗證且能持續演進的系統地圖。

快速結論

Archify 旨在解決團隊在架構討論中常見的「腦中各有圖、討論失焦」的問題。它透過將原始的 Codebase 或系統描述轉換成結構化的 Typed JSON IR，並由 Renderer、Validator 協作，最終輸出可互動、可驗證的 Artifacts。這使得架構圖不再只是單純的靜態圖像，而是成為一個能被驗證、追溯，並能與設計審查、PR Review 等流程整合的動態系統地圖。

Archify 支援五種不同類型的技術圖，涵蓋 Architecture、Workflow、Sequence、Data Flow 和 Lifecycle，分別從不同角度描繪系統的結構、流程、資料流向與狀態變化。這些圖表的呈現不僅包含視覺元素，更重要的是保留了背後的結構、關係、預設故事與互動資料，確保了其可驗證性。

Viewer 功能讓使用者可以互動式地探索系統元件，理解其關係、元數據，甚至追蹤其可達性。Delta 功能則能有效地分辨新增、變更、移動等差異，特別適用於設計審查或 PR Review，讓團隊能基於明確的差異進行討論。Archify 的價值在於將架構討論成果轉化為可打開、可查詢、可驗證、可再修改的系統地圖，而非僅止於一張漂亮的截圖。

Archify 較適合用於跨團隊設計討論、需要將圖表整合到文件或報告、或希望將 AI 理解結果轉化為可驗證檔案的場景。導入 Archify 的關鍵在於，團隊需要有使用結構化來源、願意進行工程化描述的文化，並清楚定義討論範圍，避免試圖涵蓋整個 Codebase。

這支影片在說什麼

這支影片介紹了 Archify 這個開源工具，它旨在解決傳統系統架構討論中，因圖表缺乏來源、難以追蹤更新而導致的失焦問題。Archify 將系統描述轉化為結構化的 Typed JSON IR，再透過 Renderer 和 Validator 產生可互動、可驗證的系統地圖。影片適合對軟體架構溝通、系統設計、以及如何讓 AI 對系統有更精確理解的開發者、架構師或技術領導者。

最重要的 3-5 個重點

  1. 將架構討論從靜態圖片轉化為可驗證的系統地圖： Archify 透過產生 Typed JSON IR，保留了系統的結構、關係、互動資料，並結合 Validator 確保其可信度，讓架構討論有可驗證的依據。
  2. 支援多種類型的系統圖，提供不同視角： Archify 支援 Architecture、Workflow、Sequence、Data Flow、Lifecycle 等五種圖，從結構、流程、資料流、狀態等多角度描繪系統，滿足不同層次的討論需求。
  3. 互動式 Viewer 和 Delta 功能增強溝通效率： Viewer 讓使用者能互動式探索系統元件及其關係，Delta 功能則能精確標示變更，大幅提升設計審查和 PR Review 的效率。
  4. Archify 的價值在於交付可驗證、可互動的系統知識，而非僅僅美化圖表： 它強調將討論結果轉化為可打開、可查詢、可驗證、可再修改的 Artefact，作為團隊共同的系統知識。

知識架構

  • 問題根源： 架構討論失真 (圖表無來源、難更新、與需求脫節)
  • Archify 解決方案：
    • 核心機制： Codebase/系統描述 -> Typed JSON IR -> Renderer + Validator -> Artifacts
    • Artifacts： 可互動、可驗證的系統地圖
  • 核心組件：
    • Typed JSON IR: 保留結構、關係、預設故事、互動資料
    • Renderer: 產生 HTML/SVG 等格式
    • Validator: 檢查 IR，提供結構化錯

誤訊息

  • 支援的圖表類型 (五種)：
    • Architecture (結構、服務、信任邊界)
    • Workflow (流程、審批、例外)
    • Sequence (請求流程)
    • Data Flow (資料來源、轉換、消費)
    • Lifecycle (狀態、等待、結束)
  • 互動與協作功能：
    • Viewer: 搜尋節點、聚焦元件、查看關係與元數據、追蹤可達性
    • Route Probe: 僅看作者定義的 Path，避免誤解依賴
    • Delta: 分辨新增、變更、移動，用於設計審查/PR Review
    • Viewer Story: 以有限動畫引導使用者走完特定 Path
  • 應用情境：
    • 跨團隊設計討論
    • 將圖表整合到文件 (README, Reports)
    • AI 理解結果的驗證與記錄
  • 導入考量：
    • 不適合一次性圖表繪製
    • 適合有工程文化、願意用結構化來源描述的人
    • 需清楚描述範圍，避免涵蓋整個 Repo
    • 非通用繪圖工具
  • 記憶點：
    1. JSON IR 固定技術事實
    2. Validator/Renderer 確保可信度
    3. 互動輸出與交付整合為一 Artefact

關鍵概念

  • Typed JSON IR (Intermediate Representation): Archify 的核心，將系統描述轉換為結構化的 JSON 格式，保留了系統的結構、關係、預設故事和互動資料，是可驗證的基礎。
  • Renderer: 將 Typed JSON IR 轉換為可視化輸出，如 HTML 或 SVG，生成使用者可互動的圖表。
  • Validator: 負責檢查 Typed JSON IR 的結構和邏輯，確保其正確性和可信度，並提供結構化的錯誤回饋。
  • Artifact: Archify 最終輸出的成果，可視為一個可互動、可驗證的系統地圖，包含圖表、元數據和驗證資訊。
  • Architecture Diagram: 描繪系統的服務、儲存、信任邊界等結構性關係。
  • Workflow Diagram: 展示系統的流程、審批、例外處理等動態執行路徑。
  • Sequence Diagram: 說明一次 API Request 等特定操作如何跨多個元件執行。
  • Data Flow Diagram: 描繪資料從來源、經過轉換、到最終被消費的整個生命週期。
  • Lifecycle Diagram: 關注元件或系統的狀態變化，例如等待、執行、結束等。
  • Viewer: Archify 提供的一個互動式介面，讓使用者可以搜尋、聚焦、查看元件的詳細資訊、關係和可達性。
  • Route Probe: 一種導航功能，僅顯示作者明確定義的路徑，避免將圖表上的視覺路徑誤解為實際依賴。
  • Delta: 一項功能，用於比較不同版本的系統描述，清晰標示新增、變更、移動的部分，特別適用於設計審查和 PR Review。
  • Viewer Story: 一種引導模式，透過預設的動畫路徑，帶領觀眾走過特定的系統流程或路徑。

重要例子與細節

  • 架構討論失真的情境： 團隊成員腦中有各自的圖，白板化後截圖，隔天又回到各說各話。
  • IR 保留的資訊： 結構、關係、視覺預設、故事、互動資料。
  • Validator 的錯誤回饋： 非簡單的 Note 或 Stack Trace，而是結構化的錯誤訊息，指出是哪個 Subject、哪條路徑、支援哪些修改。
  • Preview 功能： 在本機 loopback 模式開啟，適合邊改邊看；失敗時保留上一張好圖。
  • Viewer 的互動操作： 搜尋節點、聚焦單一 Compon

ent、查看關係與 Metadata、追蹤上下游的 Reachability。

  • Delta 的用途： 分辨新增 components、變化、移動，方便對照 "Before" 和 "After"，用於設計或 PR Review。
  • Archify 的限制：
    • 不適合一次性的圖表製作。
    • 不適合不懂工程化描述、不願用結構化來源的人。
    • 需要清楚定義討論範圍，避免將整個 Repo 塞入。
    • 不是通用的繪圖工具。
  • Agent 產圖的可信度： Archify 可將 AI 對系統的理解結果，轉化為可打開、可查、可驗證的檔案，而非僅留在對話記憶中。

可學習的洞察

  • 架構溝通的本質是知識傳遞與驗證： 好的架構工具不僅要能繪製，更要能確保資訊的準確性、可追溯性與可協作性。
  • 結構化是可驗證的基礎： 將非結構化的系統描述轉化為結構化的中間表示 (IR)，是實現自動化驗證、互動性展示與後續分析的關鍵。
  • 動態與互動性是未來圖表的趨勢： 靜態圖表已不足以應對複雜系統的討論，結合互動功能 (Viewer, Delta) 能顯著提升溝通效率。
  • 定義清晰的範圍與應用場景至關重要： Archify 的價值體現在特定情境，而非萬能工具，這提醒我們在引入新工具時，需評估其是否符合實際需求。
  • AI 在工程中的應用，需要驗證與落地： AI 產生的架構理解，需要透過工具轉化為可驗證的 Artefact，才能真正融入工程流程。

可行動的整理

  1. 評估團隊現有的架構討論模式： 是否存在資訊失真、難以追蹤更新的問題？
  2. 探索 Archify 的 GitHub 專案 (tt-a1i/archify)： 了解其具體實現方式和使用範例。
  3. 考慮在小範圍的跨團隊設計討論中試用 Archify： 驗證其在 Delta、Viewer 等功能上的實用性。
  4. 若使用 AI 輔助架構設計，思考如何將 AI 的輸出轉化為 Archify 的 IR： 以確保 AI 理解的可驗證性。
  5. 定義團隊進行架構討論或文件編寫的結構化標準： 確保產出的資訊具備可驗證性，即使未使用 Archify。

複習問題

  1. Archify 主要解決了傳統架構討論中的哪些痛點？
  2. Typed JSON IR 在 Archify 的架構中扮演什麼角色？它提供了哪些資訊？
  3. Archify 支援的五種技術圖分別關注系統的哪些面向？
  4. Viewer 和 Delta 功能各自提供了什麼樣的互動能力，對團隊溝通有何幫助？
  5. 在什麼樣的情境下，Archify 的價值會比較明顯？又有哪些情境不適合導入？

待確認資訊

  • 無明顯待確認資訊。

觀看原始影片