從零建一個完整 Agent 工作流（上）：架構藍圖

不是堆功能，是建系統

我統計過自己半年來的使用紀錄：平均每天對 AI 重複解釋「我是誰」3.2 次，每次花 2 分鐘，光這件小事就讓人煩躁。半年累積下來，單是「自我介紹」就燒掉超過 16 小時。這就像每天走進辦公室，同事全都失憶了，於是你得重新說一遍自己的名字、座位在哪、負責什麼專案。

你可能也這樣用 AI Agent：遇到問題，開對話，丟指令，拿結果，關掉；下次再開，又得重新解釋你是誰、你要什麼，每次都像第一次見面，久了確實讓人疲乏。

我用 Claude Code 工作半年，最大的體悟只有一個：把 AI 當「對話工具」用，等於浪費了它 90% 的能力，就像買了一棟大樓卻只用大廳會客，連電梯都沒搭過，更別提樓上的辦公室、檔案室、保全系統。一旦把它當成「可配置的系統」來設計，效率差距就不是百分比能形容的了。

我說的 AI Agent 架構藍圖，是一套分層設計的系統框架：它把 AI Agent 的行為拆解成身份、記憶、路由、守門、跨平台、安全六個獨立層次，各層各司其職又彼此連動，讓 AI Agent 從「一次性工具」長成「可累積、可擴展、可信賴的工作夥伴」。

這是「從零建一個完整 Agent 工作流」的上集，專注架構設計，下集（T10）才進入實作部署。先說清楚，這套架構不是白板上畫出來的理論，因為它支撐著我日常橫跨研究、開發、教學的工作，每天都在跑，已經跑了半年。

六層架構全景圖

想像你要蓋一棟大樓：地基打好才能立骨架，骨架穩了才能拉水電，水電通了才能做裝潢，裝潢完才能裝保全，最後才是對外通道，讓分公司也能用同一套管理系統。AI Agent 的六層架構，邏輯一模一樣。

先拉遠看全貌，細節留待後面逐層拆解：

┌─────────────────────────────────────────────────┐
│                  使用者（人類）                    │
├─────────────────────────────────────────────────┤
│  第六層：安全層（Safety Layer）                    │
│  ── 10 條底線規則 + 聖域保護 ──                    │
├─────────────────────────────────────────────────┤
│  第五層：跨平台層（Cross-Platform Layer）          │
│  ── 單一真相源 + symlink 分發 ──                  │
├─────────────────────────────────────────────────┤
│  第四層：守門層（Gate Layer）                      │
│  ── Hook 系統 + 品管攔截 ──                       │
├─────────────────────────────────────────────────┤
│  第三層：路由層（Routing Layer）                   │
│  ── Skill / SOP 自動派發 ──                       │
├─────────────────────────────────────────────────┤
│  第二層：記憶層（Memory Layer）                    │
│  ── 三層記憶架構 ──                               │
├─────────────────────────────────────────────────┤
│  第一層：身份層（Identity Layer）                  │
│  ── CLAUDE.md / AGENTS.md / BOOT.md ──           │
└─────────────────────────────────────────────────┘

每一層職責明確，往上的層依賴往下的層，卻不跳層：路由層讀記憶層的資料來決定派發目標，守門層讀安全層的規則來判斷攔截條件。分層最大的好處在於，就像大樓改裝潢不用動骨架，你可以單獨改某一層，其他層完全不動。上週我重構了整個記憶層的檔案格式，路由層跟安全層就完全零影響。

先把範圍講清楚。這六層講的是「一個 Agent 怎麼被建起來」的核心架構。如果你後來養出好幾個 Agent，要處理誰接哪種任務、哪種活該用貴的模型、哪種丟便宜的跑，那是另一套多 Agent 編排的東西，疊在這六層之上。這篇不談那個。先把一個 Agent 建紮實，再談怎麼指揮一支隊伍。

第一層：身份層 -- 大樓的門牌與地基

身份層是整棟大樓的門牌，訪客第一眼看到的就是這裡叫什麼、做什麼、歸誰管。它負責回答三個問題：你是誰的助手、行為準則是什麼、工作環境長什麼樣。少了它，每次對話都是白紙，你得反覆交代語言、路徑、偏好，時間就被一點一點吃掉。

在 Claude Code 裡，這三個問題常拆成三個檔案（名稱因平台而異，重點是職責分開，而不是檔名本身）：

檔案	職責	比喻
CLAUDE.md	專案入口與行為規範	員工手冊
AGENTS.md	角色、技能、語言與協作規則	職位說明書
BOOT.md	啟動時要知道的路徑與身份	開機設定

身份層把「永遠成立的前提」固化成檔案，讓 AI 啟動時自動載入。你不必每天到公司重新自我介紹，AI 也不該如此。它是所有層的起點：記憶層的偏好、路由層的 Skill 索引、安全規則的引用，往往都從這裡掛上去。實作上，CLAUDE.md 用 @ 匯入語法拉入其他設定，例如：

# 專案層 CLAUDE.md 示意
@AGENTS.md               # 角色與規範，跨後端共用的單一真相源
# 啟動與記憶入口多半在全域層掛入
# 其餘欄位省略

設計原則： 身份層應維持低變動頻率。若你發現自己頻繁改它，多半代表某些內容該移到記憶層或路由層。

第二層：記憶層 -- 大樓的檔案室

記憶層是大樓裡的檔案室。少了它，AI 沒有持久記憶，每一次對話都得從頭重新認識你。

我把記憶拆成 三層記憶架構：一種將 AI Agent 的持久化知識分成事實記憶（fact）、情節記憶（episodic）、暫存記憶（scratchpad）三個層級的設計模式，每一層有各自的讀寫頻率、生命週期與用途。

記憶層	內容	生命週期	讀寫頻率
事實記憶（fact）	使用者偏好、工具設定、專案索引	長期穩定	讀多寫少
情節記憶（episodic）	過去的決策、失敗、里程碑	持續累積	只追加、偶爾讀
暫存記憶（scratchpad）	當前任務的筆記、中間狀態	任務結束即過期	頻繁讀寫

上週跟 AI 討論技術選型，花了 40 分鐘分析三個方案，最後選定方案 A；這週繼續開發、提到同一個功能時，AI 卻重新分析一次，還改口建議方案 B。原因很簡單，它不記得上週的決策，那 40 分鐘等於白花。

有了記憶層，三層各司其職：

• 事實記憶記結論（此專案用方案 A）
• 情節記憶記決策過程（為何選 A、否決了什麼）
• 暫存記憶記當下狀態（目前做到哪一步）

分層是為了效率：平常只讀事實記憶就能掌握當前狀態；追問「當初為什麼」才翻情節記憶；暫存更短命，任務結束就能丟。路由層也會查這裡的 SOP 清單與工具偏好來決定派發；核心記憶檔則常被安全層列為「聖域」，不讓 AI 隨意改。

設計原則： 什麼該記、什麼不該記，是記憶層最難的決策。記太多，載入變慢、被雜訊淹沒；記太少，又會重複犯錯。我的判斷標準很簡單：同一件事對 AI 說了兩次，就該寫進事實記憶，是兩次而不是三次。

關於記憶系統的完整設計，可以參考 AI Agent 記憶系統設計：三層架構實作。

第三層：路由層 -- 大樓的電梯控制系統

這一層我花最多時間打磨，因為投資報酬率最高。

路由層就像大樓的電梯控制系統：你丟一個任務進來，它根據觸發詞自動載入對應的 SOP 與 Skill，讓 AI 用正確流程處理。概念上就是一張「觸發詞 → 工作流」的派發表，欄位怎麼長因系統而異，示意如下：

# SOP 派發表示意
triggers:
  科普:
    sop: PopSci_Writing_SOP
    # 其餘欄位省略
  # 文獻、簡報等同理：一觸發詞對一條完整管線

我把這套機制叫 Skill 路由引擎：一套觸發詞驅動的任務派發系統，讓 AI Agent 根據使用者輸入自動匹配對應的 SOP 模板與技能模組，省去每次手動指定工作流程的步驟。

沒有路由層的日子我過過。那時每次請 AI 寫科普，都要交代一長串：用哪個模板、先做文獻搜尋、按什麼格式寫、最後跑去 AI 感管線。我把步驟做成筆記、每次複製貼上，卻常漏步驟或貼到上個月的舊版流程。

現在我只要說「寫科普」三個字就好，路由層辨識觸發詞後自動載入完整 SOP、模板與所需技能，指令從 200 字壓到 3 個字，效率提升超過 50 倍，而且每次流程一致。

路由層向下讀記憶層（派發表與偏好常存在那裡），向上被守門層監控，Skill 執行中的工具呼叫都要過 Hook。

設計原則： 粒度最容易踩坑。分太粗，例如只分「寫作」與「程式」，SOP 就泛到沒用；分太細，光維護派發表就飽了。我的經驗是按「工作流類型」來分，一個觸發詞對應一條完整管線，目前大約 15 條就夠日常。

關於路由層的詳細設計，可以參考 Skill 路由引擎：讓 AI 自動選擇正確工作流。

第四層：守門層 -- 大樓的門禁閘門

光靠設定檔裡的規則並不夠。這就像只把「禁止進入」貼在門上，卻沒裝門禁刷卡機，結果誰都能闖進來。

AI 在長對話中會偏離規則。對話超過 50 個來回之後，前面寫的「禁止 rm」它可能就「忘了」，這不是規則變懶，而是被長對話稀釋掉了。守門層提供硬性攔截：不管 AI 怎麼想，試圖執行被禁止的動作就擋下來。

在 Claude Code 裡，這層通常靠 Hook 系統，概念上有兩個攔截點：

Hook 類型	觸發時機	用途
PreToolUse	工具呼叫前	擋危險操作、檢查參數
PostToolUse	工具呼叫後	掃敏感輸出、核對結果

安全規則像紙上的規章，守門層是實體門禁。你不能只靠自律保證安全，真正的邊界得由機制強制執行。它執行安全層定義的「什麼不能做」，也會對照記憶層的聖域清單；路由層觸發的 Skill，每一步工具呼叫都要過這道關。

設計原則： Hook 要精準、要快。別在 Hook 裡做複雜語意分析，那會拖慢每一次工具呼叫；做簡單模式比對就好，例如看到 rm 就擋，而不是請模型「分析是否危險」。

關於 Hook 系統的完整實作，可以參考 Hook 守門系統：AI 寫的每一行 code 都過品管。

第五層：跨平台層 -- 總部對分公司的統一管理

你可能不只用一個 AI 工具：終端機用 Claude Code，IDE 裡用 Copilot，偶爾也用 Gemini CLI。若每個工具各自設定與記憶，就像三間分公司各自訂員工守則，總部管不到。

跨平台層的做法不是翻譯，而是「同一份規章」：總部只留一本，各分公司牆上掛的是指向那一本的連結，不是各自抄副本。技術上，把 AGENTS.md 當唯一真相源，其他後端設定以 symlink 指過去，改一次，多處同時生效。

單一真相源（AGENTS.md）
    │
    ├── CLAUDE.md ──→ @AGENTS.md（Claude Code 原生展開）
    │
    ├── symlink ──→ ~/.codex/AGENTS.md（codex 原生讀取）
    │
    ├── symlink ──→ ~/.grok/AGENTS.md（grok 原生讀取）
    │
    └── symlink ──→ ~/.hermes/AGENTS.md（hermes 原生讀取）

我採用的 跨平台單一真相源，是把 AI Agent 的核心設定（身份、偏好、規則）集中在一份檔案，再由各平台以 symlink 或原生匯入指向它，這樣無論使用哪個 AI 工具，讀到的都是同一份規則、行為一致。

實際痛點是：你在 Claude Code 調教好台灣繁體中文與工具偏好，一切卻在切到另一個工具的那一刻歸零。跨平台層只負責分發，不自己發明規則；它吃身份層與記憶層的內容，安全底線也一併注入各平台。

設計原則： 做「最小共同交集」。各平台能力差太大，1:1 全同步不現實；我搞了兩天才想通，先注入語言偏好、安全底線、關鍵路徑，平台特有能力（如 Hook）接受差異，用兩成力氣解決 80% 需求。

關於跨平台同步的詳細做法，可以參考 多平台同步：一套記憶跑遍 Claude/Copilot/Gemini。

第六層：安全層 -- 大樓的保全系統

安全層是整棟大樓的保全系統，不是獨立模組，而是滲透每一層。核心是一份「不可違反規則清單」，定義 AI 在任何情況下都不能跨越的行為邊界，再交由守門層的 Hook 自動執行。

AI Agent 的自主性是雙面刃：權限愈多，能幫的事愈多，出錯的破壞力也愈大。我有一次讓 AI 執行「清理暫存檔」，結果連設定檔一起清掉，整個環境只能打碎重來。這就像請清潔工打掃，他卻把保險箱合約拿去回收；從那次之後，我才認真設計安全層。

沒有安全層	有安全層
不敢讓 AI 動檔案系統	軟刪除 + 聖域保護，安心授權
不敢讓 AI 執行 git 操作	force push 攔截 + reset 確認，放心使用
不敢讓 AI 安裝套件	安全審查流程，有序引入
限制 AI 權限 → 效率低落	明確邊界 → 大膽委派

安全層定義「什麼不能做」，守門層負責「即時攔截」。它也決定記憶層哪些檔是聖域、哪些路由需要更高權限確認，並透過跨平台層同步到所有工具。

設計原則： 寧可漏放功能，不可漏放風險。系統早期規則設嚴，理解 AI 行為後再放寬。先鬆後緊的代價，通常是一次想砸鍵盤的事故。

關於安全規則的完整設計，可以參考 AI Agent 安全底線設計：我的 10 條不可違反規則。

六層之間的協作流程

講完六層，來看實際跑起來的樣子。假設你對 AI 說：「幫我寫一篇關於 NLRP3 inflammasome 的科普文章。」

1. 身份層：載入語言與角色前提，例如要用台灣繁體中文。
2. 記憶層：查事實記憶裡的寫作偏好、相關舊文、目標讀者。
3. 路由層：辨識觸發詞「科普」，載入對應 SOP、模板與去 AI 感技能。
4. 守門層：讀寫前檢查路徑是否合法、是否碰到聖域。
5. 跨平台層：中途換工具時，仍讀到同一套偏好與格式。
6. 安全層：全程擋住誤刪文獻庫、誤寄未完成稿、亂裝來路不明套件這類越界動作。

你只下了一句指令，12 個字，六層在背後各自運轉，就像按電梯時門禁與保全同時啟動，你甚至不必知道它們存在。

架構設計的三個核心原則

搞了半年，我歸納出三個原則，不是從教科書抄來的，而是踩坑踩出來的。

原則一：關注點分離

每一層只管自己的事：記憶層不管安全，安全層不管路由，路由層也不管記憶格式。聽起來像老生常談，但在 AI Agent 脈絡特別重要，因為你會一直想在某個設定檔裡「順便加一條規則」，這時務必忍住。我把事實記憶換過儲存格式，卻只動記憶層讀寫，其他層完全不受影響。

原則二：漸進式採用

不用一次建好六層，我自己也不是；這套架構本來就是逐步長出來的：

階段	建置內容	投入時間	效益
第一步	身份層	30 分鐘	不再重複說明偏好
第二步	記憶層	1-2 小時	跨對話累積知識
第三步	安全層	30 分鐘	防止破壞性操作
第四步	守門層（基礎 Hook）	1-2 小時	自動化安全檢查
第五步	路由層	2-3 小時	觸發詞自動載入工作流
第六步	跨平台層（單一真相源 + symlink）	1-2 小時	多工具一致體驗

前三步大約半天，就有一個「記得你是誰、會累積學習、不會自爆」的 AI Agent。後面三層是錦上添花，有空再加。

原則三：人類始終在迴圈內

架構再完善，最終決策權都要留在人類手上。「不可逆操作需確認」「聖域寫入需審核」「攔截後回報而非自動修復」，都在說同一件事：AI Agent 是你的助手，不是替身。

常見的架構錯誤

設計過程中踩的坑不少，這裡列幾個我親自犯過的：

把所有東西塞進 CLAUDE.md。 我的 CLAUDE.md 一度膨脹到 400 行，AI 載入變慢，前面的規則到後面全被「稀釋」。後來砍到 30 行，其餘拆到記憶層與路由層。經驗法則：超過 200 行就該拆。

記憶不分層。 偏好、決策、暫存全塞同一檔，就像長期合約跟便利貼共抽屜，AI 每次載入一堆不相關資訊，又慢又亂。

安全規則只靠 prompt。 在對話裡說「不要刪除檔案」，跟路邊立「請勿亂丟垃圾」差不多，形同虛設；它會逃脫沒有強制力的文字規則，所以需要 Hook 硬攔截。

過早最佳化路由。 只有 3-5 個工作流就上複雜匹配。起步用簡單字串比對就夠，超過 10 個再考慮進階路由。我前三個月都這樣，一樣活得好好的。

下集預告

以上是六層架構的設計藍圖。下集「從零建一個完整 Agent 工作流（下）：實作部署」會動手把六層建起來：身份與記憶骨架、第一張派發表、基礎 Hook、把 AGENTS.md 設成單一真相源並以 symlink 分發，再用一個完整任務驗收。

如果你等不及下集，可以先拿到架構藍圖的完整圖解和設定檔模板。

---

想更深入？

我整理了一份《AI Agent 記憶系統設計藍圖》。包含三層記憶架構的完整圖解、設定檔模板、以及記憶寫入規則範例。

免費下載記憶系統藍圖

下一篇：從零建一個完整 Agent 工作流（下）：實作部署