Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
i18n(zh-TW): replace straight double-quotes with 「」 brackets
Jim Chene508f8f28524
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 478e663..fc3cbb6 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,9 +5,9 @@# 第一講. 模型能力強,不等於執行可靠-你說你也算見過世面的人了,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 描述和測試用例的任務。換到你日常開發的場景,需求模糊、沒有現成測試、隱含的業務規則散落在各處,這個數字只會更低。@@ -15,23 +15,23 @@## 同一匹馬,兩種命運-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 把寶貴的脈絡視窗花在了 `pip install` 失敗、Node 版本不對這些事上,而不是解決你的核心任務。就好比你讓一個木匠來幹活,結果錘子沒帶、釘子找不到、工作臺還是歪的,手藝再好也使不上勁。-更常見的問題是壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完程式碼,自己看了看覺得沒問題,就說完成了。讓學生交作業但不給答案檢查,結果是他自己覺得做對了,批改時卻一堆錯誤。Anthropic 還觀察到一個有意思的現象,當 agent 感覺脈絡快滿了,它們會匆忙結束目前工作,跳過驗證步驟,選一個簡單的方案而不是最優方案。他們把這叫"脈絡焦慮",跟你考試時發現時間快到了趕緊隨便選幾個選擇題是一回事。+更常見的問題是壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完程式碼,自己看了看覺得沒問題,就說完成了。讓學生交作業但不給答案檢查,結果是他自己覺得做對了,批改時卻一堆錯誤。Anthropic 還觀察到一個有意思的現象,當 agent 感覺脈絡快滿了,它們會匆忙結束目前工作,跳過驗證步驟,選一個簡單的方案而不是最優方案。他們把這叫「脈絡焦慮」,跟你考試時發現時間快到了趕緊隨便選幾個選擇題是一回事。長任務跨工作階段就更慘了,上次工作階段的發現全丟了,每個新工作階段都得重新探索專案結構、理解程式碼組織。缺乏持久化狀態的 agent 在超過 30 分鐘的任務中失敗率急劇上升。@@ -40,9 +40,9 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code理解了上面的場景,這些概念就不再是一堆術語了:- **能力鴻溝(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 就會自己編一個。@@ -52,9 +52,9 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code具體怎麼做。-**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問,是任務沒說清楚?是脈絡不夠?是沒有驗證手段?把每次失敗歸到五層防禦,任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。這裡說的是實操診斷用的五層防禦,不是上面那組六個術語。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。+**每次失敗都歸因到具體層。** 不要籠統地說「模型不行」,而是問,是任務沒說清楚?是脈絡不夠?是沒有驗證手段?把每次失敗歸到五層防禦,任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。這裡說的是實操診斷用的五層防禦,不是上面那組六個術語。養成這個習慣,你會發現「模型不行」這個結論在你的日誌裡出現得越來越少。-**給每個任務寫顯式的完成定義。** 不要說"加個搜索功能",要說:+**給每個任務寫顯式的完成定義。** 不要說「加個搜索功能」,要說:```完成標準:- 新增 GET /api/search?q=xxx 端點@@ -66,7 +66,7 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code**建立 AGENTS.md 檔案。** 在儲存庫根目錄放一個檔案,告訴 agent 這個專案的技術棧、架構約定、驗證命令。這是 harness 工程的第一步,也是投入產出比最高的一步。一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效,這不是誇張。-**建立診斷循環。** 不要把失敗當作"模型又犯傻了",而是當作"harness 又暴露了一個缺陷"的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來,你的 harness 會越來越強,agent 的表現會穩定提升。每修補一個缺陷,後續執行就更穩定。+**建立診斷循環。** 不要把失敗當作「模型又犯傻了」,而是當作「harness 又暴露了一個缺陷」的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來,你的 harness 會越來越強,agent 的表現會穩定提升。每修補一個缺陷,後續執行就更穩定。**量化改進。** 記個簡單的日誌,每個任務成功了沒有,失敗了是哪一層的問題。跑幾輪之後你就能看出來哪個層是瓶頸,集中火力修那個層。@@ -86,7 +86,7 @@ OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git一個團隊用 Claude Sonnet 給一箇中等規模的 Python Web 應用(FastAPI + PostgreSQL + Redis,約 15,000 行程式碼)添加新的 API 端點。-起初他們只給了一句話:"在 `/api/v2/users` 下添加使用者偏好設置端點"。結果呢?agent 花了 40% 的脈絡視窗探索儲存庫結構,產出了看似合理的程式碼但沒遵循專案的錯誤處理模式,用了舊版 SQLAlchemy 語法,宣稱完成但端點實際有執行時期錯誤。下一個工作階段還得重新做發現工作。+起初他們只給了一句話:「在 `/api/v2/users` 下添加使用者偏好設置端點」。結果呢?agent 花了 40% 的脈絡視窗探索儲存庫結構,產出了看似合理的程式碼但沒遵循專案的錯誤處理模式,用了舊版 SQLAlchemy 語法,宣稱完成但端點實際有執行時期錯誤。下一個工作階段還得重新做發現工作。後來他們加了 `AGENTS.md`(描述專案架構和技術棧版本)、顯式的驗證命令(`pytest tests/api/v2/ && python -m mypy src/`)、和架構決策記錄。同一模型在三次獨立執行中全部成功,脈絡使用效率提高了約 60%。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 2ae6f4d..ec0f7d1 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,17 +5,17 @@# 第二講. Harness 到底是什麼-"harness"這個詞在 AI coding agent 的圈子裡被用得越來越多了,但說實話,大部分人說的 harness 其實就只是"一個 prompt 檔案"。這不是 harness。你開了一家餐廳,只有食材,沒有灶臺、沒有刀具、沒有菜譜、沒有出菜流程,那不叫餐廳,那叫冰箱。+「harness」這個詞在 AI coding agent 的圈子裡被用得越來越多了,但說實話,大部分人說的 harness 其實就只是「一個 prompt 檔案」。這不是 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 文件則更側重狀態持久化、顯式恢復路徑和結構化的進度跟蹤。兩家公司的側重點不同,但都在說同一件事,**模型之外的一切工程基礎設施,決定了模型能力能被髮揮多少。**看看幾個你熟悉的工具。@@ -23,16 +23,16 @@ OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表**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 把儲存庫當作"記錄系統",所有必要的脈絡都必須在儲存庫裡,透過結構化的檔案和有序的目錄組織來呈現。+- **什麼是 harness**:模型權重之外的一切工程基礎設施。OpenAI 把工程師的核心工作概括為三件事:設計環境、表達意圖、建構回饋循環。Anthropic 直接把 Claude Agent SDK 稱為「通用 agent harness」。+- **儲存庫是唯一事實來源**:agent 看不到的東西,對它來說就不存在。OpenAI 把儲存庫當作「記錄系統」,所有必要的脈絡都必須在儲存庫裡,透過結構化的檔案和有序的目錄組織來呈現。- **給地圖,不給說明書**:OpenAI 的經驗,`AGENTS.md` 應該是目錄頁,不是百科全書。100 行左右就夠了,放不下就拆分到 `docs/` 目錄裡,讓 agent 按需去讀。-- **約束而非微操**:好的 harness 用可執行的規則來約束 agent,而不是在指令裡逐條叮囑。OpenAI 說"執行不變數,不要微管實現";Anthropic 發現 agent 會自信地誇讚自己的工作,解決方案是把"幹活的人"和"檢查的人"分開。+- **約束而非微操**:好的 harness 用可執行的規則來約束 agent,而不是在指令裡逐條叮囑。OpenAI 說「執行不變數,不要微管實現」;Anthropic 發現 agent 會自信地誇讚自己的工作,解決方案是把「幹活的人」和「檢查的人」分開。- **逐個組件拆除法**:想量化 harness 各組件的邊際貢獻,就逐個移除,看哪個移除後效能下降最多。它能告訴你哪些組件目前最有價值,也能暴露哪些組件暫時貢獻不明顯。Anthropic 用這個方法發現:隨著模型變強,某些組件不再關鍵,但總會有新的關鍵組件出現。## Harness 五子系統模型@@ -49,9 +49,9 @@ flowchart LRChecks --> Agent```-**指令子系統(菜譜架)**:建立 `AGENTS.md`(或 `CLAUDE.md`),內容包括專案概覽和目的(一句話說清楚這是什麼)、技術棧和版本(Python 3.11、FastAPI 0.100+、PostgreSQL 15)、首次執行命令(`make setup`、`make test`)、不可違反的硬約束("所有 API 必須走 OAuth 2.0")、指向更詳細文件的連結。+**指令子系統(菜譜架)**:建立 `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 讓環境可重現。@@ -106,4 +106,4 @@ flowchart LR2. **等模型對照下的組件價值實驗**:選一個模型和一個有挑戰性的任務。依次移除指令(刪掉 AGENTS.md)、移除回饋(不給驗證命令)、移除狀態(不提供進度檔案),每次只移除一個,測量效能下降幅度。基於結果,排出各子系統在目前任務裡的邊際價值;如果要找瓶頸,還必須同時記錄失敗日誌並做原因歸因。-3. **可供性分析**:找一個 agent 在你的專案中"想做但做不了"的場景(比如知道要用參數化查詢但不知道你專案的 ORM 怎麼寫)。分析這是執行鴻溝(不知道怎麼操作)還是評估鴻溝(不知道做得對不對),然後設計 harness 改進來彌補。+3. **可供性分析**:找一個 agent 在你的專案中「想做但做不了」的場景(比如知道要用參數化查詢但不知道你專案的 ORM 怎麼寫)。分析這是執行鴻溝(不知道怎麼操作)還是評估鴻溝(不知道做得對不對),然後設計 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 2fe4b94..2386600 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@@ -7,19 +7,19 @@你團隊的架構決策散落在 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 唯一穩定可訪問的存儲。-你可能會想:"我們團隊人少,知識都在大家腦子裡,這不也工作得好好的嗎?"沒錯,對人類來說確實可以。但你要用 agent,就得接受一個事實:agent 不能問人。所有它需要知道的東西,都必須寫下來,放在它能找到的地方。+你可能會想:「我們團隊人少,知識都在大家腦子裡,這不也工作得好好的嗎?」沒錯,對人類來說確實可以。但你要用 agent,就得接受一個事實:agent 不能問人。所有它需要知道的東西,都必須寫下來,放在它能找到的地方。-這不是"寫更多文件"的問題。這是"把決策資訊放到正確的位置"的問題。一份在 `src/api/` 目錄下、50 行的 `ARCHITECTURE.md`,比一份在 Confluence 裡、500 頁但沒人維護的設計文件有用一萬倍。就好比一張貼在你工位上的、手畫的辦公室走法圖,比一份精美的、放在檔案室裡的建築藍圖實用得多,因為前者在你需要的時候就在手邊。+這不是「寫更多文件」的問題。這是「把決策資訊放到正確的位置」的問題。一份在 `src/api/` 目錄下、50 行的 `ARCHITECTURE.md`,比一份在 Confluence 裡、500 頁但沒人維護的設計文件有用一萬倍。就好比一張貼在你工位上的、手畫的辦公室走法圖,比一份精美的、放在檔案室裡的建築藍圖實用得多,因為前者在你需要的時候就在手邊。## 知識可見性@@ -66,7 +66,7 @@ flowchart TB**原則 1:知識靠近程式碼。** 一條關於 API 端點認證的規則,應該放在 API 程式碼旁邊,而不是藏在一個巨大的全域文件裡。每個模組目錄下放一個簡短的文件,說清楚這個模組的職責、介面和特殊約束。圖書館按主題分類書架,找歷史類書籍直接去歷史書架,不用翻遍整個圖書館。-**原則 2:用標準化的入口檔案。** `AGENTS.md`(或 `CLAUDE.md`)是 agent 的"著陸頁"。它不需要包含所有資訊,但必須能讓 agent 快速回答"這是什麼專案"、"怎麼跑"、"怎麼驗證"這三個問題。50-100 行就夠了。+**原則 2:用標準化的入口檔案。** `AGENTS.md`(或 `CLAUDE.md`)是 agent 的「著陸頁」。它不需要包含所有資訊,但必須能讓 agent 快速回答「這是什麼專案」、「怎麼跑」、「怎麼驗證」這三個問題。50-100 行就夠了。**原則 3:最小但完備。** 每條知識都應該有明確的使用場景。如果你刪掉某條規則不影響 agent 的決策質量,那這條規則就不應該存在。但冷啟動測試中的每個問題都必須有答案。這是一個精妙的平衡,不多不少,剛好夠用。@@ -93,8 +93,8 @@ project/這個類比來自數據庫的事務管理,你可能覺得這是在把簡單的事情搞複雜,但實際上它給了你一個非常實用的框架。-- **原子性**:每次"邏輯操作"(比如"添加新端點並更新測試")用一個 git commit 原子化。中途掛了就 `git stash` 回溯。要麼全做,要麼不做,沒有"做了一半"。-- **一致性**:定義"一致狀態"的驗證謂詞,所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。銀行轉賬不能只扣款不入賬。+- **原子性**:每次「邏輯操作」(比如「添加新端點並更新測試」)用一個 git commit 原子化。中途掛了就 `git stash` 回溯。要麼全做,要麼不做,沒有「做了一半」。+- **一致性**:定義「一致狀態」的驗證謂詞,所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。銀行轉賬不能只扣款不入賬。- **隔離性**:多個 agent 併發工作時,狀態檔案要避免競爭條件。簡單方案:每個 agent 用獨立的進度檔案,或者用 git 分支隔離。兩個廚師不能同時往同一口鍋裡放鹽,放重了誰負責?- **持久性**:關鍵的專案知識用 git 跟蹤的檔案持久化。臨時狀態可以只在工作階段的記憶體中,但跨工作階段必須的知識必須寫到檔案裡。腦子裡的不算,寫在紙上的才算。@@ -102,12 +102,12 @@ project/一個團隊維護一個包含約 30 個微服務的電商平臺。架構決策(服務間通信協定、數據一致性策略、API 版本化規則)散落在:Confluence(部分過時)、Slack(難以搜索)、幾個資深工程師的腦子裡(不可擴展)、以及零星的程式碼註釋(不繫統)。-引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個"所有人都知道但從未寫入儲存庫"的隱性約束。新員工不知道「中午點外賣要在群裡接龍」的規矩,只能猜;猜錯了被罵,被罵了也還是沒人明說。+引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個「所有人都知道但從未寫入儲存庫」的隱性約束。新員工不知道「中午點外賣要在群裡接龍」的規矩,只能猜;猜錯了被罵,被罵了也還是沒人明說。團隊執行了改造:1. 儲存庫根目錄建立 `AGENTS.md`,寫明專案概覽、技術棧版本、全域硬約束2. 每個微服務目錄下添加 `ARCHITECTURE.md`,描述該服務的職責、介面和依賴-3. 建立集中的 `CONSTRAINTS.md`,用"禁止/必須"的明確語言記錄硬約束+3. 建立集中的 `CONSTRAINTS.md`,用「禁止/必須」的明確語言記錄硬約束4. 每個服務目錄添加 `PROGRESS.md`,記錄目前工作狀態改造後:同一 agent 能在冷啟動時回答所有關鍵專案問題,任務完成質量顯著提升。@@ -115,7 +115,7 @@ project/## 關鍵要點- 不在儲存庫裡的知識對 agent 來說等於不存在。把關鍵決策資訊放進儲存庫是最基本的 harness 投資,畫好地圖,才不會迷路。-- 用"冷啟動測試"檢驗儲存庫質量:全新工作階段能不能只看儲存庫回答五個基本問題。+- 用「冷啟動測試」檢驗儲存庫質量:全新工作階段能不能只看儲存庫回答五個基本問題。- 知識要靠近程式碼、最小但完備、跟程式碼一起更新。不是寫更多文件,是把資訊放到正確的位置。- 用 ACID 原則管理 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 840c293..a335613 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@@ -7,23 +7,23 @@你開始認真對待 harness 了,好事。你建了個 `AGENTS.md`,把你能想到的所有規則、約束、歷史教訓都塞了進去。一個月後這個檔案膨脹到了 300 行,兩個月 450 行,三個月 600 行。然後你發現 agent 的表現反而變差了,改一個小 bug,agent 花大量脈絡處理無關的部署指令;關鍵的安全約束埋在第 300 行,被直接忽略了;檔案裡有三條互相矛盾的程式碼風格規則,agent 每次隨機選一條。-這就是"巨型指令檔案"陷阱。什麼都往裡寫、覺得都有用,最後檔案膨脹,想找一條關鍵規則就得把整份文件翻一遍;agent 真正用到的可能只有三分之一。+這就是「巨型指令檔案」陷阱。什麼都往裡寫、覺得都有用,最後檔案膨脹,想找一條關鍵規則就得把整份文件翻一遍;agent 真正用到的可能只有三分之一。## 問題的根源:一個惡性循環-最常見的惡性循環是這樣,agent 犯了個錯 → 你說"加條規則防止這個" → 加到 AGENTS.md → 暫時管用 → agent 又犯了另一個錯 → 再加一條 → 重複 → 檔案膨脹到不可控。+最常見的惡性循環是這樣,agent 犯了個錯 → 你說「加條規則防止這個」 → 加到 AGENTS.md → 暫時管用 → agent 又犯了另一個錯 → 再加一條 → 重複 → 檔案膨脹到不可控。-這不是你的錯。這是一個非常自然的反應,每次出問題就"加條規則"感覺很合理,但累積效應是災難性的。讓我們看看具體出了什麼問題。+這不是你的錯。這是一個非常自然的反應,每次出問題就「加條規則」感覺很合理,但累積效應是災難性的。讓我們看看具體出了什麼問題。**脈絡預算被吃掉了。** 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 每次隨機選一條遵循。Agent 每次碰到矛盾指令只能隨機選一條遵循。+**矛盾累積。** 不同時期加的指令之間開始出現矛盾,一條說「用 TypeScript 嚴格模式」,另一條說「某些遺留檔案允許用 any」。Agent 每次隨機選一條遵循。Agent 每次碰到矛盾指令只能隨機選一條遵循。## 核心概念@@ -87,17 +87,17 @@ Python 3.11 FastAPI 後端,PostgreSQL 15 資料庫。還有些資訊直接放在程式碼裡更合適,類型定義、介面註釋、配置檔案裡的說明。Agent 讀程式碼的時候自然能看到,不用再在指令裡重複一遍。-每條指令都應該標明來源("為什麼加這條規則?")、適用條件("這條規則在什麼時候需要?")、過期條件("什麼情況下可以刪掉這條規則?")。定期審計,刪掉過時的、冗餘的、矛盾的條目。像管理程式碼依賴一樣管理你的指令,用不上的依賴就該刪掉,不然它們只會拖慢系統。+每條指令都應該標明來源(「為什麼加這條規則?」)、適用條件(「這條規則在什麼時候需要?」)、過期條件(「什麼情況下可以刪掉這條規則?」)。定期審計,刪掉過時的、冗餘的、矛盾的條目。像管理程式碼依賴一樣管理你的指令,用不上的依賴就該刪掉,不然它們只會拖慢系統。-如果某條指令必須在入口檔案裡,放頂部或底部,不要放中間。"中間迷失"效應告訴我們,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。但更好的做法是把指令放到專題文件裡,讓 agent 按需加載。+如果某條指令必須在入口檔案裡,放頂部或底部,不要放中間。「中間迷失」效應告訴我們,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。但更好的做法是把指令放到專題文件裡,讓 agent 按需加載。-OpenAI 和 Anthropic 都隱性支援拆分的做法。OpenAI 說入口檔案應"短小且以路由為導向",Anthropic 說長執行 agent 的控制資訊應"簡潔且高優先級"。兩家都在說同一件事,別把什麼都塞進一個檔案裡。指令系統得整理,不能只靠不斷追加。+OpenAI 和 Anthropic 都隱性支援拆分的做法。OpenAI 說入口檔案應「短小且以路由為導向」,Anthropic 說長執行 agent 的控制資訊應「簡潔且高優先級」。兩家都在說同一件事,別把什麼都塞進一個檔案裡。指令系統得整理,不能只靠不斷追加。## 實際案例一個 SaaS 團隊的 `AGENTS.md` 從最初的 50 行膨脹到 600 行。內容混合了技術棧版本、編碼規範、歷史 bug 修復筆記、API 使用說明、部署流程、和團隊成員的個人偏好,整份文件塞得滿滿當當,完全失去可維護性。-Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量脈絡處理無關的部署指令;安全約束"所有數據庫查詢必須用參數化查詢"埋在第 300 行,經常被忽略;三條矛盾的程式碼風格規則導致 agent 隨機選擇。+Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量脈絡處理無關的部署指令;安全約束「所有數據庫查詢必須用參數化查詢」埋在第 300 行,經常被忽略;三條矛盾的程式碼風格規則導致 agent 隨機選擇。團隊執行了文件重組:1. `AGENTS.md` 裁剪到 80 行:只保留專案概覽、執行命令、15 條全域硬約束@@ -105,13 +105,13 @@ Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量脈3. 路由檔案添加指向專題文件的連結4. 歷史筆記要麼轉成測試用例,要麼刪除-重構後:同一任務集的成功率從 45% 提升到 72%。安全約束遵循率從 60% 提升到 95%,因為從檔案中間移到了路由檔案頂部,不再被"中間迷失"了。+重構後:同一任務集的成功率從 45% 提升到 72%。安全約束遵循率從 60% 提升到 95%,因為從檔案中間移到了路由檔案頂部,不再被「中間迷失」了。## 關鍵要點-- "加條規則"是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文件是不是更合適?,別把所有規則都堆進入口文件。+- 「加條規則」是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文件是不是更合適?,別把所有規則都堆進入口文件。- 入口檔案是路由器,不是百科全書。50-200 行,只放概覽、硬約束、和連結。-- 利用"中間迷失"效應:重要資訊放檔案頂部或底部,不重要的移到專題文件。+- 利用「中間迷失」效應:重要資訊放檔案頂部或底部,不重要的移到專題文件。- 像管理技術債一樣管理指令膨脹。定期審計,每條指令要有來源、適用條件、和過期條件。- 拆分之後信噪比提升,agent 把更多脈絡預算花在實際任務上,而不是處理無關指令。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 d83549a..1a67169 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@@ -9,15 +9,15 @@想象一下,如果你是一個工匠,每天早上醒來都不記得昨天幹了什麼。你得重新認識整個工地,哪面牆砌了一半、為什麼用的是紅磚而不是青磚、水電管道走到哪了。更糟的是,你可能會把昨天已經裝好的窗戶拆了重來,因為你不記得它已經裝過了。-這就是 AI coding agent 在跨工作階段任務中面對的困境。本節課講為什麼 agent 會"斷片",以及如何透過結構化的狀態持久化讓它像一個每天堅持寫日記的工匠,雖然還是會失憶,但日記本裡記著一切。+這就是 AI coding agent 在跨工作階段任務中面對的困境。本節課講為什麼 agent 會「斷片」,以及如何透過結構化的狀態持久化讓它像一個每天堅持寫日記的工匠,雖然還是會失憶,但日記本裡記著一切。## 脈絡視窗:不是無限的脈絡視窗是有限的。這不是一個可以通過模型升級解決的問題,即使視窗大小增長到 1M tokens,複雜任務依然會用完。因為 agent 不只是在生成程式碼,它還要理解程式碼庫、跟蹤自己的決策歷史、處理工具輸出、維護對話脈絡。這些資訊加起來增長得比視窗擴容快得多。-更深層的問題在於,agent 產生的資訊不是均勻重要的。中間推理步驟包含決策的"為什麼",為什麼選了方案 A 而不是方案 B,為什麼用了這個庫而不是那個庫,為什麼跳過了某個最佳化。最終輸出只包含"是什麼",程式碼本身。壓縮策略通常保留後者但丟了前者。下一個工作階段看到程式碼但不知道為什麼這麼寫,可能會"最佳化"掉一個有意為之的設計決策。+更深層的問題在於,agent 產生的資訊不是均勻重要的。中間推理步驟包含決策的「為什麼」,為什麼選了方案 A 而不是方案 B,為什麼用了這個庫而不是那個庫,為什麼跳過了某個最佳化。最終輸出只包含「是什麼」,程式碼本身。壓縮策略通常保留後者但丟了前者。下一個工作階段看到程式碼但不知道為什麼這麼寫,可能會「最佳化」掉一個有意為之的設計決策。-Anthropic 在他們的長執行 agent 研究中發現了一個很有意思的現象:當 agent 感覺脈絡快滿了,它們會表現出一種"過早收斂"的行為,匆忙結束目前工作,跳過驗證步驟,或者選一個簡單的方案而不是最優方案。Anthropic 把這叫「脈絡焦慮」(Context Anxiety)。+Anthropic 在他們的長執行 agent 研究中發現了一個很有意思的現象:當 agent 感覺脈絡快滿了,它們會表現出一種「過早收斂」的行為,匆忙結束目前工作,跳過驗證步驟,或者選一個簡單的方案而不是最優方案。Anthropic 把這叫「脈絡焦慮」(Context Anxiety)。## 工作階段連續性流程@@ -55,7 +55,7 @@ flowchart LR- **重建成本**:新工作階段恢復到可執行狀態所需的時間。好的 harness 能把重建成本從 15 分鐘壓到 3 分鐘。- **漂移(Drift)**:agent 的理解跟程式碼儲存庫實際狀態之間的偏差。每次工作階段邊界都會引入漂移,不加控制會越漂越遠。- **脈絡焦慮**:Anthropic 觀察到的現象,agent 在接近脈絡限制時表現異常,過早結束任務以避免資訊遺失。是一種非理性的資源焦慮。-- **壓縮 vs 重置**:壓縮是在同一個工作階段裡把脈絡摘要化(保留"是什麼",可能丟了"為什麼");重置是開新工作階段從持久化狀態重建(乾淨但依賴工件完備性)。+- **壓縮 vs 重置**:壓縮是在同一個工作階段裡把脈絡摘要化(保留「是什麼」,可能丟了「為什麼」);重置是開新工作階段從持久化狀態重建(乾淨但依賴工件完備性)。## 連續性斷了以後會發生什麼@@ -67,11 +67,11 @@ flowchart LR還有驗證缺口。上個工作階段的驗證結果(哪些測試通過、哪些失敗、為什麼失敗)沒有記錄,新工作階段得重新跑一遍驗證才能瞭解目前狀態。每次都重新診斷,每次都浪費寶貴的脈絡。-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)**。這是最基本的連續性工件,日記本的核心部分:@@ -101,7 +101,7 @@ OpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化3. 更新 API 文件```-**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文件,只需要"什麼決策、為什麼、什麼時候做的",這是日記本裡的備忘:+**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文件,只需要「什麼決策、為什麼、什麼時候做的」,這是日記本裡的備忘:```markdown# 設計决策@@ -114,7 +114,7 @@ OpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化**工具 3:git 提交作為檢查點。** 每完成一個原子工作單元就提交。commit message 要說清楚做了什麼和為什麼。這是免費的、自動版本化的狀態快照。-**工具 4:init.sh 或 harness 的初始化流程。** 在 `AGENTS.md` 裡寫明每天"上班"和"下班"的流程:+**工具 4:init.sh 或 harness 的初始化流程。** 在 `AGENTS.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 設計需要對目標模型有具體的理解,而不是套用通用範本。**@@ -159,7 +159,7 @@ Anthropic 的實際數據:對於 Sonnet 4.5,脈絡焦慮足夠嚴重,以- 脈絡視窗是有限的資源。長任務一定會跨工作階段,跨工作階段一定會丟資訊,跨工作階段一定會丟資訊,這是客觀現實。- 解決方案在於更好的狀態持久化,而非更大的視窗。進度檔案 + 決策日誌 + git 檢查點,讓每個工作階段都能從可靠的記錄起步。-- 把 agent 當成會失憶的工程師來管理:每次"下班"前寫清楚做了什麼、為什麼、下一步做什麼。+- 把 agent 當成會失憶的工程師來管理:每次「下班」前寫清楚做了什麼、為什麼、下一步做什麼。- 重建成本是關鍵指標。好的 harness 應該讓新工作階段在 3 分鐘內恢復到可執行狀態。- 混合策略:短任務在工作階段內完成,長任務用結構化工件維持連續性。@@ -173,7 +173,7 @@ Anthropic 的實際數據:對於 Sonnet 4.5,脈絡焦慮足夠嚴重,以## 練習-1. **連續性損耗度量**:選一個需要至少 3 個工作階段的開發任務。不提供任何連續性工件,在每個工作階段開始時記錄 agent 花了多少脈絡來"搞清楚上次做了什麼"。工作階段結束後,建立進度檔案,讓下一個工作階段從進度檔案開始。對比有進度檔案和沒有時的重建成本。+1. **連續性損耗度量**:選一個需要至少 3 個工作階段的開發任務。不提供任何連續性工件,在每個工作階段開始時記錄 agent 花了多少脈絡來「搞清楚上次做了什麼」。工作階段結束後,建立進度檔案,讓下一個工作階段從進度檔案開始。對比有進度檔案和沒有時的重建成本。2. **交接範本設計**:設計一個最小化的交接範本,包含四個字段:儲存庫狀態(commit hash)、執行時期狀態(測試通過率)、阻塞項、下一步行動。讓一個全新的 agent 工作階段只憑這個範本恢復專案狀態,記錄恢復過程中出現的歧義點,迭代改進範本。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 c5be7cb..25f858e 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,7 +5,7 @@# 第六講. 讓 agent 每次工作前先初始化-你開了一個新的 agent 工作階段,讓它"幫我加個搜索功能"。它上來就開始改程式碼,精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現數據庫遷移腳本格式不對,又折騰了一會兒。最後搜索功能倒是加了,但整個工作階段的效率很低,大部分時間花在了"搞清楚這個專案怎麼運作"上,而不是寫搜索功能。+你開了一個新的 agent 工作階段,讓它「幫我加個搜索功能」。它上來就開始改程式碼,精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現數據庫遷移腳本格式不對,又折騰了一會兒。最後搜索功能倒是加了,但整個工作階段的效率很低,大部分時間花在了「搞清楚這個專案怎麼運作」上,而不是寫搜索功能。更好的做法是在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、專案結構搞清楚。蓋房子必須先打地基,地基幹了再砌牆;若同時進行,牆砌到一半地基未固,整棟樓都得推倒重來。@@ -39,7 +39,7 @@ flowchart TB最直接的問題:基礎設施不紮實。Agent 花了 80% 的精力寫功能程式碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了,新 agent 不知道專案怎麼跑、怎麼測、做到哪了。基礎薄弱,後患無窮。-更隱蔽的代價是"未驗證的累積",在測試框架配好之前寫的功能程式碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實作。等回頭補測試時才發現設計有問題,要重構才能讓測試通過。+更隱蔽的代價是「未驗證的累積」,在測試框架配好之前寫的功能程式碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實作。等回頭補測試時才發現設計有問題,要重構才能讓測試通過。脈絡預算也在被浪費。初始化工作(配環境、配測試、理解專案結構)消耗了大量預算,留給實際功能實作的反而不夠了。結果第一個工作階段只完成了一半的功能,第二個工作階段還得從頭理解專案。預算花在了打地基上,但地基也沒打好,兩頭都沒佔著。@@ -47,14 +47,14 @@ flowchart TBAnthropic 在他們的長執行應用開發研究中明確建議把初始化和實作分離。他們的實驗數據顯示,使用獨立初始化階段的專案,多工作階段場景中的功能完成率比混合方式高 31%。關鍵是,初始化階段投入的時間在後續 3-4 個工作階段中就能完全收回。地基打得越紮實,上面的樓蓋得越快。-OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄"的原則,第一次執行就要建立有效的操作結構,否則每次新工作階段都得重新推斷專案約定。+OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記錄」的原則,第一次執行就要建立有效的操作結構,否則每次新工作階段都得重新推斷專案約定。## 核心概念- **初始化階段**:agent 生命週期中的第一個階段,不做功能實作,只建立後續所有實作階段的執行前提。輸出的是基礎設施,不是功能程式碼。- **自舉契約**:一個專案能被全新 agent 工作階段無歧義操作的條件,能啟動、能測試、能看進度、能接手下一步。四個條件缺一不可。- **冷啟動 vs 熱啟動**:冷啟動是從空目錄開始,agent 要猜專案結構;熱啟動是從範本或已有專案開始,基礎設施已經就位。熱啟動的效果遠好於冷啟動,從有基礎設施的工地開工,效率遠高於在空地從零搭建。-- **交接就緒性**:專案在任何時刻都處於"可以被全新 agent 接手"的狀態。不需要口頭解釋,只看儲存庫內容就能接著幹。+- **交接就緒性**:專案在任何時刻都處於「可以被全新 agent 接手」的狀態。不需要口頭解釋,只看儲存庫內容就能接著幹。- **首次驗證時間**:從專案開始到第一個功能點通過驗證的時間。這是衡量初始化效率的核心指標。- **下游可用性**:初始化質量的最佳衡量標準,後續工作階段不需要依賴隱式知識就能成功執行任務的比例。@@ -136,7 +136,7 @@ OpenAI 的 Codex harness engineering 指南也強調"儲存庫作為操作記錄- 初始化和實作的最佳化目標不同,混在一起只會互相拖後腿。先打地基,再砌牆。- 初始化的產出不是程式碼,是基礎設施:可執行的環境、可驗證的測試、自舉契約、任務分解。-- 用"自舉契約"的四個條件驗收初始化:能啟動、能測試、能看進度、能接手下一步。+- 用「自舉契約」的四個條件驗收初始化:能啟動、能測試、能看進度、能接手下一步。- 熱啟動優於冷啟動。用專案範本預置標準化的基礎設施。- 初始化投入的時間會在後續 3-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 993d50b..150d5ce 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,9 +7,9 @@你讓 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 裡給它劃清邊界。## 注意力是有限的資源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 3e17875..63d4275 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@@ -11,7 +11,7 @@Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須是儲存庫裡機器可讀的檔案,不能是對話裡的非結構化描述。-## Agent 不知道"做完"是什麼意思+## Agent 不知道「做完」是什麼意思Claude Code 和 Codex 都不會自動知道你心目中的「做完」是什麼意思。你說「加一個購物車功能」,模型的理解可能是「寫一個 Cart 元件和 addToCart 方法」。而你的意思是「使用者能從瀏覽商品到下單支付完整走通」。@@ -61,7 +61,7 @@ flowchart LR- **單一權威來源**:專案裡關於「該做什麼」的所有資訊,必須從一個功能清單派生。不能出現功能清單和對話記錄矛盾的情況。- **反向壓力**:還沒通過的功能項數量就是 harness 對 agent 施加的壓力。壓力歸零 = 專案完成。-## 為什麼功能清單必須是"原語"+## 為什麼功能清單必須是「原語」文件是給人看的,原語是給系統用的。文件可以被忽略,原語不能被繞過。@@ -129,7 +129,7 @@ agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harn## 延伸閱讀- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 明確指出功能清單是控制 agent 執行範圍的「核心資料結構」-- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 強調"將工件外部化"的原則+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 強調「將工件外部化」的原則- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — 契約式設計原則,功能列表的理論基礎- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — 測試金字塔和行為規格的工程實踐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 6fefe5b..20d5c67 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@@ -53,7 +53,7 @@ flowchart LR**環境依賴性**,程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。測試環境的完全隔離設計決定了它無法反映真實部署環境中的配置差異與外部依賴狀態。-### "順便重構"是完成判定的毒藥+### 「順便重構」是完成判定的毒藥Claude Code 有一個常見行為模式,在核心功能還沒驗證通過時就開始重構程式碼、最佳化效能、改進風格。Knuth 說的「過早最佳化是萬惡之源」在 agent 場景中有了新含義,重構會改變已完成驗證和未完成驗證之間的邊界,可能破壞之前隱式正確的程式碼路徑。重構在核心功能未確立前進行,既模糊了驗證邊界,也在新的變更集中引入了額外的偵錯負擔。@@ -65,14 +65,14 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**解決方案不是讓 agent「更客觀」,同一個模型既生成又評估,內在地傾向對自己慷慨。**解決方案是把「幹活的人」和「檢查的人」分開。** 將評估職責交給獨立的 agent,評估者不受生成者的置信度影響,能更客觀地判定任務是否實際完成。-一個獨立的評估 agent,經過專門調校為"挑剔"之後,比讓生成 agent 自我評估有效得多。Anthropic 的實驗數據:+一個獨立的評估 agent,經過專門調校為「挑剔」之後,比讓生成 agent 自我評估有效得多。Anthropic 的實驗數據:| 架構 | 執行時期長 | 成本 | 核心功能是否可用 ||------|---------|------|---------------|| 單 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)@@ -99,9 +99,9 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**- **第二層:執行時期行為驗證**。測試執行、應用啟動檢查、關鍵路徑驗證。這是核心完成證據。不僅要寫了,還要能跑。- **第三層:系統級確認**。端到端測試、整合驗證、使用者場景模擬。防止過早聲明的最後一道防線。不僅要能跑,還要跑對。-### 3. 為 agent 設計好的"紅筆批註"+### 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. 捕獲執行時期信號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 fec381e..a29f4f3 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@@ -7,7 +7,7 @@你讓 agent 給 Electron 應用加一個檔案匯出功能。它寫了渲染程式元件、預載腳本、服務層邏輯,每個元件的單元測試都通過了。agent 說「做完了」。你實際一點擊匯出按鈕,檔案路徑格式不對、進度列沒反應、大檔案匯出時記憶體洩漏。5 個元件邊界缺陷,單元測試一個都沒發現。-這就像一個合唱團排練——每個聲部單獨唱的時候都完美,但合在一起的時候,女高音比男低音快了半拍,伴奏的調子和主旋律差了半個音。每個部分都"對"了,但整體跑調了。+這就像一個合唱團排練——每個聲部單獨唱的時候都完美,但合在一起的時候,女高音比男低音快了半拍,伴奏的調子和主旋律差了半個音。每個部分都「對」了,但整體跑調了。Google 的測試金字塔告訴我們:大量單元測試是基礎,但如果你止步於此,就會持續漏掉元件互動問題。對於 AI 程式碼代理來說,這個問題更嚴重,agent 傾向於只跑最快的測試然後宣告完成。**只有端到端測試能證明系統級缺陷不存在**。@@ -57,7 +57,7 @@ flowchart LRHarness --> Stronger["以後再犯會第一時間報錯"]```-OpenAI 在 Codex 工程實踐中強調:**為 agent 寫的錯誤訊息必須包含修復指導**。不寫 `"Direct filesystem access in renderer"`,而寫 `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` 這把架構規則變成了自動修正的閉環。就像合唱排練時指揮不只說「你唱錯了」,而是說「這裡你快了半拍,聽一下女低音的節奏,在第 32 小節進入」。+OpenAI 在 Codex 工程實踐中強調:**為 agent 寫的錯誤訊息必須包含修復指導**。不寫 `「Direct filesystem access in renderer」`,而寫 `「Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api.」` 這把架構規則變成了自動修正的閉環。就像合唱排練時指揮不只說「你唱錯了」,而是說「這裡你快了半拍,聽一下女低音的節奏,在第 32 小節進入」。## 核心概念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 a680c9c..6d0a827 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@@ -35,7 +35,7 @@ harness 沒有給 agent 裝上所需的儀表盤,才導致這種困境。想## 雙層可觀測性-可觀測性不是"多打點日誌"那麼簡單。它分兩層,缺一不可:+可觀測性不是「多打點日誌」那麼簡單。它分兩層,缺一不可:```mermaidflowchart LR@@ -62,7 +62,7 @@ flowchart LR## 為什麼 agent 自己解決不了這個問題-你可能在想:"agent 不能自己打日誌嗎?" 問題在於:+你可能在想:「agent 不能自己打日誌嗎?」 問題在於:1. **agent 不知道它不知道什麼**——它不會主動記錄自己沒意識到需要的訊號。agent 只記錄它意識到需要記錄的訊號,對未察覺的問題域天然盲目。2. **日誌格式不統一**,不同工作階段用不同的日誌格式,無法做系統化分析。格式各異的日誌無法在工作階段間做系統化比對分析。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 d5baa84..d5d324f 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@@ -68,7 +68,7 @@ flowchart LR- **harness 簡化**:隨著模型能力提升,定期移除不再必要的 harness 元件。今天必要的約束,三個月後可能是多餘的開銷。- **冪等清理**:清理操作無論執行多少次都產生相同結果。使清理在失敗重試場景中保持安全。-## "以後再清理"是永遠不清理+## 「以後再清理」是永遠不清理最常見的心理陷阱是「這次來不及清理了,下次再弄」。但下次的 agent 不知道你上次留下了什麼,它看到的是一堆混亂的程式碼和不確定的狀態。它會花大量時間推斷「這堆程式碼裡哪些是有意的,哪些是臨時的」。diff --git a/docs/zh-TW/resources/templates/index.md b/docs/zh-TW/resources/templates/index.mdindex 8703e5e..9b9454f 100644--- a/docs/zh-TW/resources/templates/index.md+++ b/docs/zh-TW/resources/templates/index.md@@ -31,7 +31,7 @@- 讓它在開始工作前先讀進度和功能狀態- 逼它一次只做一個功能- 要求它拿出證據才能標記完成-- 定義了什麼叫"乾淨收尾"+- 定義了什麼叫「乾淨收尾」用 `AGENTS.md` 給 Codex 或其他 agent。用 `CLAUDE.md` 給 Claude Code——內容一樣,格式按 Claude 的指令風格來的。@@ -64,7 +64,7 @@**怎麼用:**- 複製到專案根目錄-- 把"目前已驗證狀態"那段填上你的專案資訊+- 把「目前已驗證狀態」那段填上你的專案資訊- 每輪工作階段結束後更新工作階段記錄**每個字段的意思:**@@ -95,7 +95,7 @@- 每個功能需要填:- `id` — 短的唯一標識- `priority` — 整數,越小越優先- - `area` — 屬於應用的哪塊(比如 "chat"、"import"、"search")+ - `area` — 屬於應用的哪塊(比如 「chat」、「import」、「search」)- `title` — 簡短描述- `user_visible_behavior` — 功能正常時使用者能看到什麼- `status` — 四種狀態之一:`not_started`、`in_progress`、`blocked`、`passing`@@ -205,8 +205,8 @@ agent 任何時候只能有一個功能處於 `in_progress`。Evaluator rubric 評的是單次 agent 輸出的品質。Quality document 評的是程式碼庫本身的品質。它們回答的是不同的問題:-- Evaluator rubric:"這輪 agent 做得好不好?"-- Quality document:"這個專案是在變強還是變弱?"+- Evaluator rubric:「這輪 agent 做得好不好?」+- Quality document:「這個專案是在變強還是變弱?」**什麼時候更新:**