Stage 7.5 — 進階 Agentic 概念地圖（Advanced Agentic Concepts Map）¶
⏱ 時間估算：1 週（約 5 小時——不寫 code、只讀資源建立概念地圖）
🚪 進入條件：完成 Stage 7 — 多 Agent 系統與穩定運作（或至少 Stage 4 + 6 + 7）。本章是 production 之後的 frontier 概念地圖、不是入門——沒做過 production agent 會讀不出這些概念在解什麼痛點。
💡 這是一份 進階概念地圖 + reading path，不是完整教學。Stage 4 / 6 / 7 學完已能做能上線給人用的 agent（AI 自主執行體、自己會規劃 + 執行任務的 LLM 系統、俗稱 production agent）；本 stage 幫你定位業界還在討論哪些進階概念存在、每個概念解什麼問題、該先讀哪些 paper / blog，避免你工作上踩到別人已踩過的坑。
📋 本章內容（8 個區塊、依序讀）：
- 為什麼有這 stage（定位）
- 概念地圖主軸：Types → Config → Repo → Service 四層工作邊界
- 12 個進階概念 skeleton
- 為什麼選這 12 個
- 跨概念 Harness Engineering 原則（4 大類別 + 關係圖）
- 進階 agentic 應用流程（5 step）
- 完整 reading path
- 自我檢查
🔤 常用縮寫快速表（本章會反覆出現）：
縮寫 全稱 一句話解釋 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 系統：
→ 每一層上下都是一個「工作邊界」。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)
-
加料（Anthropic Multi-Agent Research 的 speculative-leap 現象）：subagent 被指派「研究某個主題」、它在報告裡擅自加上「我推測 X 也可能成立、雖然我沒驗證」這類沒人要的推論。Anthropic 在他們的 multi-agent 論文裡專門講為什麼這種「主動補完」要透過工程設計消除、不然 hallucination 會在 supervisor 沒注意時偷渡進結果。 → 出處：Anthropic — How we built our multi-agent research system (2025-06)
-
operator 給太多權限（Replit Agent 2024 prod database 事故）：根據社群討論、有使用者把 production database access 直接交給 agent、沒設「破壞性操作要先 confirm」的 gate、結果 agent 在「修 bug」過程跑了破壞性 SQL、清掉 production 資料。錯不在 agent 看起來合理地照指令做、錯在 operator 沒設邊界。 → 出處：Simon Willison 對此事故的分析（2024）（社群整理、非 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）。
🔁 Failure-mode lifecycle（產業級 agent 失敗模式怎麼演化成最佳實踐）¶
每個產業級 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 個概念依 「動到哪一層」（橫軸）+ 「解什麼類型問題」（縱軸）分群、讓你看出哪些概念一起學、哪些可以跳過。其中 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 + Cognition — Don't Build Multi-Agents |
| 2 | Contract-driven Hand-offs | Types + Service | 上游 agent 承諾的 artifacts、下游 agent 必須驗證自己真的收到了這些 artifacts | Anthropic — Building Effective Agents Routing pattern |
| 3 | Speculative / Parallel Exploration | Service（編排） | 跑 N 條 alternative 路徑、取最佳那條（不只獨立 parallel） | LangGraph Plan-Execute Tutorial |
| 4 | Agent-as-Judge / Constitutional AI | Service（agent 評 agent） | 用一個 agent 評另一個 agent 的輸出、依 principles 反覆修正 | Constitutional AI (Bai 2022) |
| 5 | Plan-Act-Reflect Loop | Service（單 agent 自我循環） | write plan → execute → critique → revise → re-execute、直到 PASS 或 EXHAUSTED | Reflexion (Shinn 2023) + Self-Discover (Zhou ICML 2024) |
| 6 | Hierarchical Task Decomposition | Service（多層 supervisor） | supervisor → worker → sub-worker、≥ 2 層 recursion | Microsoft AutoGen GroupChat docs |
| 7 | Autonomy Gradients / Trust Layers | Config（autonomy policy） | agent 不同任務有不同自主權（suggest / propose / execute） | Claude Code permission system |
| 8 | Cost-aware Budget Gates | Config（cost policy） | 超過美元預算就自動停止或升級審核（不只是 token 上限） | OpenAI Harness Engineering (2026-02) |
| 9 | Failure Injection / Chaos Eval | Service（測 agent 容錯） | 故意給 broken input / stale data / API timeout、看 agent 怎麼處理 | Hamel Husain — Evals blog series |
| 10 | Self-organizing Teams | Service（agent 動態協商 role） | agents 不是預先指派 role、而是依任務動態分工 | CAMEL (Li 2023) + AutoGen |
| 11 | Spec-driven Development | Types（spec = code） | agent 任務由 formal spec（YAML / JSON Schema）定義、不是自由 prompt | DSPy signatures tutorial |
| 12 | Graceful Degradation Paths | Config（fallback policy） | frontier model 掛掉 → fallback 便宜 model + 降預期、不直接 crash | OpenRouter routing docs + Anthropic model fallback |
為什麼選這 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、清楚整理成 5 條 named principles） - Cognition AI（Don't Build Multi-Agents） - Hamel Husain（Evals are everything） - Lilian Weng（LLM Powered Autonomous Agents）
🔤 下面表格 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 關係：
→ 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 shortAGENTS.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 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>.mdbrief 一開頭給 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>.mdbrief 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-gateYAML 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 個核心元件上（✓ = 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 |
| 2. System of Record | CLAUDE.md hierarchy + Memory persistence | Claude Code: How Claude remembers your project + Multi-Agent Research System |
| 3. Progressive Disclosure | 同詞（Anthropic Skills 自己也用「core design principle」描述） | 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 |
| 5. Throughput Changes Merge Philosophy | "Human evaluation catches what automation misses" + LLM-as-judge 並用 | Multi-Agent Research System Evaluation challenges |
Anthropic 額外強調的 3 個 OpenAI 沒重點講的原則：
| 原則 | 白話 | URL |
|---|---|---|
| Simplicity | 先用 basic LLM call、不要跳 multi-step agent | Building Effective Agents Simplicity |
| Transparency | "explicitly showing the agent's planning steps"——agent 自己秀 plan | Building Effective Agents |
| Memory persistence | context 滿前先存外部、subagent 用 fresh context 接力 | Multi-Agent Research System |
推薦閱讀順序（45 + 20 min）¶
先讀這 3 篇（總計 ~45 min）：
- Anthropic — Building Effective Agents ⭐⭐⭐ — 涵蓋原則 #1 + #4 + Simplicity / Transparency、最基礎、先讀
- Anthropic Engineering — Equipping Agents for the Real World with Agent Skills ⭐⭐⭐ — 涵蓋原則 #3、Anthropic 直接用 "progressive disclosure" 詞、3-tier loading 完整解說
- Claude Code — How Claude remembers your project ⭐⭐ — 涵蓋原則 #2、CLAUDE.md 4-tier hierarchy +
@-import+ AGENTS.md 互通
再讀這 1 篇（~20 min）：
- Anthropic — How we built our multi-agent research system — 補 #2 + #5 + Memory persistence production 案例
OpenAI 原始文章：
- OpenAI — Harness Engineering — Codex 自身 case study、5 原則的源頭
📋 概念驗證 prompt（self-quiz）¶
🛠️ 想直接動手寫 SKILL.md / CLAUDE.md？ 4 個實作用 prompt（audit 既有 / 生成新的）已移到 Stage 5——讀者真正動手寫的地方： - Stage 5.1 CLAUDE.md 設計 prompts - Stage 5.3 SKILL.md 設計 prompts
本節留 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。
📐 進階 agentic 概念應用流程（讀者導引）¶
學完前面 5 原則 + Anthropic 對照後，怎麼把這些概念實際用到 agent 設計上？ 從 Stage 7（你已能做 production agent）往下、5 個步驟到 production：
-
建立概念地圖主軸 — 四層工作邊界：Types → Config → Repo → Service。想清楚 agent 能動到 stack 哪一層、跨層算違規。 → 本 stage §概念地圖主軸：四層工作邊界
-
挑 2-3 個相關進階概念：從 12 個 skeleton 找跟你問題最相關的（Work Boundary / Contract / PAR / Autonomy 等）。 → 本 stage §12 個進階概念（pattern 清單）
-
套 5 個 OpenAI 原則（cross-cutting）：Legibility / SoR / Progressive Disclosure / Taste Invariants / Throughput Merge Philosophy。這 5 原則跨越所有 12 概念、決定「做對與否」。 → 本 stage §跨概念 Harness Engineering 原則
-
Encode 到 Skills + CLAUDE.md：用 Stage 5 的 4 個 prompt 動手寫——CLAUDE.md audit / generate（Stage 5.1）+ SKILL.md audit / generate（Stage 5.3）。
-
Verify with acceptance gate：Preset YAML 抓 drift / LLM-as-judge 自動評 / Human spot-check 補 edge case。 → 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（按你卡的問題選讀）¶
不是 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 - Cognition — Don't Build Multi-Agents - Anthropic — How we built our multi-agent research system - Lilian Weng — LLM Powered Autonomous Agents
Workflow patterns tier: - LangGraph Planning Agents Tutorial - Microsoft AutoGen docs - DSPy
Production / Harness tier: - OpenAI Harness Engineering (2026-02) - Hamel Husain Evals blog - Simon Willison coding agents notes
Frontier research papers（挑 3-5 篇深讀）: - ReAct / Reflexion / CoALA / Self-Discover / Voyager / Constitutional AI / AutoGen
中文 / hands-on: - 李宏毅 GenAI 2024 / 2025 - datawhalechina/hello-agents
📋 學完進階概念回頭看 synthesis → Stage 5 §🗺️ 7-Layer Architecture Map（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）（兩 track 共用 hub）：學 agent 怎麼跟非 API 世界互動（Computer Use / Browser Use / Code Sandbox）。或挑一個特化分支、或回過頭來貢獻這份 repo。