Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
i18n(zh-TW): enforce Hard Constraints across all zh-TW content
Jim Chen12f5edf4f0e2
diff --git a/docs-readme/zh-TW/README.md b/docs-readme/zh-TW/README.mdindex 361030d..c10fbc0 100644--- a/docs-readme/zh-TW/README.md+++ b/docs-readme/zh-TW/README.md@@ -45,7 +45,7 @@ Learn Harness Engineering 是一門專注於 AI 程式設計代理工程化的## ✨ 視覺預覽### 🏠 課程首頁-> 完整的課程大綱與核心理念介紹,提供清晰的上手路徑。+> 完整的課程大綱與核心理念介紹,提供明確的上手路徑。@@ -74,13 +74,13 @@ Learn Harness Engineering 是一門專注於 AI 程式設計代理工程化的大多數人都是慘痛教訓後才明白一個殘酷的事實:**世界上最強大的模型,如果你不在它周圍建構適當的環境,它在真實工程任務上仍然會失敗。**-你可能自己也見過這種情況。你讓 Claude 或 GPT 在你的儲存庫中執行一項任務。它一開始表現不錯——讀取檔案、撰寫程式碼,看起來很有效率。然後出了問題。它跳過了一個步驟。它破壞了一個測試。它說「完成了」,但實際上什麼都不能用。你最後花的時間比自己動手做還多。+你可能自己也見過這種情況。你讓 Claude 或 GPT 在你的儲存庫中執行一項任務。它一開始表現不錯,讀取檔案、撰寫程式碼,看起來很有效率。然後出了問題。它跳過了一個步驟。它破壞了一個測試。它說「完成了」,但實際上什麼都不能用。你最後花的時間比自己動手做還多。-這不是模型的問題。這是 harness 的問題。+問題出在 harness 的設計,而非模型本身。-證據很明確。Anthropic 進行了一項對照實驗:相同的模型(Opus 4.5)、相同的提示(「建構一個 2D 復古遊戲編輯器」)。沒有 harness 的情況下,它在 20 分鐘內花了 9 美元,產出的東西無法運作。有了完整的 harness(規劃器 + 生成器 + 評估器),它在 6 小時內花了 200 美元,建構出一個你真的可以玩的遊戲。模型沒有變。變的是 harness。+證據很明確。Anthropic 進行了一項對照實驗,相同的模型(Opus 4.5)、相同的提示(「建構一個 2D 復古遊戲編輯器」)。沒有 harness 的情況下,它在 20 分鐘內花了 9 美元,產出的東西無法運作。有了完整的 harness(規劃器 + 生成器 + 評估器),它在 6 小時內花了 200 美元,建構出一個你真的可以玩的遊戲。模型沒有變。變的是 harness。-OpenAI 也報告了 Codex 的相同結果:在一個 well-harnessed 的儲存庫中,相同的模型從「不可靠」變成「可靠」。這不是邊際改善——這是質的飛躍。+OpenAI 也報告了 Codex 的相同結果,在一個 well-harnessed 的儲存庫中,相同的模型從「不可靠」變成「可靠」。改變的規模遠超邊際調整,是質的轉變。**這門課程教你如何建構那個環境。**@@ -143,7 +143,7 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,每個子系統各有其職責:-- **Instructions(指令)** — 告訴代理該做什麼、以什麼順序、以及在開始前該閱讀什麼。不是一個巨大的檔案;而是一個漸進揭露的結構,讓代理按需導航。+- **Instructions(指令)** — 告訴代理該做什麼、以什麼順序、以及在開始前該閱讀什麼。以漸進揭露的結構組織,讓代理按需導航,而非堆成一個巨大的檔案。- **State(狀態)** — 追蹤已完成的事項、正在進行的事項、以及接下來該做的事。持久化到磁碟,讓下一個工作階段可以精確地從上一個階段停止的地方接續。- **Verification(驗證)** — 只有通過的測試套件才算數。代理不能在沒有可執行證據的情況下宣告勝利。- **Scope(範圍)** — 將代理限制在每次只做一個功能。不過度延伸。不三件事做一半。不改寫功能列表來隱藏未完成的工作。@@ -153,9 +153,9 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,## 為什麼會有這門課程-問題不是「模型能不能寫程式?」它們能。問題是:**它們能不能在真實的儲存庫中,跨越多個工作階段,在沒有持續人工監督的情況下,可靠地完成真實的工程任務?**+問題不是「模型能不能寫程式?」它們能。問題是,**它們能不能在真實的儲存庫中,跨越多個工作階段,在沒有持續人工監督的情況下,可靠地完成真實的工程任務?**-目前的答案是:沒有 harness 就不行。+目前的答案是,沒有 harness 就不行。```text沒有 HARNESS 有 HARNESS@@ -202,7 +202,7 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,你不需要讀完所有 12 堂講座才能開始受益。如果你已經在真實專案中使用程式設計代理,以下是如何立刻改善它的方法。-概念很簡單:與其只寫提示,不如給你的代理一組結構化的檔案,定義該做什麼、已經做了什麼、以及如何驗證工作。這些檔案存在你的儲存庫中,所以每個工作階段都從相同的狀態開始。+概念很簡單,與其只寫提示,不如給你的代理一組結構化的檔案,定義該做什麼、已經做了什麼、以及如何驗證工作。這些檔案存在你的儲存庫中,所以每個工作階段都從相同的狀態開始。```text你的專案根目錄@@ -303,21 +303,21 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,## 課程大綱-### 講座 — 12 個概念單元,每個回答一個核心問題+### 講座 — 12 個概念單元,每個聚焦一個關鍵提問*在[文件網站](https://walkinglabs.github.io/learn-harness-engineering/)上閱讀每堂講座的完整內容。*| 場次 | 問題 | 核心概念 ||---------|----------|-----------|| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 為什麼強大的模型在真實任務上仍然會失敗? | 基準測試與真實工程之間的能力差距 |-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | 「harness」到底是什麼意思? | 五個子系統:指令、狀態、驗證、範圍、生命週期 |+| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | 「harness」到底是什麼意思? | 五個子系統,指令、狀態、驗證、範圍、生命週期 || [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 為什麼儲存庫必須是唯一的真實來源? | 如果代理看不到它,它就不存在 |-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 為什麼一個巨大的指令檔案會失敗? | 漸進揭露:給一張地圖,不是一本百科全書 |+| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 為什麼一個巨大的指令檔案會失敗? | 漸進揭露,給一張地圖,不是一本百科全書 || [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 為什麼長時間執行的任務會失去連續性? | 將進度持久化到磁碟;從你停止的地方接續 || [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 為什麼初始化需要自己的階段? | 在代理開始工作之前驗證環境是否健康 || [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 為什麼代理會過度延伸和過早結束? | 每次一個功能;明確的完成定義 || [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 為什麼功能列表是 harness 的基本元素? | 機器可讀的範圍邊界,代理無法忽略 |-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 為什麼代理會過早宣告勝利? | 驗證缺口:信心不等於正確 |+| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 為什麼代理會過早宣告勝利? | 驗證缺口,信心不等於正確 || [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 為什麼端到端測試能改變結果? | 只有完整的流程執行才算真正的驗證 || [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 為什麼可觀測性應該屬於 harness 內部? | 如果你看不到代理做了什麼,你就無法修復它破壞的東西 || [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 為什麼每個工作階段都必須留下乾淨的狀態? | 下一個工作階段的成功取決於這個工作階段的清理 |@@ -326,12 +326,12 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,| 專案 | 你要做什麼 | Harness 機制 ||---------|------------|-------------------|-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | 將同一任務執行兩次:僅提示 vs. 規則優先 | 最小 harness:AGENTS.md + init.sh + feature_list.json |+| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | 將同一任務執行兩次,僅提示 vs. 規則優先 | 最小 harness,AGENTS.md + init.sh + feature_list.json || [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | 重構儲存庫,讓代理能夠閱讀它 | 代理可讀的工作空間 + 持久化狀態檔案 || [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | 讓代理從上次停止的地方接續 | 進度日誌 + 工作階段交接 + 多工作階段連續性 || [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | 阻止代理做得太多或太少 | 執行時回饋 + 範圍控制 + 增量索引 || [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | 讓代理驗證自己的工作 | 自我驗證 + 有依據的問答 + 基於證據的完成 |-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | 從零建構一個完整的 harness(畢業專案) | 完整 harness:所有機制 + 可觀測性 + 消融實驗 |+| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | 從零建構一個完整的 harness(畢業專案) | 完整 harness,所有機制 + 可觀測性 + 消融實驗 |```text專案演進@@ -560,7 +560,7 @@ learn-harness-engineering/[](https://github.com/walkinglabs/hands-on-modern-rl)-**Hands-on Modern RL**:一個開源的實作課程,從基礎 RL 概念銜接到 LLM 對齊、RLVR 和進階 Agentic 系統。+**Hands-on Modern RL**,一個開源的實作課程,從基礎 RL 概念銜接到 LLM 對齊、RLVR 和進階 Agentic 系統。---diff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 65c1e0d..478e663 100644--- a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -5,54 +5,54 @@# 第一講. 模型能力強,不等於執行可靠-你說你也算見過世面的人了——Claude Pro 訂著,GPT-4o 的 API key 也有,SWE-bench 排行榜上的數字你比誰都清楚。有一天你終於想讓 AI agent 幫你改一個真實的專案,信心滿滿地交代下去。結果呢?加了功能但測試掛了,改了 bug 但引入了新 bug,跑了 20 分鐘然後自信滿滿地說"完成了"——你一看程式碼,根本不是你要的東西。+你說你也算見過世面的人了,Claude Pro 訂著,GPT-4o 的 API key 也有,SWE-bench 排行榜上的數字你比誰都清楚。有一天你終於想讓 AI agent 幫你改一個真實的專案,信心滿滿地交代下去。結果呢?加了功能但測試掛了,改了 bug 但引入了新 bug,跑了 20 分鐘然後自信滿滿地說"完成了",你一看程式碼,根本不是你要的東西。這時候你的第一反應是什麼?"這模型不行,得換一個更貴的。"且慢。先別急著掏錢包。問題可能根本不在模型身上。-讓我們先看一組數據。截至 2025 年底,最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這還是精心挑選過的、有明確 issue 描述和測試用例的任務。換到你日常開發的場景——需求模糊、沒有現成測試、隱含的業務規則散落在各處——這個數字只會更低。+讓我們先看一組數據。截至 2025 年底,最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這還是精心挑選過的、有明確 issue 描述和測試用例的任務。換到你日常開發的場景,需求模糊、沒有現成測試、隱含的業務規則散落在各處,這個數字只會更低。但這組數據背後藏著一個反直覺的事實。## 同一匹馬,兩種命運-Anthropic 做過一個對照實驗。同一個 prompt("做一個 2D 復古遊戲編輯器"),同一個模型(Opus 4.5)。第一次讓它裸跑——20 分鐘,花了 $9,遊戲核心功能根本跑不起來。第二次給它配上完整的 harness(planner + generator + evaluator 三 agent 架構)——6 小時,花了 $200,遊戲可以正常遊玩。+Anthropic 做過一個對照實驗。同一個 prompt("做一個 2D 復古遊戲編輯器"),同一個模型(Opus 4.5)。第一次讓它裸跑,20 分鐘,花了 $9,遊戲核心功能根本跑不起來。第二次給它配上完整的 harness(planner + generator + evaluator 三 agent 架構),6 小時,花了 $200,遊戲可以正常遊玩。模型沒換。Opus 4.5 還是那個 Opus 4.5。換的是馬具。-OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接:Codex 在一個 harness 搭得好的儲存庫裡,表現能從"不可靠"變成"可靠"。注意他們的用詞——不是"好了一點",是質變。就像一匹千里馬,沒馬具你也能騎,但控不穩、走不遠、摔下來也不稀奇。harness 就是那整套馬具——**模型權重之外的一切工程基礎設施**。+OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Codex 在一個 harness 搭得好的儲存庫裡,表現能從"不可靠"變成"可靠"。注意他們的用詞,那不是"好了一點",是質變。一匹千里馬若沒有馬具,你也能騎,但控不穩、走不遠、摔下來也不稀奇。harness 就是那整套馬具,**模型權重之外的一切工程基礎設施**。## agent 到底卡在哪那具體是什麼在出問題?-最常見的:你根本沒把任務說清楚。你說"加個搜索功能",agent 理解的跟你完全不一樣——搜什麼?全文字還是結構化?要不要分頁?要不要標記?你沒說清楚,agent 就自己猜。猜對了是運氣,猜錯了你再改,改的成本比一開始說清楚還高。這就像你去飯館跟師傅說"來個魚",端上來是紅燒還是清蒸還是酸菜——全看運氣。+最常見的問題是任務說得不夠完整。你說"加個搜索功能",agent 理解的跟你完全不一樣,搜什麼?全文字還是結構化?要不要分頁?要不要標記?你沒說清楚,agent 就自己猜。猜對了是運氣,猜錯了你再改,改的成本比一開始說清楚還高。你去飯館跟師傅說"來個魚",端上來是紅燒還是清蒸還是酸菜,全看運氣。-就算你說清了,專案裡隱含的架構約定 agent 也不知道。你們團隊統一用 SQLAlchemy 2.0 的新語法,但 agent 預設寫了 1.x 的程式碼。所有 API 端點必須走 OAuth 2.0 認證,但這個規則只存在於你腦子裡和一個三個月前的 Slack 消息裡。Agent 看不到這些——它不是不想遵守,是壓根不知道有這回事。+就算你說清了,專案裡隱含的架構約定 agent 也不知道。你們團隊統一用 SQLAlchemy 2.0 的新語法,但 agent 預設寫了 1.x 的程式碼。所有 API 端點必須走 OAuth 2.0 認證,但這個規則只存在於你腦子裡和一個三個月前的 Slack 消息裡。Agent 看不到這些,它不是不想遵守,是壓根不知道有這回事。-環境也是個坑。開發環境配置不完整、依賴缺了、工具版本不對。Agent 把寶貴的脈絡視窗花在了 `pip install` 失敗、Node 版本不對這些事上,而不是解決你的核心任務。就好比你讓一個木匠來幹活,結果錘子沒帶、釘子找不到、工作臺還是歪的——手藝再好也使不上勁。+環境也是個坑。開發環境配置不完整、依賴缺了、工具版本不對。Agent 把寶貴的脈絡視窗花在了 `pip install` 失敗、Node 版本不對這些事上,而不是解決你的核心任務。就好比你讓一個木匠來幹活,結果錘子沒帶、釘子找不到、工作臺還是歪的,手藝再好也使不上勁。-更常見的:壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完程式碼,自己看了看覺得沒問題,就說完成了。這就像讓學生交作業但不給答案檢查——他自己覺得自己做對了,但批改的時候一堆錯誤。Anthropic 還觀察到一個有意思的現象:當 agent 感覺脈絡快滿了,它們會匆忙結束目前工作,跳過驗證步驟,選一個簡單的方案而不是最優方案。他們把這叫"脈絡焦慮"——跟你考試時發現時間快到了趕緊隨便選幾個選擇題是一回事。+更常見的問題是壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完程式碼,自己看了看覺得沒問題,就說完成了。讓學生交作業但不給答案檢查,結果是他自己覺得做對了,批改時卻一堆錯誤。Anthropic 還觀察到一個有意思的現象,當 agent 感覺脈絡快滿了,它們會匆忙結束目前工作,跳過驗證步驟,選一個簡單的方案而不是最優方案。他們把這叫"脈絡焦慮",跟你考試時發現時間快到了趕緊隨便選幾個選擇題是一回事。-長任務跨工作階段就更慘了——上次工作階段的發現全丟了,每個新工作階段都得重新探索專案結構、理解程式碼組織。缺乏持久化狀態的 agent 在超過 30 分鐘的任務中失敗率急劇上升。+長任務跨工作階段就更慘了,上次工作階段的發現全丟了,每個新工作階段都得重新探索專案結構、理解程式碼組織。缺乏持久化狀態的 agent 在超過 30 分鐘的任務中失敗率急劇上升。## 關鍵名詞解釋理解了上面的場景,這些概念就不再是一堆術語了:- **能力鴻溝(Capability Gap)**:模型在基準測試上的表現和真實任務上的表現之間的巨大落差。SWE-bench Verified 上 50-60% 的通過率意味著近一半的真實 issue 解不了。-- **Harness**:模型之外的一切——指令、工具、環境、狀態管理、驗證回饋。不是模型權重的部分,全是 harness。也就是我們說的"馬具"。+- **Harness**:模型之外的一切,指令、工具、環境、狀態管理、驗證回饋。不是模型權重的部分,全是 harness。也就是我們說的"馬具"。- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。Anthropic 的對照實驗已經證明了這一點。-- **驗證缺口**:agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說"我做完了"但實際沒做完——這是最常見的失敗模式。+- **驗證缺口**:agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說"我做完了"但實際沒做完,這是最常見的失敗模式。- **診斷循環**:執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。-- **完成定義(Definition of Done)**:一組可以用命令驗證的條件——測試通過、lint 沒報錯、類型檢查通過。沒有顯式的完成定義,agent 就會自己編一個。+- **完成定義(Definition of Done)**:一組可以用命令驗證的條件,測試通過、lint 沒報錯、類型檢查通過。沒有顯式的完成定義,agent 就會自己編一個。## 遇到失敗,先修 harness-核心原則:**遇到失敗,先別換模型,先檢查 harness。** 如果同一個模型在類似的結構良好的任務中能成功,那優先假設是 harness 的問題。這就像汽車拋錨——你不會第一時間懷疑是發動機壞了,你會先看看是不是沒油了。+核心原則,**遇到失敗,先別換模型,先檢查 harness。** 如果同一個模型在類似的結構良好的任務中能成功,那優先假設是 harness 的問題。汽車拋錨時,你不會第一時間懷疑是發動機壞了,你會先看看是不是沒油了。-具體怎麼做:+具體怎麼做。-**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問:是任務沒說清楚?是脈絡不夠?是沒有驗證手段?把每次失敗歸到五層防禦:任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。這裡說的是實操診斷用的五層防禦,不是上面那組六個術語。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。+**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問,是任務沒說清楚?是脈絡不夠?是沒有驗證手段?把每次失敗歸到五層防禦,任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。這裡說的是實操診斷用的五層防禦,不是上面那組六個術語。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。**給每個任務寫顯式的完成定義。** 不要說"加個搜索功能",要說:```@@ -64,21 +64,21 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接:Code- 類型檢查通過(mypy --strict)```-**建立 AGENTS.md 檔案。** 在儲存庫根目錄放一個檔案,告訴 agent 這個專案的技術棧、架構約定、驗證命令。這是 harness 工程的第一步,也是投入產出比最高的一步。一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效——我不是在開玩笑。+**建立 AGENTS.md 檔案。** 在儲存庫根目錄放一個檔案,告訴 agent 這個專案的技術棧、架構約定、驗證命令。這是 harness 工程的第一步,也是投入產出比最高的一步。一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效,這不是誇張。-**建立診斷循環。** 不要把失敗當作"模型又犯傻了",而是當作"harness 又暴露了一個缺陷"的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來,你的 harness 會越來越強,agent 的表現會穩定提升。就像修路——每填一個坑,下一段路就更平坦。+**建立診斷循環。** 不要把失敗當作"模型又犯傻了",而是當作"harness 又暴露了一個缺陷"的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來,你的 harness 會越來越強,agent 的表現會穩定提升。每修補一個缺陷,後續執行就更穩定。-**量化改進。** 記個簡單的日誌:每個任務成功了沒有,失敗了是哪一層的問題。跑幾輪之後你就能看出來哪個層是瓶頸,集中火力修那個層。+**量化改進。** 記個簡單的日誌,每個任務成功了沒有,失敗了是哪一層的問題。跑幾輪之後你就能看出來哪個層是瓶頸,集中火力修那個層。## 一百萬人行程式碼的實驗-OpenAI 在 2025 年做了一個激進的實驗:用 Codex 從一個空的 git 儲存庫起步,建構一個完整的內部產品。五個月後,這個儲存庫有大約 100 萬行程式碼——應用邏輯、基礎設施、工具、文件、內部開發工具——全部由 agent 生成。三個工程師驅動 Codex,開了大約 1,500 個 PR 並完成合併。平均每人每天 3.5 個 PR。+OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git 儲存庫起步,建構一個完整的內部產品。五個月後,這個儲存庫有大約 100 萬行程式碼,應用邏輯、基礎設施、工具、文件、內部開發工具,全部由 agent 生成。三個工程師驅動 Codex,開了大約 1,500 個 PR 並完成合併。平均每人每天 3.5 個 PR。-這個實驗的關鍵約束是:**人類永遠不直接寫程式碼。** 這不是噱頭,而是為了逼團隊搞清楚——當工程師的主要工作不再是寫程式碼,而是設計環境、表達意圖、建構回饋迴路時,到底什麼變了?+這個實驗的關鍵約束,是**人類永遠不直接寫程式碼。** 這個設定是為了逼團隊搞清楚,當工程師的主要工作不再是寫程式碼,而是設計環境、表達意圖、建構回饋迴路時,到底什麼變了?-早期進展比預期慢。不是 Codex 不行,而是環境不夠完整——agent 缺少必要的工具、抽象和內部結構來推進高層次目標。工程師的工作變成了:把大目標拆成小積木(設計、編碼、審查、測試),讓 agent 去搭建,然後用這些積木解鎖更復雜的任務。當某件事失敗了,修復幾乎從來不是"更努力",而是"agent 缺什麼能力,怎麼讓它既可理解又可執行"。+早期進展比預期慢。原因在於環境不夠完整,agent 缺少必要的工具、抽象和內部結構來推進高層次目標。工程師的工作變成了,把大目標拆成小積木(設計、編碼、審查、測試),讓 agent 去搭建,然後用這些積木解鎖更復雜的任務。當某件事失敗了,修復方向幾乎從來都不靠「更努力」,真正的問題是找清楚 agent 缺什麼能力、怎麼讓它既可理解又可執行。-這個實驗直接證明了本講的核心論點:**同一個模型,在空白環境裡和在有完整 harness 的環境裡,產出有本質差異。** 模型沒變,變的是環境。+這個實驗直接證明了本講的核心論點,**同一個模型,在空白環境裡和在有完整 harness 的環境裡,產出有本質差異。** 模型沒變,變的是環境。> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)@@ -95,9 +95,9 @@ OpenAI 在 2025 年做了一個激進的實驗:用 Codex 從一個空的 git## 帶走什麼- 模型能力和執行可靠性是兩回事。千里馬也得配上好馬具。-- 失敗的時候先看 harness,再看模型。換模型是成本最高的選擇——而且很多時候根本不是模型的問題。+- 失敗的時候先看 harness,再看模型。換模型是成本最高的選擇,而且很多時候根本不是模型的問題。- 每次失敗都是一個信號:你的 harness 有結構性缺陷。把它找出來、修掉。-- 五層防禦:任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。逐層排查,就像醫生看病先檢查最常見的病因。+- 五層防禦:任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。逐層排查,優先從最常見的失敗原因入手。- 一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效。真的。## 延伸閱讀@@ -112,6 +112,6 @@ OpenAI 在 2025 年做了一個激進的實驗:用 Codex 從一個空的 git1. **對比實驗**:選一個你熟悉的程式碼儲存庫和一項非平凡的修改任務。先不給任何 harness 支援,讓 agent 跑一次,記錄失敗。然後加一個 `AGENTS.md` 和顯式的驗證命令,讓同一個 agent 再跑一次。對比兩次的結果,把失敗歸因到五層防禦中的某一層。-2. **驗證缺口測量**:選 5 個編碼任務,在每個任務完成後記錄 agent 是否聲稱完成,然後用獨立測試驗證實際正確性。計算 agent 在實際沒完成時聲稱完成的比例——這就是你的驗證缺口。然後想想:加什麼驗證命令能把這個比例降下來?+2. **驗證缺口測量**:選 5 個編碼任務,在每個任務完成後記錄 agent 是否聲稱完成,然後用獨立測試驗證實際正確性。計算 agent 在實際沒完成時聲稱完成的比例,這就是你的驗證缺口。然後想想:加什麼驗證命令能把這個比例降下來?3. **診斷循環實踐**:找一個 agent 在你的專案中反覆失敗的任務。跑一次,記錄失敗。歸因到五層中的某一層。修那一層。再跑。重複三到五輪,記錄每一輪的改善。diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 645b16a..2ae6f4d 100644--- a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -5,39 +5,39 @@# 第二講. Harness 到底是什麼-"harness"這個詞在 AI coding agent 的圈子裡被用得越來越多了,但說實話,大部分人說的 harness 其實就只是"一個 prompt 檔案"。這不是 harness。就像你開了一家餐廳,只有食材——沒有灶臺、沒有刀具、沒有菜譜、沒有出菜流程——那不叫餐廳,那叫冰箱。+"harness"這個詞在 AI coding agent 的圈子裡被用得越來越多了,但說實話,大部分人說的 harness 其實就只是"一個 prompt 檔案"。這不是 harness。你開了一家餐廳,只有食材,沒有灶臺、沒有刀具、沒有菜譜、沒有出菜流程,那不叫餐廳,那叫冰箱。-這節課要給你一個精確的、可操作的 harness 定義。不是學術論文裡的抽象概念,而是你今天就能拿去用的框架:harness 由五個子系統組成,就像一個完整廚房裡的五個功能區——菜譜架、刀具架、灶臺、備菜臺、和出菜檢查口。每個子系統都有明確的職責和評判標準。+這節課要給你一個精確的、可操作的 harness 定義。這個框架可以直接使用,不同於學術論文裡的抽象概念,harness 由五個子系統組成,分別對應廚房的五個功能區,菜譜架、刀具架、灶臺、備菜臺、和出菜檢查口。每個子系統都有明確的職責和評判標準。## 以一個類比出發-想象你是一個剛入職的工程師,被丟進一個沒有任何文件的專案裡。沒有 README,程式碼裡沒有註釋,沒有人告訴你怎麼跑測試,CI 配置檔案藏在某個角落裡。你能寫出好程式碼嗎?也許能——如果你足夠聰明又足夠有耐心。但你會花大量時間在"搞清楚這個專案是怎麼回事"上,而不是在"解決問題"上。+想象你是一個剛入職的工程師,被丟進一個沒有任何文件的專案裡。沒有 README,程式碼裡沒有註釋,沒有人告訴你怎麼跑測試,CI 配置檔案藏在某個角落裡。你能寫出好程式碼嗎?也許能,如果你足夠聰明又足夠有耐心。但你會花大量時間在"搞清楚這個專案是怎麼回事"上,而不是在"解決問題"上。-AI agent 面對的困境一模一樣。而且更糟——你至少可以問同事,agent 只能看到你放在它面前的檔案和它能執行的命令。它不能拍拍同事的肩膀問"哎,這個專案的 ORM 用的是哪個版本?"+AI agent 面對的困境一模一樣。而且更糟,你至少可以問同事,agent 只能看到你放在它面前的檔案和它能執行的命令。它不能拍拍同事的肩膀問"哎,這個專案的 ORM 用的是哪個版本?"-OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表述為"儲存庫即規範"——所有必要的脈絡都應該在儲存庫裡,透過結構化的指令檔案、明確的驗證命令和清晰的目錄組織來呈現。Anthropic 的 long-running agents 文件則更側重狀態持久化、顯式恢復路徑和結構化的進度跟蹤。兩家公司的側重點不同,但都在說同一件事:**模型之外的一切工程基礎設施,決定了模型能力能被髮揮多少。**+OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表述為"儲存庫即規範",所有必要的脈絡都應該在儲存庫裡,透過結構化的指令檔案、明確的驗證命令和有序的目錄組織來呈現。Anthropic 的 long-running agents 文件則更側重狀態持久化、顯式恢復路徑和結構化的進度跟蹤。兩家公司的側重點不同,但都在說同一件事,**模型之外的一切工程基礎設施,決定了模型能力能被髮揮多少。**-看看幾個你熟悉的工具:+看看幾個你熟悉的工具。-**Claude Code** 的設計就體現了 harness 思想。它會讀你儲存庫裡的 `CLAUDE.md`(菜譜架),能用 shell 跑命令(刀具架),在你的本地環境裡執行(灶臺),有工作階段歷史(備菜臺),能跑測試看結果(出菜檢查口)。但如果你不告訴它怎麼跑測試,出菜檢查口就是斷的——菜做沒做熟誰也不知道。+**Claude Code** 的設計就體現了 harness 思想。它會讀你儲存庫裡的 `CLAUDE.md`(菜譜架),能用 shell 跑命令(刀具架),在你的本地環境裡執行(灶臺),有工作階段歷史(備菜臺),能跑測試看結果(出菜檢查口)。但如果你不告訴它怎麼跑測試,出菜檢查口就是斷的,菜做沒做熟誰也不知道。-**Cursor** 也是類似的邏輯。它的 `.cursorrules` 檔案是菜譜架,終端是刀具架,它能讀你的專案結構和 lint 配置是灶臺。但 Cursor 的狀態管理相對弱——你關掉 IDE 再打開,上次的脈絡就沒了。+**Cursor** 也是類似的邏輯。它的 `.cursorrules` 檔案是菜譜架,終端是刀具架,它能讀你的專案結構和 lint 配置是灶臺。但 Cursor 的狀態管理相對弱,你關掉 IDE 再打開,上次的脈絡就沒了。-**Codex**(OpenAI 的 coding agent)用 git worktree 隔離每個任務的執行環境,配合本地的可觀測性棧(日誌、指標、追蹤),讓每個變更都在獨立的環境中驗證。它在有 `AGENTS.md` 和清晰驗證命令的儲存庫裡,表現遠超在"裸"儲存庫裡。+**Codex**(OpenAI 的 coding agent)用 git worktree 隔離每個任務的執行環境,配合本地的可觀測性棧(日誌、指標、追蹤),讓每個變更都在獨立的環境中驗證。它在有 `AGENTS.md` 和明確驗證命令的儲存庫裡,表現遠超在"裸"儲存庫裡。-**AutoGPT** 則是反面教材——缺乏結構化的狀態管理導致長任務中脈絡不斷累積,缺乏精確的回饋機制導致 agent 陷入循環。很多人說 AutoGPT "不行",但其實是它的 harness 不行——你給它一個破灶臺,再好的食材也做不出菜來。+**AutoGPT** 則是反面教材,缺乏結構化的狀態管理導致長任務中脈絡不斷累積,缺乏精確的回饋機制導致 agent 陷入循環。很多人說 AutoGPT "不行",但其實是它的 harness 不行,你給它一個破灶臺,再好的食材也做不出菜來。## 核心概念- **什麼是 harness**:模型權重之外的一切工程基礎設施。OpenAI 把工程師的核心工作概括為三件事:設計環境、表達意圖、建構回饋循環。Anthropic 直接把 Claude Agent SDK 稱為"通用 agent harness"。-- **儲存庫是唯一事實來源**:agent 看不到的東西,對它來說就不存在。OpenAI 把儲存庫當作"記錄系統"——所有必要的脈絡都必須在儲存庫裡,透過結構化的檔案和清晰的目錄組織來呈現。-- **給地圖,不給說明書**:OpenAI 的經驗——`AGENTS.md` 應該是目錄頁,不是百科全書。100 行左右就夠了,放不下就拆分到 `docs/` 目錄裡,讓 agent 按需去讀。+- **儲存庫是唯一事實來源**:agent 看不到的東西,對它來說就不存在。OpenAI 把儲存庫當作"記錄系統",所有必要的脈絡都必須在儲存庫裡,透過結構化的檔案和有序的目錄組織來呈現。+- **給地圖,不給說明書**:OpenAI 的經驗,`AGENTS.md` 應該是目錄頁,不是百科全書。100 行左右就夠了,放不下就拆分到 `docs/` 目錄裡,讓 agent 按需去讀。- **約束而非微操**:好的 harness 用可執行的規則來約束 agent,而不是在指令裡逐條叮囑。OpenAI 說"執行不變數,不要微管實現";Anthropic 發現 agent 會自信地誇讚自己的工作,解決方案是把"幹活的人"和"檢查的人"分開。- **逐個組件拆除法**:想量化 harness 各組件的邊際貢獻,就逐個移除,看哪個移除後效能下降最多。它能告訴你哪些組件目前最有價值,也能暴露哪些組件暫時貢獻不明顯。Anthropic 用這個方法發現:隨著模型變強,某些組件不再關鍵,但總會有新的關鍵組件出現。## Harness 五子系統模型-回到廚房的類比。一個完整的廚房有五個功能區,harness 也有五個子系統:+回到廚房的類比。一個完整的廚房有五個功能區,harness 也有五個子系統。```mermaidflowchart LR@@ -51,7 +51,7 @@ flowchart LR**指令子系統(菜譜架)**:建立 `AGENTS.md`(或 `CLAUDE.md`),內容包括專案概覽和目的(一句話說清楚這是什麼)、技術棧和版本(Python 3.11、FastAPI 0.100+、PostgreSQL 15)、首次執行命令(`make setup`、`make test`)、不可違反的硬約束("所有 API 必須走 OAuth 2.0")、指向更詳細文件的連結。-**工具子系統(刀具架)**:確保 agent 有足夠的工具訪問權限。不要因為"安全考慮"把 shell 給禁了——agent 連 `pip install` 都跑不了,還怎麼幹活?但也別什麼都開放,按最小權限原則來。+**工具子系統(刀具架)**:讓 agent 有足夠的工具訪問權限。不要因為"安全考慮"把 shell 給禁了,agent 連 `pip install` 都跑不了,還怎麼幹活?但也別什麼都開放,按最小權限原則來。**環境子系統(灶臺)**:讓環境狀態自描述。用 `pyproject.toml` 或 `package.json` 鎖定依賴,用 `.nvmrc` 或 `.python-version` 指定執行時期版本,用 Docker 或 devcontainer 讓環境可重現。@@ -66,29 +66,29 @@ flowchart LR- 完整驗證:make check(包含以上全部)```-五個子系統缺一個,就像廚房裡少了一個功能區——菜還是能做,但總是彆扭。+五個子系統缺一個,廚房裡少了一個功能區,菜還是能做,但總是彆扭。-**量化 harness 組件價值的方法**:用「等模型對照下的組件拆除實驗」。保持模型不變,逐個移除五個子系統,看哪個子系統缺失時效能下降最多。下降最多的組件,說明它在目前任務裡邊際貢獻最大,值得優先保留;是否要加強它,取決於失敗歸因,而不是只看下降幅度。幾乎沒有影響的組件,也不能直接判定為無用:它可能是冗餘、設計失效,或還沒有被這個任務充分觸發。這個實驗回答的是「目前哪個組件最有價值」,不能單獨證明「瓶頸在哪裡」。真正定位瓶頸,要先看失敗記錄和歸因:任務沒說清楚、脈絡不足、環境不可復現、驗證回饋缺失,還是狀態管理斷裂;組件拆除結果只能作為輔助證據。+**量化 harness 組件價值的方法**:用「等模型對照下的組件拆除實驗」。保持模型不變,逐個移除五個子系統,看哪個子系統缺失時效能下降最多。下降最多的組件,說明它在目前任務裡邊際貢獻最大,值得優先保留;是否要加強它,取決於失敗歸因,而不是只看下降幅度。幾乎沒有影響的組件,也不能直接判定為無用,它可能是冗餘、設計失效,或還沒有被這個任務充分觸發。這個實驗回答的是「目前哪個組件最有價值」,不能單獨證明「瓶頸在哪裡」。真正定位瓶頸,要先看失敗記錄和歸因,包含任務沒說清楚、脈絡不足、環境不可復現、驗證回饋缺失,還是狀態管理斷裂;組件拆除結果只能作為輔助證據。## 一個團隊的真實經歷-一個團隊用 GPT-4o 開發一個 TypeScript + React 前端應用(約 20,000 行程式碼)。他們經歷了四個階段——其實就是在一件一件地添置廚具:+一個團隊用 GPT-4o 開發一個 TypeScript + React 前端應用(約 20,000 行程式碼)。他們經歷了四個階段,其實就是在一件一件地添置廚具。-**階段 1——空廚房**:只有 README 裡的基本專案描述。5 次執行成功 1 次(20%)。主要失敗:選錯了包管理器(npm vs yarn)、沒遵循組件命名約定、跑不了測試。+**階段 1,空廚房**:只有 README 裡的基本專案描述。5 次執行成功 1 次(20%)。主要失敗在於選錯了包管理器(npm vs yarn)、沒遵循組件命名約定、跑不了測試。-**階段 2——裝上菜譜架**:添加 `AGENTS.md`,寫明技術棧版本、命名約定、關鍵架構決策。成功率升到 60%。剩餘失敗主要來自環境問題和驗證缺失。+**階段 2,裝上菜譜架**:添加 `AGENTS.md`,寫明技術棧版本、命名約定、關鍵架構決策。成功率升到 60%。剩餘失敗主要來自環境問題和驗證缺失。-**階段 3——開起出菜檢查口**:在 `AGENTS.md` 裡列出驗證命令 `yarn test && yarn lint && yarn build`。成功率升到 80%。+**階段 3,開起出菜檢查口**:在 `AGENTS.md` 裡列出驗證命令 `yarn test && yarn lint && yarn build`。成功率升到 80%。-**階段 4——備菜臺就位**:引入進度檔案範本,agent 在每次執行中記錄完成和未完成的工作。成功率穩定在 80-100%。+**階段 4,備菜臺就位**:引入進度檔案範本,agent 在每次執行中記錄完成和未完成的工作。成功率穩定在 80-100%。四次迭代,模型一個字沒改,成功率從 20% 到接近 100%。這就是 harness 工程的力量。你沒有換更貴的食材,你只是把廚房收拾俐落了。## 關鍵要點-- Harness = 指令 + 工具 + 環境 + 狀態 + 回饋。五個子系統,就像廚房的五個功能區,缺一不可。+- Harness = 指令 + 工具 + 環境 + 狀態 + 回饋。五個子系統,分別對應廚房的五個功能區,缺一不可。- 不是模型權重的部分全是 harness。你的 harness 決定了模型能力能被髮揮多少。-- 五個子系統中,回饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚——出菜檢查口是最值得先裝的。+- 五個子系統中,回饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚,出菜檢查口是最值得先裝的。- 用「等模型對照下的組件拆除實驗」量化各子系統的邊際貢獻;定位真正瓶頸要靠失敗記錄和歸因,不能只靠拆除實驗。- Harness 和程式碼一樣會腐化。定期審計,像還技術債一樣還 harness 債。diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 28676b1..2fe4b94 100644--- a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,21 +5,21 @@# 第三講. 讓程式碼儲存庫成為唯一的事實來源-你團隊的架構決策散落在 Confluence、Slack、Jira、和幾個資深工程師的腦子裡。對人類來說這勉強夠用——你可以問同事、搜聊天記錄、翻文件。實在不行還能去茶水間堵人。但對 AI agent 來說,不在儲存庫裡的資訊等於不存在。+你團隊的架構決策散落在 Confluence、Slack、Jira、和幾個資深工程師的腦子裡。對人類來說這勉強夠用,你可以問同事、搜聊天記錄、翻文件。實在不行還能去茶水間堵人。但對 AI agent 來說,不在儲存庫裡的資訊等於不存在。-這不是誇張。想想 agent 的輸入都有什麼:系統提示和任務描述、儲存庫裡的檔案內容、以及工具執行的輸出。就這三樣。你的 Slack 歷史、Jira 工單、Confluence 頁面、和週五下午跟同事在茶水間聊的架構決定——agent 全都看不到。它不能"去問一下",也不能"搜一下聊天記錄"。它就是一個被關在儲存庫裡的工程師——儲存庫外面的事,它一概不知。+這不是誇張。想想 agent 的輸入,系統提示和任務描述、儲存庫裡的檔案內容、以及工具執行的輸出。就這三樣。你的 Slack 歷史、Jira 工單、Confluence 頁面、和週五下午跟同事在茶水間聊的架構決定,agent 全都看不到。它不能"去問一下",也不能"搜一下聊天記錄"。它就是一個被關在儲存庫裡的工程師,儲存庫外面的事,它一概不知。所以問題變成了:你給不給這個工程師一張好地圖?## 地圖上該畫什麼-OpenAI 在他們的 harness engineering 文章裡把這個問題說得非常直接:**儲存庫裡不存在的資訊,對 agent 來說等於不存在。** 他們把這稱為"儲存庫即規範"原則——儲存庫本身就是最高權威的規範文件。+OpenAI 在他們的 harness engineering 文章裡把這個問題說得非常直接,**儲存庫裡不存在的資訊,對 agent 來說等於不存在。** 他們把這稱為"儲存庫即規範"原則,儲存庫本身就是最高權威的規範文件。-Anthropic 的 long-running agents 文件也強調了類似的觀點:持久化狀態是長任務連續性的必要條件。跨工作階段的知識可恢復性直接決定了任務成功率。而這些狀態必須存在於儲存庫中——因為那是 agent 唯一穩定可訪問的存儲。+Anthropic 的 long-running agents 文件也強調了類似的觀點:持久化狀態是長任務連續性的必要條件。跨工作階段的知識可恢復性直接決定了任務成功率。而這些狀態必須存在於儲存庫中,因為那是 agent 唯一穩定可訪問的存儲。你可能會想:"我們團隊人少,知識都在大家腦子裡,這不也工作得好好的嗎?"沒錯,對人類來說確實可以。但你要用 agent,就得接受一個事實:agent 不能問人。所有它需要知道的東西,都必須寫下來,放在它能找到的地方。-這不是"寫更多文件"的問題。這是"把決策資訊放到正確的位置"的問題。一份在 `src/api/` 目錄下、50 行的 `ARCHITECTURE.md`,比一份在 Confluence 裡、500 頁但沒人維護的設計文件有用一萬倍。就好比一張貼在你工位上的、手畫的辦公室走法圖,比一份精美的、放在檔案室裡的建築藍圖實用得多——因為前者在你需要的時候就在手邊。+這不是"寫更多文件"的問題。這是"把決策資訊放到正確的位置"的問題。一份在 `src/api/` 目錄下、50 行的 `ARCHITECTURE.md`,比一份在 Confluence 裡、500 頁但沒人維護的設計文件有用一萬倍。就好比一張貼在你工位上的、手畫的辦公室走法圖,比一份精美的、放在檔案室裡的建築藍圖實用得多,因為前者在你需要的時候就在手邊。## 知識可見性@@ -34,7 +34,7 @@ flowchart LRWarning["規則不寫進儲存庫<br/>agent 就看不見"] --> Agent```-怎麼檢驗你的地圖畫得夠不夠好?做一個"冷啟動測試":開一個全新的 agent 工作階段,只看儲存庫內容,看它能不能回答五個基本問題:+怎麼檢驗你的地圖畫得夠不夠好?做一個「冷啟動測試」,開一個全新的 agent 工作階段,只看儲存庫內容,看它能不能回答五個基本問題。```mermaidflowchart TB@@ -51,24 +51,24 @@ flowchart TBA5 --> Ready```-如果它答不上來,說明地圖上有空白。空白的地方,agent 就得自己猜——猜錯了就是 bug,猜多了就浪費脈絡。每個新工作階段都要猜一遍,猜的成本遠高於一開始就把地圖畫好的成本。+如果它答不上來,說明地圖上有空白。空白的地方,agent 就得自己猜,猜錯了就是 bug,猜多了就浪費脈絡。每個新工作階段都要猜一遍,猜的成本遠高於一開始就把地圖畫好的成本。## 核心概念-- **知識可見性缺口**:專案總知識中不在儲存庫裡的比例。缺口越大,agent 失敗的概率越高。你腦子裡有多少關於這個專案的隱性知識?把它們全算上,再看有多少寫進了儲存庫——兩者的差距就是你的可見性缺口。-- **系統記錄(System of Record)**:程式碼儲存庫作為專案決策、架構約束、執行狀態和驗證標準的權威資訊源。儲存庫說了算,別的地方說了不算。就像地圖上標註了"此路不通",你就不會再往那條路走——但如果這個資訊只在老張的腦子裡,你每次都得問老張。+- **知識可見性缺口**:專案總知識中不在儲存庫裡的比例。缺口越大,agent 失敗的概率越高。你腦子裡有多少關於這個專案的隱性知識?把它們全算上,再看有多少寫進了儲存庫,兩者的差距就是你的可見性缺口。+- **系統記錄(System of Record)**:程式碼儲存庫作為專案決策、架構約束、執行狀態和驗證標準的權威資訊源。儲存庫說了算,別的地方說了不算。地圖上標出「此路不通」,走的人自然繞行;但這個資訊若只留在老張腦子裡,每次都得去問老張。- **冷啟動測試**:上一節說的五個問題。能回答幾個,你的地圖就畫了幾分。-- **發現成本**:agent 為了在儲存庫裡找到一條關鍵資訊需要消耗多少脈絡。資訊放得越隱蔽,發現成本越高,留給實際任務的預算越少。把關鍵資訊藏在十層目錄深處的 README 裡,就像把滅火器鎖在地下室的保險櫃裡——不是沒有,是用的時候找不到。-- **知識衰減率**:儲存庫中單位時間內變得過時的知識條目比例。文件和程式碼脫節是最大的敵人——比沒有文件更危險的是過時的文件。+- **發現成本**:agent 為了在儲存庫裡找到一條關鍵資訊需要消耗多少脈絡。資訊放得越隱蔽,發現成本越高,留給實際任務的預算越少。把關鍵資訊藏在十層目錄深處的 README 裡,不是沒有,是用的時候找不到。+- **知識衰減率**:儲存庫中單位時間內變得過時的知識條目比例。文件和程式碼脫節是最大的敵人,比沒有文件更危險的是過時的文件。- **ACID 類比**:把數據庫的事務管理原則(原子性、一致性、隔離性、持久性)用到 agent 的狀態管理上。後面會展開講。## 怎麼畫好這張地圖-**原則 1:知識靠近程式碼。** 一條關於 API 端點認證的規則,應該放在 API 程式碼旁邊,而不是藏在一個巨大的全域文件裡。每個模組目錄下放一個簡短的文件,說清楚這個模組的職責、介面和特殊約束。就像圖書館的書架標籤——你想找歷史類書籍,直接去標著"歷史"的書架,不用把整個圖書館翻一遍。+**原則 1:知識靠近程式碼。** 一條關於 API 端點認證的規則,應該放在 API 程式碼旁邊,而不是藏在一個巨大的全域文件裡。每個模組目錄下放一個簡短的文件,說清楚這個模組的職責、介面和特殊約束。圖書館按主題分類書架,找歷史類書籍直接去歷史書架,不用翻遍整個圖書館。**原則 2:用標準化的入口檔案。** `AGENTS.md`(或 `CLAUDE.md`)是 agent 的"著陸頁"。它不需要包含所有資訊,但必須能讓 agent 快速回答"這是什麼專案"、"怎麼跑"、"怎麼驗證"這三個問題。50-100 行就夠了。-**原則 3:最小但完備。** 每條知識都應該有明確的使用場景。如果你刪掉某條規則不影響 agent 的決策質量,那這條規則就不應該存在。但冷啟動測試中的每個問題都必須有答案。這是一個精妙的平衡——不多不少,剛好夠用。+**原則 3:最小但完備。** 每條知識都應該有明確的使用場景。如果你刪掉某條規則不影響 agent 的決策質量,那這條規則就不應該存在。但冷啟動測試中的每個問題都必須有答案。這是一個精妙的平衡,不多不少,剛好夠用。**原則 4:和程式碼一起更新。** 把知識更新跟程式碼變更綁定在一起。最簡單的方法:把架構文件放在對應的模組目錄裡。改程式碼的時候自然會看到文件,改程式碼之後 CI 提醒你檢查文件是否需要更新。@@ -91,18 +91,18 @@ project/## 用 ACID 原則管理 agent 狀態-這個類比來自數據庫的事務管理——你可能覺得這是在把簡單的事情搞複雜,但實際上它給了你一個非常實用的框架:+這個類比來自數據庫的事務管理,你可能覺得這是在把簡單的事情搞複雜,但實際上它給了你一個非常實用的框架。- **原子性**:每次"邏輯操作"(比如"添加新端點並更新測試")用一個 git commit 原子化。中途掛了就 `git stash` 回溯。要麼全做,要麼不做,沒有"做了一半"。-- **一致性**:定義"一致狀態"的驗證謂詞——所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。就像銀行轉賬——你不能只扣款不入賬。-- **隔離性**:多個 agent 併發工作時,狀態檔案要避免競爭條件。簡單方案:每個 agent 用獨立的進度檔案,或者用 git 分支隔離。兩個廚師不能同時往同一口鍋裡放鹽——放重了誰負責?+- **一致性**:定義"一致狀態"的驗證謂詞,所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。銀行轉賬不能只扣款不入賬。+- **隔離性**:多個 agent 併發工作時,狀態檔案要避免競爭條件。簡單方案:每個 agent 用獨立的進度檔案,或者用 git 分支隔離。兩個廚師不能同時往同一口鍋裡放鹽,放重了誰負責?- **持久性**:關鍵的專案知識用 git 跟蹤的檔案持久化。臨時狀態可以只在工作階段的記憶體中,但跨工作階段必須的知識必須寫到檔案裡。腦子裡的不算,寫在紙上的才算。## 一個真實的改造故事一個團隊維護一個包含約 30 個微服務的電商平臺。架構決策(服務間通信協定、數據一致性策略、API 版本化規則)散落在:Confluence(部分過時)、Slack(難以搜索)、幾個資深工程師的腦子裡(不可擴展)、以及零星的程式碼註釋(不繫統)。-引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個"所有人都知道但從未寫入儲存庫"的隱性約束。這就像一個新來的員工,沒人告訴他"中午點外賣要在群裡接龍"——他自己猜,猜錯了被罵,但罵完了還是沒人告訴他規則。+引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個"所有人都知道但從未寫入儲存庫"的隱性約束。新員工不知道「中午點外賣要在群裡接龍」的規矩,只能猜;猜錯了被罵,被罵了也還是沒人明說。團隊執行了改造:1. 儲存庫根目錄建立 `AGENTS.md`,寫明專案概覽、技術棧版本、全域硬約束@@ -114,11 +114,11 @@ project/## 關鍵要點-- 不在儲存庫裡的知識對 agent 來說等於不存在。把關鍵決策資訊放進儲存庫是最基本的 harness 投資——畫好地圖,才不會迷路。+- 不在儲存庫裡的知識對 agent 來說等於不存在。把關鍵決策資訊放進儲存庫是最基本的 harness 投資,畫好地圖,才不會迷路。- 用"冷啟動測試"檢驗儲存庫質量:全新工作階段能不能只看儲存庫回答五個基本問題。- 知識要靠近程式碼、最小但完備、跟程式碼一起更新。不是寫更多文件,是把資訊放到正確的位置。- 用 ACID 原則管理 agent 狀態:原子提交、一致性驗證、隔離併發、持久化關鍵知識。-- 知識衰減是最大敵人。過時的文件比沒有文件更危險——它會讓 agent 走錯方向還以為自己是對的。+- 知識衰減是最大敵人。過時的文件比沒有文件更危險,它會讓 agent 走錯方向還以為自己是對的。## 延伸閱讀@@ -134,4 +134,4 @@ project/2. **知識外置化量化**:列出你的專案中所有對開發工作重要的決策和約束。標註每個條目是在儲存庫內還是儲存庫外。算一下你的知識可見性缺口有多大(不在儲存庫裡的佔總數的比例)。制定計劃把缺口降到 10% 以下。-3. **ACID 準則評估**:用本講的 ACID 類比評估你的專案狀態管理。原子性——agent 的操作能不能幹淨地回溯?一致性——儲存庫有沒有"一致狀態"的驗證?隔離性——多 agent 併發時會不會互相踩腳?持久性——跨工作階段的知識是不是都持久化了?+3. **ACID 準則評估**:用本講的 ACID 類比評估你的專案狀態管理。原子性,agent 的操作能不能幹淨地回溯?一致性,儲存庫有沒有"一致狀態"的驗證?隔離性,多 agent 併發時會不會互相踩腳?持久性,跨工作階段的知識是不是都持久化了?diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex def9669..840c293 100644--- a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,31 +5,31 @@# 第四講. 把指令拆分到不同檔案裡-你開始認真對待 harness 了——好事。你建了個 `AGENTS.md`,把你能想到的所有規則、約束、歷史教訓都塞了進去。一個月後這個檔案膨脹到了 300 行,兩個月 450 行,三個月 600 行。然後你發現 agent 的表現反而變差了——改一個小 bug,agent 花大量脈絡處理無關的部署指令;關鍵的安全約束埋在第 300 行,被直接忽略了;檔案裡有三條互相矛盾的程式碼風格規則,agent 每次隨機選一條。+你開始認真對待 harness 了,好事。你建了個 `AGENTS.md`,把你能想到的所有規則、約束、歷史教訓都塞了進去。一個月後這個檔案膨脹到了 300 行,兩個月 450 行,三個月 600 行。然後你發現 agent 的表現反而變差了,改一個小 bug,agent 花大量脈絡處理無關的部署指令;關鍵的安全約束埋在第 300 行,被直接忽略了;檔案裡有三條互相矛盾的程式碼風格規則,agent 每次隨機選一條。-這就是"巨型指令檔案"陷阱。就像你往行李箱裡塞東西——覺得什麼都有用,什麼都往裡裝,結果拉鍊快崩了,想找換洗內衣得把整個箱子翻一遍。帶了一箱子東西,但真正用上的可能只有三分之一。+這就是"巨型指令檔案"陷阱。什麼都往裡寫、覺得都有用,最後檔案膨脹,想找一條關鍵規則就得把整份文件翻一遍;agent 真正用到的可能只有三分之一。## 問題的根源:一個惡性循環-最常見的惡性循環是這樣的:agent 犯了個錯 → 你說"加條規則防止這個" → 加到 AGENTS.md → 暫時管用 → agent 又犯了另一個錯 → 再加一條 → 重複 → 檔案膨脹到不可控。+最常見的惡性循環是這樣,agent 犯了個錯 → 你說"加條規則防止這個" → 加到 AGENTS.md → 暫時管用 → agent 又犯了另一個錯 → 再加一條 → 重複 → 檔案膨脹到不可控。-這不是你的錯。這是一個非常自然的反應——每次出問題就"加條規則"感覺很合理,就像每次出門忘帶東西就往包裡多塞一樣。但累積效應是災難性的。讓我們看看具體出了什麼問題。+這不是你的錯。這是一個非常自然的反應,每次出問題就"加條規則"感覺很合理,但累積效應是災難性的。讓我們看看具體出了什麼問題。-**脈絡預算被吃掉了。** Agent 的脈絡視窗是有限的。假設你的 agent 有 200K tokens 的視窗(Claude 的標準),一個膨脹的指令檔案可能佔掉 10-20K。看起來還有不少餘量?但一個複雜的任務可能需要讀幾十個源檔案、工具執行的輸出也占脈絡、對話歷史也在累積。到真正需要理解程式碼的時候,預算已經不夠了——就像你的行李箱塞滿了"萬一用得著"的東西,結果放不下真正需要帶的電腦了。+**脈絡預算被吃掉了。** Agent 的脈絡視窗是有限的。假設你的 agent 有 200K tokens 的視窗(Claude 的標準),一個膨脹的指令檔案可能佔掉 10-20K。看起來還有不少餘量?但一個複雜的任務可能需要讀幾十個源檔案、工具執行的輸出也占脈絡、對話歷史也在累積。到真正需要理解程式碼的時候,預算已經不夠了。-**中間迷失。** "Lost in the Middle"這篇論文(Liu et al., 2023)清楚地證明了:LLM 對長文字中間部分的資訊利用效率顯著低於兩端。你的 AGENTS.md 有 600 行,第 300 行寫的是"所有數據庫查詢必須用參數化查詢"——這是安全硬約束。但它被埋在中間,agent 幾乎一定會忽略它。就像你的行李箱裡那瓶防曬霜——明明在最底層,但你翻三遍也找不到,最後又去買了一瓶。+**中間迷失。** "Lost in the Middle"這篇論文(Liu et al., 2023)清楚地證明了:LLM 對長文字中間部分的資訊利用效率顯著低於兩端。你的 AGENTS.md 有 600 行,第 300 行寫的是"所有數據庫查詢必須用參數化查詢",這是安全硬約束。但它被埋在中間,agent 幾乎一定會忽略它。-**優先級衝突。** 檔案裡混合了不可違反的硬約束("不得使用 eval()")、重要的設計指導("優先使用函數式風格")、和某個特定場景的歷史教訓("上週修了一個 WebSocket 記憶體洩漏,注意類似的模式")。這三條規則的重要性完全不同,但在檔案裡看起來一模一樣。Agent 沒有可靠的信號來區分——就像行李箱裡護照和充電線混在一起,看不出哪個更緊急。+**優先級衝突。** 檔案裡混合了不可違反的硬約束("不得使用 eval()")、重要的設計指導("優先使用函數式風格")、和某個特定場景的歷史教訓("上週修了一個 WebSocket 記憶體洩漏,注意類似的模式")。這三條規則的重要性完全不同,但在檔案裡看起來一模一樣。Agent 沒有可靠的信號來區分優先級。-**維護衰減。** 大檔案天生難維護。指令過時了沒人刪——因為刪除的後果不確定("也許別的地方依賴這條規則?"),但加新指令是無成本的。結果檔案只增不減,信噪比持續下降。這和軟體裡的技術債務積累一模一樣。+**維護衰減。** 大檔案天生難維護。指令過時了沒人刪,因為刪除的後果不確定("也許別的地方依賴這條規則?"),但加新指令是無成本的。結果檔案只增不減,信噪比持續下降。這和軟體裡的技術債務積累一模一樣。-**矛盾累積。** 不同時期加的指令之間開始出現矛盾——一條說"用 TypeScript 嚴格模式",另一條說"某些遺留檔案允許用 any"。Agent 每次隨機選一條遵循。就像你媽說"穿厚點",你爸說"別穿太多",你站在門口不知道聽誰的。+**矛盾累積。** 不同時期加的指令之間開始出現矛盾,一條說"用 TypeScript 嚴格模式",另一條說"某些遺留檔案允許用 any"。Agent 每次隨機選一條遵循。Agent 每次碰到矛盾指令只能隨機選一條遵循。## 核心概念-- **指令膨脹**:當指令檔案佔用了超過脈絡視窗 10-15% 的時候,它就開始擠佔程式碼閱讀和任務推理的預算。600 行的 `AGENTS.md` 可能佔用 10,000-20,000 tokens——對 128K 的視窗來說,這就吃掉了 8-15%。+- **指令膨脹**:當指令檔案佔用了超過脈絡視窗 10-15% 的時候,它就開始擠佔程式碼閱讀和任務推理的預算。600 行的 `AGENTS.md` 可能佔用 10,000-20,000 tokens,對 128K 的視窗來說,這就吃掉了 8-15%。- **中間迷失效應**:Liu 等人 2023 年的研究證明,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。埋在 600 行檔案中間第 300 行的關鍵約束,被有效忽略的概率非常高。-- **指令信噪比(SNR)**:檔案中與目前任務相關的指令佔總指令的比例。做 bug 修復時被要求讀 50 行部署指令——SNR 很低。+- **指令信噪比(SNR)**:檔案中與目前任務相關的指令佔總指令的比例。做 bug 修復時被要求讀 50 行部署指令,SNR 很低。- **路由檔案**:短小的入口檔案,核心功能是引導 agent 去找更詳細的文件,而不是自己包含所有內容。50-200 行就夠了。- **漸進式披露**:先給概要資訊,需要的時候再給詳細資訊。好的 harness 設計和好的 UI 設計一樣,不把所有選項一次性砸到使用者臉上。- **優先級模糊度**:當所有指令以相同格式和位置呈現時,agent 分不清哪些是不可違反的硬約束,哪些是建議性的軟約束。@@ -57,9 +57,9 @@ flowchart TB## 拆分思路-核心原則:常用資訊放手邊,偶爾用的收起來,用不上的別帶。+核心原則,常用資訊放手邊,偶爾用的收起來,用不上的別帶。-入口檔案 `AGENTS.md` 控制在 50-200 行,只放最常用的東西——專案概覽(一兩句話說清楚這是什麼)、首次執行命令(`make setup && make test`)、全域硬約束(不超過 15 條不可違反的規則)、指向專題文件的連結(一行描述 + 適用條件)。+入口檔案 `AGENTS.md` 控制在 50-200 行,只放最常用的東西,專案概覽(一兩句話說清楚這是什麼)、首次執行命令(`make setup && make test`)、全域硬約束(不超過 15 條不可違反的規則)、指向專題文件的連結(一行描述 + 適用條件)。```markdown# AGENTS.md@@ -83,33 +83,33 @@ Python 3.11 FastAPI 後端,PostgreSQL 15 資料庫。- 測試標準 (`docs/testing-standards.md`) — 编寫測試時参考```-每個專題文件 50-150 行,按主題放在 `docs/` 目錄下或對應模組目錄旁。Agent 只在需要時才去讀。就像行李箱裡的收納袋——內衣一個袋,洗漱一個袋,充電器一個袋。找東西不用翻整個箱子。+每個專題文件 50-150 行,按主題放在 `docs/` 目錄下或對應模組目錄旁。Agent 只在需要時才去讀。找東西不用翻整份文件。-還有些資訊直接放在程式碼裡更合適——類型定義、介面註釋、配置檔案裡的說明。Agent 讀程式碼的時候自然能看到,不用再在指令裡重複一遍。+還有些資訊直接放在程式碼裡更合適,類型定義、介面註釋、配置檔案裡的說明。Agent 讀程式碼的時候自然能看到,不用再在指令裡重複一遍。-每條指令都應該標明來源("為什麼加這條規則?")、適用條件("這條規則在什麼時候需要?")、過期條件("什麼情況下可以刪掉這條規則?")。定期審計,刪掉過時的、冗餘的、矛盾的條目。像管理程式碼依賴一樣管理你的指令——用不上的依賴就該刪掉,不然它們只會拖慢系統。+每條指令都應該標明來源("為什麼加這條規則?")、適用條件("這條規則在什麼時候需要?")、過期條件("什麼情況下可以刪掉這條規則?")。定期審計,刪掉過時的、冗餘的、矛盾的條目。像管理程式碼依賴一樣管理你的指令,用不上的依賴就該刪掉,不然它們只會拖慢系統。-如果某條指令必須在入口檔案裡,放頂部或底部——不要放中間。"中間迷失"效應告訴我們,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。但更好的做法是把指令放到專題文件裡,讓 agent 按需加載。+如果某條指令必須在入口檔案裡,放頂部或底部,不要放中間。"中間迷失"效應告訴我們,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。但更好的做法是把指令放到專題文件裡,讓 agent 按需加載。-OpenAI 和 Anthropic 都隱性支援拆分的做法。OpenAI 說入口檔案應"短小且以路由為導向",Anthropic 說長執行 agent 的控制資訊應"簡潔且高優先級"。兩家都在說同一件事:別把什麼都塞進一個檔案裡。行李箱得整理,不能只靠蠻力塞。+OpenAI 和 Anthropic 都隱性支援拆分的做法。OpenAI 說入口檔案應"短小且以路由為導向",Anthropic 說長執行 agent 的控制資訊應"簡潔且高優先級"。兩家都在說同一件事,別把什麼都塞進一個檔案裡。指令系統得整理,不能只靠不斷追加。## 實際案例-一個 SaaS 團隊的 `AGENTS.md` 從最初的 50 行膨脹到 600 行。內容混合了技術棧版本、編碼規範、歷史 bug 修復筆記、API 使用說明、部署流程、和團隊成員的個人偏好——整個行李箱塞得滿滿當當,拉鍊都快崩了。+一個 SaaS 團隊的 `AGENTS.md` 從最初的 50 行膨脹到 600 行。內容混合了技術棧版本、編碼規範、歷史 bug 修復筆記、API 使用說明、部署流程、和團隊成員的個人偏好,整份文件塞得滿滿當當,完全失去可維護性。Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量脈絡處理無關的部署指令;安全約束"所有數據庫查詢必須用參數化查詢"埋在第 300 行,經常被忽略;三條矛盾的程式碼風格規則導致 agent 隨機選擇。-團隊執行了"行李箱整理":+團隊執行了文件重組:1. `AGENTS.md` 裁剪到 80 行:只保留專案概覽、執行命令、15 條全域硬約束2. 建立專題文件:`docs/api-patterns.md`(120 行)、`docs/database-rules.md`(60 行)、`docs/testing-standards.md`(80 行)3. 路由檔案添加指向專題文件的連結4. 歷史筆記要麼轉成測試用例,要麼刪除-重構後:同一任務集的成功率從 45% 提升到 72%。安全約束遵循率從 60% 提升到 95%——因為從檔案中間移到了路由檔案頂部,不再被"中間迷失"了。+重構後:同一任務集的成功率從 45% 提升到 72%。安全約束遵循率從 60% 提升到 95%,因為從檔案中間移到了路由檔案頂部,不再被"中間迷失"了。## 關鍵要點-- "加條規則"是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文件是不是更合適?——別什麼都往行李箱裡塞。+- "加條規則"是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文件是不是更合適?,別把所有規則都堆進入口文件。- 入口檔案是路由器,不是百科全書。50-200 行,只放概覽、硬約束、和連結。- 利用"中間迷失"效應:重要資訊放檔案頂部或底部,不重要的移到專題文件。- 像管理技術債一樣管理指令膨脹。定期審計,每條指令要有來源、適用條件、和過期條件。diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdindex be8260f..d83549a 100644--- a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md@@ -5,19 +5,19 @@# 第五講. 讓跨工作階段的任務保持脈絡連續-你讓 Claude Code 幫你實作一個完整的功能,它跑了 30 分鐘,做了大部分工作,但脈絡快滿了。你開個新工作階段繼續,然後發現:它不記得上次做了什麼決策、為什麼選了方案 A 而不是方案 B、哪些檔案已經改過、測試跑到什麼狀態了。它得花 15 分鐘重新探索一遍專案,而且可能跟上次的做法不一致。+你讓 Claude Code 幫你實作一個完整的功能,它跑了 30 分鐘,做了大部分工作,但脈絡快滿了。你開個新工作階段繼續,然後發現,它不記得上次做了什麼決策、為什麼選了方案 A 而不是方案 B、哪些檔案已經改過、測試跑到什麼狀態了。它得花 15 分鐘重新探索一遍專案,而且可能跟上次的做法不一致。-想象一下,如果你是一個工匠,每天早上醒來都不記得昨天幹了什麼。你得重新認識整個工地——哪面牆砌了一半、為什麼用的是紅磚而不是青磚、水電管道走到哪了。更糟的是,你可能會把昨天已經裝好的窗戶拆了重來,因為你不記得它已經裝過了。+想象一下,如果你是一個工匠,每天早上醒來都不記得昨天幹了什麼。你得重新認識整個工地,哪面牆砌了一半、為什麼用的是紅磚而不是青磚、水電管道走到哪了。更糟的是,你可能會把昨天已經裝好的窗戶拆了重來,因為你不記得它已經裝過了。-這就是 AI coding agent 在跨工作階段任務中面對的困境。本節課講為什麼 agent 會"斷片",以及如何透過結構化的狀態持久化讓它像一個每天堅持寫日記的工匠——雖然還是會失憶,但日記本裡記著一切。+這就是 AI coding agent 在跨工作階段任務中面對的困境。本節課講為什麼 agent 會"斷片",以及如何透過結構化的狀態持久化讓它像一個每天堅持寫日記的工匠,雖然還是會失憶,但日記本裡記著一切。## 脈絡視窗:不是無限的-脈絡視窗是有限的。這不是一個可以通過模型升級解決的問題——即使視窗大小增長到 1M tokens,複雜任務依然會用完。因為 agent 不只是在生成程式碼,它還要理解程式碼庫、跟蹤自己的決策歷史、處理工具輸出、維護對話脈絡。這些資訊加起來增長得比視窗擴容快得多。+脈絡視窗是有限的。這不是一個可以通過模型升級解決的問題,即使視窗大小增長到 1M tokens,複雜任務依然會用完。因為 agent 不只是在生成程式碼,它還要理解程式碼庫、跟蹤自己的決策歷史、處理工具輸出、維護對話脈絡。這些資訊加起來增長得比視窗擴容快得多。-更深層的問題:agent 產生的資訊不是均勻重要的。中間推理步驟包含決策的"為什麼"——為什麼選了方案 A 而不是方案 B,為什麼用了這個庫而不是那個庫,為什麼跳過了某個最佳化。最終輸出只包含"是什麼"——程式碼本身。壓縮策略通常保留後者但丟了前者。下一個工作階段看到程式碼但不知道為什麼這麼寫,可能會"最佳化"掉一個有意為之的設計決策。+更深層的問題在於,agent 產生的資訊不是均勻重要的。中間推理步驟包含決策的"為什麼",為什麼選了方案 A 而不是方案 B,為什麼用了這個庫而不是那個庫,為什麼跳過了某個最佳化。最終輸出只包含"是什麼",程式碼本身。壓縮策略通常保留後者但丟了前者。下一個工作階段看到程式碼但不知道為什麼這麼寫,可能會"最佳化"掉一個有意為之的設計決策。-Anthropic 在他們的長執行 agent 研究中發現了一個很有意思的現象:當 agent 感覺脈絡快滿了,它們會表現出一種"過早收斂"的行為——匆忙結束目前工作,跳過驗證步驟,或者選一個簡單的方案而不是最優方案。這就像你考試時發現時間快到了,趕緊隨便選幾個選擇題一樣。Anthropic 把這叫"脈絡焦慮"。+Anthropic 在他們的長執行 agent 研究中發現了一個很有意思的現象:當 agent 感覺脈絡快滿了,它們會表現出一種"過早收斂"的行為,匆忙結束目前工作,跳過驗證步驟,或者選一個簡單的方案而不是最優方案。Anthropic 把這叫「脈絡焦慮」(Context Anxiety)。## 工作階段連續性流程@@ -54,26 +54,26 @@ flowchart LR- **連續性工件**:持久化的狀態檔案,讓新工作階段能無歧義地恢復到上次離開的地方。最基本的形式:進度日誌 + 驗證記錄 + 下一步行動。就是那個工匠的日記本。- **重建成本**:新工作階段恢復到可執行狀態所需的時間。好的 harness 能把重建成本從 15 分鐘壓到 3 分鐘。- **漂移(Drift)**:agent 的理解跟程式碼儲存庫實際狀態之間的偏差。每次工作階段邊界都會引入漂移,不加控制會越漂越遠。-- **脈絡焦慮**:Anthropic 觀察到的現象——agent 在接近脈絡限制時表現異常,過早結束任務以避免資訊遺失。是一種非理性的資源焦慮。+- **脈絡焦慮**:Anthropic 觀察到的現象,agent 在接近脈絡限制時表現異常,過早結束任務以避免資訊遺失。是一種非理性的資源焦慮。- **壓縮 vs 重置**:壓縮是在同一個工作階段裡把脈絡摘要化(保留"是什麼",可能丟了"為什麼");重置是開新工作階段從持久化狀態重建(乾淨但依賴工件完備性)。## 連續性斷了以後會發生什麼-上個工作階段花了很多脈絡預算分析了三種方案的優劣,最終選了方案 B。這個工作階段的 agent 不知道這個分析過程,可能基於不完整的資訊重新做了決策——而且可能選了方案 A。就像那個失憶的工匠不記得為什麼選了紅磚,今天看著覺得青磚更好看,就把昨天的牆拆了重砌。+上個工作階段花了很多脈絡預算分析了三種方案的優劣,最終選了方案 B。這個工作階段的 agent 不知道這個分析過程,可能基於不完整的資訊重新做了決策,而且可能選了方案 A。新工作階段的 agent 不知道上個工作階段的分析過程,可能基於不完整的資訊重新決策,結果選了不同的方案。-更要命的是重複勞動。Agent 不確定某項工作是否已完成,重新做了一遍。或者更糟——做了一半發現跟已有的實作衝突,需要返工。工地上不能兩撥人同時砌同一面牆——但在沒有進度記錄的情況下,新來的人完全不知道這面牆已經有人在砌了。+更要命的是重複勞動。Agent 不確定某項工作是否已完成,重新做了一遍。或者更糟,做了一半發現跟已有的實作衝突,需要返工。工地上不能兩撥人同時砌同一面牆,但在沒有進度記錄的情況下,新來的人完全不知道這面牆已經有人在砌了。-幾個工作階段累積下來,實作方向可能已經悄悄偏離了原始需求。每個新工作階段對專案目標的理解都略有偏差,就像傳話遊戲——經過十個人傳話,"幫我買杯咖啡"可能變成了"幫我買個咖啡機"。+幾個工作階段累積下來,實作方向可能已經悄悄偏離了原始需求。每個新工作階段對專案目標的理解都略有偏差,每次偏差微小,累積起來卻可能大相徑庭。還有驗證缺口。上個工作階段的驗證結果(哪些測試通過、哪些失敗、為什麼失敗)沒有記錄,新工作階段得重新跑一遍驗證才能瞭解目前狀態。每次都重新診斷,每次都浪費寶貴的脈絡。-OpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化的重要性。OpenAI 的 harness engineering 文章把儲存庫當作"操作記錄"——每次操作的結果都應該在儲存庫裡留下可追溯的痕跡。Anthropic 的 long-running agents 文件則更具體地建議使用"交接檔案"——包含目前狀態、已知問題和下一步行動的結構化文件。+OpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化的重要性。OpenAI 的 harness engineering 文章把儲存庫當作"操作記錄",每次操作的結果都應該在儲存庫裡留下可追溯的痕跡。Anthropic 的 long-running agents 文件則更具體地建議使用"交接檔案",包含目前狀態、已知問題和下一步行動的結構化文件。## 給失憶工匠的日記本-核心思路:**把 agent 當成一個會失憶的超級工程師來管理。** 每次它要"下班"之前,必須把關鍵資訊寫下來,讓下一個"接班"的 agent 能快速上手。+核心思路,**把 agent 當成一個會失憶的超級工程師來管理。** 每次它要"下班"之前,必須把關鍵資訊寫下來,讓下一個"接班"的 agent 能快速上手。-**工具 1:進度檔案(PROGRESS.md)**。這是最基本的連續性工件——日記本的核心部分:+**工具 1:進度檔案(PROGRESS.md)**。這是最基本的連續性工件,日記本的核心部分:```markdown# 專案進度@@ -101,7 +101,7 @@ OpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化3. 更新 API 文件```-**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文件,只需要"什麼決策、為什麼、什麼時候做的"——這是日記本裡的備忘:+**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文件,只需要"什麼決策、為什麼、什麼時候做的",這是日記本裡的備忘:```markdown# 設計决策@@ -133,13 +133,13 @@ OpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化### 脈絡焦慮的深層分析-Anthropic 在 2026 年 3 月發佈的研究進一步揭示了脈絡焦慮的具體表現:在 Sonnet 4.5 上,當脈絡接近視窗限制時,agent 會表現出強烈的"過早收斂"行為。這就像考試時發現時間快到了,趕緊隨便填選擇題。+Anthropic 在 2026 年 3 月發佈的研究進一步揭示了脈絡焦慮的具體表現:在 Sonnet 4.5 上,當脈絡接近視窗限制時,agent 會表現出強烈的"過早收斂"行為。這種行為是可量化、可預測的。針對這個現象,有兩種策略:-**壓縮(Compaction)**:在同一個工作階段裡把早期對話摘要化。優點是保留連續性,agent 能看到"是什麼"。缺點是"為什麼"經常在摘要中遺失——為什麼選了方案 B 而非 A,為什麼跳過了某個最佳化。更關鍵的是,壓縮並不能消除脈絡焦慮——agent 知道脈絡曾經很大,心理上仍然傾向於加速收尾。+**壓縮(Compaction)**:在同一個工作階段裡把早期對話摘要化。優點是保留連續性,agent 能看到"是什麼"。缺點是"為什麼"經常在摘要中遺失,為什麼選了方案 B 而非 A,為什麼跳過了某個最佳化。更關鍵的是,壓縮並不能消除脈絡焦慮,agent 知道脈絡曾經很大,心理上仍然傾向於加速收尾。-**重置(Context Reset)**:完全清空脈絡,開一個新工作階段,從持久化工件重建。優點是乾淨的心理狀態——新工作階段沒有"我快沒時間了"的焦慮。缺點是依賴交接工件的完備性。如果日記本裡漏了關鍵資訊,新工作階段可能在錯誤方向上浪費時間。+**重置(Context Reset)**:完全清空脈絡,開一個新工作階段,從持久化工件重建。優點是乾淨的心理狀態,新工作階段沒有"我快沒時間了"的焦慮。缺點是依賴交接工件的完備性。如果日記本裡漏了關鍵資訊,新工作階段可能在錯誤方向上浪費時間。Anthropic 的實際數據:對於 Sonnet 4.5,脈絡焦慮足夠嚴重,以至於壓縮單獨不夠用,脈絡重置成為 harness 設計的關鍵組件。但對於 Opus 4.5,這種行為大幅減弱,可以不依賴重置而靠壓縮管理脈絡。這意味著:**harness 設計需要對目標模型有具體的理解,而不是套用通用範本。**@@ -149,16 +149,16 @@ Anthropic 的實際數據:對於 Sonnet 4.5,脈絡焦慮足夠嚴重,以一個 agent 被要求實作一個帶使用者認證的部落格系統,12 個功能點,預計需要 5 個工作階段。-**沒有日記本的基線**:工作階段 1 實作了使用者模型和基礎路由。工作階段 2 開始時,agent 不記得認證中間件的介面約定,花了約 15 分鐘推斷上次的設計意圖。到工作階段 3,累積漂移導致 agent 開始重複已實作的功能。到工作階段 5,儲存庫有大量冗餘程式碼,但核心認證功能仍未通過端對端測試。12 個功能點只完成了 7 個,其中 3 個有隱含的正確性問題。就像那個沒寫日記的工匠——到了第五天,工地上一團亂,有些牆砌了兩遍,有些該砌的根本沒砌。+**沒有日記本的基線**:工作階段 1 實作了使用者模型和基礎路由。工作階段 2 開始時,agent 不記得認證中間件的介面約定,花了約 15 分鐘推斷上次的設計意圖。到工作階段 3,累積漂移導致 agent 開始重複已實作的功能。到工作階段 5,儲存庫有大量冗餘程式碼,但核心認證功能仍未通過端對端測試。12 個功能點只完成了 7 個,其中 3 個有隱含的正確性問題。**有日記本的對照**:使用進度檔案、決策日誌、驗證記錄和 git 檢查點。每個工作階段結束時自動更新狀態報告。工作階段 2 的重建成本降到約 3 分鐘。到工作階段 5,所有 12 個功能點完成且通過驗證。-定量對比:重建時間減少約 78%,功能完成率從 58% 提升到 100%,隱含缺陷率從 43% 降到 8%。工匠還是那個會失憶的工匠,但有了日記本,他的每一天都從昨天停下的地方開始,而不是從零開始。+定量對比,重建時間減少約 78%,功能完成率從 58% 提升到 100%,隱含缺陷率從 43% 降到 8%。工匠還是那個會失憶的工匠,但有了日記本,他的每一天都從昨天停下的地方開始,而不是從零開始。## 關鍵要點-- 脈絡視窗是有限的資源。長任務一定會跨工作階段,跨工作階段一定會丟資訊——這就像工匠每天都會失憶一樣,是客觀現實。-- 解決方案不是更大的視窗,而是更好的狀態持久化。進度檔案 + 決策日誌 + git 檢查點——給失憶的工匠一個可靠的日記本。+- 脈絡視窗是有限的資源。長任務一定會跨工作階段,跨工作階段一定會丟資訊,跨工作階段一定會丟資訊,這是客觀現實。+- 解決方案在於更好的狀態持久化,而非更大的視窗。進度檔案 + 決策日誌 + git 檢查點,讓每個工作階段都能從可靠的記錄起步。- 把 agent 當成會失憶的工程師來管理:每次"下班"前寫清楚做了什麼、為什麼、下一步做什麼。- 重建成本是關鍵指標。好的 harness 應該讓新工作階段在 3 分鐘內恢復到可執行狀態。- 混合策略:短任務在工作階段內完成,長任務用結構化工件維持連續性。diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdindex fcfb559..c5be7cb 100644--- a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md+++ b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md@@ -5,17 +5,17 @@# 第六講. 讓 agent 每次工作前先初始化-你開了一個新的 agent 工作階段,讓它"幫我加個搜索功能"。它上來就開始改程式碼——精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現數據庫遷移腳本格式不對,又折騰了一會兒。最後搜索功能倒是加了,但整個工作階段的效率很低——大部分時間花在了"搞清楚這個專案怎麼運作"上,而不是寫搜索功能。+你開了一個新的 agent 工作階段,讓它"幫我加個搜索功能"。它上來就開始改程式碼,精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現數據庫遷移腳本格式不對,又折騰了一會兒。最後搜索功能倒是加了,但整個工作階段的效率很低,大部分時間花在了"搞清楚這個專案怎麼運作"上,而不是寫搜索功能。-更好的做法是:在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、專案結構搞清楚。就像蓋房子——你不能邊打地基邊砌牆,不然牆砌到一半地基還沒幹,整棟樓都得推倒重來。先打地基,地基幹了,再砌牆,一氣呵成。+更好的做法是在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、專案結構搞清楚。蓋房子必須先打地基,地基幹了再砌牆;若同時進行,牆砌到一半地基未固,整棟樓都得推倒重來。這節課講的就是為什麼初始化必須是獨立的階段,不能跟實作混在一起。## 地基和牆:兩種完全不同的工作-初始化和實作的最佳化目標完全不同。實作階段的目標是:最大化已驗證功能的數量和質量。初始化階段的目標是:最大化後續所有實作的可靠性和效率。+初始化和實作的最佳化目標完全不同。實作階段的目標是最大化已驗證功能的數量和質量。初始化階段的目標是最大化後續所有實作的可靠性和效率。-當你把初始化和實作混在一起的時候,agent 面臨一個多目標最佳化問題——它要同時搭基礎設施和寫功能程式碼。在沒有顯式優先級設定的情況下,agent 自然傾向於寫程式碼(因為那是直接可見的產出),而犧牲基礎設施(因為它的價值只能在後續工作階段中體現)。這就像讓施工隊同時打地基和砌牆——他們很可能會急著砌牆,因為牆看得見、能交差。但地基沒打好的房子,後面出的問題是系統性的。+當你把初始化和實作混在一起的時候,agent 面臨一個多目標最佳化問題,它要同時搭基礎設施和寫功能程式碼。在沒有顯式優先級設定的情況下,agent 自然傾向於寫程式碼(因為那是直接可見的產出),而犧牲基礎設施(因為它的價值只能在後續工作階段中體現)。施工隊若同時打地基和砌牆,往往會急著砌牆,因為牆看得見、能交差。但地基沒打好,後面出的問題是系統性的。## 初始化生命週期@@ -37,26 +37,26 @@ flowchart TB## 混在一起做會怎樣-最直接的問題:地基打不牢。Agent 花了 80% 的精力寫功能程式碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了——新 agent 不知道專案怎麼跑、怎麼測、做到哪了。地基不牢,地動山搖。+最直接的問題:基礎設施不紮實。Agent 花了 80% 的精力寫功能程式碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了,新 agent 不知道專案怎麼跑、怎麼測、做到哪了。基礎薄弱,後患無窮。-更隱蔽的代價是"未驗證的累積"——在測試框架配好之前寫的功能程式碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實作。就像在地基沒幹的時候就開始貼瓷磚,等發現地面不平時,瓷磚全得撬掉重來。+更隱蔽的代價是"未驗證的累積",在測試框架配好之前寫的功能程式碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實作。等回頭補測試時才發現設計有問題,要重構才能讓測試通過。-脈絡預算也在被浪費。初始化工作(配環境、配測試、理解專案結構)消耗了大量預算,留給實際功能實作的反而不夠了。結果第一個工作階段只完成了一半的功能,第二個工作階段還得從頭理解專案。預算花在了打地基上,但地基也沒打好——兩頭都沒佔著。+脈絡預算也在被浪費。初始化工作(配環境、配測試、理解專案結構)消耗了大量預算,留給實際功能實作的反而不夠了。結果第一個工作階段只完成了一半的功能,第二個工作階段還得從頭理解專案。預算花在了打地基上,但地基也沒打好,兩頭都沒佔著。-最容易被忽略的是隱式假設埋下的雷。Agent 在初始化過程中做的決策(用什麼測試框架、目錄怎麼組織、依賴怎麼管理)如果不顯式記錄下來,後續工作階段就可能做出矛盾的選擇。第一個施工隊用的是水泥地基,第二個施工隊不知道,往上面打了木樁——地基直接裂了。+最容易被忽略的是隱式假設埋下的雷。Agent 在初始化過程中做的決策(用什麼測試框架、目錄怎麼組織、依賴怎麼管理)如果不顯式記錄下來,後續工作階段就可能做出矛盾的選擇。第一個施工隊用的是水泥地基,第二個施工隊不知道,往上面打了木樁,地基直接裂了。-Anthropic 在他們的長執行應用開發研究中明確建議把初始化和實作分離。他們的實驗數據:使用獨立初始化階段的專案,多工作階段場景中的功能完成率比混合方式高 31%。關鍵是——初始化階段投入的時間在後續 3-4 個工作階段中就能完全收回。地基打得越紮實,上面的樓蓋得越快。+Anthropic 在他們的長執行應用開發研究中明確建議把初始化和實作分離。他們的實驗數據顯示,使用獨立初始化階段的專案,多工作階段場景中的功能完成率比混合方式高 31%。關鍵是,初始化階段投入的時間在後續 3-4 個工作階段中就能完全收回。地基打得越紮實,上面的樓蓋得越快。-OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄"的原則——第一次執行就要建立清晰的操作結構,否則每次新工作階段都得重新推斷專案約定。+OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄"的原則,第一次執行就要建立有效的操作結構,否則每次新工作階段都得重新推斷專案約定。## 核心概念-- **初始化階段**:agent 生命週期中的第一個階段,不做功能實作,只建立後續所有實作階段的執行前提。輸出不是程式碼,而是基礎設施。-- **自舉契約**:一個專案能被全新 agent 工作階段無歧義操作的條件——能啟動、能測試、能看進度、能接手下一步。四個條件缺一不可。-- **冷啟動 vs 熱啟動**:冷啟動是從空目錄開始,agent 要猜專案結構;熱啟動是從範本或已有專案開始,基礎設施已經就位。熱啟動的效果遠好於冷啟動——就像在有水電的工地上開工,比在荒郊野嶺從頭搞起快得多。+- **初始化階段**:agent 生命週期中的第一個階段,不做功能實作,只建立後續所有實作階段的執行前提。輸出的是基礎設施,不是功能程式碼。+- **自舉契約**:一個專案能被全新 agent 工作階段無歧義操作的條件,能啟動、能測試、能看進度、能接手下一步。四個條件缺一不可。+- **冷啟動 vs 熱啟動**:冷啟動是從空目錄開始,agent 要猜專案結構;熱啟動是從範本或已有專案開始,基礎設施已經就位。熱啟動的效果遠好於冷啟動,從有基礎設施的工地開工,效率遠高於在空地從零搭建。- **交接就緒性**:專案在任何時刻都處於"可以被全新 agent 接手"的狀態。不需要口頭解釋,只看儲存庫內容就能接著幹。- **首次驗證時間**:從專案開始到第一個功能點通過驗證的時間。這是衡量初始化效率的核心指標。-- **下游可用性**:初始化質量的最佳衡量標準——後續工作階段不需要依賴隱式知識就能成功執行任務的比例。+- **下游可用性**:初始化質量的最佳衡量標準,後續工作階段不需要依賴隱式知識就能成功執行任務的比例。## 怎麼做好初始化@@ -64,7 +64,7 @@ OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄**1. 可執行的環境。** 專案能啟動、依賴都裝好、沒有環境問題。地基澆好了,沒裂縫。-**2. 可驗證的測試框架。** 至少有一個示例測試能通過。這證明測試框架本身是配對的——就像地基上立了一根柱子,證明地基能承重。+**2. 可驗證的測試框架。** 至少有一個示例測試能通過。這是對測試框架本身配對的驗證。**3. 自舉契約文件。** 一個明確的文件告訴後續工作階段:```markdown@@ -109,9 +109,9 @@ OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄**5. Git 提交作為檢查點。** 初始化完成後提交一個乾淨的 checkpoint。後續所有工作都從這個 checkpoint 開始。-**熱啟動策略**:不要從空目錄開始。用一個專案範本(create-react-app、fastapi-template 等)預置好標準的目錄結構、依賴配置和測試框架。把通用的初始化步驟預置到範本裡,只留下專案特有的初始化工作。就像在有通水通電的工地上開工,比從荒郊野嶺開始強一萬倍。+**熱啟動策略**:不要從空目錄開始。用一個專案範本(create-react-app、fastapi-template 等)預置好標準的目錄結構、依賴配置和測試框架。把通用的初始化步驟預置到範本裡,只留下專案特有的初始化工作。在已有通用基礎設施的基礎上開工,效率遠高於從空白目錄起步。-**初始化的完成條件**:不是"寫了多少程式碼",而是自舉契約的四個條件都滿足了——能啟動、能測試、能看進度、能接手下一步。用這個檢查清單驗收初始化:+**初始化的完成條件**:自舉契約的四個條件都滿足了,能啟動、能測試、能看進度、能接手下一步。用這個檢查清單驗收初始化:```markdown## 初始化驗收清單@@ -126,11 +126,11 @@ OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄一個 React 前端專案的兩種初始化方式對比:-**混合方式(邊打地基邊砌牆)**:agent 在第一個工作階段中同時做了專案腳手架建立和首個功能實作。工作階段結束時,儲存庫有可執行的程式碼,但:沒有顯式的啟動/測試命令文件、沒有進度跟蹤檔案、沒有任務分解。第二個工作階段花了約 20 分鐘推斷專案結構、測試框架和建構流程——就像新來的施工隊看著一片工地,不知道地基打到什麼程度、水電管道走到哪了,只能一個個挖開來看。+**混合方式(邊打地基邊砌牆)**:agent 在第一個工作階段中同時做了專案腳手架建立和首個功能實作。工作階段結束時,儲存庫有可執行的程式碼,但沒有顯式的啟動/測試命令文件、沒有進度跟蹤檔案、沒有任務分解。第二個工作階段花了約 20 分鐘重新推斷專案結構、測試框架和建構流程,耗費大量時間。-**獨立初始化(先打地基)**:第一個工作階段只做初始化——用專案範本建立目錄結構、配置測試框架(Vitest + React Testing Library)、寫一個示例測試並驗證通過、建立自舉契約文件和任務分解檔案、提交初始檢查點。第二個工作階段的重建時間不到 3 分鐘,直接從任務列表開始工作——施工隊來了,看了一眼施工圖就知道從哪裡接著幹。+**獨立初始化(先打地基)**:第一個工作階段只做初始化,用專案範本建立目錄結構、配置測試框架(Vitest + React Testing Library)、寫一個示例測試並驗證通過、建立自舉契約文件和任務分解檔案、提交初始檢查點。第二個工作階段的重建時間不到 3 分鐘,直接從任務列表開始工作,施工隊來了,看了一眼施工圖就知道從哪裡接著幹。-整個專案週期對比:混合方式的總重建時間(跨所有工作階段)比獨立初始化多約 60%。獨立初始化多花的那 20 分鐘在後續工作階段中被成倍收回。就像地基打得紮實,上面蓋樓的效率反而更高——慢即是快。+整個專案週期對比:混合方式的總重建時間(跨所有工作階段)比獨立初始化多約 60%。獨立初始化多花的那 20 分鐘在後續工作階段中被成倍收回。前期投入的時間在後續工作階段中被成倍收回,慢即是快。## 關鍵要點@@ -138,7 +138,7 @@ OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄- 初始化的產出不是程式碼,是基礎設施:可執行的環境、可驗證的測試、自舉契約、任務分解。- 用"自舉契約"的四個條件驗收初始化:能啟動、能測試、能看進度、能接手下一步。- 熱啟動優於冷啟動。用專案範本預置標準化的基礎設施。-- 初始化投入的時間會在後續 3-4 個工作階段中完全收回。這不是額外的成本,是前期投資——地基打得越紮實,樓蓋得越快。+- 初始化投入的時間會在後續 3-4 個工作階段中完全收回。這不是額外的成本,是前期投資,初始化越紮實,後續工作效率越高。## 延伸閱讀@@ -150,7 +150,7 @@ OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄## 練習-1. **自舉契約設計**:為一個你正在開發的專案寫一個完整的自舉契約。然後開一個全新的 agent 工作階段,只給它看儲存庫內容(不給任何口頭脈絡),讓它嘗試啟動專案、跑測試、瞭解目前進度。記錄它遇到的問題——每個問題都對應自舉契約中缺失的一個條款。+1. **自舉契約設計**:為一個你正在開發的專案寫一個完整的自舉契約。然後開一個全新的 agent 工作階段,只給它看儲存庫內容(不給任何口頭脈絡),讓它嘗試啟動專案、跑測試、瞭解目前進度。記錄它遇到的問題,每個問題都對應自舉契約中缺失的一個條款。2. **對比實驗**:選一箇中等複雜度的新專案。方式 A:讓 agent 初始化和首次實作同時做。方式 B:先花一個工作階段做獨立初始化,第二個工作階段開始實作。在 4 個工作階段後對比:首次驗證時間、重建成本、功能完成率。diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.mdindex 04e72f4..993d50b 100644--- a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -7,13 +7,13 @@你讓 Claude Code「給這個專案加上使用者認證功能」,結果它同時開始改資料庫 schema、寫路由、改前端元件、還順手重構了錯誤處理中介軟體。兩個小時後你一看——12 個檔案被修改,800 行新程式碼,但沒有一個功能是端到端跑通的。-貪多嚼不爛,這句話放到 AI agent 身上格外貼切。Agent 天生就有"多做一點"的衝動——看到相關的事情就順手一起做了,和那種在超市本來只打算買瓶醬油、結果推著滿滿一車出來的人一個德行。問題是,人類買了太多東西最多浪費錢,agent 同時做太多事情則是每一件都做不好。+貪多嚼不爛,這句話放到 AI agent 身上格外貼切。Agent 天生就有"多做一點"的衝動,看到相關的事情就順手一起做了,和那種在超市本來只打算買瓶醬油、結果推著滿滿一車出來的人一個德行。問題是,人類買了太多東西最多浪費錢,agent 同時做太多事情則是每一件都做不好。-Anthropic 在 "Effective harnesses for long-running agents" 工程部落格中明確指出:當提示太寬泛時,agent 傾向於「同時啟動多件事」而非「先做完一件事」。OpenAI 在 Codex 工程實踐中也發現,沒有顯式範圍控制的任務,完成率會暴跌。這不是模型的問題——是你沒有在 harness 裡給它劃清邊界。+Anthropic 在 "Effective harnesses for long-running agents" 工程部落格中明確指出:當提示太寬泛時,agent 傾向於「同時啟動多件事」而非「先做完一件事」。OpenAI 在 Codex 工程實踐中也發現,沒有顯式範圍控制的任務,完成率會暴跌。這不是模型的問題,是你沒有在 harness 裡給它劃清邊界。## 注意力是有限的資源-這不是比喻,是數學。假設 agent 的脈絡容量為 C,同時啟動 k 個任務,每個任務平均獲得 C/k 的推理資源。當 C/k 低於完成單個任務所需的最小閾值時,所有任務都做不完。這就像你的胃就那麼大——同時塞十個包子進去,不是一個都消化不了,而是十個都消化不良。+這不是比喻,是數學。假設 agent 的脈絡容量為 C,同時啟動 k 個任務,每個任務平均獲得 C/k 的推理資源。當 C/k 低於完成單個任務所需的最小閾值時,所有任務都做不完。這就像你的胃就那麼大,同時塞十個包子進去,十個都消化不良。Claude Code 的真實行為很說明問題。你讓它「新增使用者註冊功能」,它很可能這樣做:@@ -22,11 +22,11 @@ Claude Code 的真實行為很說明問題。你讓它「新增使用者註冊3. 發現需要電子郵件驗證,於是加郵件服務4. 看到密碼需要加密,於是引入 bcrypt5. 注意到錯誤處理不統一,於是重構全局錯誤中介軟體-6. 看到測試檔案結構不清晰,於是重組目錄結構+6. 看到測試檔案結構雜亂,於是重組目錄結構-6 步之後,每一個都是半成品。沒有端到端驗證,程式碼之間耦合複雜,下一個工作階段來接手時會一臉懵。就像一個人同時炒六道菜,每道菜都下了鍋但沒有一道出鍋——全糊了。+6 步之後,每一個都是半成品。沒有端到端驗證,程式碼之間耦合複雜,下一個工作階段來接手時會一臉懵。就像一個人同時炒六道菜,每道菜都下了鍋但沒有一道出鍋,全糊了。-Anthropic 的實驗數據直接支援這一點:使用「小下一步」策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的程式碼行數和實際完成的功能數量呈弱負相關——寫得越多,完成得越少。貪多嚼不爛,數據為證。+Anthropic 的實驗數據直接支援這一點:使用「小下一步」策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的程式碼行數和實際完成的功能數量呈弱負相關,寫得越多,完成得越少。貪多嚼不爛,數據為證。## WIP=1 工作流@@ -52,20 +52,20 @@ flowchart TB## 核心概念-- **過度延伸(Overreach)**:agent 在一次工作階段中啟動的任務數量超過最優值。它不是主觀判斷,而是可量化的——同時做 5 個功能但 0 個跑通,就是 overreach。+- **過度延伸(Overreach)**:agent 在一次工作階段中啟動的任務數量超過最優值。它可以量化——同時做 5 個功能但 0 個跑通,就是 overreach。- **不足完成(Under-finish)**:已啟動的任務中,通過端到端驗證的比例低於閾值。寫了程式碼但沒跑通測試,就是 under-finish。-- **WIP 限制(Work-in-Progress Limit)**:來自 Kanban 方法論。核心思想:限制同時在進行的任務數量。對於 agent,WIP=1 是最安全的預設值——做完一個再做下一個。就像自助餐廳不要一次拿太多盤子,吃完一盤再去拿下一盤。+- **WIP 限制(Work-in-Progress Limit)**:來自 Kanban 方法論。核心思想:限制同時在進行的任務數量。對於 agent,WIP=1 是最安全的預設值,做完一個再做下一個。就像自助餐廳不要一次拿太多盤子,吃完一盤再去拿下一盤。- **完成證據(Completion Evidence)**:一個任務從「進行中」變成「已完成」必須滿足的可驗證條件。沒有這個,agent 會用「程式碼看起來沒問題」代替「行為通過測試」。- **範圍表面(Scope Surface)**:一個 DAG 結構,每個節點是一個工作單元,邊是依賴關係。狀態只有四種:未開始、進行中、阻塞、已通過。- **完成壓力(Completion Pressure)**:harness 通過 WIP 限制和完成證據要求共同產生的約束力,迫使 agent 先完成目前任務再開始新任務。## Overreach 和 Under-finish 是一對難兄難弟-這兩個問題不是獨立的,而是互相加劇。overreach 導致注意力分散,注意力分散導致 under-finish,under-finish 留下的半成品程式碼又增加了系統複雜度,進一步導致下一個任務的 overreach。惡性循環。+這兩個問題互相加劇。overreach 導致注意力分散,注意力分散導致 under-finish,under-finish 留下的半成品程式碼又增加了系統複雜度,進一步導致下一個任務的 overreach。惡性循環。用 Kanban 的語言說:Little 法則告訴我們 L = lambda * W。如果在製品數量 L 過大(同時做太多事),每個任務的前置時間 W 必然增加。對於 agent 來說,這意味著每個功能從開始到驗證通過的時間被拉長,失敗概率被放大。-這在人類世界也是老問題了——Steve McConnell 在《Rapid Development》中記錄,範圍蔓延是專案失敗的首要原因。但人類至少有「我已經做得夠多了」的直覺,agent 完全沒有。生成下一個想法的成本對模型來說太低了——寫一行「順便把這個也改了」幾乎不消耗額外 token,但每個額外的修改都會稀釋 agent 的注意力。就像在自助餐廳裡,每多拿一個盤子的邊際成本幾乎為零,但你的胃只有那麼大。+這在人類世界也是老問題了。Steve McConnell 在《Rapid Development》中記錄,範圍蔓延是專案失敗的首要原因。但人類至少有「我已經做得夠多了」的直覺,agent 完全沒有。生成下一個想法的成本對模型來說太低了,寫一行「順便把這個也改了」幾乎不消耗額外 token,但每個額外的修改都會稀釋 agent 的注意力。就像在自助餐廳裡,每多拿一個盤子的邊際成本幾乎為零,但你的胃只有那麼大。## 怎麼做才對@@ -80,11 +80,11 @@ flowchart TB- 不要在實作功能 A 時「順便」重構功能 B```-就像吃自助餐——一次只拿一盤,吃完再去拿。+就像吃自助餐,一次只拿一盤,吃完再去拿。### 2. 給每個任務定義顯式的完成證據-完成不是「程式碼寫完了」,而是「行為驗證通過了」。在你的功能列表裡,每個條目都要有驗證命令:+完成的標準是「行為驗證通過了」,不是「程式碼寫完了」。在你的功能列表裡,每個條目都要有驗證命令:```F01: 使用者註冊@@ -104,7 +104,7 @@ harness 應該持續跟蹤 VCR(Verified Completion Rate)= 已通過驗證的一個 8 個功能項的 REST API 專案,兩種策略對比:-**自助餐模式(無約束)**:agent 在第一個工作階段同時啟動 5 個功能。產出約 800 行程式碼,涉及 12 個檔案。端到端測試通過率只有 20%——只有使用者註冊跑通了。其餘 4 個功能:資料庫 schema 建了但缺驗證邏輯,路由定義了但返回格式錯誤。就像一個人同時炒六道菜,只有一道勉強能吃。到第 3 個工作階段結束,8 個功能只完成 3 個。+**自助餐模式(無約束)**:agent 在第一個工作階段同時啟動 5 個功能。產出約 800 行程式碼,涉及 12 個檔案。端到端測試通過率只有 20%,只有使用者註冊跑通了。其餘 4 個功能:資料庫 schema 建了但缺驗證邏輯,路由定義了但返回格式錯誤。就像一個人同時炒六道菜,只有一道勉強能吃。到第 3 個工作階段結束,8 個功能只完成 3 個。**單盤模式(WIP=1)**:agent 在第一個工作階段只做使用者註冊。產出約 200 行程式碼,涉及 4 個檔案。端到端測試 100% 通過。提交乾淨的、已驗證的實現。到第 4 個工作階段結束,8 個功能完成 7 個(第 8 個因外部依賴被阻塞)。@@ -112,11 +112,11 @@ harness 應該持續跟蹤 VCR(Verified Completion Rate)= 已通過驗證的## 關鍵要點-- **WIP=1 是 agent harness 的預設安全設置**——做完一個再做下一個,不要試圖並行。一口吃不成胖子。-- **完成證據必須是可執行的**——「程式碼看起來沒問題」不算完成,「curl 返回 201」才算。-- **範圍表面必須外部化為檔案**——不能只在對話裡說,必須在儲存庫裡有機器可讀的記錄。-- **overreach 和 under-finish 是共生問題**——解決一個就解決了另一個。-- **「少做但做完」永遠優於「多做但做半」**——agent 程式碼行數和功能完成率呈負相關。質量永遠比數量重要。+- **WIP=1 是 agent harness 的預設安全設置**,做完一個再做下一個,不要試圖並行。一口吃不成胖子。+- **完成證據必須是可執行的**,「程式碼看起來沒問題」不算完成,「curl 返回 201」才算。+- **範圍表面必須外部化為檔案**,不能只在對話裡說,必須在儲存庫裡有機器可讀的記錄。+- **overreach 和 under-finish 是共生問題**,解決一個就解決了另一個。+- **「少做但做完」永遠優於「多做但做半」**,agent 程式碼行數和功能完成率呈負相關。質量永遠比數量重要。## 延伸閱讀@@ -129,6 +129,6 @@ harness 應該持續跟蹤 VCR(Verified Completion Rate)= 已通過驗證的1. **任務原子化練習**:選一個寬泛需求(如「實現使用者管理系統」),把它拆成至少 5 個原子工作單元。每個單元寫清楚:(a) 單一行為描述,(b) 可執行的驗證命令,(c) 依賴關係。檢查是否滿足 WIP=1 的約束。-2. **對比實驗**:在同一個專案上跑兩次——一次不給約束,一次強制 WIP=1。比較:驗證完成率、總程式碼行數、有效程式碼比例。+2. **對比實驗**:在同一個專案上跑兩次,一次不給約束,一次強制 WIP=1。比較:驗證完成率、總程式碼行數、有效程式碼比例。3. **完成證據審計**:回顧一個最近的 agent 執行結果,把每個程式碼變更分類為「已完成行為」、「未完成行為」或「腳手架」。給每個未完成行為補充缺失的驗證命令。diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.mdindex 9a7fa68..288bc29 100644--- a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md@@ -1,6 +1,6 @@# 通過閘門策略-一個功能只有在以下條件滿足時,才能從 `passes: false` 變更為 `passes: true`:+一個功能在以下所有條件滿足後,方可從 `passes: false` 變更為 `passes: true`:- 預期的工作流程已被執行- 成功的證據已被記錄diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.mdindex c84a30c..3e17875 100644--- a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md@@ -5,9 +5,9 @@# 第八講. 用功能清單約束 agent 該做什麼-你讓 agent 做一個電商網站,跑完之後它告訴你「做完了」。你打開程式碼一看——使用者認證有了,但購物車的結算按鈕點了沒反應,支付流程根本沒接上。問題是:你從來沒告訴它「做完」的標準是什麼,所以它用自己的標準——「程式碼寫了不少,看起來挺完整」。+你讓 agent 做一個電商網站,跑完之後它告訴你「做完了」。你打開程式碼一看——使用者認證有了,但購物車的結算按鈕點了沒反應,支付流程根本沒接上。問題是:你從來沒告訴它「做完」的標準是什麼,所以它用自己的標準,「程式碼寫了不少,看起來挺完整」。-功能清單(feature list)在很多人眼裡就是個備忘錄——寫下來怕忘了,寫完扔在一邊。但在 harness 的世界裡,功能清單不是給人看的備忘錄,而是整個 harness 的脊樑骨。調度器靠它選任務,驗證器靠它判完成,交接器靠它生成報告。脊樑骨斷了,全身都癱。+功能清單(feature list)在很多人眼裡就是個備忘錄,寫下來怕忘了,寫完扔在一邊。但在 harness 的世界裡,功能清單是整個 harness 的脊樑骨,不只是一份給人看的備忘錄。調度器靠它選任務,驗證器靠它判完成,交接器靠它生成報告。脊樑骨斷了,全身都癱。Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須是儲存庫裡機器可讀的檔案,不能是對話裡的非結構化描述。@@ -15,7 +15,7 @@ Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須Claude Code 和 Codex 都不會自動知道你心目中的「做完」是什麼意思。你說「加一個購物車功能」,模型的理解可能是「寫一個 Cart 元件和 addToCart 方法」。而你的意思是「使用者能從瀏覽商品到下單支付完整走通」。-這個理解鴻溝在沒有功能清單的情況下會持續存在。agent 用自己的隱式標準判斷完成——通常是「程式碼沒有明顯的語法錯誤」。而你需要的是端到端的行為驗證。就像你讓朋友幫你買菜,說「買點水果」,他拎了一袋檸檬回來——他要的水果,你要的水果,不是一個水果。+這個理解鴻溝在沒有功能清單的情況下會持續存在。agent 用自己的隱式標準判斷完成,通常是「程式碼沒有明顯的語法錯誤」。而你需要的是端到端的行為驗證。就像你讓朋友幫你買菜,說「買點水果」,他拎了一袋檸檬回來,他要的水果,你要的水果,不是一個水果。看看這種常見的進度記錄:@@ -54,10 +54,10 @@ flowchart LR## 核心概念-- **功能清單是 harness 原語**:它不是「可選的規劃工具」,而是其他所有 harness 元件依賴的基礎資料結構。就像資料庫裡的表結構——你不能說「要不我們省掉主索引鍵吧」,省掉了整個系統就解體了。+- **功能清單是 harness 原語**:它是其他所有 harness 元件依賴的基礎資料結構,不是「可選的規劃工具」。就像資料庫裡的表結構,你不能說「要不我們省掉主索引鍵吧」,省掉了整個系統就解體了。- **三元組結構**:每個功能項是 `(行為描述, 驗證命令, 目前狀態)` 的三元組。缺了任何一項,這個功能項就不完整。行為描述告訴 agent 做什麼,驗證命令告訴它怎麼算做完,狀態告訴它現在到哪了。- **狀態機模型**:每個功能項有四種狀態——`not_started`、`active`、`blocked`、`passing`。狀態轉移由 harness 控制,不是 agent 想改就能改。-- **通過狀態門控**:功能從 `active` 變成 `passing` 的唯一方式是驗證命令執行成功。這是不可逆的——`passing` 了就不能退回去。就像考試及格了就是及格了,不能事後改分數。+- **通過狀態門控**:功能從 `active` 變成 `passing` 的唯一方式是驗證命令執行成功。這是不可逆的,`passing` 了就不能退回去。就像考試及格了就是及格了,不能事後改分數。- **單一權威來源**:專案裡關於「該做什麼」的所有資訊,必須從一個功能清單派生。不能出現功能清單和對話記錄矛盾的情況。- **反向壓力**:還沒通過的功能項數量就是 harness 對 agent 施加的壓力。壓力歸零 = 專案完成。@@ -65,14 +65,14 @@ flowchart LR文件是給人看的,原語是給系統用的。文件可以被忽略,原語不能被繞過。-類比資料庫的觸發器約束和應用層的檢查邏輯:前者由資料庫引擎強制執行,任何 SQL 都無法跳過;後者依賴於應用程式碼的正確性,可能被意外繞過。功能清單作為 harness 原語,就是資料庫級別的約束——agent 不能繞過它。+類比資料庫的觸發器約束和應用層的檢查邏輯:前者由資料庫引擎強制執行,任何 SQL 都無法跳過;後者依賴於應用程式碼的正確性,可能被意外繞過。功能清單作為 harness 原語,就是資料庫級別的約束,agent 不能繞過它。具體來說,功能清單服務四個 harness 元件:-1. **調度器**:讀狀態,選下一個 `not_started` 的功能。就像工廠的排產系統——看完訂單才知道下一步做什麼。-2. **驗證器**:執行驗證命令,判斷是否允許狀態轉移。就像質檢——不是你說合格就合格,得通過檢驗。-3. **交接報告器**:從功能清單自動生成工作階段交接摘要。就像換班時自動生成的交接表——不用手寫,系統自己出。-4. **進度追蹤器**:統計各狀態分佈,提供專案健康度指標。就像儀表盤——一眼看出專案走到哪了。+1. **調度器**:讀狀態,選下一個 `not_started` 的功能。就像工廠的排產系統,看完訂單才知道下一步做什麼。+2. **驗證器**:執行驗證命令,判斷是否允許狀態轉移。就像質檢,不是你說合格就合格,得通過檢驗。+3. **交接報告器**:從功能清單自動生成工作階段交接摘要。就像換班時自動生成的交接表,不用手寫,系統自己出。+4. **進度追蹤器**:統計各狀態分佈,提供專案健康度指標。就像儀表盤,一眼看出專案走到哪了。## 怎麼做@@ -92,7 +92,7 @@ flowchart LR### 2. 讓 harness 控制狀態轉移-agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harness 執行驗證命令,根據結果決定是否允許狀態轉移。這就是「通過狀態門控」——不是你說考過了就考過了,得看成績單。+agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harness 執行驗證命令,根據結果決定是否允許狀態轉移。這就是「通過狀態門控」,不是你說考過了就考過了,得看成績單。### 3. 在 CLAUDE.md 裡寫清楚規則@@ -101,18 +101,18 @@ agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harn- 功能清單檔案: /docs/features.md- 每次只啟動一個功能項- 功能項驗證命令必須通過才能標為 passing-- 不要修改功能清單的狀態——由驗證指令碼自動更新+- 不要修改功能清單的狀態,由驗證指令碼自動更新```### 4. 粒度校準-每個功能項應該是「一次工作階段能完成」的範圍。太粗了做不完,太細了管理開銷大。「使用者可以新增商品到購物車」是一個好粒度,「實現購物車」太粗了,「建立 Cart 模型的 name 欄位」太細了。就像切牛排——不能整塊啃,也不能切成肉末。+每個功能項應該是「一次工作階段能完成」的範圍。太粗了做不完,太細了管理開銷大。「使用者可以新增商品到購物車」是一個好粒度,「實現購物車」太粗了,「建立 Cart 模型的 name 欄位」太細了。就像切牛排,不能整塊啃,也不能切成肉末。## 實際案例一個電商平台的開發任務,10 個功能項。對比兩種追蹤方式:-**備忘錄模式**:agent 用非結構化筆記記錄進度。3 個工作階段後,筆記變成了「做了使用者認證和商品列表、購物車基本完成但還有 bug、支付沒開始」。新工作階段需要 20 分鐘推斷狀態,最終重複實現了已完成的功能。就像你的購物清單上寫著「牛奶、麵包、還有那個什麼來著」——到超市了你還是不知道要買什麼。+**備忘錄模式**:agent 用非結構化筆記記錄進度。3 個工作階段後,筆記變成了「做了使用者認證和商品列表、購物車基本完成但還有 bug、支付沒開始」。新工作階段需要 20 分鐘推斷狀態,最終重複實現了已完成的功能。就像你的購物清單上寫著「牛奶、麵包、還有那個什麼來著」,到超市了你還是不知道要買什麼。**脊樑骨模式**:每個功能項有明確的狀態和驗證命令。新工作階段讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。@@ -121,9 +121,9 @@ agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harn## 關鍵要點- **功能清單是 harness 的脊樑骨**,不是給人看的備忘錄。調度器、驗證器、交接器都依賴它。-- **每個功能項必須有三元組**:行為描述 + 驗證命令 + 目前狀態。缺一項就不完整——就像三條腿的凳子少一條腿。+- **每個功能項必須有三元組**:行為描述 + 驗證命令 + 目前狀態。缺一項就不完整,就像三條腿的凳子少一條腿。- **狀態轉移由 harness 控制**,agent 不能自己改狀態。通過驗證 = 唯一的升級路徑。-- **功能清單是專案的單一權威來源**——任何關於「該做什麼」的資訊都從這裡派生。+- **功能清單是專案的單一權威來源**,任何關於「該做什麼」的資訊都從這裡派生。- **粒度控制在「一次工作階段能完成」的範圍**。太粗做不完,太細管不過來。## 延伸閱讀diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdindex 735598d..6fefe5b 100644--- a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md+++ b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md@@ -5,15 +5,15 @@# 第九講. 防止 agent 提前宣告完成-你讓 agent 實現「密碼重置」功能。它改了資料庫 schema、寫了 API 端點、加了郵件範本,跑了單元測試(全部通過),然後自信地告訴你「做完了」。你實際一跑——密碼重置連結發不出去(郵件服務配置缺失)、資料庫遷移半途失敗(schema 不一致)、端到端流程根本沒走過一遍。+你讓 agent 實現「密碼重置」功能。它改了資料庫 schema、寫了 API 端點、加了郵件範本,跑了單元測試(全部通過),然後自信地告訴你「做完了」。你實際一跑,密碼重置連結發不出去(郵件服務配置缺失)、資料庫遷移半途失敗(schema 不一致)、端到端流程根本沒走過一遍。-這種感覺你一定不陌生——考試時把卷子寫得滿滿當當,信心滿滿地第一個交卷,結果成績出來不及格。卷子寫滿了,不代表做對了。+這種感覺你一定不陌生,考試時把卷子寫得滿滿當當,信心滿滿地第一個交卷,結果成績出來不及格。卷子寫滿了,不代表做對了。-這不是偶然事件。Guo 等人 2017 年在 ICML 上的經典論文證明:**現代神經網路系統性地過度自信**——模型自報的置信度顯著高於實際準確率。AI 程式碼代理也一樣:它「覺得」做完了,但實際上差得遠。你的 harness 必須用外部化的、基於執行的驗證來替代 agent 的「感覺」。+這不是偶然事件。Guo 等人 2017 年在 ICML 上的經典論文證明:**現代神經網路一致性地過度自信**——模型自報的置信度顯著高於實際準確率。AI 程式碼代理也一樣,它「覺得」做完了,但實際上差得遠。你的 harness 必須用外部化的、基於執行的驗證來替代 agent 的「感覺」。## 滑坡效應-過早完成聲明幾乎總是一樣的手法:程式碼看著還行——語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際執行或只跑了部分測試。跑了單元測試但跳過整合測試,跑了測試但沒檢查覆蓋率。最後「程式碼看起來沒問題」就被當作了「功能已完成」的證據。交卷了。+過早完成聲明幾乎總是一樣的手法,程式碼看著還行,語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際執行或只跑了部分測試。跑了單元測試但跳過整合測試,跑了測試但沒檢查覆蓋率。最後「程式碼看起來沒問題」就被當作了「功能已完成」的證據。交卷了。每一步都在遺失資訊。從任務規範到程式碼實現到執行時期行為,每次轉換都可能引入偏差,而每次跳過的驗證都加劇了資訊不對稱。@@ -36,8 +36,8 @@ flowchart LR## 核心概念-- **過早完成聲明**:agent 斷言任務完成,但實際上存在未滿足的正確性規範。核心問題:agent 依據程式碼層面的局部信心做判斷,系統級正確性需要全局驗證。-- **置信度校準偏差**:agent 自報的完成信心與實際完成質量之間的系統性差距。對複雜多檔案任務,這個偏差顯著為正——agent 總是比實際做得更自信。就像學生考完試估分總是偏高。+- **過早完成聲明**:agent 斷言任務完成,但實際上存在未滿足的正確性規範。問題在於,agent 依據程式碼層面的局部信心做判斷,系統級正確性需要全局驗證。+- **置信度校準偏差**:agent 自報的完成信心與實際完成質量之間的系統性差距。對複雜多檔案任務,這個偏差顯著為正,agent 總是比實際做得更自信。這種過度自信在跨任務類型的測試中一致重現,不因任務難度降低而消失。- **終止標準**:一組明確的、可執行的判定條件,定義在 harness 裡。agent 必須滿足所有條件才能聲明完成。「完成」從主觀判斷變成了客觀判定。- **驗證-確認雙閘門**:第一層驗證檢查「程式碼是否正確實現了指定行為」;第二層確認檢查「系統級行為是否滿足端到端需求」。兩層都通過才算完成。- **執行時期回饋信號**:來自程式執行的日誌、程式狀態、健康檢查。這是 harness 判定完成質量的客觀基礎。@@ -45,25 +45,25 @@ flowchart LR## 單元測試通過 ≠ 任務完成-這是最常見的陷阱,也是最危險的一個。agent 寫了程式碼,跑了單元測試,全部綠色,然後說「做完了」。但單元測試的設計哲學——隔離被測單元、模擬依賴——恰好使其無法檢測跨元件問題:+這是最常見的陷阱,也是最危險的一個。agent 寫了程式碼,跑了單元測試,全部綠色,然後說「做完了」。但單元測試的設計哲學(隔離被測單元、模擬依賴),恰好使其無法檢測跨元件問題:-**介面不相符**:渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題。就像樂隊裡每個樂手各自練習都完美,但合在一起才發現定調不一樣。+**介面不相符**,渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。跨元件的介面契約無法透過隔離測試驗證,只有整合執行才能暴露真正的相容性問題。-**狀態傳播錯誤**:資料庫遷移改了表結構,但 ORM 的快取層還持有舊結構的快取條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。+**狀態傳播錯誤**,資料庫遷移改了表結構,但 ORM 的快取層還持有舊結構的快取條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。-**環境依賴性**:程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。就像在排練室唱得很好,上台演出時音響設備出了問題。+**環境依賴性**,程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。測試環境的完全隔離設計決定了它無法反映真實部署環境中的配置差異與外部依賴狀態。### "順便重構"是完成判定的毒藥-Claude Code 有一個常見行為模式:在核心功能還沒驗證通過時就開始重構程式碼、最佳化效能、改進風格。Knuth 說的「過早最佳化是萬惡之源」在 agent 場景中有了新含義——重構會改變已完成驗證和未完成驗證之間的邊界,可能破壞之前隱式正確的程式碼路徑。就像你數學大題還沒做完,就跑去把前面選擇題的答案重新抄一遍格式——浪費時間不說,還可能抄錯了。+Claude Code 有一個常見行為模式,在核心功能還沒驗證通過時就開始重構程式碼、最佳化效能、改進風格。Knuth 說的「過早最佳化是萬惡之源」在 agent 場景中有了新含義,重構會改變已完成驗證和未完成驗證之間的邊界,可能破壞之前隱式正確的程式碼路徑。重構在核心功能未確立前進行,既模糊了驗證邊界,也在新的變更集中引入了額外的偵錯負擔。### 自我評價的系統性偏差-Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**當 agent 被要求評估自己的工作時,它系統性地過度正面評價——即使人類觀察者認為質量明顯不達標。** 這就像讓學生自己給自己判卷——對自己的答案總是特別寬容。+Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**當 agent 被要求評估自己的工作時,它一致性地過度正面評價,即使人類觀察者認為質量明顯不達標。** 同一模型負責生成與評估,其評估結果天然偏向肯定自身的輸出。-這個問題在主觀任務(如設計美感)上尤其嚴重——「版面配置是否精緻」是一個判斷題,agent 可靠地偏向正面。即使在有可驗證結果的任務上,agent 也會因為判斷失誤而影響表現。+這個問題在主觀任務(如設計美感)上尤其嚴重,「版面配置是否精緻」是一個判斷題,agent 可靠地偏向正面。即使在有可驗證結果的任務上,agent 也會因為判斷失誤而影響表現。-解決方案不是讓 agent「更客觀」——同一個模型既生成又評估,內在地傾向對自己慷慨。**解決方案是把「幹活的人」和「檢查的人」分開。** 就像考試不能讓學生自己批改自己的卷子——得有個獨立的閱卷老師。+解決方案不是讓 agent「更客觀」,同一個模型既生成又評估,內在地傾向對自己慷慨。**解決方案是把「幹活的人」和「檢查的人」分開。** 將評估職責交給獨立的 agent,評估者不受生成者的置信度影響,能更客觀地判定任務是否實際完成。一個獨立的評估 agent,經過專門調校為"挑剔"之後,比讓生成 agent 自我評估有效得多。Anthropic 的實驗數據:@@ -72,7 +72,7 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**| 單 agent 裸跑 | 20 分鐘 | $9 | 否(遊戲實體無法響應輸入) || 三 agent(planner + generator + evaluator) | 6 小時 | $200 | 是(遊戲可以正常遊玩) |-這是同一個模型(Opus 4.5),同一段提示詞("做一個 2D 復古遊戲編輯器")。區別只在 harness——從"裸奔"到"planner 擴展需求 → generator 逐功能實現 → evaluator 用 Playwright 實際點擊測試"。+這是同一個模型(Opus 4.5),同一段提示詞("做一個 2D 復古遊戲編輯器")。區別只在 harness,從"裸奔"到"planner 擴展需求 → generator 逐功能實現 → evaluator 用 Playwright 實際點擊測試"。> 來源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)@@ -95,13 +95,13 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**### 2. 構建三層終止校驗-- **第一層:語法與靜態分析**。成本最低,資訊量最小,但必須通過。這是最低限度的檢查——字都沒寫錯才能往下看。+- **第一層:語法與靜態分析**。成本最低,資訊量最小,但必須通過。這是最低限度的檢查,字都沒寫錯才能往下看。- **第二層:執行時期行為驗證**。測試執行、應用啟動檢查、關鍵路徑驗證。這是核心完成證據。不僅要寫了,還要能跑。- **第三層:系統級確認**。端到端測試、整合驗證、使用者場景模擬。防止過早聲明的最後一道防線。不僅要能跑,還要跑對。### 3. 為 agent 設計好的"紅筆批註"-OpenAI 在 Codex 實踐中提出了一個特別有效的模式:**給 agent 寫的錯誤訊息要包含修復指導**。不要像閱卷老師只畫個大紅叉,要像好老師一樣在旁邊寫上「這裡應該怎麼改」。不要用 `"Test failed"`,而用 `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` 這種具體的、可操作的回饋讓 agent 能自我修正,而不需要人類介入。+OpenAI 在 Codex 實踐中提出了一個特別有效的模式,**給 agent 寫的錯誤訊息要包含修復指導**。不要像閱卷老師只畫個大紅叉,要像好老師一樣在旁邊寫上「這裡應該怎麼改」。不要用 `"Test failed"`,而用 `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` 這種具體的、可操作的回饋讓 agent 能自我修正,而不需要人類介入。### 4. 捕獲執行時期信號@@ -113,28 +113,28 @@ OpenAI 在 Codex 實踐中提出了一個特別有效的模式:**給 agent 寫## 實際案例-**任務**:實現使用者密碼重置功能。涉及資料庫操作、郵件發送和 API 端點修改。+**任務**,實現使用者密碼重置功能。涉及資料庫操作、郵件發送和 API 端點修改。-**提前交卷路徑**:agent 修改資料庫 schema、編寫 API 端點、新增郵件範本、跑單元測試(通過)、聲明完成。卷子寫得滿滿當當。+**提前交卷路徑**,agent 修改資料庫 schema、編寫 API 端點、新增郵件範本、跑單元測試(通過)、聲明完成。卷子寫得滿滿當當。-**實際扣分項**:(1) 端到端流程未測試——重置連結的實際發送和驗證未確認。(2) 資料庫遷移在部分執行後失敗,導致 schema 不一致。(3) 郵件服務配置在目標環境中缺失。+**實際扣分項**,(1) 端到端流程未測試,重置連結的實際發送和驗證未確認。(2) 資料庫遷移在部分執行後失敗,導致 schema 不一致。(3) 郵件服務配置在目標環境中缺失。-**harness 介入**:終止校驗強制執行——(1) 啟動完整應用驗證重置端點可訪問;(2) 執行完整重置流程;(3) 驗證資料庫狀態一致性。所有缺陷在工作階段內被發現,節省了 5-10 倍的後續修復成本。獨立閱卷老師批出了真正的問題。+**harness 介入**,終止校驗強制執行,(1) 啟動完整應用驗證重置端點可訪問;(2) 執行完整重置流程;(3) 驗證資料庫狀態一致性。所有缺陷在工作階段內被發現,節省了 5-10 倍的後續修復成本。獨立閱卷老師批出了真正的問題。## 關鍵要點-- **agent 系統性地過度自信**——置信度校準偏差是客觀存在的。卷子寫滿了不代表做對了。+- **agent 普遍過度自信**,置信度校準偏差是客觀存在的。卷子寫滿了不代表做對了。- **完成判定必須外部化**——harness 獨立驗證,不信任 agent 的「感覺」。不能讓學生自己批自己的卷子。-- **三層校驗缺一不可**——語法通過、行為通過、系統通過,層層遞進。-- **錯誤訊息要像好老師的紅筆批注**——包含具體修復步驟,讓 agent 能自我修正。-- **核心功能驗證通過之前不許重構**——完成優先級約束是防止過早最佳化的關鍵。+- **三層校驗缺一不可**,語法通過、行為通過、系統通過,層層遞進。+- **錯誤訊息要像好老師的紅筆批注**,包含具體修復步驟,讓 agent 能自我修正。+- **核心功能驗證通過之前不許重構**,完成優先級約束是防止過早最佳化的關鍵。## 延伸閱讀-- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — 證明現代深度網路系統性地過度自信-- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 執行時期證據在完成判定中的關鍵作用-- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 過早完成聲明是 agent 的主要失敗模式之一-- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — 測試方法層次和有效性的經典參考+- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599),證明現代深度網路普遍過度自信+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents),執行時期證據在完成判定中的關鍵作用+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/),過早完成聲明是 agent 的主要失敗模式之一+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing),測試方法層次和有效性的經典參考## 練習@@ -142,4 +142,4 @@ OpenAI 在 Codex 實踐中提出了一個特別有效的模式:**給 agent 寫2. **校準偏差測量**:選 10 個不同類型的編碼任務,記錄 agent 的自報完成信心和實際完成品質。計算偏差值,分析它和任務複雜度的關係。-3. **多層防禦實驗**:對同一組任務跑三種配置——(a) 僅靜態分析,(b) 加單元測試,(c) 完整三層校驗。比較過早完成聲明的比例和未捕獲缺陷的數量。+3. **多層防禦實驗**:對同一組任務跑三種配置,(a) 僅靜態分析,(b) 加單元測試,(c) 完整三層校驗。比較過早完成聲明的比例和未捕獲缺陷的數量。diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.mdindex 34ac40c..fec381e 100644--- a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -5,21 +5,21 @@# 第十講. 跑通完整流程才算真正驗證-你讓 agent 給 Electron 應用加一個檔案匯出功能。它寫了渲染程式元件、預載腳本、服務層邏輯,每個元件的單元測試都通過了。agent 說「做完了」。你實際一點擊匯出按鈕——檔案路徑格式不對、進度列沒反應、大檔案匯出時記憶體洩漏。5 個元件邊界缺陷,單元測試一個都沒發現。+你讓 agent 給 Electron 應用加一個檔案匯出功能。它寫了渲染程式元件、預載腳本、服務層邏輯,每個元件的單元測試都通過了。agent 說「做完了」。你實際一點擊匯出按鈕,檔案路徑格式不對、進度列沒反應、大檔案匯出時記憶體洩漏。5 個元件邊界缺陷,單元測試一個都沒發現。這就像一個合唱團排練——每個聲部單獨唱的時候都完美,但合在一起的時候,女高音比男低音快了半拍,伴奏的調子和主旋律差了半個音。每個部分都"對"了,但整體跑調了。-Google 的測試金字塔告訴我們:大量單元測試是基礎,但如果你止步於此,就會系統性地漏掉元件互動問題。對於 AI 程式碼代理來說,這個問題更嚴重——agent 傾向於只跑最快的測試然後宣告完成。**只有端到端測試能證明系統級缺陷不存在**。+Google 的測試金字塔告訴我們:大量單元測試是基礎,但如果你止步於此,就會持續漏掉元件互動問題。對於 AI 程式碼代理來說,這個問題更嚴重,agent 傾向於只跑最快的測試然後宣告完成。**只有端到端測試能證明系統級缺陷不存在**。## 單元測試的盲區-單元測試的設計哲學是隔離——模擬依賴,專注被測單元。這個哲學使單元測試快速且精確,但也製造了系統性的盲區。就像合唱排練時每個聲部戴著耳機對著伴奏唱——聽著都挺好,但真正合在一起才發現問題:+單元測試的設計哲學是隔離,模擬依賴,專注被測單元。這個哲學使單元測試快速且精確,但也製造了系統性的盲區。就像合唱排練時每個聲部戴著耳機對著伴奏唱,聽著都挺好,但真正合在一起才發現問題:-**介面不相符**:渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題——就像兩個聲部各自練的時候都覺得節奏沒問題,一合才發現一個用 4/4 拍一個用 3/4 拍。+**介面不相符**:渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題,就像兩個聲部各自練的時候都覺得節奏沒問題,一合才發現一個用 4/4 拍一個用 3/4 拍。**狀態傳播錯誤**:資料庫遷移改了表結構,但 ORM 的快取層還持有舊結構的快取條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。就像換了一首歌的歌詞,但有人還在唱舊版本。-**資源生命週期問題**:檔案描述符、資料庫連線、網路通訊端的獲取和釋放跨越多個元件。單元測試為每個測試建立和銷毀獨立資源,不會暴露資源競爭或洩漏。就像排練時每個聲部輪流用麥克風,但演出時所有聲部同時上台——麥克風不夠用了。+**資源生命週期問題**:檔案描述符、資料庫連線、網路通訊端的獲取和釋放跨越多個元件。單元測試為每個測試建立和銷毀獨立資源,不會暴露資源競爭或洩漏。就像排練時每個聲部輪流用麥克風,但演出時所有聲部同時上台,麥克風不夠用了。**環境依賴性**:程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。就像排練廳裡唱得好好的,到了戶外音樂節風一吹麥克風一嘯叫就全亂了。@@ -61,23 +61,23 @@ OpenAI 在 Codex 工程實踐中強調:**為 agent 寫的錯誤訊息必須包## 核心概念-- **元件邊界缺陷**:元件 A 和 B 各自單元測試通過,但它們的互動產生了不正確的行為。這是端到端測試最擅長捕獲的問題類型——合唱裡各聲部單獨都對但合起來跑調的那種。+- **元件邊界缺陷**:元件 A 和 B 各自單元測試通過,但它們的互動產生了不正確的行為。這是端到端測試最擅長捕獲的問題類型,合唱裡各聲部單獨都對但合起來跑調的那種。- **測試充分性梯度**:單元測試能檢測的缺陷 <= 整合測試能檢測的缺陷 <= 端到端測試能檢測的缺陷。每往上一層,檢測能力增強。- **架構邊界執行規則**:把架構文件裡的規則(如「渲染程式不能直接存取檔案系統」)變成可執行的自動化檢查。從「寫在紙上」變成「跑在 CI 裡」。-- **審查回饋提升**:把重複出現的程式碼審查意見轉化為自動化測試。每次發現重複問題就加一條規則,harness 會自動變強。就像合唱排練時指揮把常見的錯誤編成練習曲——下次再犯同樣的錯誤,不用指揮說,練習曲自己就暴露了。+- **審查回饋提升**:把重複出現的程式碼審查意見轉化為自動化測試。每次發現重複問題就加一條規則,harness 會自動變強。就像合唱排練時指揮把常見的錯誤編成練習曲,下次再犯同樣的錯誤,不用指揮說,練習曲自己就暴露了。- **面向 agent 的錯誤訊息**:失敗資訊不只是說「出了什麼問題」,還要告訴 agent 具體怎麼修。這把測試失敗變成自我修正的回饋循環。## 怎麼做### 0. 先定好架構邊界,再寫端到端測試-端到端測試的前提是系統有清晰的邊界。如果架構是一團麵條,端到端測試只會證明「這團麵條整體能跑」,不會告訴你哪裡違反了設計意圖。就像合唱團如果連分聲部都沒分好,排練再多也是亂唱。+端到端測試的前提是系統有明確的邊界。如果架構是一團麵條,端到端測試只會證明「這團麵條整體能跑」,不會告訴你哪裡違反了設計意圖。就像合唱團如果連分聲部都沒分好,排練再多也是亂唱。-OpenAI 的經驗:**對 agent 生成的程式碼庫,架構約束必須是第一天就建立的早期前置條件,不是等團隊規模大了再考慮的事。** 原因很直接——agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。沒有架構約束,agent 會在每次工作階段中引入更多偏差。+OpenAI 的經驗:**對 agent 生成的程式碼庫,架構約束必須是第一天就建立的早期前置條件,不是等團隊規模大了再考慮的事。** 原因很直接,agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。沒有架構約束,agent 會在每次工作階段中引入更多偏差。-OpenAI 採用了「分層領域架構」——每個業務領域被分成固定的層:Types → Config → Repo → Service → Runtime → UI。依賴方向嚴格向前,跨領域關注點通過顯式的 Providers 介面進入。任何其他依賴都是禁止的,並且通過自訂 lint 機械執行。+OpenAI 採用了「分層領域架構」,每個業務領域被分成固定的層:Types → Config → Repo → Service → Runtime → UI。依賴方向嚴格向前,跨領域關注點通過顯式的 Providers 介面進入。任何其他依賴都是禁止的,並且通過自訂 lint 機械執行。-關鍵原則:**執行不變數,不微管實現。** 比如要求「資料在邊界解析」,但不規定用哪個程式庫。錯誤訊息要包含修復指導——不只是說「違規了」,而是告訴 agent 具體怎麼改。+關鍵原則:**執行不變數,不微管實現。** 比如要求「資料在邊界解析」,但不規定用哪個程式庫。錯誤訊息要包含修復指導,不只是說「違規了」,還要告訴 agent 具體怎麼改。> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)@@ -114,7 +114,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea### 4. 建立審查回饋提升流程-每次在程式碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。就像合唱團的排練筆記——每次排練發現的問題都記下來,下次排練前先檢查這些點。久而久之,常見錯誤越來越少,音樂越來越和諧。+每次在程式碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。就像合唱團的排練筆記,每次排練發現的問題都記下來,下次排練前先檢查這些點。久而久之,常見錯誤越來越少,音樂越來越和諧。## 實際案例@@ -132,22 +132,22 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea| 權限問題 | 打包環境權限不同 | 未檢測 | 檢測 || 錯誤傳播 | 服務層例外未到 UI 層 | 未檢測 | 檢測 |-5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。代價是測試時間從 2 秒增加到 15 秒——在 agent 工作流裡完全可以接受。每個聲部單獨唱得再好,也比不上一次完整的合唱排練。+5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。代價是測試時間從 2 秒增加到 15 秒,在 agent 工作流裡完全可以接受。每個聲部單獨唱得再好,也比不上一次完整的合唱排練。## 關鍵要點-- **單元測試對元件邊界缺陷系統性盲視**——它們的隔離設計恰好使其無法檢測互動問題。每個人唱得都對,不代表合唱不跑調。+- **單元測試對元件邊界缺陷系統性盲視**,它們的隔離設計恰好使其無法檢測互動問題。每個人唱得都對,不代表合唱不跑調。- **端到端測試不僅檢測缺陷,還改變 agent 的編碼行為**——讓它更關注整合和邊界。-- **架構規則必須可執行**——不是寫在文件裡等人來看,而是每次提交自動檢查。-- **錯誤訊息要面向 agent 設計**——包含「怎麼修」的具體步驟,形成自我修正閉環。-- **審查回饋提升讓 harness 自動變強**——每個被捕獲的缺陷類別都變成永久防線。+- **架構規則必須可執行**,要每次提交自動檢查,不應只寫在文件裡等人查看。+- **錯誤訊息要面向 agent 設計**,包含「怎麼修」的具體步驟,形成自我修正閉環。+- **審查回饋提升讓 harness 自動變強**,每個被捕獲的缺陷類別都變成永久防線。## 延伸閱讀-- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — 測試金字塔模型的經典來源-- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 架構約束自動化執行的工程實踐-- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — 主動注入故障驗證系統彈性-- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — 屬性測試方法,介於示例測試和形式化驗證之間+- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software),測試金字塔模型的經典來源+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/),架構約束自動化執行的工程實踐+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237),主動注入故障驗證系統彈性+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf),屬性測試方法,介於示例測試和形式化驗證之間## 練習diff --git a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.mdindex 9814c24..a680c9c 100644--- a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -7,31 +7,31 @@你讓 agent 做一個功能,它跑了 20 分鐘,改了一堆檔案,然後告訴你「做完了但有兩個測試失敗」。你問它為什麼失敗,它說「不太確定,可能是時序問題」。你問它改了哪些關鍵路徑,它說「讓我看看程式碼……」。-這不是 agent 能力不夠,是你的 harness 沒有給它裝儀表盤。想象你在開一輛沒有儀表盤的車——沒有速度表、沒有油量表、沒有發動機故障燈。你能開,但你不知道開多快、還剩多少油、發動機是不是快爆了。技術再好的司機,蒙著眼也得出事。+harness 沒有給 agent 裝上所需的儀表盤,才導致這種困境。想象你在開一輛沒有儀表盤的車,沒有速度表、沒有油量表、沒有發動機故障燈。你能開,但你不知道開多快、還剩多少油、發動機是不是快爆了。技術再好的司機,蒙著眼也得出事。-**沒有可觀測性,agent 在不確定狀態中做決策,評估變成主觀判斷,重試變成盲目摸索。** OpenAI 和 Anthropic 都將可靠性定義為證據問題——harness 必須以可指導下一步決策的形式暴露執行時期行為和評估訊號。+**沒有可觀測性,agent 在不確定狀態中做決策,評估變成主觀判斷,重試變成盲目摸索。** OpenAI 和 Anthropic 都將可靠性定義為證據問題,harness 必須以可指導下一步決策的形式暴露執行時期行為和評估訊號。## 可觀測性缺失的真實代價當 harness 缺乏可觀測性時,四類問題系統性出現:-**無法區分「正確」和「看似正確」**:一個函式在程式碼審查時看起來完全正確——語法對、邏輯通。但執行時期因為邊界條件處理錯誤,在特定輸入下產生了不正確結果。只有執行時期追蹤能揭示實際執行路徑偏離了預期。就像一個演員排練時臺詞全對了,但上台演出時燈光一打,表情和走位全都變了——你不看現場是發現不了的。+**無法區分「正確」和「看似正確」**,一個函式在程式碼審查時看起來完全正確,語法對、邏輯通。但執行時期因為邊界條件處理錯誤,在特定輸入下產生了不正確結果。只有執行時期追蹤能揭示實際執行路徑偏離了預期。靜態審查只能驗證程式碼結構,無法取代對實際執行路徑的直接觀察。-**評估變成玄學**:沒有評分標準和驗收條件時,評估者(人或 agent)依賴隱式假設。同一個輸出,不同評估者可能給出截然不同的評價。質量評估不可復現。就像體操比賽沒有評分標準——這個裁判覺得你的動作優雅,那個裁判覺得你落地不穩,誰說了算?+**評估變成玄學**,沒有評分標準和驗收條件時,評估者(人或 agent)依賴隱式假設。同一個輸出,不同評估者可能給出截然不同的評價。質量評估不可復現。評估標準的缺失使品質判斷無法對齊,同一輸出的評價結果因評估者而異。-**重試變成盲猜**:agent 不知道為什麼失敗時,重試方向是隨機的。它可能在錯誤的方向上反覆嘗試——修復了不相關的程式碼路徑而忽略真正的故障根源。就像你開車發現車跑偏了,但你沒有儀表盤——你猜是輪胎的問題換了輪胎,實際是方向盤的 alignment 出了問題。每次盲重試都消耗 token 和時間。+**重試變成盲猜**,agent 不知道為什麼失敗時,重試方向是隨機的。它可能在錯誤的方向上反覆嘗試,修復了不相關的程式碼路徑而忽略真正的故障根源。每次錯誤方向的重試都擴大了與真正根因的距離。每次盲重試都消耗 token 和時間。-**工作階段交接資訊斷崖**:當未完成的工作移交給下一個工作階段時,缺乏可觀測性意味著新工作階段必須從零診斷系統狀態。Anthropic 的長期執行 agent 觀察表明,這種重複診斷可能佔工作階段總時間的 30-50%。就像換班司機上車發現沒有交接記錄——他得花半小時檢查油量、胎壓、發動機狀態才能出發。+**工作階段交接資訊斷崖**,當未完成的工作移交給下一個工作階段時,缺乏可觀測性意味著新工作階段必須從零診斷系統狀態。Anthropic 的長期執行 agent 觀察表明,這種重複診斷可能佔工作階段總時間的 30-50%。新工作階段缺乏前一階段的脈絡,必須從頭診斷,重複投入本可省略的工作。## Claude Code 的真實場景想象一個使用「計劃者-生成者-評估者」三角色工作流的 harness,執行「為應用添加暗色模式」任務。-**沒有儀表盤**:計劃者輸出模糊描述。生成者根據模糊描述實現暗色模式,但和計劃者的隱式預期不一致。評估者基於自己的隱式標準拒絕,但說不出具體哪裡不對——「感覺不太對」。生成者基於模糊拒絕理由盲重試。循環 3-4 次,總耗時約 45 分鐘,最終勉強產出。+**沒有儀表盤**,計劃者輸出模糊描述。生成者根據模糊描述實現暗色模式,但和計劃者的隱式預期不一致。評估者基於自己的隱式標準拒絕,但說不出具體哪裡不對,「感覺不太對」。生成者基於模糊拒絕理由盲重試。循環 3-4 次,總耗時約 45 分鐘,最終勉強產出。-**有完整儀表盤**:計劃者輸出衝刺合約——列明要改哪些元件、每個元件的驗證標準、排除項(不處理列印樣式)。生成者按合約實現。執行時期可觀測性記錄每個元件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用——「按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)」。一次迭代出高質量結果,總耗時約 15 分鐘。+**有完整儀表盤**,計劃者輸出衝刺合約,列明要改哪些元件、每個元件的驗證標準、排除項(不處理列印樣式)。生成者按合約實現。執行時期可觀測性記錄每個元件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用,「按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)」。一次迭代出高質量結果,總耗時約 15 分鐘。-效率差 3 倍。區別只在可觀測性——給車裝上了儀表盤。+效率差 3 倍。區別只在可觀測性,給車裝上了儀表盤。## 雙層可觀測性@@ -47,26 +47,26 @@ flowchart LRVerdict --> Generator```-**執行時期可觀測性**:系統層的訊號——日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。這是你車上的儀表盤——速度、油量、發動機溫度。+**執行時期可觀測性**,系統層的訊號——日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。這是你車上的儀表盤,速度、油量、發動機溫度。-**過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。這是你的導航系統——不光知道現在在哪,還知道為什麼走這條路。+**過程可觀測性**,harness 決策工件的可見性,計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。這是你的導航系統,不光知道現在在哪,還知道為什麼走這條路。## 核心概念-- **執行時期可觀測性**:系統層的訊號——日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。-- **過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。-- **任務軌跡**:一個任務從開始到完成的完整決策路徑記錄,類似分佈式系統中的請求追蹤。agent 的每一步操作及其脈絡都被記錄。就像黑匣子——出了問題可以重播完整過程。-- **衝刺合約**:編碼開始前協商的短期協定——明確任務範圍、驗證標準、排除項。是過程可觀測性的核心工具。-- **評估評分標準**:把質量評估從主觀判斷變成基於證據的結構化評分。使不同評估者對同一輸出產生相似結論。就像體操比賽的評分標準——有了它,十個裁判的分才不會差太遠。+- **執行時期可觀測性**:系統層的訊號,日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。+- **過程可觀測性**:harness 決策工件的可見性,計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。+- **任務軌跡**:一個任務從開始到完成的完整決策路徑記錄,類似分佈式系統中的請求追蹤。agent 的每一步操作及其脈絡都被記錄。出現問題時,可依任務軌跡完整重播決策過程,精確定位分叉點。+- **衝刺合約**:編碼開始前協商的短期協定,明確任務範圍、驗證標準、排除項。是過程可觀測性的核心工具。+- **評估評分標準**:把質量評估從主觀判斷變成基於證據的結構化評分。使不同評估者對同一輸出產生相似結論。結構化評分使評估流程具備可重現性,避免主觀判斷的不一致性。- **雙層可觀測性**:系統層和過程層同時設計、相互增強。執行時期信號解釋行為,過程工件解釋意圖。## 為什麼 agent 自己解決不了這個問題你可能在想:"agent 不能自己打日誌嗎?" 問題在於:-1. **agent 不知道它不知道什麼**——它不會主動記錄自己沒意識到需要的訊號。就像你不知道油箱快漏了的時候,你不會去看油量表——因為你壓根不知道該看。-2. **日誌格式不統一**——不同工作階段用不同的日誌格式,無法做系統化分析。就像十個司機各寫各的交接記錄,格式都不一樣,下一個司機看不懂。-3. **過程可觀測性不是日誌能解決的**——衝刺合約和評分標準是結構化的工件,需要 harness 層面的支援。不是多 print 幾行就能搞定的。+1. **agent 不知道它不知道什麼**——它不會主動記錄自己沒意識到需要的訊號。agent 只記錄它意識到需要記錄的訊號,對未察覺的問題域天然盲目。+2. **日誌格式不統一**,不同工作階段用不同的日誌格式,無法做系統化分析。格式各異的日誌無法在工作階段間做系統化比對分析。+3. **過程可觀測性不是日誌能解決的**,衝刺合約和評分標準是結構化的工件,需要 harness 層面的支援。不是多 print 幾行就能搞定的。## 怎麼裝儀表盤@@ -82,7 +82,7 @@ flowchart LR### 2. 實施衝刺合約-在每個任務開始前,生成者和評估者(可能是同一個 agent 的不同呼叫)協商一份合約——就像施工隊開工前籤的施工協定:+在每個任務開始前,生成者和評估者(可能是同一個 agent 的不同呼叫)協商一份合約,協定任務範圍與完成標準:```markdown# 衝刺合約: 暗色模式支援@@ -104,7 +104,7 @@ flowchart LR### 3. 建立評估評分標準-把"好不好"變成可量化的評分——就像給體操比賽定評分標準:+把「好不好」轉為可量化的結構化評分:```markdown# 評分標準@@ -137,24 +137,24 @@ Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們三個 agent 各司其職,每個都有明確的可觀測性角色:-**Planner(規劃者)**:接收一段 1-4 句話的使用者需求,擴展成完整產品規格。被要求「大膽設定範圍」並且「專注於產品脈絡和高層技術設計,而不是詳細的技術實現」。原因是:如果 planner 過早指定了粒度技術細節且搞錯了,錯誤會級聯到下游實現。更好的做法是約束交付物,讓 agent 在執行中自己找到路徑。就像建築設計師只畫效果圖和結構圖,不規定每塊磚怎麼砌。+**Planner(規劃者)**,接收一段 1-4 句話的使用者需求,擴展成完整產品規格。被要求「大膽設定範圍」並且「專注於產品脈絡和高層技術設計,而不是詳細的技術實現」。原因是,如果 planner 過早指定了粒度技術細節且搞錯了,錯誤會級聯到下游實現。更好的做法是約束交付物,讓 agent 在執行中自己找到路徑。粒度過細的技術規格若有誤,錯誤會在實現階段逐層放大。-**Generator(生成者)**:按 sprint 逐個功能實現。每個 sprint 前和 evaluator 協商一份 sprint 合約——約定這個功能塊「做完」的標準。然後按合約實現,自評後交給 QA。按合約施工,不按感覺施工。+**Generator(生成者)**,按 sprint 逐個功能實現。每個 sprint 前和 evaluator 協商一份 sprint 合約,約定這個功能塊「做完」的標準。然後按合約實現,自評後交給 QA。按合約施工,不按感覺施工。-**Evaluator(評估者)**:用 Playwright MCP 像使用者一樣點擊執行中的應用,測試 UI 功能、API 端點和資料庫狀態。對每個 sprint 按四個維度評分——產品深度、功能性、視覺設計和程式碼品質。每個維度有硬性閾值,任一不達標則 sprint 失敗,generator 收到詳細回饋後修復。就像驗收工程師拿著驗收標準逐項檢查——不達標就打回去重做。+**Evaluator(評估者)**,用 Playwright MCP 像使用者一樣點擊執行中的應用,測試 UI 功能、API 端點和資料庫狀態。對每個 sprint 按四個維度評分,產品深度、功能性、視覺設計和程式碼品質。每個維度有硬性閾值,任一不達標則 sprint 失敗,generator 收到詳細回饋後修復。評分失敗的 sprint 連同具體說明一併交回 generator 修復,通過後方可進入下一個功能。-QA 第 1 輪回饋的示例——「這是一個視覺上令人印象深刻的應用,AI 整合工作良好,但核心 DAW 功能有幾個是展示性的,沒有互動深度:剪輯不能拖拽/移動,沒有樂器 UI 面板(合成器旋鈕、鼓墊),沒有視覺效果編輯器(EQ 曲線、壓縮器儀表)」。這些不是邊緣情況——它們是讓 DAW 可用的核心互動。具體的、有證據的回饋,不是「感覺不對」。+QA 第 1 輪回饋的示例,「這是一個視覺上令人印象深刻的應用,AI 整合工作良好,但核心 DAW 功能有幾個是展示性的,沒有互動深度,剪輯不能拖拽/移動,沒有樂器 UI 面板(合成器旋鈕、鼓墊),沒有視覺效果編輯器(EQ 曲線、壓縮器儀表)」。這些不是邊緣情況,它們是讓 DAW 可用的核心互動。具體的、有證據的回饋,不是「感覺不對」。-Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題,然後說服自己這些問題不嚴重,最終批準工作。調校方式是:讀 evaluator 的日誌,找到它的判斷和人類判斷分叉的地方,更新 QA 的 prompt 解決那些問題。經過幾輪這種開發循環,evaluator 的評分才變得合理。就像訓練一個新驗收工程師——一開始他太寬容,出了幾次事故後學會了嚴格。+Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題,然後說服自己這些問題不嚴重,最終批準工作。調校方式是,讀 evaluator 的日誌,找到它的判斷和人類判斷分叉的地方,更新 QA 的 prompt 解決那些問題。經過幾輪這種開發循環,evaluator 的評分才變得合理。evaluator 的初始版本通常過於寬容,需要通過日誌分析與 prompt 迭代才能達到可用的評分標準。> 來源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)## 關鍵要點-- **可觀測性是 harness 的架構屬性**——不是事後新增的功能,而是設計時必須考慮的核心能力。儀表盤不是可選配件,是出廠標配。-- **雙層可觀測性缺一不可**——執行時期訊號解釋「發生了什麼」,過程工件解釋「為什麼這樣做」。速度表和導航系統各有各的用處。-- **衝刺合約前置對齊工作**——防止「生成者做了評估者因可預見原因立即拒絕的東西」。施工協定要在開工前簽,不是完工後補。-- **評分標準讓評估可復現**——不同評估者對同一輸出產生相似評分。有了評分標準,十個裁判的分才不會差太遠。+- **可觀測性是 harness 的架構屬性**,是設計時必須考慮的核心能力。儀表盤不是可選配件,是出廠標配。+- **雙層可觀測性缺一不可**,執行時期訊號解釋「發生了什麼」,過程工件解釋「為什麼這樣做」。速度表和導航系統各有各的用處。+- **衝刺合約前置對齊工作**,防止「生成者做了評估者因可預見原因立即拒絕的東西」。施工協定要在開工前簽,不是完工後補。+- **評分標準讓評估可復現**,不同評估者對同一輸出產生相似評分。有了評分標準,十個裁判的分才不會差太遠。- **可觀測性缺失導致 30-50% 的工作階段時間浪費在重複診斷上**。## 延伸閱讀@@ -170,4 +170,4 @@ Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題2. **衝刺合約實踐**:為一個真實任務寫衝刺合約。讓 agent 按合約執行,對比沒有合約時的效率和品質差異。-3. **任務軌跡構建**:記錄一個完整編碼任務中 agent 的每一步操作。用 OpenTelemetry 語義約定標注。分析軌跡中的資訊瓶頸——哪些步驟的決策缺乏足夠的訊號支援。+3. **任務軌跡構建**:記錄一個完整編碼任務中 agent 的每一步操作。用 OpenTelemetry 語義約定標注。分析軌跡中的資訊瓶頸,哪些步驟的決策缺乏足夠的訊號支援。diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdindex 4ecab2b..d5baa84 100644--- a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md@@ -7,29 +7,29 @@你的 agent 跑了一下午,改了 20 個檔案,提交了程式碼,工作階段結束。下一個 agent 工作階段開始,一上來就發現:建構失敗了、測試紅了、臨時調試檔案到處都是、功能清單沒更新、進度完全不清楚。新工作階段的前 30 分鐘全花在「搞清楚上一個工作階段到底幹了什麼」上。-這就像大學宿舍——你不倒垃圾,下一個室友進來就得替你收拾。他本來的計劃是複習考試,結果先花半小時收拾你留下的爛攤子。更要命的是,收拾完了他也不想複習了——環境太差,心情也差。+一個工作階段留下的混亂,直接壓縮了下一個工作階段的可用時間。新工作階段本來要做新功能,卻先花半小時釐清上一個工作階段的殘局,環境混亂更會降低後續工作品質。OpenAI 和 Anthropic 都明確指出:**長期可靠性取決於操作紀律,不僅是單次執行的成功。** 每個工作階段結束時的狀態品質,直接決定下一個工作階段的效率。## 熵增是預設狀態-Lehman 的軟體演化定律告訴我們:持續變更的系統,除非主動管理,否則複雜性必然增加。這對 AI 程式碼代理尤其成立——agent 每次工作階段都會引入變更,如果不在退出時清理,技術債務會指數級累積。宿舍不打掃,髒衣服和外賣盒只會越堆越多,不會自己消失。+Lehman 的軟體演化定律表明,持續變更的系統,除非主動管理,否則複雜性必然增加。這對 AI 程式碼代理尤其成立,agent 每次工作階段都會引入變更,如果不在退出時清理,技術債務會指數級累積。宿舍不打掃,髒衣服和外賣盒只會越堆越多,不會自己消失。-OpenAI 在 5 個月的 Codex 實驗中觀察到:**agent 會複製儲存庫中已有的模式——即使那些模式是不均勻的或次優的。** 隨著時間的推移,這種複製必然導致漂移。就像宿舍裡的公共區域——第一個人在桌上放了一個杯子,第二個人覺得「反正已經亂了」又放了一個,一週後桌上堆滿了。+OpenAI 在 5 個月的 Codex 實驗中觀察到,**agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。** 隨著時間的推移,這種複製必然導致漂移。初始的模式不均勻性在反覆複製後會逐漸放大,最終導致程式碼庫明顯漂移。-OpenAI 團隊最初花每週五(20% 的工作時間)手動清理「AI slop」。不出所料,這種方式不可擴展。就像宿舍每週大掃除一次——其他六天的髒亂差還是得忍。他們的解決方案是:+OpenAI 團隊最初花每週五(20% 的工作時間)手動清理「AI slop」。不出所料,這種方式不可擴展。週期性的手動清理無法阻止日常累積的技術債。他們的解決方案是:-1. **把「黃金原則」編碼進儲存庫**:比如「優先使用共享工具套件而非手寫的 ad-hoc 輔助函式」(保持不變數集中)、「不要 YOLO 式地猜資料結構」(驗證邊界或依賴類型化 SDK)。這些原則是具體的、機械的、可自動檢查的。-2. **建立週期性的清理流程**:一組背景 Codex 任務定期掃描偏差,更新品質評分,開針對性的重構 PR。大多數可以在一分鐘內審查並自動合併。就像宿舍安裝了自動掃地機器人——不用你動手,定期清理。-3. **人類品味捕獲一次,持續執行**:審查意見、重構 PR、使用者端 bug 都被轉化為文件更新或直接編碼到工具中。當文件不夠用時,把規則提升為程式碼。就像把宿舍公約從「口頭約定」變成「貼在門上的檢查表」。+1. **把「黃金原則」編碼進儲存庫**,比如「優先使用共享工具套件而非手寫的 ad-hoc 輔助函式」(保持不變數集中)、「不要 YOLO 式地猜資料結構」(驗證邊界或依賴類型化 SDK)。這些原則是具體的、機械的、可自動檢查的。+2. **建立週期性的清理流程**,一組背景 Codex 任務定期掃描偏差,更新品質評分,開針對性的重構 PR。大多數可以在一分鐘內審查並自動合併。自動化清理任務取代了手動定期大掃除,降低維護成本。+3. **人類品味捕獲一次,持續執行**,審查意見、重構 PR、使用者端 bug 都被轉化為文件更新或直接編碼到工具中。當文件不夠用時,把規則提升為程式碼。口頭約定固化為可執行的規則,使品味標準持續生效。-這個機制就像垃圾回收——技術債是高息貸款,持續小額還清幾乎總是比攢到一次性爆發好得多。+技術債的累積與清償遵循高息貸款邏輯,持續小額還清幾乎總是比攢到一次性爆發好得多。> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)## 清潔狀態:不只看地上有沒有垃圾-清潔狀態不是單一的「程式碼能編譯」。程式碼能無錯建構——這是最基本的,下一個工作階段不應該先修建構錯誤。就像你搬出去的時候水電不能是斷的。所有測試也得通過,包括工作階段之前就存在的測試——工作階段有責任不破壞已有功能。而且要在 CI 環境驗證,不是「在我機器上通過」。+清潔狀態不是單一的「程式碼能編譯」。程式碼能無錯建構——這是最基本的,下一個工作階段不應該先修建構錯誤。可建構是移交狀態的最低門檻,不可跳過。所有測試也得通過,包括工作階段之前就存在的測試,工作階段有責任不破壞已有功能。而且要在 CI 環境驗證,不是「在我機器上通過」。```mermaidflowchart LR@@ -45,7 +45,7 @@ flowchart LRFix --> Build```-但這還不夠。目前進度必須記錄在機器可讀的工件中——已完成的子任務和通過標準、進行中但未完成的子任務和目前狀態、尚未開始的子任務。好的進度記錄減少 60-80% 的工作階段啟動診斷時間。調試日誌、臨時檔案、註解掉的程式碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個工作階段的認知負擔。標準啟動路徑也必須可用——下一個工作階段能不能不人工干預就開始工作?環境初始化、程式碼庫載入、脈絡獲取、任務選擇,這些路徑不能被破壞。+但這還不夠。目前進度必須記錄在機器可讀的工件中,已完成的子任務和通過標準、進行中但未完成的子任務和目前狀態、尚未開始的子任務。好的進度記錄減少 60-80% 的工作階段啟動診斷時間。調試日誌、臨時檔案、註解掉的程式碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個工作階段的認知負擔。標準啟動路徑也必須可用,下一個工作階段能不能不人工干預就開始工作?環境初始化、程式碼庫載入、脈絡獲取、任務選擇,這些路徑不能被破壞。```mermaidflowchart LR@@ -62,17 +62,17 @@ flowchart LR## 核心概念- **清潔狀態**:工作階段結束時系統滿足五個條件——建構通過、測試通過、進度已記錄、無過時工件、啟動路徑可用。缺一個都不算「做完」。-- **工作階段完整性**:類比資料庫事務——要麼全部提交並留下清潔狀態,要麼回溯到上一致狀態。沒有中間地帶。-- **品質文件**:對每個模塊的品質等級做持續記錄的活躍工件。不是一次性評估,而是追蹤程式碼庫是變強了還是變弱了。-- **清理循環**:定期的維護工作階段,目標是系統性減少程式碼庫中的熵。不是緊急修復,而是常規運維——就像宿舍的每週值日表。+- **工作階段完整性**:類比資料庫事務,要麼全部提交並留下清潔狀態,要麼回溯到上一致狀態。沒有中間地帶。+- **品質文件**:對每個模塊的品質等級做持續記錄的活躍工件。持續追蹤程式碼庫是變強了還是變弱了。+- **清理循環**:定期的維護工作階段,目標是系統性減少程式碼庫中的熵。是常規運維,而非一次性緊急處置。- **harness 簡化**:隨著模型能力提升,定期移除不再必要的 harness 元件。今天必要的約束,三個月後可能是多餘的開銷。-- **冪等清理**:清理操作無論執行多少次都產生相同結果。確保清理在失敗重試場景中仍然安全。+- **冪等清理**:清理操作無論執行多少次都產生相同結果。使清理在失敗重試場景中保持安全。## "以後再清理"是永遠不清理-最常見的心理陷阱是「這次來不及清理了,下次再弄」。但下次的 agent 不知道你上次留下了什麼——它看到的是一堆混亂的程式碼和不確定的狀態。它會花大量時間推斷「這堆程式碼裡哪些是有意的,哪些是臨時的」。+最常見的心理陷阱是「這次來不及清理了,下次再弄」。但下次的 agent 不知道你上次留下了什麼,它看到的是一堆混亂的程式碼和不確定的狀態。它會花大量時間推斷「這堆程式碼裡哪些是有意的,哪些是臨時的」。-更糟的是,每個工作階段都有自己的任務目標。新工作階段來的時候是要做新功能的,不是來清理上一個工作階段的爛攤子的。它會忽略混亂直接開始新工作,然後在混亂的基礎上引入更多混亂。這是熵增的正回饋循環——就像宿舍越亂你越不想收拾,越不收拾越亂,最後誰都不想回宿舍了。+更糟的是,每個工作階段都有自己的任務目標。新工作階段來的時候是要做新功能的,不是來清理上一個工作階段的爛攤子的。它會忽略混亂直接開始新工作,然後在混亂的基礎上引入更多混亂。這是熵增的正回饋循環,混亂基礎上引入更多變更,使狀態愈發難以追蹤,形成自我強化的惡性循環。資料為證。一個使用 agent 持續開發 12 週的專案,沒有清潔策略的情況下:@@ -86,7 +86,7 @@ flowchart LR- 第 1 週:100%,100%,5 分鐘- 第 12 週:97%,95%,9 分鐘-12 週後,建構通過率差 29 個百分點,新工作階段啟動時間差 85%。這不是理論推導,是實際可觀測到的差異。每週不倒垃圾的宿舍和每週倒垃圾的宿舍,12 週後的差距是驚人的。+12 週後,建構通過率差 29 個百分點,新工作階段啟動時間差 85%。以上數據源自實際觀測,有明確的可重現紀錄。每週不倒垃圾的宿舍和每週倒垃圾的宿舍,12 週後的差距是驚人的。## 怎麼做@@ -107,13 +107,13 @@ flowchart LR結合兩種清理模式:-**即時清理(每個工作階段結束時)**:清理本次工作階段建立的臨時工件、更新功能清單狀態、確保建構和測試通過。這是「引用計數式」清理——用完就清。就像吃完飯馬上洗碗,不留到第二天。+**即時清理(每個工作階段結束時)**,清理本次工作階段建立的臨時工件、更新功能清單狀態、讓建構和測試通過。這是「引用計數式」清理,用完就清,避免積累。-**定期清理(每週一次)**:全系統掃描——處理累積的結構性問題、更新品質文件、執行基準測試檢測漂移。這是「追蹤式」清理——定期做一次大掃除。+**定期清理(每週一次)**,全系統掃描,處理累積的結構性問題、更新品質文件、執行基準測試檢測漂移。這是「追蹤式」清理,定期做一次大掃除。### 3. 維護質量文檔-質量文檔是對每個模塊持續評分的活躍工件——就像宿舍的衛生檢查評分表:+質量文檔持續追蹤每個模塊的品質等級:```markdown# 品質文件@@ -133,23 +133,23 @@ flowchart LR- 程式碼規範: 部分遵循```-新工作階段讀這個文件就知道優先處理哪裡。品質評分最低的模組先修。就像衛生檢查表上標記了「需要重點打掃的區域」——下一個值日生知道重點在哪裡。+新工作階段讀這個文件就知道優先處理哪裡。品質評分最低的模組先修。模組評分直接決定下一個工作階段的修復優先順序。### 4. 定期簡化 harness-harness 裡的每個元件之所以存在,是因為模型無法獨立做好某件事。但隨著模型改進,這些假設會過時。就像你大一的時候需要學長帶著選課,到了大三你自己就知道怎麼選了——學長的作用變小了,但有些事情你還是需要問。+harness 裡的每個元件之所以存在,是因為模型無法獨立做好某件事。但隨著模型改進,這些假設會過時。模型能力提升後,原本必要的 harness 元件可能變成多餘的開銷,而部分元件在特定任務難度下仍具價值。-Anthropic 的實驗直接展示了這一點。他們最初的 harness 包含 sprint 拆分機制——把工作分成小塊讓 Sonnet 4.5 逐個完成。當 Opus 4.6 發佈後,模型的原生能力已經可以自主處理工作分解,sprint 構造變成了不必要的開銷。移除後,builder agent 能連續工作超過兩小時而不會跑偏,反而更流暢。+Anthropic 的實驗直接展示了這一點。他們最初的 harness 包含 sprint 拆分機制,把工作分成小塊讓 Sonnet 4.5 逐個完成。當 Opus 4.6 發佈後,模型的原生能力已經可以自主處理工作分解,sprint 構造變成了不必要的開銷。移除後,builder agent 能連續工作超過兩小時而不會跑偏,反而更流暢。-但 evaluator 的情況不同。即使 Opus 4.6 能力更強,在任務接近模型能力邊界時,evaluator 仍然提供了實際價值——捕獲 generator 的遺漏功能和存根實現。這意味著 evaluator 不是一個固定的是/否決策,而是取決於任務難度相對於模型能力的位置。+但 evaluator 的情況不同。即使 Opus 4.6 能力更強,在任務接近模型能力邊界時,evaluator 仍然提供了實際價值,捕獲 generator 的遺漏功能和存根實現。這意味著 evaluator 的必要性取決於任務難度相對於模型能力的位置。-**推薦做法**:每月挑一個 harness 元件,暫時停用它,跑基準任務。如果結果沒退化,永久移除。如果退化了,恢復或用更輕量的替代。就像定期檢查宿舍公約——大四了還在執行「大一的宿舍公約」就不太合理了。+**推薦做法**,每月挑一個 harness 元件,暫時停用它,跑基準任務。如果結果沒退化,永久移除。如果退化了,恢復或用更輕量的替代。定期重新評估 harness 元件的必要性,隨模型能力演進移除已過時的約束。-一個更具體的原則:**隨著模型改進,harness 的有趣組合不是變少了,而是移動了。** 以前必須解決的問題被模型能力覆蓋了,但新的能力邊界打開了以前不可能的 harness 設計。AI 工程師的工作是持續找到下一個有價值的組合。+一個更具體的原則:**隨著模型改進,harness 的有趣組合移動了。** 以前必須解決的問題被模型能力覆蓋了,但新的能力邊界打開了以前不可能的 harness 設計。AI 工程師的工作是持續找到下一個有價值的組合。### 5. 清理操作必須冪等-清理腳本要能安全地重複執行——就像打掃衛生,掃兩遍比掃一遍更乾淨,但不會更髒:+清理腳本要能安全地重複執行,無論執行幾次都輸出相同結果:```bash# 冪等的清理操作@@ -160,27 +160,27 @@ npm run test # 驗證清理未破壞功能### 6. 高吞吐量改變了 merge 哲學-當 agent 的產出遠超人類審查能力時,傳統的 merge 哲學需要調整。OpenAI 團隊的經驗:在一個 agent 每天開 3.5 個 PR(且後來增加到更多)的環境裡,最小化阻塞式 merge gate 是正確的。PR 應該短命。測試 flake 通常用後續執行解決,而不是無限期阻塞進度。在一個修正成本很低、等待成本很高的系統裡,快速前進 + 快速修正是比緩慢確認更好的策略。+當 agent 的產出遠超人類審查能力時,傳統的 merge 哲學需要調整。OpenAI 團隊的經驗表明,在一個 agent 每天開 3.5 個 PR(且後來增加到更多)的環境裡,最小化阻塞式 merge gate 是正確的。PR 應該短命。測試 flake 通常用後續執行解決,而不是無限期阻塞進度。在一個修正成本很低、等待成本很高的系統裡,快速前進 + 快速修正是比緩慢確認更好的策略。-**注意**:這在低產出環境裡是不負責任的。但在 agent 產出遠超人類注意力的環境裡,這往往是正確的權衡。關鍵判斷標準:**修正一個 bug 的平均成本 vs 等待人類審查一個 PR 的平均成本。** 前者低於後者時,快速合併是對的。+**注意**,這在低產出環境裡是不負責任的。但在 agent 產出遠超人類注意力的環境裡,這通常是正確的權衡。關鍵判斷標準,**修正一個 bug 的平均成本 vs 等待人類審查一個 PR 的平均成本。** 前者低於後者時,快速合併是對的。## 實際案例一個使用 agent 持續開發的 Electron 應用,12 週演化過程的對比資料:-**無清潔策略(對照組)**——從不倒垃圾的宿舍:第 12 週,建構通過率 68%,測試通過率 61%,新工作階段啟動 60+ 分鐘,過時工件 103 個。+**無清潔策略(對照組)**,從不倒垃圾的宿舍,第 12 週,建構通過率 68%,測試通過率 61%,新工作階段啟動 60+ 分鐘,過時工件 103 個。-**有清潔策略(實驗組)**——每天值日的宿舍:每個工作階段結束時執行完整清潔檢查 + 每週清理循環。第 12 週,建構通過率 97%,測試通過率 95%,新工作階段啟動 9 分鐘,過時工件 11 個。+**有清潔策略(實驗組)**,每天值日的宿舍,每個工作階段結束時執行完整清潔檢查 + 每週清理循環。第 12 週,建構通過率 97%,測試通過率 95%,新工作階段啟動 9 分鐘,過時工件 11 個。到第 12 週,實驗組的建構通過率比對照組高 29 個百分點,測試通過率高 34 個百分點,新工作階段啟動時間減少 85%。每天多花 5 分鐘打掃衛生,12 週後省下了幾十個小時的混亂時間。## 關鍵要點-- **清潔狀態是工作階段完成的必要條件**——不是可選的善後工作,是「完成定義」的一部分。你不倒垃圾,下一個室友就得替你倒。-- **五個維度缺一不可**——建構、測試、進度、工件、啟動,每個都要顯式檢查。-- **品質文件讓程式碼庫健康可追蹤**——知道哪裡在退化才能主動修復。衛生檢查表不是形式主義,是讓你知道哪塊地還沒拖。-- **定期簡化 harness**——隨著模型能力提升,移除不再必要的約束。大四了就別執行大一的宿舍公約了。-- **「以後再清理」等於永遠不清理**——熵增是預設狀態,只有主動的清潔操作才能對抗它。+- **清潔狀態是工作階段完成的必要條件**,不是可選的善後工作,是「完成定義」的一部分。你不倒垃圾,下一個室友就得替你倒。+- **五個維度缺一不可**,建構、測試、進度、工件、啟動,每個都要顯式檢查。+- **品質文件讓程式碼庫健康可追蹤**,知道哪裡在退化才能主動修復。衛生檢查表不是形式主義,是讓你知道哪塊地還沒拖。+- **定期簡化 harness**,隨著模型能力提升,移除不再必要的約束。大四了就別執行大一的宿舍公約了。+- **「以後再清理」等於永遠不清理**,熵增是預設狀態,主動的清潔操作是對抗熵增的唯一途徑。## 延伸閱讀diff --git a/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.mdindex 5c296f9..d018a1a 100644--- a/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md+++ b/docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md@@ -20,7 +20,7 @@| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-01/starter) | 弱 harness 版本。只有 [`task-prompt.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/starter/task-prompt.md) 作為任務描述,沒有 `AGENTS.md` 或 `feature_list.json`。 | 把提示詞交給程式碼代理,衡量它在沒有額外結構時完成了什麼。 || [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-01/solution) | 相同的產品切片,但加入明確的 harness 產物:[`AGENTS.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/AGENTS.md)、[`CLAUDE.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/CLAUDE.md)、[`init.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/init.sh)、[`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/feature_list.json)、[`claude-progress.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/claude-progress.md)。 | 對照規則與驗證證據如何把同一任務變得可執行、可驗收。 |-四個具體功能是:視窗啟動、文件清單、問答面板、本地資料目錄建立。每個功能的預期證據請看 `solution/feature_list.json`。+四個具體功能是視窗啟動、文件清單、問答面板、本地資料目錄建立。每個功能的預期證據請看 `solution/feature_list.json`。## 用什麼工具diff --git a/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md b/docs/zh-TW/projects/project-02-agent-readable-workspace/index.mdindex 44b7953..a6d72f6 100644--- a/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md+++ b/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md@@ -7,7 +7,7 @@P01 證明了準備規則有用。但 P01 的任務一次工作階段就完成了。真實開發不是這樣的——你昨天做了一半,今天開啟新工作階段,代理得從儲存庫狀態中釐清「做了什麼、尚未完成什麼、接下來要做什麼」。-這個專案要求你為儲存庫加上「可讀性」:讓一個全新的代理開啟儲存庫後,能快速理解專案結構、知道目前進度、銜接上次的工作。具體任務是給知識庫應用加上三個功能:文件匯入、文件詳情頁面、匯入後的本地持久化。這些功能必須跨至少兩個代理工作階段完成。+這個專案要求你為儲存庫加上「可讀性」,讓一個全新的代理開啟儲存庫後,能快速理解專案結構、知道目前進度、銜接上次的工作。具體任務是給知識庫應用加上三個功能,包括文件匯入、文件詳情頁面、匯入後的本地持久化。這些功能必須跨至少兩個代理工作階段完成。你需要執行兩次。第一次不給代理任何幫助,看它在第二個工作階段裡要花多久才能「銜接上」。第二次提前放好 `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md`,讓它快速對齊脈絡。diff --git a/docs/zh-TW/projects/project-03-multi-session-continuity/index.md b/docs/zh-TW/projects/project-03-multi-session-continuity/index.mdindex 1f027ed..9cde1e3 100644--- a/docs/zh-TW/projects/project-03-multi-session-continuity/index.md+++ b/docs/zh-TW/projects/project-03-multi-session-continuity/index.md@@ -7,9 +7,9 @@P02 解決了「銜接」的問題,但代理銜接之後能否完整且正確地完成任務,則是另一回事。這個專案要你為代理加上範圍控制和驗證關卡。-你要實作的知識庫功能是:文件分塊、元資料提取、索引進度顯示、附引用的問答流程。這些功能比前兩個專案複雜,代理更容易偏離目標,可能多做了不在範圍內的事,或是宣稱完成卻未通過驗證。+你要實作的知識庫功能是文件分塊、元資料提取、索引進度顯示、附引用的問答流程。這些功能比前兩個專案複雜,代理更容易偏離目標,可能多做了不在範圍內的事,或是宣稱完成卻未通過驗證。-你需要一個 `feature_list.json`,每個功能有明確的狀態(failing / passing)。規則很簡單:一次只做一個功能,沒有可執行的驗證證據就不能標成 passing。執行兩次,一次不給這些約束,一次嚴格執行,觀察結果差距。+你需要一個 `feature_list.json`,每個功能有明確的狀態(failing / passing)。規則很簡單,一次只做一個功能,沒有可執行的驗證證據就不能標成 passing。執行兩次,一次不給這些約束,一次嚴格執行,觀察結果差距。## 使用倉庫內建專案diff --git a/docs/zh-TW/projects/project-04-incremental-indexing/index.md b/docs/zh-TW/projects/project-04-incremental-indexing/index.mdindex 5f5519f..4214c62 100644--- a/docs/zh-TW/projects/project-04-incremental-indexing/index.md+++ b/docs/zh-TW/projects/project-04-incremental-indexing/index.md@@ -7,9 +7,9 @@前三個專案關注的是「讓代理把任務做完」。這個專案關注的是「出了問題怎麼修」——而且不是你修,是讓代理自己透過執行時期訊號來修。-你要做兩件事。第一,給知識庫應用加上執行時期可觀測性:啟動日誌、匯入和索引的日誌、問答失敗時的使用者可見錯誤狀態。第二,在儲存庫中明確定義架構約束,讓代理不可能靜默地跨層違規(main / preload / renderer / services 之間的邊界)。+你要做兩件事。第一,給知識庫應用加上執行時期可觀測性,包括啟動日誌、匯入和索引的日誌、問答失敗時的使用者可見錯誤狀態。第二,在儲存庫中明確定義架構約束,讓代理不可能靜默地跨層違規(main / preload / renderer / services 之間的邊界)。-然後你會在程式碼裡植入一個執行時期 bug,讓代理去修。執行兩次:一次不給日誌和約束,觀察代理如何修正;一次給好日誌和架構規則,看差別。+然後你會在程式碼裡植入一個執行時期 bug,讓代理去修。執行兩次,一次不給日誌和約束,觀察代理如何修正;一次給好日誌和架構規則,看差別。## 使用倉庫內建專案diff --git a/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md b/docs/zh-TW/projects/project-05-grounded-qa-verification/index.mdindex e7e5b43..075bbe5 100644--- a/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md+++ b/docs/zh-TW/projects/project-05-grounded-qa-verification/index.md@@ -7,7 +7,7 @@前四個專案裡,「檢查做得對不對」這件事要麼是你手動做的,要麼是靠檔案規則強制執行的。這個專案要讓代理自行檢查。-方法是角色分離。以前是同一個代理既寫程式碼又判斷品質。現在拆開:一個代理負責實作(生成者),另一個代理負責審查(評估者)。更進一步,還可以加一個負責規劃的角色(規劃者)。你要執行三次,看每加一層角色分離,結果好多少。+方法是角色分離。以前是同一個代理既寫程式碼又判斷品質。現在拆開,生成者代理負責實作,評估者代理負責審查。更進一步,還可以加一個負責規劃的角色(規劃者)。你要執行三次,看每加一層角色分離,結果好多少。選一個實質性的功能升級(如多輪對話歷史、引用面板重新設計、文件集合與篩選),三次都做同一個升級,唯一變數是 harness 的角色分工。diff --git a/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md b/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.mdindex c6506d9..9d274b4 100644--- a/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md+++ b/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md@@ -7,7 +7,7 @@這是結業專案。把前五個專案學到的所有東西組裝起來,執行一次完整的基準測試,然後做一輪清理,驗證品質是可以持續維護的。-你要用一套固定的多功能任務集,涵蓋知識庫應用的完整產品切片:匯入文件、建構索引、附引用的問答、執行時期可觀測性、可讀可重啟的儲存庫狀態。先執行一次弱 harness 基線,再執行一次你組裝的最強 harness,然後做一輪清理和重新執行。最後還要做一次 harness 精簡實驗——刪掉一個組件,觀察結果是否變差,判斷哪些組件是真正有用的、哪些是多餘的開銷。+你要用一套固定的多功能任務集,涵蓋知識庫應用的完整產品切片,包括匯入文件、建構索引、附引用的問答、執行時期可觀測性、可讀可重啟的儲存庫狀態。先執行一次弱 harness 基線,再執行一次你組裝的最強 harness,然後做一輪清理和重新執行。最後還要做一次 harness 精簡實驗——刪掉一個組件,觀察結果是否變差,判斷哪些組件是真正有用的、哪些是多餘的開銷。## 使用倉庫內建專案diff --git a/docs/zh-TW/resources/index.md b/docs/zh-TW/resources/index.mdindex b2000ec..9e4fd26 100644--- a/docs/zh-TW/resources/index.md+++ b/docs/zh-TW/resources/index.md@@ -1,6 +1,6 @@# 繁體中文資源庫-這個資料夾把課程裡的方法整理成可以直接參考和複用的材料,不是再講一遍概念,而是盡量回答兩個問題:+這個資料夾把課程裡的方法整理成可以直接參考和複用的材料,重點回答兩個問題,而不是再講一遍概念:- 我現在應該先抄哪些檔案- 這些檔案分別解決什麼問題diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md b/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.mdindex f96d425..0274227 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md@@ -52,4 +52,4 @@2. 如果產品領域或架構層有明顯變化,更新 `docs/QUALITY_SCORE.md`。3. 如果有延期處理的債務,記到 `docs/exec-plans/tech-debt-tracker.md`。4. 已完成的計畫及時移到 `docs/exec-plans/completed/`。-5. 保證儲存庫可重啟,並留下清晰的下一步動作。+5. 保證儲存庫可重啟,並留下明確的下一步動作。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/FRONTEND.mdindex 4c03e69..e308ef5 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/FRONTEND.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/FRONTEND.md@@ -4,7 +4,7 @@## UI 原則-- 先保證清晰,再追求新鮮感。+- 先保證易懂,再追求新鮮感。- 互動流程要可發現、可重走、可重啟。- 優先沉澱少量可複用元件,而不是到處長一次性變體。- 無障礙檢查屬於正常驗證,不是最後的美化工作。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PLANS.mdindex fa5d5f7..9d682d6 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/PLANS.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PLANS.md@@ -28,7 +28,7 @@## 執行規則-- 一份 active plan 同一時間應該只有一個清晰的目前步驟。+- 一份 active plan 同一時間應該只有一個明確的目前步驟。- plan 要隨著工作推進而更新,不要把它當成靜態散文。- 只要某個決策改變了實現方向,就記到 plan 裡。- 已完成的計畫要移到 `completed/`,讓後續 agent 仍然能發現歷史脈絡。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/RELIABILITY.mdindex 1a4cf03..b7cd129 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/RELIABILITY.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/RELIABILITY.md@@ -22,7 +22,7 @@- `[journey 2]`- `[journey 3]`-每條黃金旅程都應該有可重複的驗證路徑和清晰的失敗信號。+每條黃金旅程都應該有可重複的驗證路徑和明確的失敗信號。## 可靠性規則diff --git a/docs/zh-TW/resources/openai-advanced/sops/index.md b/docs/zh-TW/resources/openai-advanced/sops/index.mdindex 1ccfe05..2e397e2 100644--- a/docs/zh-TW/resources/openai-advanced/sops/index.md+++ b/docs/zh-TW/resources/openai-advanced/sops/index.md@@ -20,4 +20,4 @@3. 把得到的規則編碼回 `repo-template/` 裡的文件。4. 把反覆出現的 review 評論升級成檢查、腳本或 guardrail。-這些 SOP 不是讓你機械照抄,而是為了讓 harness 更可讀、更可執行、更可複用。+這些 SOP 的目的是讓 harness 更可讀、更可執行、更可複用,供你直接參考、執行、改造,而非機械照抄。diff --git a/docs/zh-TW/resources/templates/AGENTS.md b/docs/zh-TW/resources/templates/AGENTS.mdindex f43a415..402d602 100644--- a/docs/zh-TW/resources/templates/AGENTS.md+++ b/docs/zh-TW/resources/templates/AGENTS.md@@ -1,6 +1,6 @@# AGENTS.md-這個儲存庫面向長時執行的 coding agent 工作流。目標不是儘可能快地產出程式碼,而是讓每一輪工作階段結束後,下一個工作階段仍然能無猜測地繼續工作。+這個儲存庫面向長時執行的 coding agent 工作流。目標是讓每一輪工作階段結束後,下一個工作階段仍然能無猜測地繼續工作,而不是儘可能快地產出程式碼。## 開工流程@@ -46,5 +46,5 @@1. 更新 `claude-progress.md`2. 更新 `feature_list.json`3. 記錄仍未解決的風險或 blocker-4. 在工作處於安全狀態後,用清晰的提交資訊提交+4. 在工作處於安全狀態後,用明確的提交資訊提交5. 保證下一輪工作階段可以直接執行 `./init.sh`diff --git a/docs/zh-TW/resources/templates/index.md b/docs/zh-TW/resources/templates/index.mdindex 7286845..8703e5e 100644--- a/docs/zh-TW/resources/templates/index.md+++ b/docs/zh-TW/resources/templates/index.md@@ -24,7 +24,7 @@- 複製到專案根目錄- 把開工流程裡的步驟換成你自己專案的路徑和命令- 工作規則按你們團隊的約定調整-- 完成定義那一段別改——那是整個 harness 最關鍵的部分+- 完成定義那一段別改,那是整個 harness 最關鍵的部分**它幫 agent 做什麼:**@@ -133,7 +133,7 @@ agent 任何時候只能有一個功能處於 `in_progress`。## clean-state-checklist.md-收尾檢查清單。每次工作階段結束前過一遍,確保儲存庫處於下一輪可以直接開工的狀態。+收尾檢查清單。每次工作階段結束前過一遍,讓儲存庫在下一輪可以直接開工。**怎麼用:**@@ -217,10 +217,10 @@ Evaluator rubric 評的是單次 agent 輸出的品質。Quality document 評的**和 harness 簡化的關係:**-Quality document 也可以用來驗證 harness 是否可以簡化。Harness 裡的每個元件都編碼了一個假設——"模型做不到這件事"。模型變強後,這些假設就過時了。檢查某個元件是否還有必要:+Quality document 也可以用來驗證 harness 是否可以簡化。Harness 裡的每個元件都編碼了一個假設,也就是「模型做不到這件事」。模型變強後,這些假設就過時了。檢查某個元件是否還有必要:1. 拍一份 quality document 快照。2. 移除一個 harness 元件。3. 跑基準測試。4. 再拍一份快照。-5. 對比——評級沒降,說明那個元件是多餘的。降了,就恢復。+5. 對比後,評級沒降,說明那個元件是多餘的。降了,就恢復。diff --git a/docs/zh-TW/skills/index.md b/docs/zh-TW/skills/index.mdindex b77d1ea..20c0e0f 100644--- a/docs/zh-TW/skills/index.md+++ b/docs/zh-TW/skills/index.md@@ -4,7 +4,7 @@## harness-creator-面向 AI 程式設計代理的生產級 harness 工程技能。幫助建立、評估和改進五個核心 harness 子系統:指令、狀態、驗證、範圍和工作階段生命週期。+面向 AI 程式設計代理的生產級 harness 工程技能。幫助建立、評估和改進五個核心 harness 子系統,涵蓋指令、狀態、驗證、範圍和工作階段生命週期。### 它能做什麼