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

上集回顧，這集動手

想像一下：你花了 30 分鐘跟 AI 解釋專案背景、語言偏好、安全規則，好不容易產出一份漂亮的報告。隔天打開新對話，AI 卻問你：「請問你是誰？」87% 的人就是在這一刻放棄了 AI 協作。問題不在 AI 太笨，而在你沒有幫它蓋一間記得住事情的房子。

上一篇 從零建一個完整 Agent 工作流（上）：架構藍圖 裡，我把整套 AI Agent 系統的架構攤開來看：哪些模組該存在、彼此怎麼連動、資料流怎麼走。如果說那篇是建築設計圖，這篇就是施工手冊。

我把 Agent 工作流部署 定義成一套流程：把 AI 助手從「單次對話」升級為「持久化協作系統」，一路搭起房間格局（目錄結構）、開機鑰匙（身份設定）、大腦（記憶架構）、SOP 路由、守門員（Hook）與跨平台同步這六大層級。

我花了半年在 Claude Code 上反覆疊代，也踩了不少坑（詳見 我的 AI Agent 犯過的 7 個致命錯誤），最終收斂成七步驟部署流程。下面從空資料夾走到可運作系統，每步附目的、檔案示意與驗證方式。

Step 1：建立 Vault 房間格局

目的

所有東西都需要一個家。Agent 系統的第一步不是寫程式，而是決定「什麼東西放哪裡」，就像搬進新房子第一件事是規劃房間格局。因為目錄結構不只決定了 AI 能不能找到正確的檔案，也決定了你半年後還能不能維護這套系統。

實作

在你的工作目錄下建立以下結構：

mkdir -p MyAgent/{memory,scripts,docs}
mkdir -p MyAgent_iCloud/{_Agent_System/{10_Projects,30_Resources/{306_Writing,309_Templates},99_System},_User_Workspace/{01_Inbox,02_Tasks,03_Agent_Outbox}}

核心分區邏輯：

區域	用途	放什麼
memory/	Agent 的大腦	fact.yml、episodic.jsonl、scratchpad.md
scripts/	工具間	管線腳本、排程任務
docs/	設計文件	規格書、計畫書
_Agent_System/	Agent 運作資源	SOP 範本、專案資料、系統記錄
_User_Workspace/	人類工作區	待辦、收件匣、Agent 產出

這裡有一個關鍵設計：Agent 的運作資源和人類的工作區分開。AI 讀寫 _Agent_System/，人類主要操作 _User_Workspace/，因為一旦混在一起，檔案就會互踩、東西會被吃掉。這個分離能減少 90% 的檔案踩踏事故。兩邊只透過明確的介面（Inbox/Outbox）溝通：你把需求放進 Inbox，AI 取出來處理，成品再放回 Outbox，彼此不會互相踩踏。

驗證

tree -L 2 MyAgent/ && tree -L 3 MyAgent_iCloud/

先確認資料夾都在。若用 iCloud，Finder 未必即時，務必用 ls 確認 _Agent_System 已同步，不要只看 Finder。

Step 2：寫你的第一份 CLAUDE.md

目的

CLAUDE.md 既是 Agent 的開機鑰匙，也是它的身份證。Claude Code 每次啟動都會先讀這個檔案，就像員工第一天上班先翻員工手冊一樣，它決定了 AI 知道自己是誰、該遵守什麼規則、遇到問題去哪裡找資料。少了這個檔案，你每次對話都得從頭交代背景，時間全耗在重複的自我介紹上。

關於 CLAUDE.md 的設計哲學，可以參考 CLAUDE.md 設計哲學：讓 AI 記住你是誰。

實作

在專案根目錄建立 CLAUDE.md：

# CLAUDE.md -- 我的 AI Agent 設定

## 身份
- 你是我的個人 AI 助手
- 時區：GMT+8｜語言：台灣繁體中文

## 記憶路由
| 記憶類型 | 寫入位置 |
|---------|---------|
| 偏好/規則 | memory/fact.yml |
| 決策記錄 | memory/episodic.jsonl |
| 任務暫存 | memory/scratchpad.md |

## 安全規則
- rm 禁止：改用 mv 檔案 _DELETE_檔案
- API Key 嚴禁 hardcode；不可逆操作前必須取得許可
# 其餘工具偏好省略

@AGENTS.md

幾個重點：簡潔優先（每次對話都載入，太長就浪費 token，細節用 @ 匯入）；記憶路由表避免亂放；安全規則寫最上層確保第一時間讀到；共用規則（如 AGENTS.md）用 @ 拉出去做多平台共用。

驗證

啟動 Claude Code，請它說自己是誰、安全規則有哪些；答對就表示 CLAUDE.md 生效。

Step 3：建立 memory/ 三層大腦

目的

這是整套系統最關鍵的一步。memory/ 就是 Agent 的大腦，少了它，AI 每次對話都得從零開始。因為這裡的三層架構讓 AI 同時具備短期工作記憶、長期事實記憶與決策歷程記憶，就像人腦用便條紙、檔案櫃和日記本三種方式記東西。

詳細的記憶系統設計原理，請看 AI Agent 記憶系統設計：三層架構實作。

實作

建立三個核心檔案：

Layer 1：fact.yml（事實記憶）

# memory/fact.yml -- 長期事實與偏好
user:
  name: "你的名字"
  language: "台灣繁體中文"
  preferences:
    writing_style: "直接、不囉唆"
# 其餘 tools / projects 欄位省略

fact.yml 存放不太會變的資訊：你是誰、偏好什麼、正在做哪些專案，所以每當 AI 需要「了解你」，就會來讀這個檔案。

Layer 2：episodic.jsonl（情節記憶）

{"ts":"2026-05-27T10:00:00+08:00","type":"decision","summary":"選擇用 R 而非 Python 做統計分析，因為 ggplot2 圖表品質較好","tags":["tools","statistics"]}
{"ts":"2026-05-27T14:30:00+08:00","type":"lesson","summary":"發現 rm -rf 差點刪掉設定檔，改用軟刪除規則","tags":["safety","incident"]}

episodic.jsonl 是 append-only 的時間軸記錄，每一行是一個事件：做了什麼決策、學到什麼教訓、完成了什麼里程碑，因此每當 AI 需要「回想過去經驗」，就會查這個檔案。

Layer 3：scratchpad.md（工作暫存）

# Scratchpad -- 當前任務筆記
## 進行中
- [ ] 個人網站首頁：配色已定，待 RWD 斷點
## 待確認
- 要不要加部落格？等週五討論

scratchpad.md 是最短命的記憶，只放當前暫存；每個 session 開始時 AI 掃過就能接續進度。

三層如何協作

層級	生命週期	更新頻率	查詢場景
fact.yml	長期（月/年）	偏好變更時	「我是誰」「我偏好什麼」
episodic.jsonl	永久（append-only）	每次重要決策	「上次為什麼這樣做」「之前踩過什麼坑」
scratchpad.md	短期（天/週）	每次工作更新	「現在做到哪了」「還有什麼待辦」

驗證

# 抽查三檔可讀、jsonl 每行合法即可
head -n 2 memory/fact.yml memory/episodic.jsonl memory/scratchpad.md

再在 Claude Code 問自己的語言偏好，AI 應能從 fact.yml 找到答案。

Step 4：配置第一個 SOP 路由

目的

當你發現自己對 AI 說了第三次「幫我用這個格式寫科普文章」，就該把它變成一個 SOP 路由，別再拖了。SOP 路由的核心概念是：觸發詞 → 自動載入對應的範本和指引，因此能省去你每次重複下指令。

完整的 Skill 路由設計，請參考 Skill 路由引擎：讓 AI 自動選擇正確工作流。

實作

建立路由設定檔：

# memory/sop_dispatch.yml -- SOP 觸發路由
routes:
  - trigger: ["寫科普", "科普文章", "popsci"]
    sop: "_Agent_System/30_Resources/309_Templates/PopSci_SOP.md"
    description: "科普文章寫作流程"
  # 其餘 trigger（週報、文獻整理…）省略

然後在 CLAUDE.md 中加入路由指引：

## SOP 路由
遇到以下觸發詞時，自動載入對應 SOP：
- 完整路由表 → memory/sop_dispatch.yml

接著建立你的第一個 SOP 範本。以科普文章為例：

# PopSci_SOP.md -- 科普文章寫作 SOP
## 步驟
1. 目標讀者 → 2. 字數（800-1500）→ 3. TL;DR／背景／案例／行動建議
4. 台灣繁體中文（專有名詞保留英文）
5. 成品進 _User_Workspace/01_Inbox/013_待發佈文章/
## 品質檢查
- [ ] TL;DR、具體案例、無中國用語、字數在區間
# 其餘檢查項省略

驗證

在 Claude Code 中說「幫我寫一篇科普文章」，觀察 AI 是否自動載入 SOP 並按步驟執行。如果 AI 反過來問你該用什麼格式，就表示路由沒有正確觸發，這時回頭檢查 sop_dispatch.yml 的觸發詞設定即可。

Step 5：安裝第一個 Hook

目的

Hook 是站在 Agent 門口的守門員。每次 AI 要動手做事，不管是寫檔案、跑指令還是改設定，守門員都會先攔下來檢查一遍，確認沒問題才放行。少了這個守門員，你的 Agent 就會像一台沒有煞車的車，油門一踩就回不了頭。

Hook 系統的完整設計請看 Hook 守門系統：AI 寫的每一行 code 都過品管。

實作

在專案的 .claude/ 目錄下建立 Hook 設定：

mkdir -p .claude/hooks

建立一個 PreToolUse hook。攔截危險的檔案操作。設定寫在 .claude/settings.json：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash|Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/safety_check.sh\"",
        "timeout": 5
      }]
    }]
  }
}

#!/bin/bash
# .claude/hooks/safety_check.sh -- 安全守門
# Hook 從 stdin 收到一包 JSON，不是位置參數
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 攔截 rm。只有 exit 2 會真的擋下這次呼叫
if [ "$TOOL_NAME" = "Bash" ] && echo "$COMMAND" | grep -qE '(^|[[:space:]])rm([[:space:]]|$)'; then
  echo "BLOCKED: 偵測到 rm。請改用 mv 檔案 _DELETE_檔案。" >&2
  exit 2
fi
# .env 寫入同樣 exit 2；記憶檔可只警告不擋（其餘規則省略）
case "$FILE_PATH" in *.env|*.env.*) echo "BLOCKED: .env 需人工操作。" >&2; exit 2 ;; esac
exit 0

這裡有兩個地方最容易寫錯，我自己就踩過。第一，hook 拿到的東西不是位置參數，是從 stdin 灌進來的一整包 JSON，所以你得用 jq 去挖 .tool_name 和 .tool_input。第二，退出碼決定一切：只有 exit 2 會真的把這次工具呼叫擋下來，順便把 stderr 的訊息回灌給 AI 看。寫成 exit 1 的話，Claude 只會當成一個不阻斷的錯誤，該刪的照樣刪。我第一版就是寫 exit 1，測試時看到訊息跳出來以為擋住了，結果檔案早就沒了。

記得 chmod +x .claude/hooks/safety_check.sh，否則 hook 呼叫會失敗。

你應該攔截什麼

攔截類型	範例	處理方式
破壞性指令	rm -rf、git reset --hard	直接封鎖
敏感檔案修改	.env、fact.yml、設定檔	警告 + 要求確認
對外通訊	curl POST、git push	要求確認
大量檔案操作	一次修改超過 10 個檔案	暫停確認

驗證

在 Claude Code 中故意說「幫我刪除 memory/fact.yml」。Hook 應該攔截並回報警告。如果 AI 直接執行了刪除，表示 Hook 沒有正確安裝。回頭檢查 settings.json 路徑和腳本權限。

Step 6：跨平台注入

目的

如果你同時使用 Claude Code、GitHub Copilot CLI、Gemini CLI，你不會想在三個地方各寫一本員工手冊，因為那種維修成本高得嚇人。所以跨平台注入的核心是：一份員工手冊（AGENTS.md），多處引用，這樣不管新人從哪個門進來，拿到的規則都一樣。

多平台同步的完整攻略請看 多平台同步：一套記憶跑遍 Claude/Copilot/Gemini。

實作

建立共用規則檔 AGENTS.md。這就是你的 AI 員工手冊：

# AGENTS.md -- AI 員工手冊（跨平台共用規則）
## 安全底線
- rm 禁止：改用 mv 檔案 _DELETE_檔案
- API Key 嚴禁 hardcode；不可逆操作前必須取得許可
- git push --force 到 main 禁止
## 語言／記憶
- 台灣繁體中文；生醫/科技名詞保留英文
- 記憶路由同 CLAUDE.md（細節省略）

然後在各平台引入同一份規則：

Claude Code（CLAUDE.md）：

@AGENTS.md

codex / grok / hermes：

# 讀家目錄 AGENTS.md：用 symlink 指回同一份，不要各抄一份
ln -sfn "$PWD/AGENTS.md" ~/.codex/AGENTS.md
# ~/.grok/AGENTS.md、~/.hermes/AGENTS.md 同理

agy（Antigravity CLI）： 不用設定，它原生就讀 repo 根目錄的 AGENTS.md。

我原本是用 cp 把 AGENTS.md 複製到各平台的，但複製有個很煩的地方：改完主檔要記得跑同步，忘了跑就有兩份不一樣的規則在跑，而你不會馬上發現。後來我全部換成 symlink，因為連結沒有「過期」這回事，改一次，五個地方同時生效。

要注意的是，符號連結只解決「規則放在哪」，並不解決「規則長什麼樣」。因為 Claude Code 用 @ 匯入語法把 AGENTS.md 展開進 CLAUDE.md，codex、grok、hermes 是直接讀家目錄那份，agy 連讀取路徑都不用你指定，四種載入方式對應的是同一份內容，所以你要做的只是確保那份內容本身站得住腳。

驗證

分別在 Claude Code 和其他 CLI 工具中，問問各自的安全規則，確認回答一致。如果某個平台不知道安全規則，就表示同步沒有成功。

Step 7：端對端驗證

目的

前六步各自驗證了單一模組，但 Agent 系統的價值在於模組之間的連動，所以最後一步是跑一個完整的端對端場景，確認所有模組串起來能正常運作。

驗證場景

以下是我建議用來測試整套系統的驗證腳本：

場景：請 AI 幫你整理一份技術筆記

1. 觸發 SOP 路由：說「幫我寫一份技術筆記」。確認 AI 載入對應 SOP
2. 記憶讀取：AI 應該知道你的語言偏好（fact.yml）。用繁體中文回應
3. Hook 運作：如果筆記涉及檔案操作，Hook 應該正常放行（非危險操作不攔截）
4. 產出歸檔：完成的筆記應該存到正確的 _User_Workspace/ 路徑
5. 記憶寫入：AI 應該在 scratchpad.md 更新任務狀態。在 episodic.jsonl 記下這次任務

端對端檢查清單

## Agent 系統部署驗證
- [ ] memory/ 三檔、_Agent_System/、_User_Workspace/（Inbox/Outbox）齊備
- [ ] CLAUDE.md 生效：AI 能答「你是誰」「我的偏好」
- [ ] fact.yml / episodic.jsonl / scratchpad.md 可讀寫
- [ ] 至少一個 SOP 觸發詞能載入並按步驟執行
- [ ] Hook：rm 被攔、非危險操作放行、敏感檔有警告
- [ ] AGENTS.md 存在且至少同步到一個其他平台，安全規則一致
# 其餘細項省略

Quick Start 總整理

最快 1-2 小時可跑完精簡版：建目錄與最小 CLAUDE.md、補 memory 三檔與一條 SOP、掛 PreToolUse hook（chmod +x）、再寫 AGENTS.md 用 symlink 分發。骨架如下（完整 cat/EOF 省略，對照上文）：

# 1–4. 目錄 + CLAUDE.md + memory 三檔 + SOP 路由（細節省略）
mkdir -p MyAgent/{memory,scripts,docs,.claude/hooks}

# 5. Hook 核心：stdin 收 JSON；攔 rm 必須 exit 2（完整腳本見 Step 5）
# if echo "$CMD" | grep -qE '(^|[[:space:]])rm([[:space:]]|$)'; then exit 2; fi

# 6. 跨平台：先寫好 MyAgent/AGENTS.md（內容見 Step 6），再 symlink 指回同一份
#    目標不存在時 ln -sfn 會靜默建出斷鏈，所以順序不能顛倒
ln -sfn "$PWD/MyAgent/AGENTS.md" ~/.codex/AGENTS.md
# ~/.grok、~/.hermes 同理；agy 原生讀 repo 根目錄

7 個步驟就能從空資料夾走到可運作系統；第一次可能要一兩個小時微調，建好後協作效率會明顯不同。

建好之後呢？

這七步只是起點。系統活起來後維護成本其實不高，每週 10 分鐘就夠：

• SOP 越加越多：重複下同一指令就新增路由
• 守門員越來越精明：從攔 rm，到依專案設定不同放行規則
• 大腦越來越有價值：episodic.jsonl 累積 50 篇以上後，AI 更能「記得」決策脈絡
• 跨平台同步：筆電用 Claude Code、公司用 Copilot 時，一致規則能少很多混亂

侷限也清楚：放著不管會變負擔。它不是裝潢完就擺著的樣品屋，而是跟著工作演化的活系統；每週花十分鐘回顧微調，三個月後你會有一個真正理解你的 AI 助手。

真實場景比較見 2026 年 AI Agent 工具鏈完整評比。

---

想更深入？

我把這套七步驟流程整理成了一份《AI Agent 系統設計藍圖》，包含完整的目錄結構範本、CLAUDE.md 模板、記憶系統設定範例，還有我自己實際在用的 Hook 腳本。

免費下載 AI Agent 系統設計藍圖

下一篇：我的 AI Agent 犯過的 7 個致命錯誤