# Stage 7.5 — 進階 Agentic 概念地圖（Advanced Agentic Concepts Map）

> **繁體中文** | [简体中文](./07.5-advanced-agentic-concepts.zh-Hans.md) | [English](./07.5-advanced-agentic-concepts.en.md)

⏱ **時間估算**：1 週（約 5 小時——不寫 code、只讀資源建立概念地圖）

> 🚪 **進入條件**：完成 [Stage 7 — 多 Agent 系統與穩定運作](07-multi-agent-production.md)（或至少 Stage 4 + 6 + 7）。本章是 production 之後的 frontier 概念地圖、不是入門——沒做過 production agent 會讀不出這些概念在解什麼痛點。

> 💡 這是一份 **進階概念地圖 + reading path**，不是完整教學。Stage 4 / 6 / 7 學完已能做能上線給人用的 **agent**（AI 自主執行體、自己會規劃 + 執行任務的 LLM 系統、俗稱 production agent）；本 stage 幫你定位**業界還在討論哪些進階概念存在**、**每個概念解什麼問題**、**該先讀哪些 paper / blog**，避免你工作上踩到別人已踩過的坑。

> 📋 **本章內容**（8 個區塊、依序讀）：
>
> 1. 為什麼有這 stage（定位）
> 2. 概念地圖主軸：**Types → Config → Repo → Service** 四層工作邊界
> 3. 12 個進階概念 skeleton
> 4. 為什麼選這 12 個
> 5. 跨概念 Harness Engineering 原則（4 大類別 + 關係圖）
> 6. 進階 agentic 應用流程（5 step）
> 7. 完整 reading path
> 8. 自我檢查

> 🔤 **常用縮寫快速表**（本章會反覆出現）：
>
> | 縮寫 | 全稱 | 一句話解釋 |
> |---|---|---|
> | **agent** | AI 自主執行體 | 自己會規劃 + 執行任務的 LLM 系統 |
> | **PR** | Pull Request | 把改動送進主分支的請求（GitHub 術語）|
> | **SoR** | System of Record | 知識的權威來源、唯一 source of truth |
> | **ACI** | Agent-Computer Interface | agent 跟系統之間的對接層（工具 / API / docs）|
> | **MCP** | Model Context Protocol | 把 agent 工具標準化的 spec |
> | **PAR** | Plan-Act-Reflect | 單 agent 自我循環模式（規劃 → 執行 → 反思 → 修正 → 重試）|
> | **CI** | Continuous Integration | commit 後自動跑 test / lint 的系統 |
> | **QA** | Quality Assurance | 品質把關（人工或自動）|
> | **lint / linter** | — | 自動掃 code 找違規的工具 |
> | **`[OAI]` / `[Anth]`** | OpenAI / Anthropic | 後面的 source tag |

## 🎯 為什麼有這 stage

Stage 4 / 6 / 7 加起來足以做 **70% 的 production-grade agent**（能給真人用、不會三天兩頭出包）。每個 stage 教什麼、學完能做什麼：

| Stage | 教什麼 | 學完能做什麼 |
|---|---|---|
| **4** | 挑 **framework**（agent 用哪個工具寫）| LangGraph / AutoGen / DSPy 選一個來寫 agent |
| **6** | **context engineering**（動態管理塞給 agent 的資料）| memory / retrieval / prompt 組裝 |
| **7** | **harness engineering**（agent 周圍的可靠運作環境）| observability / retry / cost gate / eval / sandbox 等 8 個元件 |
| **7.5（本章）**| **進階概念地圖** | 遇到問題知道翻哪份 paper / 看別人 agent 知道它在做什麼 / 知道每個概念對應 agent 系統哪一層 |

但前線的 AI lab（Anthropic / OpenAI / Cognition / Microsoft）+ 學術界（Stanford / CMU / Princeton）在 2024-2026 持續推出 12+ 個進階設計概念。**有些現在你不用、但需要知道它存在**——這樣以後遇到問題、才知道有現成 pattern 可以套。本 stage 不是再教一套理論、而是給你一張**地圖**：

- 不是要你全學會
- 不是要你全用
- 是讓你**遇到問題時、知道該翻哪份 paper / blog 找答案**
- 是讓你**看別人寫的 agent 時、看得出它在做什麼**——舉例：別人的 agent 一出錯就「重試 N 次直到放棄」（=只有 retry）、跟它「出錯後先反思一次、修正做法、再重試」（即所謂 PAR loop）、是完全不同等級的設計。能看出差別、你才知道該不該借用對方的做法
- 是讓你**知道每個概念該套到 agent 系統哪個部分、解哪一類問題**

## 🧭 概念地圖主軸：四層工作邊界（work boundary）

本 stage 用**工作邊界**作為整理進階 agentic workflow 的主軸：先把 agent 系統拆成 4 層（**Types → Config → Repo → Service**、下面馬上展開）。接著問：agent 操作的對象屬於哪一層？跨層越界會出什麼問題？這不是要用單一模型解釋整章、而是先給讀者一個定位座標、後面 12 個概念才能放到同一張圖上比較。

> 💡 **「stack」是什麼意思**：軟體工程習慣把系統拆成上下層、每層各管一件事、上層蓋在下層之上、合稱 stack（堆疊）。例如 web 應用常見「frontend → backend → database」三層 stack。本 stage 把 agent 系統也拆成 4 層（Types / Config / Repo / Service）、看 agent 該動到哪一層。

> ⚠️ **這套 4 層跟 Stage 7 的 prompt → context → harness 三層不一樣、是兩種不同視角**：
> - **Prompt → Context → Harness**（Stage 7）：**stack 位置**——你正在設計或處理的是「prompt 字串 / context 資訊 / 外圍 runtime」哪一類對象？
> - **Types → Config → Repo → Service**（本 stage）：**自主權範圍**——agent 能動到 stack 多深？跨層越界算違規嗎？
>
> 兩者**正交**、解不同問題。讀完本節後可以同時用兩種視角看 agent 系統。

借用軟體架構的 **Types → Config → Repo → Service** 分層、套到 agent 系統：

![Agentic Stack 四層工作邊界](../resources/diagrams/stack-4layer.png)

→ **每一層上下都是一個「工作邊界」**。agent 操作的範圍 = 它的自主權範圍：

- **Agent at Types layer** = 只能符合既有契約、不能改 schema（例：Codex 接到 brief 後、只能加 inline gloss）
- **Agent at Config layer** = 可以調 budget / policy 但不能改 memory（例：context-budget 改 max_cost_usd）
- **Agent at Repo layer** = 可以讀寫 memory / vector store 但不能 redesign workflow
- **Agent at Service layer** = 可以 recompose 整個 workflow、最高自主權

### 為什麼工作邊界適合當主軸

很多進階概念最後都會回到同一個問題：agent 的自主權到底到哪裡為止？把 agent 當成新進實習生來想：你交代一個明確的小任務、他卻自作主張把鄰近的東西也動了——這就叫「跨工作邊界」。產業界已經有 3 個公開記錄的真實案例可以對應：

- **越界沒收手**（Cognition 的 Flappy Bird 案例）：用 **multi-agent**（多個 agent 並行協作）拆解任務、其中一個 **subagent**（主 agent 派出的子 agent、執行某個子任務）負責畫綠色管道、另一個負責畫雲朵背景，結果合起來雙方風格完全對不上——因為每個 subagent 只看到自己那塊、不知道對方在做什麼、也拿不到對方的 **context**（上下文、agent 拿到的全部資訊）。Cognition 寫得直白：「sub-agent 像一群過度自信的新人、根本不會在該問的時候問問題」。
  → 出處：[Cognition — Don't Build Multi-Agents (2025-06)](https://cognition.ai/blog/dont-build-multi-agents)

- **加料**（Anthropic Multi-Agent Research 的 speculative-leap 現象）：subagent 被指派「研究某個主題」、它在報告裡擅自加上「我推測 X 也可能成立、雖然我沒驗證」這類沒人要的推論。Anthropic 在他們的 multi-agent 論文裡專門講為什麼這種「主動補完」要透過工程設計消除、不然 hallucination 會在 supervisor 沒注意時偷渡進結果。
  → 出處：[Anthropic — How we built our multi-agent research system (2025-06)](https://www.anthropic.com/engineering/built-multi-agent-research-system)

- **operator 給太多權限**（Replit Agent 2024 prod database 事故）：根據社群討論、有使用者把 production database access 直接交給 agent、沒設「破壞性操作要先 confirm」的 gate、結果 agent 在「修 bug」過程跑了破壞性 SQL、清掉 production 資料。錯不在 agent 看起來合理地照指令做、錯在 operator 沒設邊界。
  → 出處：[Simon Willison 對此事故的分析（2024）](https://simonwillison.net/2024/Aug/26/replit/)（社群整理、非 Replit 官方 postmortem）

**這 3 個案例告訴你的事**：

- agent 不會「剛好停在你交代的那個點」——brief 要明確寫「**只能動 X、絕對不要動 Y**」、subagent 要明確收到 parent 的 full context
- agent 會主動「補完」沒被要求的東西——要靠 structured output schema + evaluator-optimizer loop 把這類 speculative 內容過濾掉
- 規則「裝好了 ≠ 會被遵守」——operator 自律不夠、必須有 mechanical gate（permission check / cost cap / destructive op confirm）才擋得住

→ **實作對照**：work boundary 寫進 brief（Anthropic 的 brief template、LangGraph 的 state schema、`agent-collab-skills` 的 task-splitter 都是同一概念）、並在 acceptance gate / evaluator loop 中強制檢查；破壞性操作則加 explicit gate（見 [§📚 12 進階概念表 #7 Autonomy Gradients](#-12-個進階概念--skeleton)）。

### 🔁 Failure-mode lifecycle（產業級 agent 失敗模式怎麼演化成最佳實踐）

![Failure-Mode Evolution Cycle](../resources/diagrams/failure-lifecycle.png)

每個產業級 agent failure mode 都走過 **發現 incident → 公開文件化 → encode 成 framework pattern → 自動消除** 的循環。5 個有公開記錄的案例：

| # | Incident（發現）| 文件化（命名）| Codify（變成什麼 pattern）| 公開出處 |
|---|---|---|---|---|
| 1 | Multi-agent subagent context drift（Flappy Bird 風格分裂）| "Sub-agents don't share principal-agent context" | **Single-thread principle**: 別堆 multi-agent、用 linear orchestration | Cognition 2025-06 |
| 2 | Subagent speculative leap（沒驗證的推論偷渡進結果）| "Speculative hallucination via filling-in" | **Evaluator-optimizer loop**: 加 critique step 強制 review | Anthropic Multi-Agent Research 2025-06 |
| 3 | Production permission drift（agent 砍 prod DB）| "Unbounded autonomy on destructive ops" | **Autonomy gradient**: suggest / propose / execute 三段授權 | Replit Agent 2024 incident |
| 4 | Agent looping without self-criticism（AutoGPT 卡 loop）| "Reflexion-less iteration" | **Plan-Act-Reflect loop**: 加 self-critique + revise | Reflexion paper (Shinn 2023) |
| 5 | Skill library corruption（broken skill 進 library）| "Untested skill commit" | **Pre-verify before commit**: skill 入 library 前必跑 test | Voyager paper (Wang 2024) |

→ **這套「fail → publish → codify → fix」循環是整個 agentic 領域的進化機制**——不是「一開始就寫死所有規則」、而是「**每個 production incident 都被公開 + codify 成 pattern**」。Anthropic Skills 的 `references/` 機制、OpenAI 的 Taste Invariants、LangChain 的 evaluator pattern、Anthropic 的 evaluator-optimizer——都是同一邏輯的不同實作。

→ **怎麼用這張表學**：遇到自己 agent 出包時、查上表「最像哪一行」、然後讀對應 pattern 名（Single-thread / Evaluator-optimizer / Autonomy gradient / PAR / Pre-verify）的 deep dive。本 stage 後面 12 個 skeleton 涵蓋全部 5 個 pattern。

## 📚 12 個進階概念 — skeleton

每個概念 ≤ 4 行：一句話定義 + 動到哪一層 + 最值得讀的 1 個資源。

### 🗺️ 12 概念 cluster map（動到哪一層 × 解什麼類型的問題）

![12 Advanced Agentic AI Concepts — Cluster Map](../resources/diagrams/concept-cluster.png)

上圖把 12 個概念依 **「動到哪一層」**（橫軸）+ **「解什麼類型問題」**（縱軸）分群、讓你看出哪些概念一起學、哪些可以跳過。其中 **Work Boundary（#1）跨所有層**（屬於通用紀律、不是某個特定位置）。

→ **怎麼用這張 map**：
- **第一次學**：先學「**編排類 + 反思類**」（共 6 個、是 multi-agent / production 的基礎）
- **要 deploy production**：補「**治理類 + 韌性類**」（共 6 個、防止上線出包）
- **跨類別主軸**：**Work Boundary（#1）是貫穿所有 12 概念的 root discipline**

下面 12 個概念用表格列出（# / 概念 / 動到哪一層 / 一句話定義 / 最佳讀物）：

| # | 概念 | 動到哪一層 | 一句話定義 | 最佳讀物 |
|---|---|---|---|---|
| 1 | **Work Boundary / Scope Discipline** | 跨所有層（discipline）| agent 只動 brief 指定的對象、不越界 | [Hamel — Evals + Skills](https://hamel.dev/blog/posts/evals-skills/) + [Cognition — Don't Build Multi-Agents](https://cognition.ai/blog/dont-build-multi-agents) |
| 2 | **Contract-driven Hand-offs** | Types + Service | 上游 agent 承諾的 artifacts、下游 agent 必須驗證自己真的收到了這些 artifacts | [Anthropic — Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) Routing pattern |
| 3 | **Speculative / Parallel Exploration** | Service（編排）| 跑 N 條 alternative 路徑、取最佳那條（不只獨立 parallel）| [LangGraph Plan-Execute Tutorial](https://blog.langchain.com/planning-agents/) |
| 4 | **Agent-as-Judge / Constitutional AI** | Service（agent 評 agent）| 用一個 agent 評另一個 agent 的輸出、依 principles 反覆修正 | [Constitutional AI (Bai 2022)](https://arxiv.org/abs/2212.08073) |
| 5 | **Plan-Act-Reflect Loop** | Service（單 agent 自我循環）| write plan → execute → critique → revise → re-execute、直到 PASS 或 EXHAUSTED | [Reflexion (Shinn 2023)](https://arxiv.org/abs/2303.11366) + [Self-Discover (Zhou ICML 2024)](https://arxiv.org/abs/2402.03620) |
| 6 | **Hierarchical Task Decomposition** | Service（多層 supervisor）| supervisor → worker → sub-worker、≥ 2 層 recursion | [Microsoft AutoGen GroupChat docs](https://microsoft.github.io/autogen/) |
| 7 | **Autonomy Gradients / Trust Layers** | Config（autonomy policy）| agent 不同任務有不同自主權（suggest / propose / execute）| [Claude Code permission system](https://docs.claude.com/en/docs/agents-and-tools/claude-code/overview) |
| 8 | **Cost-aware Budget Gates** | Config（cost policy）| 超過美元預算就自動停止或升級審核（不只是 token 上限）| [OpenAI Harness Engineering (2026-02)](https://openai.com/index/harness-engineering) |
| 9 | **Failure Injection / Chaos Eval** | Service（測 agent 容錯）| 故意給 broken input / stale data / API timeout、看 agent 怎麼處理 | [Hamel Husain — Evals blog series](https://hamel.dev/blog/posts/evals/) |
| 10 | **Self-organizing Teams** | Service（agent 動態協商 role）| agents 不是預先指派 role、而是依任務動態分工 | [CAMEL (Li 2023)](https://arxiv.org/abs/2303.17760) + AutoGen |
| 11 | **Spec-driven Development** | Types（spec = code）| agent 任務由 formal spec（YAML / JSON Schema）定義、不是自由 prompt | [DSPy](https://github.com/stanfordnlp/dspy) signatures tutorial |
| 12 | **Graceful Degradation Paths** | Config（fallback policy）| frontier model 掛掉 → fallback 便宜 model + 降預期、不直接 crash | [OpenRouter routing docs](https://openrouter.ai/docs) + [Anthropic model fallback](https://docs.claude.com/en/docs/build-with-claude/models) |

## 為什麼選這 12 個

- 都有可驗證的一手來源（primary source、Anthropic / OpenAI / Cognition / Microsoft / academic paper），不是空談
- 都對應到至少一個公開實作（LangGraph / AutoGen / Anthropic Skills / DSPy 等）、可以直接拿來抄
- 都在 Stage 4 / 6 / 7 已覆蓋的概念之外（沒重複）
- 避免「無限延伸」——其他進階概念（Voyager skill learning / MemoryLLM / world models）很重要但**先學這 12 個再說**

## 🔬 跨概念 Harness Engineering 原則（多 source 整理）

**這些原則不是任何單一廠商的**——Anthropic、OpenAI、Cognition、Hamel Husain 等都在各自的文章 / blog / docs 中表達過、用詞不同但指向同一組設計約束。下面先把**原則分成 4 大類**、列出主要來源、再展開細節。

> 📚 主要 source：
> - **Anthropic**（Building Effective Agents · Skills · Multi-Agent Research · CLAUDE.md memory docs）
> - **OpenAI**（[Harness Engineering 2026-02](https://openai.com/index/harness-engineering/)、清楚整理成 5 條 named principles）
> - **Cognition AI**（[Don't Build Multi-Agents](https://cognition.ai/blog/dont-build-multi-agents)）
> - **Hamel Husain**（[Evals are everything](https://hamel.dev/blog/posts/evals/)）
> - **Lilian Weng**（[LLM Powered Autonomous Agents](https://lilianweng.github.io/posts/2023-06-23-agent/)）

> 🔤 **下面表格 source tag 縮寫對照**（之後 chapter 都會用這 4 個 tag）：
> - `[OAI]` = OpenAI
> - `[Anth]` = Anthropic
> - `[Cognition]` = Cognition AI
> - `[Hamel]` = Hamel Husain

### 4 大類別 × 多 source

| 類別 | 核心問題 | 該類別下的原則（含 source） |
|---|---|---|
| **① Context 管理** | 上下文不爆炸、agent 永遠拿到對的資訊 | **System of Record** [OAI] / **Memory Persistence** [Anth] / **Progressive Disclosure** [OAI + Anth] |
| **② Interface / 溝通** | agent 看得懂 codebase、也能說清楚自己在做什麼 | **Legibility** [OAI] / **ACI / Tool Documentation** [Anth] / **Transparency**（show planning）[Anth] |
| **③ Quality / 驗證** | 寫得對 / 不能 hallucinate | **Taste Invariants** [OAI] / **Evaluator-Optimizer loop** [Anth] / **Human + LLM-as-Judge** [Anth] / **"Evals are everything"** [Hamel] |
| **④ Process 紀律** | scale + iterate 不爆 | **Simplicity** [Anth] / **Throughput Changes Merge Philosophy** [OAI] / **Don't Build Multi-Agents (when unnecessary)** [Cognition] |

→ **OpenAI 那 5 個原則是「有最清楚命名 + 完整 case study」的整理版本**——但類別 ① 的 SoR / Memory Persistence、類別 ② 的 ACI、類別 ③ 的 Eval-Optimizer、類別 ④ 的 Simplicity 都是 Anthropic 等其他來源先講的。下面先沿用 OpenAI 的命名版本展開、因為細節最完整；每節再標註對應的 Anthropic 等來源。

### 原則之間的主要關係（cross-category dependencies）

不是 5 個 / 12 個獨立原則——它們之間有 **enabling 關係**：

![5 個 Harness Engineering 原則之間的 cross-source dependency](../resources/diagrams/principle-dependency.png)

→ **4 個關係 insight**：

| 關係 | 描述 | 為什麼重要 |
|---|---|---|
| **SoR + Memory + PD 三者配對** | SoR 提供目的地、Memory 跨 session 保存資訊、Progressive Disclosure 是導航機制 | 三者單獨用不夠、必須一起設計 |
| **Legibility ↔ Transparency 雙向** | agent 能讀 codebase 才能 self-report；agent 會 self-report 你才能驗證 legibility 有效 | 互為前提、缺一不可 |
| **Quality 是 Process 自動化前置** | 沒寫死 invariants + eval loop、人類就無法把 review 交給 automation | 是 ④ Process 的必要條件 |
| **Simplicity 是隱性 root** | 一開始堆 multi-agent、所有其他原則複雜度爆增 | Cognition「Don't Build Multi-Agents」= Anthropic「Simplicity」、同一回事 |

→ 下面 5 個小節用 OpenAI 命名版本展開（最完整）、每節都會回頭標 cross-source mapping。

### 為什麼要在意這些原則 — Why → What → How

下表以「**痛點（Why）→ 原則（What）→ 實作（How）**」三層解釋這些原則在解什麼問題、用什麼工具落地：

| 痛點（Why）| 原則（What）| 實作（How）|
|---|---|---|
| Context 200k 滿 / Multi-agent context overflow | Progressive Disclosure + Memory Persistence | Skills `references/` / `CLAUDE.md` `@-import` / `.ai/<task>` brief |
| Agent 看不懂自家 codebase | Legibility + Tool Doc / ACI | `AGENTS.md` 100 行 / poka-yoke 工具設計 / 一致 schema 命名 |
| 多 agent desync、不同事實版本 | System of Record | `docs/` + `.coord/` shared-memory skill |
| 隨機 drift / Review 漏抓 | Taste Invariants + Transparency（planning 顯示）| `agent-acceptance-gate` preset YAMLs / evaluator-optimizer loop |
| Agent 寫 PR 快、Human QA 跟不上 | Throughput Changes Merge Philosophy | mandatory preset / LLM-as-judge / Human spot-check |
| 一上來就堆 multi-agent overkill | Simplicity（Anthropic）| 先 basic LLM call、確認需要才加 agent |

→ **6 個痛點 → 5 + 3 個原則**（OpenAI 5 + Anthropic 3 extra）→ **8+ 個具體工具 / 機制**。

### 5 個 OpenAI 原則速查表

下面 5 節各自展開原則細節（含 OpenAI 原文 quote）；先給速查表：

| # | 原則 | 一句話 | 跨 work boundary | 對應 tool |
|---|---|---|---|---|
| 1 | **Legibility** | 把 agent 當新進工程師、為它優化 navigability（不是讓人讀懂 agent） | Repo + Types | Skill `references/` + AGENTS.md / CLAUDE.md pattern |
| 2 | **System of Record** | 知識住 `docs/`、不住 prompt；100 行 entry map 指向深處 | Repo | `.coord/memory.yml` shared-memory + AGENTS.md / CLAUDE.md |
| 3 | **Progressive Disclosure** | 小 entry point + 教 agent 之後去哪查（跟 SoR 配對：SoR 提供 destination、PD 是 navigation）| Repo + Types | Skill `references/` 機制 + Codex `.ai/<task>.md` brief |
| 4 | **Architecture & Taste Invariants** | 定義邊界、不細管實作；lint 強制 schema / 命名 / 檔案大小 | Config + cross-cutting | `agent-acceptance-gate` preset YAML、custom linter |
| 5 | **Throughput Changes Merge Philosophy** | agent PR 速度 > 人類 QA 速度 → QA 必須自動化、不依賴逐行讀 | Service（merge workflow）| 自動 lint + test + acceptance gate、mandatory preset |

→ 下面 5 節展開每個原則本身、最後 Anthropic ↔ OpenAI 對照 列出兩家對照詞 + 推薦讀本。

### 1. Legibility — 讓 agent 能讀懂 codebase / docs

> "Because the repository is entirely agent-generated, it's optimized first for **Codex's legibility**." — OpenAI

人類讀 code 有很多視覺輔助：IDE 高亮、跳轉、目錄樹、滑鼠 hover、直覺。**agent 全部沒有**——它只看純文字 + 工具回傳值。如果 codebase / docs 對 agent 不友善、agent 讀錯地方、推論錯方向、寫錯 code。優化方向跟「讓人讀懂 agent 輸出」相反：**把 agent 當新進工程師、為它優化 navigability**。

**(a) Codebase 對 agent 友善**

像給新人寫的 onboarding 文件、所有「靠經驗推測」的東西都得明寫：

- **一致 schema 命名**：`get_user_by_id` 永遠用這個格式、不要混 `fetchUser` / `findUserById` / `userLookup` 三種寫法。AI 看 1000 個檔案、靠 pattern matching 推論、規律不一致就會推錯。
- **檔案大小限制**：規定檔案 < 500 行、agent 一次能完整讀進 context。超過 500 行 agent 一次讀不完、就會跳讀、漏看關鍵邏輯。
- **`docs/` 階層結構**：`docs/api/` / `docs/architecture/` / `docs/runbook/` 分得清楚、agent 才知道 routing。亂塞一個目錄裡、agent 找不到入口。

**(b) Tool / API 對 agent 友善（ACI）**

agent 跟工具的對接層、就是 ACI（Agent-Computer Interface）。設計目標：

- **清楚的 tool description**：每個 tool 一行講「幹什麼」、不是只寫 function signature。AI 沒法靠變數名猜功能。
- **Poka-yoke 工具設計**：把容易出錯的設計拿掉。例：強制吃 absolute path、不允許 relative；強制吃 ISO 日期格式、不允許自由文字。讓 agent 想犯錯都犯不了。
- **Schema 標註**：每個欄位都有 type + 簡述 + 範例值。AI 看了就能直接用、不用猜。

→ **核心精神**：**為 agent 優化、不是為人**——很多優化方向跟「讓人讀爽」相反、但 agent 才是現在 80% 的 reader。

- **跨 work boundary**：Repo + Types
- **對應 tool**：Claude Code Skill 的 `references/` 機制 + AGENTS.md / CLAUDE.md pattern

### 2. System of Record — 知識的唯一權威來源

> "The repository's knowledge base lives in a structured `docs/` directory **treated as the system of record**. A short `AGENTS.md` (roughly 100 lines) is injected into context and serves primarily as a map." — OpenAI

LLM 容易忘事、容易腦補。如果你把所有業務知識都塞進 system prompt、會發生兩件事：(1) context 立刻爆（200k token 也不夠塞）、(2) 不同 agent / 不同 session 讀到的版本對不上、產生「自相矛盾的事實」。SoR（System of Record、知識的權威來源）解這個問題：**所有真實知識住外部 docs、不住 prompt、agent 從 docs 動態拉**。

**(a) 知識住 docs、不住 prompt**

像公司只有一份「員工手冊」當權威、不要每個 onboarding 都重抄一份：

- **100 行 entry map**：AGENTS.md / CLAUDE.md 只放「地圖」（指向 `docs/` 各區的索引）、不放實際內容。
- **`docs/` 結構化**：實際內容住 `docs/api/`、`docs/architecture/`、`docs/runbook/` 等子目錄、agent 按需拉。
- **prompt 絕不重複 docs 內容**：避免「prompt 講一套、docs 講另一套」的版本對不上。

**(b) 跨 session / 跨 agent 持久化**

agent 不是一次性對話、會跨好幾個 session、subagent 之間也要共享事實：

- **`.coord/memory.yml` 共享記憶**：subagent 跟 supervisor 讀同一份、不會各自記不同版本。
- **decisions log**：重要決策寫進 docs、新 session 從讀檔開始、不依賴「上次跟 agent 講過的話」。
- **versioned**：用 git 管 docs、要追溯「這條知識什麼時候改的」隨時可查。

→ **核心精神**：**唯一權威、單向同步**——agent 從 SoR 拉、不從 prompt 拉；SoR 改了所有 agent 下次跑都讀新版本。

- **跨 work boundary**：Repo
- **對應 tool**：`.coord/memory.yml`（[agent-shared-memory](https://github.com/WenyuChiou/agent-collab-skills) skill）+ AGENTS.md / CLAUDE.md pattern

### 3. Progressive Disclosure — 從 small entry point 漸進深挖

> "Agents start with a small, stable entry point and **are taught where to look next**, rather than being overwhelmed up front." — OpenAI

一次塞太多 context 給 agent、它會被淹沒——注意力分散、抓不到重點、品質下降、token cost 暴增。**正確做法是分批揭露**：先給 small + stable 的入口、再「教 agent 之後去哪查」。跟 #2 SoR 配對運作：**SoR 提供目的地**、**PD（Progressive Disclosure）是導航機制**。

**(a) Small entry point**

入門 prompt 像書的目錄、不是整本書：

- **AGENTS.md / CLAUDE.md 100 行**：只放最高層的「這個專案幹什麼 + 主要結構在哪」、不放細節。
- **brief 而非 dump**：給 agent 任務時、用 100 行 brief、不是 vibrate 整個 codebase。
- **入口要 stable**：100 行的內容變動越少越好、agent 才能對它建立可靠的 mental model。

**(b) Navigation 機制——教 agent 之後去哪挖**

agent 需要的時候、自己去拉深處資料：

- **Skill `references/` 機制**：Claude Code 的 Skill 把詳細 reference 放在 `references/` 子目錄、agent 需要才 load。預設不進 prompt、需要才進。
- **`@-import` 語法**：CLAUDE.md 可以寫 `@docs/architecture.md` 指向深處、按需拉而不是預先塞。
- **task brief 指向法**：Codex `.ai/<task>.md` brief 一開頭給 agent 「先讀 `docs/X.md` 第 1-2 節、執行前再讀 `docs/Y.md`」。

→ **核心精神**：**懶載入（lazy load）勝過熱載入（eager load）**——能晚一刻塞 context、就晚一刻。

- **跨 work boundary**：Repo + Types
- **對應 tool**：Claude Code Skill 的 `references/` 機制（只在 agent 需要才 load）+ Codex `.ai/<task>.md` brief pattern（先讀 brief 再決定深挖）

### 4. Architecture & Taste Invariants — 用 lint 強制不變量

> "We enforce these rules with custom linters and structural tests, plus a small set of **'taste invariants.'** ... **By enforcing invariants, not micromanaging implementations**, we let agents ship fast." — OpenAI

AI 寫 code 時傾向「怎麼快怎麼來」、常導致模組過度耦合、命名混亂、檔案爆炸。OpenAI 團隊用**強制性結構規則**約束 AI、讓 agent 在你劃好的邊界內快跑、而不是每行都要人盯：

**(a) Enforcing Architecture — 用「物理邊界」框住 AI**

像在蓋房子前先搭好鋼筋支架、AI 只能在格子裡填肉：

- **單向依賴（One-way Dependency）**：定義嚴格的層級、底層的 Types 絕對不能引用高層的 Service。AI 想偷渡 import 會被擋。
- **剛性目錄結構**：規定特定的 code 必須待在特定目錄（如 `models/` / `controllers/` / `schemas/`）、AI 不能自己亂建 folder。
- **自動化 Linter**：如果 AI 寫出違規 code（例如在數據層直接呼叫 API）、CI 自動拒絕 merge、逼 AI 重寫。

**(b) Enforcing Taste — 把「工程美學」變成規則**

「品味」聽起來主觀、但工程上指的是**可維護性、一致性、簡潔度**。AI 沒有美感、它只會根據機率產出結果——所以要把美感寫成 lint 規則：

- **黃金準則 list**：寫下「**偏好 composition 而非 inheritance**」、「**函數必須短小**」、「**檔案 < 500 行**」這類原則、變成 invariant。
- **程式碼風格統一**：harness 強制 AI 產出的命名、邏輯組織看起來像「同一個高階工程師寫的」、而不是混雜風格的大雜燴。
- **拒絕「AI slop」**：AI 常生成冗餘、無用但「看起來正確」的 code。設定「品味基準」要求 AI 不斷重構、簡化、直到達到人類專家認可的優雅程度。

→ **核心精神**：**定義邊界、不細管實作**——讓 agent 在你劃好的格子裡自由衝、而不是每行都要人盯。

- **跨 work boundary**：Config + cross-cutting（lint 規則寫在 Config、強制檢查跨所有層）
- **對應 tool**：`agent-acceptance-gate` YAML preset（`multi-locale-mirror-sync.yml` / `catalog-entry-add.yml` / `fact-check-frontier-models.yml`）——預先 codify「跑出來該長什麼樣」

### 5. Throughput Changes Merge Philosophy — agent 高吞吐 → 人類 QA 變瓶頸

> "...3.5 PRs per engineer per day... **the bottleneck became human QA capacity**." — OpenAI

過去 1 個工程師 1 天寫 1-2 個 PR、人類逐行 review 跟得上。**agent 上線後變成 1 天 3.5 個 PR**、再加上 self-correcting agent 自己會 retry、實質吞吐還更高。問題不是 agent 不夠快、是**人類 review 來不及**——QA 變瓶頸。Merge 邏輯必須換、不能再依賴「人逐行讀過」當 quality gate。

**(a) Pre-merge automation——把 review 自動化**

人不再是逐行 reviewer、是 spot-checker：

- **自動 lint**：CI 跑 linter 強制 style / schema / 命名。agent 違規 → CI 紅燈、merge 被擋。
- **自動 test**：unit test + integration test 全自動跑、coverage 不達標不能 merge。
- **自動 acceptance gate**：commit 前跑 acceptance gate preset（如 `multi-locale-mirror-sync.yml`）、預先 codify「跑出來該長什麼樣」、agent 不符就 fail。

**(b) Self-verification——agent 自己先驗一輪**

agent 提 PR 前、先自己跑一遍 evaluator-optimizer loop：

- **agent 內建 critique step**：寫完 code 再呼叫一次 critique agent 自審、發現問題就重寫。
- **LLM-as-judge 自動評分**：用另一個 LLM agent 給 PR 打分、低於門檻就退回 agent 改。
- **Human spot-check only**：人類只看 agent + LLM-judge 都過關後的「最終樣子」、不再逐行讀過程。

→ **核心精神**：**Quality gate 從「人讀過」變成「機器跑過 + 人 spot-check」**——人類角色從「逐行守門」升級為「決定 gate 怎麼設」。

- **跨 work boundary**：Service（merge workflow）
- **對應 tool**：`agent-acceptance-gate` 整套、特別是 mandatory preset 機制（trigger fire → preset 必跑）

### 5 原則 × Stage 7 Harness 8 元件對照表

下表展示 5 個原則怎麼作用到 [Stage 7 Harness Engineering 的 8 個核心元件](07-multi-agent-production.md#harness-的-8-個核心元件)上（✓ = applies、✓★ = primary lever）：

| 原則 ＼ Harness 元件 | 1. Agent Loop | 2. Tool Reg | 3. Ctx Mgr | 4. Retry | 5. Sandbox | 6. Obs | 7. Eval | 8. Cost / Lat |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| **1. Legibility** |  | ✓ | ✓ |  |  | ✓ |  |  |
| **2. SoR** |  |  | ✓★ |  |  | ✓ |  |  |
| **3. Progr. Disc.** | ✓ |  | ✓★ |  |  |  |  | ✓ |
| **4. Invariants** |  | ✓ |  | ✓ | ✓ |  | ✓★ |  |
| **5. Merge Phil.** |  |  |  |  |  |  | ✓★ | ✓ |

→ **Context Manager（#3）+ Eval（#7）是被 4-5 個原則同時作用的熱點**——這也是 v0.2.3 preset / `agent-acceptance-gate` / `agent-shared-memory` 都圍著這兩個元件設計的原因。

→ **Tool Registry（#2）+ Observability（#6）次熱**——被 3 個原則影響、Legibility 把 schema 寫對 + Invariants 把 lint 寫對 + SoR 把紀錄寫對。

→ **Retry / Sandbox / Cost-Latency** 只被 1-2 個原則作用——這幾個元件相對「機械」、原則上對應 1 個 lever 就夠。

### 📚 Anthropic ↔ OpenAI cross-vendor 對照 + 推薦讀本

OpenAI 那 5 原則 Anthropic 大部分也都討論過、用的詞不同。下表是 cross-vendor 對照、每個都附 canonical URL：

| OpenAI 原則 | Anthropic 對應詞 / pattern | 最權威 URL |
|---|---|---|
| **1. Legibility** | ACI（Agent-Computer Interface）+ Tool Documentation | [Building Effective Agents Appendix](https://www.anthropic.com/engineering/building-effective-agents) |
| **2. System of Record** | CLAUDE.md hierarchy + Memory persistence | [Claude Code: How Claude remembers your project](https://code.claude.com/docs/en/memory) + [Multi-Agent Research System](https://www.anthropic.com/engineering/built-multi-agent-research-system) |
| **3. Progressive Disclosure** | **同詞**（Anthropic Skills 自己也用「core design principle」描述）| [Equipping Agents for the Real World with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) ⭐⭐⭐ |
| **4. Taste Invariants** | Evaluator-optimizer loops + Tool "poka-yoke"（如強制 absolute filepath）| [Building Effective Agents Evaluator-optimizer](https://www.anthropic.com/engineering/building-effective-agents) |
| **5. Throughput Changes Merge Philosophy** | "Human evaluation catches what automation misses" + LLM-as-judge 並用 | [Multi-Agent Research System Evaluation challenges](https://www.anthropic.com/engineering/built-multi-agent-research-system) |

**Anthropic 額外強調的 3 個 OpenAI 沒重點講的原則**：

| 原則 | 白話 | URL |
|---|---|---|
| **Simplicity** | 先用 basic LLM call、不要跳 multi-step agent | [Building Effective Agents Simplicity](https://www.anthropic.com/engineering/building-effective-agents) |
| **Transparency** | "explicitly showing the agent's planning steps"——agent 自己秀 plan | [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) |
| **Memory persistence** | context 滿前先存外部、subagent 用 fresh context 接力 | [Multi-Agent Research System](https://www.anthropic.com/engineering/built-multi-agent-research-system) |

#### 推薦閱讀順序（45 + 20 min）

**先讀這 3 篇（總計 ~45 min）**：

1. [Anthropic — Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) ⭐⭐⭐ — 涵蓋原則 #1 + #4 + Simplicity / Transparency、**最基礎、先讀**
2. [Anthropic Engineering — Equipping Agents for the Real World with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) ⭐⭐⭐ — 涵蓋原則 #3、Anthropic 直接用 "progressive disclosure" 詞、3-tier loading 完整解說
3. [Claude Code — How Claude remembers your project](https://code.claude.com/docs/en/memory) ⭐⭐ — 涵蓋原則 #2、CLAUDE.md 4-tier hierarchy + `@-import` + AGENTS.md 互通

**再讀這 1 篇（~20 min）**：

4. [Anthropic — How we built our multi-agent research system](https://www.anthropic.com/engineering/built-multi-agent-research-system) — 補 #2 + #5 + Memory persistence production 案例

**OpenAI 原始文章**：

5. [OpenAI — Harness Engineering](https://openai.com/index/harness-engineering/) — Codex 自身 case study、5 原則的源頭

### 📋 概念驗證 prompt（self-quiz）

> 🛠️ **想直接動手寫 SKILL.md / CLAUDE.md？** 4 個實作用 prompt（audit 既有 / 生成新的）已**移到 [Stage 5](05-claude-code-ecosystem.md)**——讀者真正動手寫的地方：
> - [Stage 5.1  CLAUDE.md 設計 prompts](05-claude-code-ecosystem.md#-claudemd-設計-prompts依-5-原則)
> - [Stage 5.3  SKILL.md 設計 prompts](05-claude-code-ecosystem.md#-skillmd-設計-prompts含-skill-creator-替代)

本節留 **1 個 quiz prompt 讓你確認自己懂這 5 個原則**（不寫 code 的概念 check）：

#### Prompt 1 — Self-quiz（考自己懂不懂這 5 原則）

```
我剛學完 OpenAI 5 個 harness engineering 原則：
1. Legibility
2. System of Record
3. Progressive Disclosure
4. Taste Invariants
5. Throughput Changes Merge Philosophy

請出 5 道情境題、每題描述一個真實的 SKILL.md / CLAUDE.md 設計決定（例如「我把所有 examples 都塞 SKILL.md 主檔、< 1000 行」），問**違反哪一條原則 + 該怎麼修**。

一次出 1 題、等我回答後給回饋、再出下一題。最後給總成績。
```

→ **建議用法**：學完上面 5 個原則後跑這個 quiz 確認你抓到 concept；實作面（寫 SKILL.md / CLAUDE.md）的 prompt 在 [Stage 5](05-claude-code-ecosystem.md)。

### 📐 進階 agentic 概念應用流程（讀者導引）

學完前面 5 原則 + Anthropic 對照後，**怎麼把這些概念實際用到 agent 設計上？** 從 Stage 7（你已能做 production agent）往下、5 個步驟到 production：

1. **建立概念地圖主軸 — 四層工作邊界**：Types → Config → Repo → Service。想清楚 agent 能動到 stack 哪一層、跨層算違規。
   → 本 stage §概念地圖主軸：四層工作邊界

2. **挑 2-3 個相關進階概念**：從 12 個 skeleton 找跟你問題最相關的（Work Boundary / Contract / PAR / Autonomy 等）。
   → 本 stage §12 個進階概念（pattern 清單）

3. **套 5 個 OpenAI 原則（cross-cutting）**：Legibility / SoR / Progressive Disclosure / Taste Invariants / Throughput Merge Philosophy。這 5 原則跨越所有 12 概念、決定「做對與否」。
   → 本 stage §跨概念 Harness Engineering 原則

4. **Encode 到 Skills + CLAUDE.md**：用 Stage 5 的 4 個 prompt 動手寫——CLAUDE.md audit / generate（[Stage 5.1](05-claude-code-ecosystem.md#51--claude-code-基礎)）+ SKILL.md audit / generate（[Stage 5.3](05-claude-code-ecosystem.md#53--skillsclaude-code-的行為層-claude-code-生態最關鍵的一層)）。

5. **Verify with acceptance gate**：Preset YAML 抓 drift / LLM-as-judge 自動評 / Human spot-check 補 edge case。
   → [agent-collab-skills](https://github.com/WenyuChiou/agent-collab-skills)

→ **Production agent ready**：可穩定給人用、有自動驗證、有可預測失敗。

→ **怎麼用這 5 步**：第一次讀本 stage 時、照 1 → 5 順序走；之後實作 agent 卡關時、回來判斷自己卡在哪一步。

→ **跟前面 Why → What → How 表的差別**：那張是「**痛點 ↔ 原則 ↔ 工具**」的橫向對應、reference 用；這 5 步是「**從學完到上線**」的縱向流程、do-this-then-this 用。

## 📖 完整 reading path（按 depth 分層）

按深度排序、不必全讀。Foundation tier 必讀（~95 min）、其他**遇到問題再深挖**：

### 🌳 Reading decision tree（按你卡的問題選讀）

![Agentic AI Advanced Reading Decision Tree](../resources/diagrams/reading-decision-tree.png)

不是 reading list、是 **decision tree**——你現在卡哪個問題、就先讀對應的那 1-2 篇（上圖 5 個分支對應 5 種卡關狀況；下面是每個分支讀完第 1 篇後的進階推薦）：

**分支讀完後的延伸閱讀**（branch-specific second readings）：

- 「不知道 agent 怎麼開始」→ 再讀 ReAct paper + Lilian Weng "LLM Powered Autonomous Agents"
- 「multi-agent 要不要用、怎麼開」→ 再讀 Anthropic Multi-Agent Research（case study section）
- 「context 沒效率」→ 再讀 Anthropic Multi-Agent Research（memory section）
- 「eval 怎麼寫 / 自動驗證」→ 再讀 Anthropic Multi-Agent Research（eval section）
- 「想跟上 frontier 現況」→ 再讀 AutoGen + ReAct paper

→ **規則**：每個分支**最多挑 2 篇深讀**——讀完再回來看自己其他問題、決定下一篇。不要 broad-scan 全部清單。

下面是按 depth tier 排的完整 list（給已知道想讀什麼的人查）：

**Foundation tier**（先讀這 4 個、~95 min 總長）:
- [Anthropic — Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents)
- [Cognition — Don't Build Multi-Agents](https://cognition.ai/blog/dont-build-multi-agents)
- [Anthropic — How we built our multi-agent research system](https://www.anthropic.com/engineering/built-multi-agent-research-system)
- [Lilian Weng — LLM Powered Autonomous Agents](https://lilianweng.github.io/posts/2023-06-23-agent/)

**Workflow patterns tier**:
- [LangGraph Planning Agents Tutorial](https://blog.langchain.com/planning-agents/)
- [Microsoft AutoGen docs](https://microsoft.github.io/autogen/)
- [DSPy](https://dspy.ai/learn/)

**Production / Harness tier**:
- [OpenAI Harness Engineering (2026-02)](https://openai.com/index/harness-engineering)
- [Hamel Husain Evals blog](https://hamel.dev/blog/posts/evals/)
- [Simon Willison coding agents notes](https://simonwillison.net/tags/coding-agents/)

**Frontier research papers**（挑 3-5 篇深讀）:
- ReAct / Reflexion / CoALA / Self-Discover / Voyager / Constitutional AI / AutoGen

**中文 / hands-on**:
- [李宏毅 GenAI 2024 / 2025](https://speech.ee.ntu.edu.tw/~hylee/)
- [datawhalechina/hello-agents](https://github.com/datawhalechina/hello-agents)

> 📋 **學完進階概念回頭看 synthesis** → [Stage 5 §🗺️ 7-Layer Architecture Map](05-claude-code-ecosystem.md#-7-layer-architecture-map先看這張圖再讀-51-56)（Claude Code 7 個 primitive + 3 個工程學 discipline 整合圖）

## ✅ 自我檢查

讀完本 stage 應該能：

- [ ] 用 **Types → Config → Repo → Service** 四層解釋 Cognition Flappy Bird / Anthropic speculative-leap 為什麼算 work boundary 違規
- [ ] 說出 12 個進階概念中 5 個的「動到哪一層」+ 一句話定義
- [ ] 講得出 Harness Engineering 原則的 4 大類別（① Context 管理 / ② Interface / ③ Quality 驗證 / ④ Process 紀律）各自解什麼問題，以及類別之間的 enabling 關係
- [ ] 知道下一步該翻哪份 paper / blog（不必全部讀完）
- [ ] 區分 PAR loop（單 agent 自我修正）vs agent-debate（2 agents 對峙）
- [ ] 在 brief 中明確寫出 task 的 work boundary（in / out）

→ 全部能做到 = 你已超出 Stage 7 production 化的範圍、進入 frontier agentic workflow design。**剩下就是看哪個 paper 對你最痛、深讀那個**。

---

→ 接下來 [**Stage 8 — Agent 操作介面（Agent Interfaces）**](08-agent-interfaces.md)（**兩 track 共用 hub**）：學 agent 怎麼跟非 API 世界互動（Computer Use / Browser Use / Code Sandbox）。或挑一個[特化分支](../README.md#️-學習地圖兩條學習路徑)、或回過頭來貢獻這份 repo。