用 Context Engineering 優化任何工作流：CLAUDE.md + AGENTS.md 實戰

問題：你的 Agent 有失憶症

想像你請了一個超強的外包，但他每天早上都忘光你公司的一切。週一，你解釋測試要放 tests/integration/，不是 tests/unit/。週二，你再解釋一遍。週三，你放慢速度再解釋一遍，開始懷疑是不是自己有問題。

沒有 context engineering 的 AI agent 就是這種感覺。

每次開一個新的 Claude Code session，你的 agent 從零開始。它不知道你的 test runner 是 Vitest 不是 Jest。不知道你的團隊用 GitHub Actions deploy 而不是 Vercel。不知道 src/legacy/ 是一個不能碰的地雷區，也不知道每個 PR 都要寫 changelog。

所以你解釋。每次都解釋。然後 agent 還是做錯，因為在聊天視窗裡用自然語言下的指示本質上就是模糊的、不完整的，而且 session 結束就被遺忘。就像把設定寫在便利貼上然後祈禱有人會看。

Claude 官方的使用案例列了「Workflow improvement planner」-- 你描述你的流程，模型建議優化方向。一次性的腦力激盪可以用。但當你需要 agent 在你的 workflow 中反覆執行時就崩了，因為它每次都從零開始。

Context engineering 解決這個問題。不在聊天中重新解釋 workflow，而是把知識編碼進結構化檔案 -- CLAUDE.md、AGENTS.md、Skills、hooks、memory -- 每次 session 自動載入。把它想成基礎建設，不是指令。Agent 在你打第一個字之前就理解你的 workflow。每一次都是。

這篇文章教你從頭建立這套系統，附上一個真實 workflow 的前後對比。

前後對比：同一個任務，兩個世界

任務：建立一個遵循團隊慣例的新 API endpoint，寫好 integration test，開一個 draft PR。

沒有 Context Engineering 的情況

Session 1（週一）：

你：建一個 POST /api/v2/invoices endpoint。
Agent：*在 src/routes/invoices.ts 建立了檔案*
你：不對，v2 的 route 要放 src/api/v2/。
Agent：*搬移*
你：request validation 我們用 Zod，不是 inline 檢查。
Agent：*用 Zod 重寫*
你：測試要放 tests/integration/，不是 tests/unit/。
Agent：*搬移測試*
你：我們用 pnpm test:integration，不是 npm test。
Agent：*跑 pnpm test:integration*

五次修正。十分鐘的來回。Agent 做了事，但你在微管理每一個結構決策。就像跟一個從沒看過你 codebase 的人 pair programming -- 而且這個人隔天就全忘了。

Session 2（週二，新 session）：

你：建一個 POST /api/v2/payments endpoint。
Agent：*在 src/routes/payments.ts 建立了檔案*
你：...同樣的修正，從頭來一遍。

Agent 全忘了。你本人就是 context。

有 Context Engineering 的情況

你花 20 分鐘設好三個檔案。之後每次 session：

你：建一個 POST /api/v2/invoices endpoint。
Agent：我會按照你的 v2 API 慣例來建立 endpoint。
  - 建立 src/api/v2/invoices/route.ts，包含 Zod 驗證
  - 建立 tests/integration/invoices.test.ts
  - 執行 pnpm test:integration... 全部通過
  - 開啟 draft PR，已加上 changelog

零修正。兩分鐘內完成。Agent 每一個結構決策都正確，因為知識在你打字之前就已經載入了。

差異不在更聰明的模型。在更聰明的 context。同一顆引擎，但用了對的燃料。

三層系統

Workflow 的 context engineering 用三層架構，各在不同時間和範圍載入。想像成 CSS specificity：一個到處都套用的基礎層、一個工具專屬的中間層、一個按需載入的任務層。

完整的檔案類型比較請看 SKILL.md vs CLAUDE.md vs AGENTS.md。這裡聚焦在如何用這些檔案來優化 workflow。

第一層：AGENTS.md -- Workflow 的唯一事實來源

AGENTS.md 是跨工具的 context 檔案。Claude Code、Codex CLI、Gemini CLI、Copilot CLI、Cursor 都會讀。它永遠載入。裡面的每個 token 都跟所有任務搶資源。這讓它成為昂貴的不動產 -- 就像 kernel 的 hot path，每個 byte 都很重要。

用在 workflow 優化時，AGENTS.md 編碼的是適用於所有任務的結構性決策：檔案放哪、用什麼工具、什麼不能碰。

# AGENTS.md

## Architecture
- Node.js 22, TypeScript strict, Fastify 5
- Database: PostgreSQL 16 via Drizzle ORM
- API routes: src/api/v1/ (legacy, read-only) and src/api/v2/ (active)
- Auth: Custom JWT middleware in src/middleware/auth.ts

## Conventions
- Request validation: Zod schemas in src/schemas/
- Error handling: Result<T, E> pattern (src/lib/result.ts)
- DB queries: src/repositories/ only, never in route handlers
- Tests: Vitest for unit (tests/unit/), Supertest for integration (tests/integration/)
- Every PR must include a CHANGELOG.md entry

## Constraints
- Never modify src/api/v1/ routes (legacy clients depend on exact signatures)
- Never write raw SQL -- use Drizzle query builder
- Never skip integration tests for new endpoints

## Commands
- Dev: pnpm dev | Test: pnpm test:integration | Lint: pnpm lint
- Build: pnpm build | Migrate: pnpm db:migrate

25 行。捕捉了「前」情境中 agent 做錯的每一個結構決策。CLAUDE.md 撰寫指南 有完整的寫法教學；核心原則是：只放 agent 讀程式碼推不出來的東西。如果從 package.json 就能推斷，就不用重複寫。

第二層：CLAUDE.md -- Agent 專屬行為

CLAUDE.md 在 AGENTS.md 之上加入 Claude Code 專屬指示。保持精簡 -- 20 行以下。這裡編碼的是 agent 該怎麼運作，不是專案長什麼樣。把 AGENTS.md 想成 README.md，CLAUDE.md 想成 .editorconfig -- 一個描述專案，一個設定工具。

# CLAUDE.md

Read AGENTS.md for project architecture and conventions.

## Behavior
- When compacting, preserve the full list of modified files and test results
- Prefer subagents for research tasks (exploring unfamiliar code, reading docs)
- After completing a task, run the relevant test suite before reporting done

## Memory
- Check ~/.claude/memory/ for cross-session notes on recent decisions
- When I make an architectural decision during a session, save it to memory

Memory 區塊對 workflow 特別有力。Claude Code 的 memory 系統跨 session 保存知識 -- 架構決策、使用者偏好、你在對話中討論過的專案模式。Agent 在 session 開始時檢查 memory，就能從上次 session 中斷處接續。差別就在一個有記筆記本的外包跟一個沒有的。

第三層：Skills -- 你的 Workflow 食譜

真正的 workflow 優化在這一層。AGENTS.md 和 CLAUDE.md 告訴 agent 你的專案長什麼樣。Skills 告訴 agent 如何執行特定的工作。如果說第一層和第二層是地圖，第三層就是逐步導航。

Skill 只在任務匹配其描述時載入。做無關的事時零 token 成本。所以 skills 可以很詳細 -- 上限 500 行 -- 不會膨脹每次 session。

以下是消除「前」情境那五次修正的 API endpoint skill：

---
name: create-api-endpoint
description: >
  Use this skill when creating new API endpoints, route handlers,
  or REST resources. Triggers on: new endpoint, new route, API creation,
  POST/GET/PUT/DELETE handler.
---

## Create API Endpoint

### Step 1: Scaffold
1. Create route file in src/api/v2/[resource]/route.ts
2. Create Zod schema in src/schemas/[resource].ts
3. Create repository in src/repositories/[resource].ts (if new resource)

### Step 2: Implementation
1. Define request/response Zod schemas first
2. Implement repository method with Drizzle query builder
3. Wire route handler: validate -> repository -> Result pattern -> response
4. Add auth middleware if endpoint requires authentication

### Step 3: Testing
1. Create integration test in tests/integration/[resource].test.ts
2. Test happy path, validation errors, auth failures, and edge cases
3. Run: pnpm test:integration -- [resource]

### Step 4: Finalize
1. Add CHANGELOG.md entry under "Added"
2. Run full lint: pnpm lint
3. Open draft PR with description following PR template

### Anti-patterns
- Never put DB queries in the route handler -- always go through a repository
- Never skip Zod validation -- even for internal endpoints
- Never create v1 routes -- all new endpoints are v2

35 行的 workflow 專屬知識。沒有這個 skill，你每次都手動解釋這些步驟。有了它，agent 自主執行完整 workflow。差別就在給人一份食譜跟每餐從頭解釋烹飪原理。

建立 skills 的進階內容請看 context engineering 與 skill 分層 和 好的 skill 設計原則。

Hooks：自動化的 Context 載入

Claude Code hooks 讓你在 agent 生命週期的特定時間點自動執行 script。用在 workflow 優化時，hooks 的核心功能是：確保 context 不需要手動 prompt 就能載入。它們是你 agent 設定的 init.d。

{
  "hooks": {
    "session_start": [
      {
        "command": "cat .workflow-status.md 2>/dev/null || echo 'No active workflow'",
        "description": "Load current workflow status"
      }
    ],
    "pre_commit": [
      {
        "command": "pnpm lint --quiet",
        "description": "Lint before every commit"
      }
    ]
  }
}

session_start hook 是 workflow 中最實用的。它可以載入一個追蹤進度的狀態檔 -- 哪些 ticket 在處理中、上次 deploy 了什麼、哪些測試正在失敗。Agent 在每次 session 開始時就有情境感知能力，不只是結構知識。差別就在走進辦公室看到白板 vs 走進去看到空牆。

Memory：跨 Session 的知識

Claude Code 的 memory 系統（~/.claude/memory/）儲存跨 session 持續存在的筆記。如果 AGENTS.md 是專案的憲法、skills 是標準作業程序，memory 就是隨時間累積的組織知識 -- 那些沒人寫下來但大家都知道的事。

與 workflow 相關的 memory 包括：

• 架構決策。 「2026-03-15 決定把內部服務從 REST 遷移到 tRPC。外部 API 維持 REST。」
• Blockers。 「payments 模組的 integration tests 因為 Stripe sandbox 速率限制而不穩定。要單獨跑，不能並行。」
• 進行中的工作。 「正在重構 auth middleware。新版在 src/middleware/auth-v2.ts。舊版仍在使用。遷移完成前不要刪除。」

Memory 系統讓 agent 從無狀態工具變成會隨時間累積知識的存在。每次 session 都讓 agent 在下次 session 時更聰明一點。這是複利效應套用在 AI 輔助上。

建立你的系統：30 分鐘設定

從零到可運作的 context engineering 系統，完整步驟如下。

第 1-10 分鐘：AGENTS.md

打開你的專案。在根目錄建立 AGENTS.md。寫四個區塊：Architecture、Conventions、Constraints、Commands。控制在 30 行以下。只放一個新進工程師在第一個 PR 會做錯的事 -- 那就是 agent 需要知道的訊號。完整範本請看 CLAUDE.md 撰寫指南，AGENTS.md 的結構完全相同。

第 10-15 分鐘：CLAUDE.md

在根目錄建立 CLAUDE.md。最少三行：引用 AGENTS.md、compaction 行為、subagent 偏好。總共 15 行以下。克制過度指定的衝動。如果你發現自己在寫一整段，那大概該放在 skill 裡。

第 15-25 分鐘：你的前兩個 Skills

找出你最常做的兩個任務。那些你每週至少做兩次的。在 .claude/skills/ 為每個建立一個 skill。每個 skill 應該是逐步食譜，附上 anti-pattern 清單。參考 10 個常見的 CLAUDE.md 錯誤 避免在 skill 寫作中踩到同樣的坑。

第 25-30 分鐘：測試

開一個新的 Claude Code session。給 agent 你的 skill 涵蓋的任務之一。觀察它是否每一步都正確，不需要修正。如果偏離了，精修 skill 的措辭。如果完美執行，你的設定就完成了。這就是你的 integration test。

複利效應

Context engineering 不是一次性設定。它會像維護良好的 codebase 一樣複利成長。

第 1 週：你編碼了基本的專案結構和兩個 workflow。Agent 不再問檔案要放哪。

第 4 週：你加了 deployment、code review、database migration、PR 建立的 skills。Memory 累積了架構決策和已知 blockers。Agent 處理你 80% 的例行工作不需要修正。

第 12 週：新團隊成員靠讀你的 AGENTS.md 和 skills 上手。Agent 透過遵循慣例來教他們你的規範。Context 檔案變成活的文件，永遠準確，因為 agent 每天在執行中強化它。你的文件永遠不會過時，因為它同時也是你的設定。

Claude 官方文件的 workflow improvement planner 給你一次關於流程痛點的對話。Context engineering 給你一套對你的具體流程永久變聰明的系統。差異就是建議和基礎建設的差異。建議會淡忘。基礎建設會複利。

用 Termdock 實現 Workspace 層級的持久化

上面描述的 context engineering 系統 -- CLAUDE.md、AGENTS.md、skills、hooks、memory -- 存在你的專案目錄和 home 目錄。任何終端都能用。但終端 session 很脆弱。關掉一個分頁，失去捲動歷史。切換專案，失去佈局。重啟電腦，從頭開始。Context 是持久的。環境不是。

Termdock 在 workspace 層級解決這個問題。你的終端 session、分割面板佈局、環境變數、工作目錄，全部跨重啟持續保存。重新打開一個 workspace，每個面板都在你離開的位置 -- 包括正在執行任務的 Claude Code session。

對 context engineering workflow 來說，這代表：

• 多面板編輯。 一個面板改 CLAUDE.md、另一個測 agent、第三個看 logs。佈局持續保存。
• 專案切換。 每個專案有自己的 workspace 和終端佈局。切換時不會丟失狀態。
• Session 延續。 週五蓋上筆電，週一打開。你的 agent session、檔案編輯、終端歷史全部完好。

Context engineering 讓 agent 記住你的 workflow。Termdock 讓你的終端記住你的 workspace。兩者結合，什麼都不會被遺忘。