前 24 天，我們把 Agent Harness 拆成很多獨立機制。

從 Day 25 開始，我們不再新增新的抽象層。

接下來要做的是反過來看真實 Agent：

這些 Mechanism 在一個實際系統裡，到底怎麼組在一起？

第一個系統是 Claude Code。

Awesome Agent Architecture 研究的版本固定在 v2.1.88，而且把 Claude Code 當成完整 Harness 的主要參考系統，覆蓋 Day 1 到 Day 24 對應的所有架構層。

這篇不想回答：

Claude Code 有哪些功能？

而是回答：

為什麼一個 Coding Agent 需要這麼多 Harness？每一層到底在擋哪種 Failure？

先看最裡面：Agent Loop 其實還是很小

不管 Claude Code 外面有多少功能，最內層仍然可以簡化成：

messages[]
↓
Model
↓
Tool Call?
├── No → End
└── Yes
     ↓
   Tool Runtime
     ↓
   Tool Result
     ↓
   messages[]
     ↓
   Model

這和 Day 2 沒有本質差別。

所以 Claude Code 最值得學的第一件事不是：

Agent Loop 很複雜。

而是：

Agent Loop 本身很小，Production Engineering 幾乎都發生在 Loop 周圍。

真正的複雜度來自模型開始能影響真實 Repository 之後，系統必須回答：

• 它可以看到哪些檔案？
• 哪些 Tool 可以出現在這一輪？
• 哪個 Tool Call 可以直接執行？
• 哪些 Side Effect 必須 Ask？
• Shell 跑在哪個環境？
• Project Instruction 從哪裡來？
• Context 滿了怎麼處理？
• Child Agent 看什麼？
• Hook 什麼時候介入？
• Background Work 如何追蹤？
• 外部 MCP Capability 如何加入？

這些都不是 Model Weight 能解決的。

1. Tool Runtime：模型只提出 Action，不直接執行 Action

對 Coding Agent 來說，最重要的能力通常不是「回答」。

而是：

Read
Search
Edit
Shell
Git
External Tool

模型產生的是 Structured Request。

Harness 才負責真的執行。

所以完整路徑比較像：

Model
↓
Tool Request
↓
Tool Registry
↓
Schema / Argument Handling
↓
Permission
↓
Execution
↓
Normalized Result
↓
Model

這就是 Day 3 的核心。

如果把這一層拿掉，Claude 再會寫 Code，也只是：

告訴你應該怎麼改。

不是：

真的在 Repository 裡完成修改。

2. Bash 是最強的 Tool，也因此最需要 Harness

Coding Agent 的很多能力都可以透過 Shell 完成：

git
pytest
npm
python
docker
grep
find
curl

這也是為什麼 Bash 類 Tool 很有吸引力。

它提供一個非常大的 Capability Surface。

但同一個 Tool 也可以執行：

rm
git push
ssh
curl external-service

所以 Coding Agent 很快會遇到 Day 4 的核心問題：

Capability 和 Authority 必須分開。

模型可以知道 Shell 能做什麼。

但「這一次可以做什麼」必須由 Harness 決定。

3. Permission：真正的安全邊界不在 Prompt

如果 Prompt 寫：

不要執行危險操作。

這是一個 Behavior Instruction。

不是 Security Boundary。

真正的執行邊界更接近：

Tool Request
↓
Policy
├── Allow
├── Ask
└── Deny

例如：

Read file
→ Allow

Run tests
→ Allow

Delete file
→ Ask

External side effect
→ Ask or Deny

最重要的架構分工是：

Model 可以提議 Action，Harness 決定 Action 是否被允許發生。

這件事會一路延伸到 Subagent、MCP、Background Work。

4. Sandbox：允許執行，不代表可以無限制影響環境

Permission 回答：

這個操作可以做嗎？

Sandbox 回答：

如果它真的執行，最多能影響哪裡？

例如一個 Shell Command 已經通過 Permission。

仍然需要考慮：

• Filesystem Scope
• Network
• Process
• Environment Variables
• Secrets
• Working Directory

所以：

Permission
+
Sandbox

是兩個不同控制層。

Approval 也不能取代 Sandbox。

人類同意某次操作，不代表底層 Command 永遠不可能出錯。

5. Project Instructions：CLAUDE.md 的本質是 Local Context

很多人把 CLAUDE.md 理解成：

一個更長的 System Prompt。

從 Harness 角度，更好的理解是：

Repository-local Context Source。

它可以承載：

• Build Command
• Test Command
• Project Convention
• Architecture Constraint
• Coding Rule
• Verification Requirement

它的價值不是 Markdown。

而是讓 Project-specific Knowledge 跟著 Repository，而不是全部塞進 Global Prompt。

如果你有三個 Repository：

Repo A
Python + pytest

Repo B
TypeScript + pnpm

Repo C
Rust + cargo

最差的方式是讓三套規則永遠同時出現在 Context。

比較好的方式是：

Global Policy
+
Current Project Context
+
Current Task

這就是 Day 11 的 Prompt Assembly。

6. Context Management：Repository 是 Environment，不是 Prompt

Coding Agent 最容易遇到的錯誤是：

Repository 很大，所以想辦法把更多 Code 塞進 Context。

但再大的 Context Window，也不適合每一輪都重新讀整個 Repository。

更合理的是：

Repository
↓
Search
↓
Read Relevant Files
↓
Task-specific Working Context

這讓 Search / Read 同時扮演兩個角色：

Tool Runtime

真的讀取環境。

Context Selection

決定下一輪模型值得看到什麼。

所以 Coding Agent 裡：

Tool Runtime 和 Context Management 其實高度耦合。

差的 Search 不只是找不到檔案。

它會直接污染 Context。

7. Context 壓縮不是直接把 History 砍掉

A3 對 Claude Code Context Management 的整理很重要：

它不是只做一個 Summary。

而是傾向先使用比較便宜的 Reduction，例如：

• 把大型 Output Persist 到外部
• 在 Context 中留下 Stub
• 移除可重新讀取的 Detail
• 最後才用 Summary

也就是：

能 Externalize 的先 Externalize，能 Re-read 的先 Re-read，Summary 放在後面。

這比「Context 快滿了就總結全部」更可靠。

因為 Summary 是 Lossy。

而 File / Artifact Reference 是 Recoverable。

8. Hooks：Deterministic Extension 不需要重新問 Model

假設每次 Agent 改完檔案後，都必須：

Run formatter

你可以把它寫在 Prompt：

記得 Format。

但如果這條規則是固定的，為什麼要每次讓模型決定？

Hooks 提供的是 Lifecycle Extension Point。

概念上：

PreToolUse
Tool
PostToolUse

外部邏輯可以在已知節點：

• Observe
• Validate
• Transform
• Block
• Trigger Extra Action

這和 Day 5 的結論一致：

核心 Loop 決定 Agent 怎麼前進，Hook 負責在已知節點觀察、修改或阻擋。

9. Subagent：真正的價值是 Context Boundary

Claude Code 也很適合用來理解 Day 7 的 Subagent。

假設 Parent 正在處理一個大型 Repository。

它只需要知道：

Auth 模組主要入口在哪？哪些檔案和目前 Bug 有關？

Research Child 可以自己：

• Search
• Read
• Compare
• Summarize

最後只回 Parent：

入口
相關檔案
Evidence
建議下一步

Parent 不需要看到 Child 全部探索過程。

所以 Subagent 的價值不是：

多開一個 Claude。

而是：

讓局部問題在局部 Context 裡被解決。

10. Child 不應該自動繼承 Parent 的全部 Authority

如果 Parent 有：

Read
Write
Shell
MCP
External Access

Research Child 未必需要全部。

更合理的 Scope：

Research Child
Read + Search

Implementation Child
Read + Write + Test

Review Child
Read only

這把 Day 4 的 Least Privilege 延伸到 Multi-Agent。

Parent 能做，不代表 Child 也應該能做。

11. Skills：不要把所有 Workflow 永久塞進 Context

Coding Agent 很快會累積很多操作知識：

• Debug
• Review
• Release
• Migration
• Testing
• Security
• Documentation

如果全部永遠存在 System Prompt，Context 會越來越大。

Skill 的正確價值是 Progressive Disclosure：

Catalog
↓
Select
↓
Load
↓
Use

也就是：

Agent 先知道有哪些能力，需要時再讀完整方法。

這不是單純把 Prompt 拆檔案。

而是 Context Loading Policy。

12. MCP：連上能力，不等於獲得權限

MCP 讓 Coding Agent 可以接：

• Internal Search
• Database
• Browser
• Issue Tracker
• Custom Service

但完整 Control Flow 仍然應該是：

MCP Server
↓
Discover
↓
Registry
↓
Permission
↓
Task Scope
↓
Model-visible Tools

一個 Server 提供十個 Tool，不代表當前 Task 應該看到十個 Tool。

這同時影響：

• Security
• Tool Selection Accuracy
• Context Cost

13. Git 是 Coding Agent 天然的 Verification Surface

Coding Agent 有一個其他 Agent Domain 很羨慕的東西：

Git。

因為修改結果可以被結構化觀察：

git diff
git status
commit
branch

再加上：

tests
lint
type check
build

所以 Coding Agent 很適合建立 Verification Loop：

Model says:
Done

Harness checks:
Diff?
Tests?
Forbidden paths?
Required artifacts?

這讓「完成」不再只是語言宣告。

而是 Evidence。

14. Worktree 與 Background Work：Task 開始脫離單一 Session

當 Coding Agent 可以：

• 同時跑多個 Child
• 執行長時間 Test
• Background Process
• Parallel Worktree

Task 就不再只是：

一個 terminal session 裡的對話。

它開始需要：

• Handle
• State
• Ownership
• Cancellation
• Result Delivery
• Workspace Binding

也就是前面 Day 13 到 Day 16 的 Task / Background / Isolation。

完整 Harness 的特徵就是：

一個新 Capability 一加入，周圍會自然長出新的 Control Problem。

15. Claude Code 最值得學的不是 Feature List，而是 Control Plane

如果只看功能，你會得到：

Read
Write
Bash
Hooks
Subagents
Skills
MCP

如果用 Harness Lens 看，你看到的是：

Model
↓
Context Assembly
↓
Tool Selection
↓
Permission
↓
Execution
↓
Observation
↓
Verification

然後在外層再掛：

Hooks
Subagents
Background Work
MCP
Project Context

真正讓 Agent 可用的不是哪一個單獨 Feature。

而是：

這些 Feature 是否都有清楚的執行邊界。

Claude Code 可以怎麼畫？

                   Project Context
                         │
User ──────────────▶ Context Assembly
                         │
                         ▼
                       Model
                         │
                    Tool Request
                         │
               ┌─────────▼─────────┐
               │  Harness Control   │
               │                    │
               │ Tool Registry      │
               │ Permission         │
               │ Hooks              │
               │ Skills             │
               │ Subagents          │
               │ MCP                │
               │ Context Manager    │
               └─────────┬─────────┘
                         │
                         ▼
                 Files / Shell / Git
                         │
                    Observation
                         │
                         └──────▶ Model

最重要的不是方塊很多。

而是：

Model 永遠不是直接碰 Environment。

中間有 Harness。

Failure Modes

1. 把 Harness 行為歸功於 Model：真正失敗時會修錯地方。
2. 把所有安全規則寫進 Prompt：Guidance 被誤當 Enforcement。
3. Tool Surface 永遠最大化：增加 Tool Selection 難度與安全風險。
4. Subagent 全部繼承 Parent Context / Tool：多 Agent 只把成本與 Authority 複製更多份。
5. Context 滿了就直接 Summary：可重新讀取的 Evidence 被 Lossy Compression。
6. Agent 說完成就結束：沒有用 Diff / Test / Build 驗證。
7. 為了「完整 Harness」複製所有 Feature：沒有對應 Failure Mode 的 Layer 只會增加 Maintenance。

從 Claude Code 可以帶走的七個原則

1. Agent Loop 很小，Harness 才是主要 Engineering Surface。
2. Capability 和 Authority 分開。
3. Repository 是 Environment，不是 Prompt。
4. Project Knowledge 應該 Localize，而不是 Globalize。
5. Deterministic Control 不需要 Model。
6. Subagent 的價值是 Context / Responsibility Boundary，不是數量。
7. Coding Agent 的完成條件應該盡量落在可驗證 Evidence。

今天的結論

Claude Code 最值得拆的，不是：

它為什麼比較會寫 Code？

而是：

當一個 Model 可以真的修改 Repository 時，Harness 如何控制它可以看什麼、做什麼、影響什麼，以及如何證明它真的完成。

這也是完整 Production Harness 最清楚的樣子。

但 Claude Code 的主要工作場景仍然是 Coding Session。

下一篇我們會換一個完全不同的系統。

如果 Agent 的目標不是「完成這次 Coding Task」，而是：

跨 Session 記得你、學會你的 Workflow、從不同 Messaging Channel 接工作，而且幾天後還能自己醒來繼續做事。

Harness 的重心會完全改變。

Day 26：Hermes Agent。

完整系列與程式碼範例收錄於 https://github.com/hardness1020/awesome-agent-architecture