Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
i18n(zh-TW): refine Traditional Chinese content for Taiwan conventions
Jim Chena12945f41e44
diff --git a/docs-readme/zh-TW/README.md b/docs-readme/zh-TW/README.mdindex e160a5f..361030d 100644--- a/docs-readme/zh-TW/README.md+++ b/docs-readme/zh-TW/README.md@@ -55,7 +55,7 @@ Learn Harness Engineering 是一門專注於 AI 程式設計代理工程化的### 🗂️ 即用的資源庫-> 專為解決多輪 AI 代理開發中常見陷阱(如上下文遺失、過早宣告任務完成)而設計的模板與參考配置。+> 專為解決多輪 AI 代理開發中常見陷阱(如脈絡遺失、過早宣告任務完成)而設計的模板與參考配置。@@ -275,7 +275,7 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,階段 3:連接工作階段 階段 4:回饋與範圍======================= ==================- L05 跨工作階段保持上下文 L07 劃清任務邊界+ L05 跨工作階段保持脈絡 L07 劃清任務邊界L06 每次代理工作階段前初始化 L08 功能列表作為 harness基本元素|diff --git a/docs/zh-TW/index.md b/docs/zh-TW/index.mdindex 5f1a548..cda4411 100644--- a/docs/zh-TW/index.md+++ b/docs/zh-TW/index.md@@ -1,12 +1,12 @@# 歡迎來到 Learn Harness Engineering-Learn Harness Engineering 是一門專注於 AI 程式設計智慧體工程化落地的課程。本課程深入研究並總結了業界最前沿的 Harness Engineering(工具馬具/腳手架工程)理論與實踐,參考資料包括:+Learn Harness Engineering 是一門專注於 AI 程式設計代理工程實踐的課程。本課程深入研究並整理業界前沿的 Harness Engineering(執行環境工程)理論與實踐,參考資料包括:- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)-透過系統性的環境設計、狀態管理、驗證與控制機制,本課程旨在幫助你讓 Codex 和 Claude Code 等 AI Agent 能夠真正可靠地完成真實工程任務。它透過明確的規則和邊界約束你的 AI 程式設計助手,幫助你更可靠地建構功能、修復 Bug 並自動化開發任務。+透過系統性的環境設計、狀態管理、驗證與控制機制,本課程旨在幫助你讓 Codex 和 Claude Code 等 AI 代理能夠真正可靠地完成真實工程任務。它透過明確的規則和邊界約束你的 AI 程式設計助手,幫助你更可靠地建構功能、修復 bug 並自動化開發任務。## 開始學習@@ -19,17 +19,17 @@ Learn Harness Engineering 是一門專注於 AI 程式設計智慧體工程化</a><a href="./projects/" class="card"><h3>專案</h3>- <p>動手實踐,從零開始搭建一個可靠的 Agent 工作環境。</p>+ <p>動手實踐,從零開始搭建一個可靠的代理工作環境。</p></a><a href="./resources/" class="card"><h3>資源庫</h3>- <p>開箱即用的範本(AGENTS.md、feature_list.json 等),可直接複製到你自己的程式碼倉庫中。</p>+ <p>開箱即用的範本(AGENTS.md、feature_list.json 等),可直接複製到你自己的儲存庫中。</p></a></div>## Harness 的核心機制-Harness 的本質不是「讓模型變聰明」,而是給模型建立一套閉環的**工作系統**。你可以透過下面的簡單圖示理解它的核心運作流:+Harness 的核心在於為模型建立一套閉環的**工作系統**,讓模型更聰明並非其目的。你可以透過下面的簡單圖示理解它的核心運作流:```mermaidgraph TD@@ -55,11 +55,11 @@ graph TD你將在本課程中掌握以下核心概念:<ul class="index-list">- <li>用明確的規則和邊界<strong>約束 Agent 的行為</strong>。</li>- <li>在跨會話的長時任務中<strong>保持上下文連續性</strong>。</li>- <li><strong>防止 Agent 提前宣告</strong>任務完成。</li>- <li>讓 Agent 學會透過完整的流水線測試來<strong>驗證自己的工作</strong>。</li>- <li>讓 Agent 的執行過程<strong>可觀測、可除錯</strong>。</li>+ <li>用明確的規則和邊界<strong>約束代理的行為</strong>。</li>+ <li>在跨工作階段的長時任務中<strong>保持脈絡連續性</strong>。</li>+ <li><strong>防止代理提前宣告</strong>任務完成。</li>+ <li>讓代理學會透過完整的流水線測試來<strong>驗證自己的工作</strong>。</li>+ <li>讓代理的執行過程<strong>可觀測、可除錯</strong>。</li></ul>## 下一步@@ -69,5 +69,5 @@ graph TD<ul class="index-list"><li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">L01. 模型能力強,不等於執行可靠</a>:從理論開始。</li><li><a href="./projects/project-01-baseline-vs-minimal-harness/">P01. 提示詞 vs 規則驅動</a>:完成你的第一個對比實戰任務。</li>- <li><a href="./resources/templates/">繁體中文範本</a>:取得最小 Harness 範本包(AGENTS.md、feature_list.json 等),直接用於你的專案。</li>+ <li><a href="./resources/templates/">繁體中文範本</a>:取得最小 harness 範本包(AGENTS.md、feature_list.json 等),直接用於你的專案。</li></ul>diff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/index.mdindex 9b09c1e..22a4f23 100644--- a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/index.md+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/index.md@@ -4,4 +4,4 @@- 強大的模型在薄弱的環境中失敗- 規格不足的 repo 設定-- 缺少反饋迴圈+- 缺少回饋迴圈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 32e8cc6..65c1e0d 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@@ -1,11 +1,11 @@[English Version →](../../../en/lectures/lecture-01-why-capable-agents-still-fail/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/code/)> 實戰練習:[Project 01. 只寫提示詞讓 agent 做,和定好規則再讓它做,差多少](./../../projects/project-01-baseline-vs-minimal-harness/index.md)# 第一講. 模型能力強,不等於執行可靠-你說你也算見過世面的人了——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 分鐘然後自信滿滿地說"完成了"——你一看程式碼,根本不是你要的東西。這時候你的第一反應是什麼?"這模型不行,得換一個更貴的。"且慢。先別急著掏錢包。問題可能根本不在模型身上。@@ -19,28 +19,28 @@ Anthropic 做過一個對照實驗。同一個 prompt("做一個 2D 復古遊模型沒換。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 說"我做完了"但實際沒做完——這是最常見的失敗模式。- **診斷循環**:執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。@@ -52,29 +52,29 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直白:Code具體怎麼做:-**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問:是任務沒說清楚?是上下文不夠?是沒有驗證手段?把每次失敗歸到五層防禦:任務規範、上下文供給、執行環境、驗證反饋、狀態管理。這裡說的是實操診斷用的五層防禦,不是上面那組六個術語。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。+**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問:是任務沒說清楚?是脈絡不夠?是沒有驗證手段?把每次失敗歸到五層防禦:任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。這裡說的是實操診斷用的五層防禦,不是上面那組六個術語。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。**給每個任務寫顯式的完成定義。** 不要說"加個搜索功能",要說:```完成標準:-- 新增 GET /api/search?q=xxx 端点-- 支持分页,默認 20 条-- 返回結果包含高亮片段+- 新增 GET /api/search?q=xxx 端點+- 支援分頁,預設 20 條+- 返回結果包含標記片段- 所有新程式碼通過 pytest- 類型檢查通過(mypy --strict)```-**創建 AGENTS.md 檔案。** 在倉庫根目錄放一個檔案,告訴 agent 這個項目的技術棧、架構約定、驗證命令。這是 harness 工程的第一步,也是投入產出比最高的一步。一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效——我不是在開玩笑。+**建立 AGENTS.md 檔案。** 在儲存庫根目錄放一個檔案,告訴 agent 這個專案的技術棧、架構約定、驗證命令。這是 harness 工程的第一步,也是投入產出比最高的一步。一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效——我不是在開玩笑。**建立診斷循環。** 不要把失敗當作"模型又犯傻了",而是當作"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 缺什麼能力,怎麼讓它既可理解又可執行"。@@ -82,22 +82,22 @@ OpenAI 在 2025 年做了一個激進的實驗:用 Codex 從一個空的 git> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## 一個更接地氣的例子+## 一個更親民的例子-一個團隊用 Claude Sonnet 給一箇中等規模的 Python Web 應用(FastAPI + PostgreSQL + Redis,約 15,000 行代碼)添加新的 API 端點。+一個團隊用 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%。+後來他們加了 `AGENTS.md`(描述專案架構和技術棧版本)、顯式的驗證命令(`pytest tests/api/v2/ && python -m mypy src/`)、和架構決策記錄。同一模型在三次獨立執行中全部成功,脈絡使用效率提高了約 60%。模型沒變。變的還是 harness。## 帶走什麼-- 模型能力和執行可靠性是兩回事。千裡馬也得配上好馬具。+- 模型能力和執行可靠性是兩回事。千里馬也得配上好馬具。- 失敗的時候先看 harness,再看模型。換模型是成本最高的選擇——而且很多時候根本不是模型的問題。- 每次失敗都是一個信號:你的 harness 有結構性缺陷。把它找出來、修掉。-- 五層防禦:任務規範、上下文供給、執行環境、驗證反饋、狀態管理。逐層排查,就像醫生看病先檢查最常見的病因。+- 五層防禦:任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。逐層排查,就像醫生看病先檢查最常見的病因。- 一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效。真的。## 延伸閱讀@@ -110,8 +110,8 @@ OpenAI 在 2025 年做了一個激進的實驗:用 Codex 從一個空的 git## 練習-1. **對比實驗**:選一個你熟悉的代碼倉庫和一項非平凡的修改任務。先不給任何 harness 支持,讓 agent 跑一次,記錄失敗。然後加一個 `AGENTS.md` 和顯式的驗證命令,讓同一個 agent 再跑一次。對比兩次的結果,把失敗歸因到五層防禦中的某一層。+1. **對比實驗**:選一個你熟悉的程式碼儲存庫和一項非平凡的修改任務。先不給任何 harness 支援,讓 agent 跑一次,記錄失敗。然後加一個 `AGENTS.md` 和顯式的驗證命令,讓同一個 agent 再跑一次。對比兩次的結果,把失敗歸因到五層防禦中的某一層。2. **驗證缺口測量**:選 5 個編碼任務,在每個任務完成後記錄 agent 是否聲稱完成,然後用獨立測試驗證實際正確性。計算 agent 在實際沒完成時聲稱完成的比例——這就是你的驗證缺口。然後想想:加什麼驗證命令能把這個比例降下來?-3. **診斷循環實踐**:找一個 agent 在你的項目中反覆失敗的任務。跑一次,記錄失敗。歸因到五層中的某一層。修那一層。再跑。重複三到五輪,記錄每一輪的改善。+3. **診斷循環實踐**:找一個 agent 在你的專案中反覆失敗的任務。跑一次,記錄失敗。歸因到五層中的某一層。修那一層。再跑。重複三到五輪,記錄每一輪的改善。diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/index.mdindex b9bcdeb..e8188e1 100644--- a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/index.md+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/index.md@@ -1,6 +1,6 @@# 第 02 講的程式碼-此資料夾用於區分以下項目的小型範例:+此資料夾用於區分以下專案的小型範例:- 模型行為- harness 行為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 7e61206..645b16a 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@@ -1,6 +1,6 @@[English Version →](../../../en/lectures/lecture-02-what-a-harness-actually-is/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/code/)> 實戰練習:[Project 01. 只寫提示詞讓 agent 做,和定好規則再讓它做,差多少](./../../projects/project-01-baseline-vs-minimal-harness/index.md)# 第二講. Harness 到底是什麼@@ -9,31 +9,31 @@這節課要給你一個精確的、可操作的 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 把倉庫當作"記錄系統"——所有必要的上下文都必須在倉庫裡,通過結構化的檔案和清晰的目錄組織來呈現。+- **什麼是 harness**:模型權重之外的一切工程基礎設施。OpenAI 把工程師的核心工作概括為三件事:設計環境、表達意圖、建構回饋循環。Anthropic 直接把 Claude Agent SDK 稱為"通用 agent harness"。+- **儲存庫是唯一事實來源**:agent 看不到的東西,對它來說就不存在。OpenAI 把儲存庫當作"記錄系統"——所有必要的脈絡都必須在儲存庫裡,透過結構化的檔案和清晰的目錄組織來呈現。- **給地圖,不給說明書**:OpenAI 的經驗——`AGENTS.md` 應該是目錄頁,不是百科全書。100 行左右就夠了,放不下就拆分到 `docs/` 目錄裡,讓 agent 按需去讀。-- **約束而非微操**:好的 harness 用可執行的規則來約束 agent,而不是在指令裡逐條叮囑。OpenAI 說"執行不變量,不要微管實現";Anthropic 發現 agent 會自信地誇讚自己的工作,解決方案是把"幹活的人"和"檢查的人"分開。-- **逐個組件拆除法**:想量化 harness 各組件的邊際貢獻,就逐個移除,看哪個移除後性能下降最多。它能告訴你哪些組件當前最有價值,也能暴露哪些組件暫時貢獻不明顯。Anthropic 用這個方法發現:隨著模型變強,某些組件不再關鍵,但總會有新的關鍵組件出現。+- **約束而非微操**:好的 harness 用可執行的規則來約束 agent,而不是在指令裡逐條叮囑。OpenAI 說"執行不變數,不要微管實現";Anthropic 發現 agent 會自信地誇讚自己的工作,解決方案是把"幹活的人"和"檢查的人"分開。+- **逐個組件拆除法**:想量化 harness 各組件的邊際貢獻,就逐個移除,看哪個移除後效能下降最多。它能告訴你哪些組件目前最有價值,也能暴露哪些組件暫時貢獻不明顯。Anthropic 用這個方法發現:隨著模型變強,某些組件不再關鍵,但總會有新的關鍵組件出現。## Harness 五子系統模型@@ -41,23 +41,23 @@ OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表```mermaidflowchart LR- Rules["專案规则<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]+ Rules["專案規則<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]State["進度和 git<br/>PROGRESS.md / commits"] --> AgentAgent --> Tools["工具<br/>shell / 檔案 / 測試"]- Tools --> Env["執行环境<br/>依赖 / 服務 / 版本"]+ Tools --> Env["執行環境<br/>依賴 / 服務 / 版本"]Env --> Checks["檢查結果<br/>test / lint / build"]Checks --> 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` 都跑不了,還怎麼幹活?但也別什麼都開放,按最小權限原則來。-**環境子系統(灶臺)**:讓環境狀態自描述。用 `pyproject.toml` 或 `package.json` 鎖定依賴,用 `.nvmrc` 或 `.python-version` 指定運行時版本,用 Docker 或 devcontainer 讓環境可重現。+**環境子系統(灶臺)**:讓環境狀態自描述。用 `pyproject.toml` 或 `package.json` 鎖定依賴,用 `.nvmrc` 或 `.python-version` 指定執行時期版本,用 Docker 或 devcontainer 讓環境可重現。-**狀態子系統(備菜臺)**:長任務必須有進度跟蹤。用一個簡單的 `PROGRESS.md` 檔案記錄:哪些做完了,哪些在做,哪些被阻塞。每個會話結束前更新,下一個會話開始時讀取。+**狀態子系統(備菜臺)**:長任務必須有進度跟蹤。用一個簡單的 `PROGRESS.md` 檔案記錄:哪些做完了,哪些在做,哪些被阻塞。每個工作階段結束前更新,下一個工作階段開始時讀取。-**反饋子系統(出菜檢查口)**:這是投入產出比最高的子系統。在 `AGENTS.md` 裡顯式列出驗證命令:+**回饋子系統(出菜檢查口)**:這是投入產出比最高的子系統。在 `AGENTS.md` 裡顯式列出驗證命令:```驗證命令:- 測試:pytest tests/ -x@@ -68,29 +68,29 @@ flowchart LR五個子系統缺一個,就像廚房裡少了一個功能區——菜還是能做,但總是彆扭。-**量化 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%。剩餘失敗主要來自環境問題和驗證缺失。**階段 3——開起出菜檢查口**:在 `AGENTS.md` 裡列出驗證命令 `yarn test && yarn lint && yarn build`。成功率升到 80%。-**階段 4——備菜臺就位**:引入進度檔案範本,agent 在每次運行中記錄完成和未完成的工作。成功率穩定在 80-100%。+**階段 4——備菜臺就位**:引入進度檔案範本,agent 在每次執行中記錄完成和未完成的工作。成功率穩定在 80-100%。-四次迭代,模型一個字沒改,成功率從 20% 到接近 100%。這就是 harness 工程的力量。你沒有換更貴的食材,你只是把廚房收拾利索了。+四次迭代,模型一個字沒改,成功率從 20% 到接近 100%。這就是 harness 工程的力量。你沒有換更貴的食材,你只是把廚房收拾俐落了。## 關鍵要點-- Harness = 指令 + 工具 + 環境 + 狀態 + 反饋。五個子系統,就像廚房的五個功能區,缺一不可。+- Harness = 指令 + 工具 + 環境 + 狀態 + 回饋。五個子系統,就像廚房的五個功能區,缺一不可。- 不是模型權重的部分全是 harness。你的 harness 決定了模型能力能被髮揮多少。-- 五個子系統中,反饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚——出菜檢查口是最值得先裝的。+- 五個子系統中,回饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚——出菜檢查口是最值得先裝的。- 用「等模型對照下的組件拆除實驗」量化各子系統的邊際貢獻;定位真正瓶頸要靠失敗記錄和歸因,不能只靠拆除實驗。-- Harness 和代碼一樣會腐化。定期審計,像還技術債一樣還 harness 債。+- Harness 和程式碼一樣會腐化。定期審計,像還技術債一樣還 harness 債。## 延伸閱讀@@ -102,8 +102,8 @@ flowchart LR## 練習-1. **Harness 五元組審計**:拿你正在用 AI agent 的項目,按五元組框架做一個完整審計。每個子系統打 1-5 分。找出最低分的那個子系統,花 30 分鐘改進它,然後觀察 agent 的表現變化。+1. **Harness 五元組審計**:拿你正在用 AI agent 的專案,按五元組框架做一個完整審計。每個子系統打 1-5 分。找出最低分的那個子系統,花 30 分鐘改進它,然後觀察 agent 的表現變化。-2. **等模型對照下的組件價值實驗**:選一個模型和一個有挑戰性的任務。依次移除指令(刪掉 AGENTS.md)、移除反饋(不給驗證命令)、移除狀態(不提供進度檔案),每次只移除一個,測量性能下降幅度。基於結果,排出各子系統在當前任務裡的邊際價值;如果要找瓶頸,還必須同時記錄失敗日誌並做原因歸因。+2. **等模型對照下的組件價值實驗**:選一個模型和一個有挑戰性的任務。依次移除指令(刪掉 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 7592e7f..28676b1 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@@ -1,91 +1,91 @@[English Version →](../../../en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)-> 實戰練習:[Project 02. 讓 agent 看懂項目、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)+> 實戰練習:[Project 02. 讓 agent 看懂專案、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)-# 第三講. 讓代碼倉庫成為唯一的事實來源+# 第三講. 讓程式碼儲存庫成為唯一的事實來源-你團隊的架構決策散落在 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 頁但沒人維護的設計文件有用一萬倍。就好比一張貼在你工位上的、手畫的辦公室走法圖,比一份精美的、放在檔案室裡的建築藍圖實用得多——因為前者在你需要的時候就在手邊。## 知識可見性```mermaidflowchart LR- Slack["Slack 裡的规则"] --> Write["寫进倉庫檔案<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]- Confluence["Confluence 裡的规则"] --> Write- Heads["工程师脑子裡的规则"] --> Write- Jira["Jira 裡的规则"] --> Write- Write --> Repo["倉庫檔案"]- Repo --> Agent["新的 agent 會話<br/>直接讀倉庫"]- Warning["规则不寫进倉庫<br/>agent 就看不见"] --> Agent+ Slack["Slack 裡的規則"] --> Write["寫進儲存庫檔案<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]+ Confluence["Confluence 裡的規則"] --> Write+ Heads["工程師腦子裡的規則"] --> Write+ Jira["Jira 裡的規則"] --> Write+ Write --> Repo["儲存庫檔案"]+ Repo --> Agent["新的 agent 工作階段<br/>直接讀儲存庫"]+ Warning["規則不寫進儲存庫<br/>agent 就看不見"] --> Agent```-怎麼檢驗你的地圖畫得夠不夠好?做一個"冷啟動測試":開一個全新的 agent 會話,只看倉庫內容,看它能不能回答五個基本問題:+怎麼檢驗你的地圖畫得夠不夠好?做一個"冷啟動測試":開一個全新的 agent 工作階段,只看儲存庫內容,看它能不能回答五個基本問題:```mermaidflowchart TB- Q1["這是什么系統?"] --> A1["AGENTS.md / README"]- Q2["怎么组织的?"] --> A2["ARCHITECTURE.md / 模块文檔"]- Q3["怎么跑?"] --> A3["Makefile / init.sh / package scripts"]- Q4["怎么驗證?"] --> A4["測試、lint、check 命令"]- Q5["现在做到哪了?"] --> A5["PROGRESS.md / 功能清單 / git 历史"]+ Q1["這是什麼系統?"] --> A1["AGENTS.md / README"]+ Q2["怎麼組織的?"] --> A2["ARCHITECTURE.md / 模組文件"]+ Q3["怎麼跑?"] --> A3["Makefile / init.sh / package scripts"]+ Q4["怎麼驗證?"] --> A4["測試、lint、check 命令"]+ Q5["現在做到哪了?"] --> A5["PROGRESS.md / 功能清單 / git 歷史"]- A1 --> Ready["新的會話不用问人<br/>就能開始工作"]+ A1 --> Ready["新的工作階段不用問人<br/>就能開始工作"]A2 --> ReadyA3 --> ReadyA4 --> ReadyA5 --> 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 行就夠了。+**原則 2:用標準化的入口檔案。** `AGENTS.md`(或 `CLAUDE.md`)是 agent 的"著陸頁"。它不需要包含所有資訊,但必須能讓 agent 快速回答"這是什麼專案"、"怎麼跑"、"怎麼驗證"這三個問題。50-100 行就夠了。**原則 3:最小但完備。** 每條知識都應該有明確的使用場景。如果你刪掉某條規則不影響 agent 的決策質量,那這條規則就不應該存在。但冷啟動測試中的每個問題都必須有答案。這是一個精妙的平衡——不多不少,剛好夠用。-**原則 4:和代碼一起更新。** 把知識更新跟代碼變更綁定在一起。最簡單的方法:把架構文檔放在對應的模塊目錄裡。改代碼的時候自然會看到文檔,改代碼之後 CI 提醒你檢查文檔是否需要更新。+**原則 4:和程式碼一起更新。** 把知識更新跟程式碼變更綁定在一起。最簡單的方法:把架構文件放在對應的模組目錄裡。改程式碼的時候自然會看到文件,改程式碼之後 CI 提醒你檢查文件是否需要更新。-**具體的倉庫結構**:+**具體的儲存庫結構**:```project/-├── AGENTS.md # 入口:專案概覽、執行命令、硬约束+├── AGENTS.md # 入口:專案概覽、執行命令、硬約束├── src/│ ├── api/│ │ ├── ARCHITECTURE.md # API 层的架构决策│ │ └── ...│ ├── db/-│ │ ├── CONSTRAINTS.md # 資料庫操作的硬约束+│ │ ├── CONSTRAINTS.md # 資料庫操作的硬約束│ │ └── ...│ └── ...-├── PROGRESS.md # 当前進度:做了什么、在做什么、被什么阻塞+├── PROGRESS.md # 目前進度:做了什麼、在做什麼、被什麼阻塞└── Makefile # 標準化的操作命令:setup、test、lint、check```@@ -93,32 +93,32 @@ project/這個類比來自數據庫的事務管理——你可能覺得這是在把簡單的事情搞複雜,但實際上它給了你一個非常實用的框架:-- **原子性**:每次"邏輯操作"(比如"添加新端點並更新測試")用一個 git commit 原子化。中途掛了就 `git stash` 回滾。要麼全做,要麼不做,沒有"做了一半"。+- **原子性**:每次"邏輯操作"(比如"添加新端點並更新測試")用一個 git commit 原子化。中途掛了就 `git stash` 回溯。要麼全做,要麼不做,沒有"做了一半"。- **一致性**:定義"一致狀態"的驗證謂詞——所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。就像銀行轉賬——你不能只扣款不入賬。- **隔離性**:多個 agent 併發工作時,狀態檔案要避免競爭條件。簡單方案:每個 agent 用獨立的進度檔案,或者用 git 分支隔離。兩個廚師不能同時往同一口鍋裡放鹽——放重了誰負責?-- **持久性**:關鍵的項目知識用 git 跟蹤的檔案持久化。臨時狀態可以只在會話內存裡,但跨會話必須的知識必須寫到檔案裡。腦子裡的不算,寫在紙上的才算。+- **持久性**:關鍵的專案知識用 git 跟蹤的檔案持久化。臨時狀態可以只在工作階段的記憶體中,但跨工作階段必須的知識必須寫到檔案裡。腦子裡的不算,寫在紙上的才算。## 一個真實的改造故事-一個團隊維護一個包含約 30 個微服務的電商平臺。架構決策(服務間通信協議、數據一致性策略、API 版本化規則)散落在:Confluence(部分過時)、Slack(難以搜索)、幾個資深工程師的腦子裡(不可擴展)、以及零星的代碼註釋(不繫統)。+一個團隊維護一個包含約 30 個微服務的電商平臺。架構決策(服務間通信協定、數據一致性策略、API 版本化規則)散落在:Confluence(部分過時)、Slack(難以搜索)、幾個資深工程師的腦子裡(不可擴展)、以及零星的程式碼註釋(不繫統)。-引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個"所有人都知道但從未寫入倉庫"的隱性約束。這就像一個新來的員工,沒人告訴他"中午點外賣要在群裡接龍"——他自己猜,猜錯了被罵,但罵完了還是沒人告訴他規則。+引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個"所有人都知道但從未寫入儲存庫"的隱性約束。這就像一個新來的員工,沒人告訴他"中午點外賣要在群裡接龍"——他自己猜,猜錯了被罵,但罵完了還是沒人告訴他規則。團隊執行了改造:-1. 倉庫根目錄創建 `AGENTS.md`,寫明項目概覽、技術棧版本、全局硬約束-2. 每個微服務目錄下添加 `ARCHITECTURE.md`,描述該服務的職責、接口和依賴-3. 創建集中的 `CONSTRAINTS.md`,用"禁止/必須"的明確語言記錄硬約束-4. 每個服務目錄添加 `PROGRESS.md`,記錄當前工作狀態+1. 儲存庫根目錄建立 `AGENTS.md`,寫明專案概覽、技術棧版本、全域硬約束+2. 每個微服務目錄下添加 `ARCHITECTURE.md`,描述該服務的職責、介面和依賴+3. 建立集中的 `CONSTRAINTS.md`,用"禁止/必須"的明確語言記錄硬約束+4. 每個服務目錄添加 `PROGRESS.md`,記錄目前工作狀態-改造後:同一 agent 能在冷啟動時回答所有關鍵項目問題,任務完成質量顯著提升。+改造後:同一 agent 能在冷啟動時回答所有關鍵專案問題,任務完成質量顯著提升。## 關鍵要點-- 不在倉庫裡的知識對 agent 來說等於不存在。把關鍵決策信息放進倉庫是最基本的 harness 投資——畫好地圖,才不會迷路。-- 用"冷啟動測試"檢驗倉庫質量:全新會話能不能只看倉庫回答五個基本問題。-- 知識要靠近代碼、最小但完備、跟代碼一起更新。不是寫更多文檔,是把信息放到正確的位置。+- 不在儲存庫裡的知識對 agent 來說等於不存在。把關鍵決策資訊放進儲存庫是最基本的 harness 投資——畫好地圖,才不會迷路。+- 用"冷啟動測試"檢驗儲存庫質量:全新工作階段能不能只看儲存庫回答五個基本問題。+- 知識要靠近程式碼、最小但完備、跟程式碼一起更新。不是寫更多文件,是把資訊放到正確的位置。- 用 ACID 原則管理 agent 狀態:原子提交、一致性驗證、隔離併發、持久化關鍵知識。-- 知識衰減是最大敵人。過時的文檔比沒有文檔更危險——它會讓 agent 走錯方向還以為自己是對的。+- 知識衰減是最大敵人。過時的文件比沒有文件更危險——它會讓 agent 走錯方向還以為自己是對的。## 延伸閱讀@@ -130,8 +130,8 @@ project/## 練習-1. **冷啟動測試**:在你的項目裡開一個全新的 agent 會話(不提供任何口頭上下文),只讓它看倉庫內容,然後問它五個問題:這是什麼系統?怎麼組織的?怎麼運行?怎麼驗證?現在進度如何?記錄它答不上來的問題,然後改進倉庫讓它能答上來。+1. **冷啟動測試**:在你的專案裡開一個全新的 agent 工作階段(不提供任何口頭脈絡),只讓它看儲存庫內容,然後問它五個問題:這是什麼系統?怎麼組織的?怎麼執行?怎麼驗證?現在進度如何?記錄它答不上來的問題,然後改進儲存庫讓它能答上來。-2. **知識外置化量化**:列出你的項目中所有對開發工作重要的決策和約束。標註每個條目是在倉庫內還是倉庫外。算一下你的知識可見性缺口有多大(不在倉庫裡的佔總數的比例)。制定計劃把缺口降到 10% 以下。+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/code/anti-patterns.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.mdindex 10def73..6850d83 100644--- a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md@@ -4,4 +4,4 @@- 在多個地方重複相同的規則- 編寫無人審核的過時規則- 撰寫過於具體而鮮少適用的條件式指令-- 在啟動上下文中嵌入冗長的工具手冊+- 在啟動脈絡中嵌入冗長的工具手冊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 49cebaf..def9669 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@@ -1,11 +1,11 @@[English Version →](../../../en/lectures/lecture-04-why-one-giant-instruction-file-fails/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)-> 實戰練習:[Project 02. 讓 agent 看懂項目、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)+> 實戰練習:[Project 02. 讓 agent 看懂專案、接住上次的工作](./../../projects/project-02-agent-readable-workspace/index.md)# 第四講. 把指令拆分到不同檔案裡-你開始認真對待 harness 了——好事。你建了個 `AGENTS.md`,把你能想到的所有規則、約束、歷史教訓都塞了進去。一個月後這個檔案膨脹到了 300 行,兩個月 450 行,三個月 600 行。然後你發現 agent 的表現反而變差了——改一個小 bug,agent 花大量上下文處理無關的部署指令;關鍵的安全約束埋在第 300 行,被直接忽略了;檔案裡有三條互相矛盾的代碼風格規則,agent 每次隨機選一條。+你開始認真對待 harness 了——好事。你建了個 `AGENTS.md`,把你能想到的所有規則、約束、歷史教訓都塞了進去。一個月後這個檔案膨脹到了 300 行,兩個月 450 行,三個月 600 行。然後你發現 agent 的表現反而變差了——改一個小 bug,agent 花大量脈絡處理無關的部署指令;關鍵的安全約束埋在第 300 行,被直接忽略了;檔案裡有三條互相矛盾的程式碼風格規則,agent 每次隨機選一條。這就是"巨型指令檔案"陷阱。就像你往行李箱裡塞東西——覺得什麼都有用,什麼都往裡裝,結果拉鍊快崩了,想找換洗內衣得把整個箱子翻一遍。帶了一箱子東西,但真正用上的可能只有三分之一。@@ -15,40 +15,40 @@這不是你的錯。這是一個非常自然的反應——每次出問題就"加條規則"感覺很合理,就像每次出門忘帶東西就往包裡多塞一樣。但累積效應是災難性的。讓我們看看具體出了什麼問題。-**上下文預算被吃掉了。** 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 每次隨機選一條遵循。就像你媽說"穿厚點",你爸說"別穿太多",你站在門口不知道聽誰的。## 核心概念-- **指令膨脹**:當指令檔案佔用了超過上下文窗口 10-15% 的時候,它就開始擠佔代碼閱讀和任務推理的預算。600 行的 `AGENTS.md` 可能佔用 10,000-20,000 tokens——對 128K 的窗口來說,這就吃掉了 8-15%。-- **中間迷失效應**:Liu 等人 2023 年的研究證明,LLM 對長文本中間部分的信息利用效率顯著低於兩端。埋在 600 行檔案中間第 300 行的關鍵約束,被有效忽略的概率非常高。-- **指令信噪比(SNR)**:檔案中與當前任務相關的指令佔總指令的比例。做 bug 修復時被要求讀 50 行部署指令——SNR 很低。-- **路由檔案**:短小的入口檔案,核心功能是引導 agent 去找更詳細的文檔,而不是自己包含所有內容。50-200 行就夠了。-- **漸進式披露**:先給概要信息,需要的時候再給詳細信息。好的 harness 設計和好的 UI 設計一樣,不把所有選項一次性砸到用戶臉上。+- **指令膨脹**:當指令檔案佔用了超過脈絡視窗 10-15% 的時候,它就開始擠佔程式碼閱讀和任務推理的預算。600 行的 `AGENTS.md` 可能佔用 10,000-20,000 tokens——對 128K 的視窗來說,這就吃掉了 8-15%。+- **中間迷失效應**:Liu 等人 2023 年的研究證明,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。埋在 600 行檔案中間第 300 行的關鍵約束,被有效忽略的概率非常高。+- **指令信噪比(SNR)**:檔案中與目前任務相關的指令佔總指令的比例。做 bug 修復時被要求讀 50 行部署指令——SNR 很低。+- **路由檔案**:短小的入口檔案,核心功能是引導 agent 去找更詳細的文件,而不是自己包含所有內容。50-200 行就夠了。+- **漸進式披露**:先給概要資訊,需要的時候再給詳細資訊。好的 harness 設計和好的 UI 設計一樣,不把所有選項一次性砸到使用者臉上。- **優先級模糊度**:當所有指令以相同格式和位置呈現時,agent 分不清哪些是不可違反的硬約束,哪些是建議性的軟約束。## 指令檔案架構```mermaidflowchart LR- Mono["一個超长 AGENTS.md"] --> MonoLoad["改一個小 bug<br/>也得把部署說明和历史备注全讀一遍"]- MonoLoad --> MonoRisk["關键规则埋在中间<br/>很容易漏掉"]+ Mono["一個超長 AGENTS.md"] --> MonoLoad["改一個小 bug<br/>也得把部署說明和歷史備注全讀一遍"]+ MonoLoad --> MonoRisk["關鍵規則埋在中間<br/>很容易漏掉"]- Router["短 AGENTS.md"] --> Topics["按任務去讀 API / 資料庫 / 測試文檔"]- Topics --> RoutedResult["把更多上下文留给程式碼阅讀<br/>和驗證"]+ Router["短 AGENTS.md"] --> Topics["按任務去讀 API / 資料庫 / 測試文件"]+ Topics --> RoutedResult["把更多脈絡留給程式碼閱讀<br/>和驗證"]``````mermaidflowchart TB- File["600 行指令檔案"] --> Top["顶部<br/>快速開始 + 硬约束"]- File --> Mid["中部<br/>第 300 行的安全规则"]+ File["600 行指令檔案"] --> Top["頂部<br/>快速開始 + 硬約束"]+ File --> Mid["中部<br/>第 300 行的安全規則"]File --> Bot["底部<br/>明确的結束檢查清單"]Top --> Seen["高概率被记住"]Bot --> Seen@@ -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@@ -68,52 +68,52 @@ flowchart TBPython 3.11 FastAPI 後端,PostgreSQL 15 資料庫。## 快速開始-- 安装:`make setup`+- 安裝:`make setup`- 測試:`make test`- 完整驗證:`make check`-## 硬约束+## 硬約束- 所有 API 必須走 OAuth 2.0 認證-- 所有資料庫查询必須用 SQLAlchemy 2.0 语法+- 所有資料庫查詢必須用 SQLAlchemy 2.0 語法- 所有 PR 必須通過 pytest + mypy --strict + ruff check-## 专题文檔-- API 設計規範 (`docs/api-patterns.md`) — 添加新端点時必讀-- 資料庫操作约束 (`docs/database-rules.md`) — 涉及資料庫修改時必讀+## 專題文件+- API 設計規範 (`docs/api-patterns.md`) — 添加新端點時必讀+- 資料庫操作約束 (`docs/database-rules.md`) — 涉及資料庫修改時必讀- 測試標準 (`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 使用說明、部署流程、和團隊成員的個人偏好——整個行李箱塞得滿滿當當,拉鍊都快崩了。-Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量上下文處理無關的部署指令;安全約束"所有數據庫查詢必須用參數化查詢"埋在第 300 行,經常被忽略;三條矛盾的代碼風格規則導致 agent 隨機選擇。+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. 路由檔案添加指向專題文檔的鏈接+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%——因為從檔案中間移到了路由檔案頂部,不再被"中間迷失"了。## 關鍵要點-- "加條規則"是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文檔是不是更合適?——別什麼都往行李箱裡塞。-- 入口檔案是路由器,不是百科全書。50-200 行,只放概覽、硬約束、和鏈接。-- 利用"中間迷失"效應:重要信息放檔案頂部或底部,不重要的移到專題文檔。+- "加條規則"是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文件是不是更合適?——別什麼都往行李箱裡塞。+- 入口檔案是路由器,不是百科全書。50-200 行,只放概覽、硬約束、和連結。+- 利用"中間迷失"效應:重要資訊放檔案頂部或底部,不重要的移到專題文件。- 像管理技術債一樣管理指令膨脹。定期審計,每條指令要有來源、適用條件、和過期條件。-- 拆分之後信噪比提升,agent 把更多上下文預算花在實際任務上,而不是處理無關指令。+- 拆分之後信噪比提升,agent 把更多脈絡預算花在實際任務上,而不是處理無關指令。## 延伸閱讀@@ -125,8 +125,8 @@ Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量上## 練習-1. **信噪比審計**:拿你當前的入口指令檔案,列出所有指令條目。選 5 個不同的常見任務類型,標註每條指令是否跟該任務相關。計算每個任務類型的 SNR。那些對大多數任務都是噪聲的指令,移到專題文檔裡。+1. **信噪比審計**:拿你目前的入口指令檔案,列出所有指令條目。選 5 個不同的常見任務類型,標註每條指令是否跟該任務相關。計算每個任務類型的 SNR。那些對大多數任務都是噪聲的指令,移到專題文件裡。-2. **漸進式披露重構**:如果你有一個超過 300 行的指令檔案,把它拆成:(a) 不超過 100 行的路由檔案,(b) 3-5 個專題文檔。重構前後各跑同一組任務(至少 5 個),對比成功率。+2. **漸進式披露重構**:如果你有一個超過 300 行的指令檔案,把它拆成:(a) 不超過 100 行的路由檔案,(b) 3-5 個專題文件。重構前後各跑同一組任務(至少 5 個),對比成功率。3. **中間迷失驗證**:在一個長指令檔案裡,把一條關鍵約束分別放在頂部、中間、底部各跑一組任務(每組至少 5 次),看遵循率有沒有差別。你可能會驚訝於位置效應有多大。diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.mdindex 40b3920..b3f676a 100644--- a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md@@ -13,5 +13,5 @@## 下一步最佳步驟- 修復 `.txt` 匯入路徑-- 端到端驗證匯入功能+- 端對端驗證匯入功能- 然後新增文件詳細資訊面板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 a3fc2a7..be8260f 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@@ -1,115 +1,115 @@[English Version →](../../../en/lectures/lecture-05-why-long-running-tasks-lose-continuity/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)> 實戰練習:[Project 03. 讓 agent 關掉再打開還能接著幹](./../../projects/project-03-multi-session-continuity/index.md)-# 第五講. 讓跨會話的任務保持上下文連續+# 第五講. 讓跨工作階段的任務保持脈絡連續-你讓 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 把這叫"脈絡焦慮"。-## 會話連續性流程+## 工作階段連續性流程-沒有連續性工件的時候,每個新會話都是一場災難:+沒有連續性工件的時候,每個新工作階段都是一場災難:```mermaidflowchart LR- S1["會話 1<br/>功能做到一半"] --> End1["上下文快满了<br/>會話結束"]- End1 --> S2["會話 2 重新開始"]- S2 --> Guess["重新讀目录、重跑測試、<br/>猜上次為什么這么寫"]- Guess --> Drift["程式碼會重复改<br/>恢复速度也很慢"]+ S1["工作階段 1<br/>功能做到一半"] --> End1["脈絡快滿了<br/>工作階段結束"]+ End1 --> S2["工作階段 2 重新開始"]+ S2 --> Guess["重新讀目錄、重跑測試、<br/>猜上次為什麼這麼寫"]+ Guess --> Drift["程式碼會重複改<br/>恢復速度也很慢"]```-有連續性工件的時候,新會話能快速接上:+有連續性工件的時候,新工作階段能快速接上:```mermaidflowchart LR- Work["會話 1 的工作"] --> Progress["PROGRESS.md<br/>已完成 / 进行中 / 下一步"]- Work --> Decisions["DECISIONS.md<br/>為什么這样做"]+ Work["工作階段 1 的工作"] --> Progress["PROGRESS.md<br/>已完成 / 進行中 / 下一步"]+ Work --> Decisions["DECISIONS.md<br/>為什麼這樣做"]Work --> Verify["驗證記錄<br/>哪些測試通過或失敗"]- Work --> Commit["Git 檢查点<br/>当前倉庫狀態"]+ Work --> Commit["Git 檢查點<br/>目前儲存庫狀態"]- Progress --> Rebuild["會話 2 重建"]+ Progress --> Rebuild["工作階段 2 重建"]Decisions --> RebuildVerify --> RebuildCommit --> Rebuild- Rebuild --> Resume["新會話能很快接上"]+ Rebuild --> Resume["新工作階段能很快接上"]```## 核心概念-- **上下文窗口是有限的**:不管模型吹多大的窗口(128K、200K、1M),長任務總會用完。用完之後要麼壓縮(丟信息),要麼重置(開新會話)。兩種方式都會丟東西。-- **連續性工件**:持久化的狀態檔案,讓新會話能無歧義地恢復到上次離開的地方。最基本的形式:進度日誌 + 驗證記錄 + 下一步行動。就是那個工匠的日記本。-- **重建成本**:新會話恢復到可執行狀態所需的時間。好的 harness 能把重建成本從 15 分鐘壓到 3 分鐘。-- **漂移(Drift)**:agent 的理解跟代碼倉庫實際狀態之間的偏差。每次會話邊界都會引入漂移,不加控制會越漂越遠。-- **上下文焦慮**:Anthropic 觀察到的現象——agent 在接近上下文限制時表現異常,過早結束任務以避免信息丟失。是一種非理性的資源焦慮。-- **壓縮 vs 重置**:壓縮是在同一個會話裡把上下文摘要化(保留"是什麼",可能丟了"為什麼");重置是開新會話從持久化狀態重建(乾淨但依賴工件完備性)。+- **脈絡視窗是有限的**:不管模型吹多大的視窗(128K、200K、1M),長任務總會用完。用完之後要麼壓縮(丟資訊),要麼重置(開新工作階段)。兩種方式都會丟東西。+- **連續性工件**:持久化的狀態檔案,讓新工作階段能無歧義地恢復到上次離開的地方。最基本的形式:進度日誌 + 驗證記錄 + 下一步行動。就是那個工匠的日記本。+- **重建成本**:新工作階段恢復到可執行狀態所需的時間。好的 harness 能把重建成本從 15 分鐘壓到 3 分鐘。+- **漂移(Drift)**:agent 的理解跟程式碼儲存庫實際狀態之間的偏差。每次工作階段邊界都會引入漂移,不加控制會越漂越遠。+- **脈絡焦慮**:Anthropic 觀察到的現象——agent 在接近脈絡限制時表現異常,過早結束任務以避免資訊遺失。是一種非理性的資源焦慮。+- **壓縮 vs 重置**:壓縮是在同一個工作階段裡把脈絡摘要化(保留"是什麼",可能丟了"為什麼");重置是開新工作階段從持久化狀態重建(乾淨但依賴工件完備性)。## 連續性斷了以後會發生什麼-上個會話花了很多上下文預算分析了三種方案的優劣,最終選了方案 B。這個會話的 agent 不知道這個分析過程,可能基於不完整的信息重新做了決策——而且可能選了方案 A。就像那個失憶的工匠不記得為什麼選了紅磚,今天看著覺得青磚更好看,就把昨天的牆拆了重砌。+上個工作階段花了很多脈絡預算分析了三種方案的優劣,最終選了方案 B。這個工作階段的 agent 不知道這個分析過程,可能基於不完整的資訊重新做了決策——而且可能選了方案 A。就像那個失憶的工匠不記得為什麼選了紅磚,今天看著覺得青磚更好看,就把昨天的牆拆了重砌。-更要命的是重複勞動。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)**。這是最基本的連續性工件——日記本的核心部分:```markdown# 專案進度-## 当前狀態+## 目前狀態- 最新 commit: abc1234 (feat: add user preferences endpoint)- 測試狀態: 42/43 通過 (test_pagination_edge_case 失敗)- Lint: 通過## 已完成- [x] 使用者模型和資料庫迁移-- [x] 基础 CRUD 端点-- [x] 認證中间件集成+- [x] 基础 CRUD 端點+- [x] 認證中介層整合-## 进行中-- [ ] 分页功能 (90% - 邊界条件測試失敗)+## 進行中+- [ ] 分頁功能 (90% - 邊界條件測試失敗)## 已知問題- test_pagination_edge_case 在空結果集時返回 500- 需要确認是否要在列表中包含已删除使用者## 下一步-1. 修復分页邊界条件 bug+1. 修復分頁邊界條件 bug2. 添加"是否包含已删除使用者"的查询参數-3. 更新 API 文檔+3. 更新 API 文件```-**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文檔,只需要"什麼決策、為什麼、什麼時候做的"——這是日記本裡的備忘:+**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文件,只需要"什麼決策、為什麼、什麼時候做的"——這是日記本裡的備忘:```markdown# 設計决策-## 2024-01-15: 使用 Redis 缓存使用者偏好-- 原因: 讀取频率高(每次 API 調用都需要),數據量小+## 2024-01-15: 使用 Redis 快取使用者偏好+- 原因: 讀取频率高(每次 API 呼叫都需要),數據量小- 否决方案: 用 PostgreSQL 物化视图(變更频率高,物化视图維護成本不劃算)-- 约束: 缓存 TTL 设為 5 分钟,寫入時主動失效+- 約束: 快取 TTL 設為 5 分鐘,寫入時主動失效```**工具 3:git 提交作為檢查點。** 每完成一個原子工作單元就提交。commit message 要說清楚做了什麼和為什麼。這是免費的、自動版本化的狀態快照。@@ -117,51 +117,51 @@ OpenAI 和 Anthropic 都在他們的文檔裡強調了結構化狀態持久化**工具 4:init.sh 或 harness 的初始化流程。** 在 `AGENTS.md` 裡寫明每天"上班"和"下班"的流程:```markdown-## 每次會話開始時(上班打卡)-1. 讀 PROGRESS.md 了解当前狀態+## 每次工作階段開始時(上班打卡)+1. 讀 PROGRESS.md 了解目前狀態2. 讀 DECISIONS.md 了解重要决策-3. 跑 make check 确認倉庫處于一致狀態+3. 跑 make check 确認儲存庫處于一致狀態4. 從 PROGRESS.md 的"下一步"部分继續工作-## 每次會話結束前(下班打卡)+## 每次工作階段結束前(下班打卡)1. 更新 PROGRESS.md2. 跑 make check 确認一致狀態3. 提交所有已完成的工作```-**混合策略**:不需要每次都重置上下文。短任務(30 分鐘以內)可以在同一個會話裡完成。長任務(跨會話)必須用進度檔案和決策日誌來維持連續性。判斷標準:如果任務需要的上下文超過窗口的 60%,就開始準備交接。+**混合策略**:不需要每次都重置脈絡。短任務(30 分鐘以內)可以在同一個工作階段裡完成。長任務(跨工作階段)必須用進度檔案和決策日誌來維持連續性。判斷標準:如果任務需要的脈絡超過視窗的 60%,就開始準備交接。-### 上下文焦慮的深層分析+### 脈絡焦慮的深層分析-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 設計需要對目標模型有具體的理解,而不是套用通用範本。**+Anthropic 的實際數據:對於 Sonnet 4.5,脈絡焦慮足夠嚴重,以至於壓縮單獨不夠用,脈絡重置成為 harness 設計的關鍵組件。但對於 Opus 4.5,這種行為大幅減弱,可以不依賴重置而靠壓縮管理脈絡。這意味著:**harness 設計需要對目標模型有具體的理解,而不是套用通用範本。**> 來源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)## 實際案例-一個 agent 被要求實現一個帶用戶認證的博客系統,12 個功能點,預計需要 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 個功能點完成且通過驗證。+**有日記本的對照**:使用進度檔案、決策日誌、驗證記錄和 git 檢查點。每個工作階段結束時自動更新狀態報告。工作階段 2 的重建成本降到約 3 分鐘。到工作階段 5,所有 12 個功能點完成且通過驗證。定量對比:重建時間減少約 78%,功能完成率從 58% 提升到 100%,隱含缺陷率從 43% 降到 8%。工匠還是那個會失憶的工匠,但有了日記本,他的每一天都從昨天停下的地方開始,而不是從零開始。## 關鍵要點-- 上下文窗口是有限的資源。長任務一定會跨會話,跨會話一定會丟信息——這就像工匠每天都會失憶一樣,是客觀現實。-- 解決方案不是更大的窗口,而是更好的狀態持久化。進度檔案 + 決策日誌 + git 檢查點——給失憶的工匠一個靠譜的日記本。+- 脈絡視窗是有限的資源。長任務一定會跨工作階段,跨工作階段一定會丟資訊——這就像工匠每天都會失憶一樣,是客觀現實。+- 解決方案不是更大的視窗,而是更好的狀態持久化。進度檔案 + 決策日誌 + git 檢查點——給失憶的工匠一個可靠的日記本。- 把 agent 當成會失憶的工程師來管理:每次"下班"前寫清楚做了什麼、為什麼、下一步做什麼。-- 重建成本是關鍵指標。好的 harness 應該讓新會話在 3 分鐘內恢復到可執行狀態。-- 混合策略:短任務在會話內完成,長任務用結構化工件維持連續性。+- 重建成本是關鍵指標。好的 harness 應該讓新工作階段在 3 分鐘內恢復到可執行狀態。+- 混合策略:短任務在工作階段內完成,長任務用結構化工件維持連續性。## 延伸閱讀@@ -173,8 +173,8 @@ Anthropic 的實際數據:對於 Sonnet 4.5,上下文焦慮足夠嚴重,## 練習-1. **連續性損耗度量**:選一個需要至少 3 個會話的開發任務。不提供任何連續性工件,在每個會話開始時記錄 agent 花了多少上下文來"搞清楚上次做了什麼"。會話結束後,創建進度檔案,讓下一個會話從進度檔案開始。對比有進度檔案和沒有時的重建成本。+1. **連續性損耗度量**:選一個需要至少 3 個工作階段的開發任務。不提供任何連續性工件,在每個工作階段開始時記錄 agent 花了多少脈絡來"搞清楚上次做了什麼"。工作階段結束後,建立進度檔案,讓下一個工作階段從進度檔案開始。對比有進度檔案和沒有時的重建成本。-2. **交接範本設計**:設計一個最小化的交接範本,包含四個字段:倉庫狀態(commit hash)、運行時狀態(測試通過率)、阻塞項、下一步行動。讓一個全新的 agent 會話只憑這個範本恢復項目狀態,記錄恢復過程中出現的歧義點,迭代改進範本。+2. **交接範本設計**:設計一個最小化的交接範本,包含四個字段:儲存庫狀態(commit hash)、執行時期狀態(測試通過率)、阻塞項、下一步行動。讓一個全新的 agent 工作階段只憑這個範本恢復專案狀態,記錄恢復過程中出現的歧義點,迭代改進範本。-3. **混合策略實驗**:在一個包含 5 個會話的開發任務中,對比三種策略:(a) 每次都開全新會話 + 進度檔案,(b) 在同一個會話裡儘可能多做(上下文壓縮),(c) 混合策略(短任務在會話內,長任務跨會話 + 進度檔案)。對比重建時間、功能完成率和決策一致性。+3. **混合策略實驗**:在一個包含 5 個工作階段的開發任務中,對比三種策略:(a) 每次都開全新工作階段 + 進度檔案,(b) 在同一個工作階段裡儘可能多做(脈絡壓縮),(c) 混合策略(短任務在工作階段內,長任務跨工作階段 + 進度檔案)。對比重建時間、功能完成率和決策一致性。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 a955893..fcfb559 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@@ -1,107 +1,107 @@[English Version →](../../../en/lectures/lecture-06-why-initialization-needs-its-own-phase/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)> 實戰練習:[Project 03. 讓 agent 關掉再打開還能接著幹](./../../projects/project-03-multi-session-continuity/index.md)# 第六講. 讓 agent 每次工作前先初始化-你開了一個新的 agent 會話,讓它"幫我加個搜索功能"。它上來就開始改代碼——精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現數據庫遷移腳本格式不對,又折騰了一會兒。最後搜索功能倒是加了,但整個會話的效率很低——大部分時間花在了"搞清楚這個項目怎麼運作"上,而不是寫搜索功能。+你開了一個新的 agent 工作階段,讓它"幫我加個搜索功能"。它上來就開始改程式碼——精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現數據庫遷移腳本格式不對,又折騰了一會兒。最後搜索功能倒是加了,但整個工作階段的效率很低——大部分時間花在了"搞清楚這個專案怎麼運作"上,而不是寫搜索功能。-更好的做法是:在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、項目結構搞清楚。就像蓋房子——你不能邊打地基邊砌牆,不然牆砌到一半地基還沒幹,整棟樓都得推倒重來。先打地基,地基幹了,再砌牆,一氣呵成。+更好的做法是:在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、專案結構搞清楚。就像蓋房子——你不能邊打地基邊砌牆,不然牆砌到一半地基還沒幹,整棟樓都得推倒重來。先打地基,地基幹了,再砌牆,一氣呵成。-這節課講的就是為什麼初始化必須是獨立的階段,不能跟實現混在一起。+這節課講的就是為什麼初始化必須是獨立的階段,不能跟實作混在一起。## 地基和牆:兩種完全不同的工作-初始化和實現的優化目標完全不同。實現階段的目標是:最大化已驗證功能的數量和質量。初始化階段的目標是:最大化後續所有實現的可靠性和效率。+初始化和實作的最佳化目標完全不同。實作階段的目標是:最大化已驗證功能的數量和質量。初始化階段的目標是:最大化後續所有實作的可靠性和效率。-當你把初始化和實現混在一起的時候,agent 面臨一個多目標優化問題——它要同時搭基礎設施和寫功能代碼。在沒有顯式優先級設定的情況下,agent 自然傾向於寫代碼(因為那是直接可見的產出),而犧牲基礎設施(因為它的價值只能在後續會話中體現)。這就像讓施工隊同時打地基和砌牆——他們大概率會急著砌牆,因為牆看得見、能交差。但地基沒打好的房子,後面出的問題是系統性的。+當你把初始化和實作混在一起的時候,agent 面臨一個多目標最佳化問題——它要同時搭基礎設施和寫功能程式碼。在沒有顯式優先級設定的情況下,agent 自然傾向於寫程式碼(因為那是直接可見的產出),而犧牲基礎設施(因為它的價值只能在後續工作階段中體現)。這就像讓施工隊同時打地基和砌牆——他們很可能會急著砌牆,因為牆看得見、能交差。但地基沒打好的房子,後面出的問題是系統性的。## 初始化生命週期```mermaidflowchart TB- subgraph Wrong["混在一起的一次會話(錯誤)"]- W1["一上來就開始做功能"] --> W2["做到一半才發现环境和測試缺口"]+ subgraph Wrong["混在一起的一次工作階段(錯誤)"]+ W1["一上來就開始做功能"] --> W2["做到一半才發現環境和測試缺口"]W2 --> W3["累积未经驗證的程式碼"]- W3 --> W4["下個會話还得重新摸專案狀態"]+ W3 --> W4["下個工作階段還得重新摸專案狀態"]end- subgraph Right["獨立初始化阶段(正确)"]- R1["會話 1:环境可執行"] --> R2["示例測試通過"]- R2 --> R3["寫出啟動契约 + 任務清單"]- R3 --> R4["提交干净檢查点"]- R4 --> R5["後續會話直接開始做已準备好的任務"]+ subgraph Right["獨立初始化階段(正確)"]+ R1["工作階段 1:環境可執行"] --> R2["示例測試通過"]+ R2 --> R3["寫出啟動契約 + 任務清單"]+ R3 --> R4["提交乾淨檢查点"]+ R4 --> R5["後續工作階段直接開始做已準备好的任務"]end```## 混在一起做會怎樣-最直接的問題:地基打不牢。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 生命週期中的第一個階段,不做功能實作,只建立後續所有實作階段的執行前提。輸出不是程式碼,而是基礎設施。+- **自舉契約**:一個專案能被全新 agent 工作階段無歧義操作的條件——能啟動、能測試、能看進度、能接手下一步。四個條件缺一不可。+- **冷啟動 vs 熱啟動**:冷啟動是從空目錄開始,agent 要猜專案結構;熱啟動是從範本或已有專案開始,基礎設施已經就位。熱啟動的效果遠好於冷啟動——就像在有水電的工地上開工,比在荒郊野嶺從頭搞起快得多。+- **交接就緒性**:專案在任何時刻都處於"可以被全新 agent 接手"的狀態。不需要口頭解釋,只看儲存庫內容就能接著幹。+- **首次驗證時間**:從專案開始到第一個功能點通過驗證的時間。這是衡量初始化效率的核心指標。+- **下游可用性**:初始化質量的最佳衡量標準——後續工作階段不需要依賴隱式知識就能成功執行任務的比例。## 怎麼做好初始化-**把初始化當作一個獨立的階段來執行。** 第一個會話只做初始化,不寫任何業務功能代碼。初始化的產出是:+**把初始化當作一個獨立的階段來執行。** 第一個工作階段只做初始化,不寫任何業務功能程式碼。初始化的產出是:-**1. 可運行的環境。** 項目能啟動、依賴都裝好、沒有環境問題。地基澆好了,沒裂縫。+**1. 可執行的環境。** 專案能啟動、依賴都裝好、沒有環境問題。地基澆好了,沒裂縫。**2. 可驗證的測試框架。** 至少有一個示例測試能通過。這證明測試框架本身是配對的——就像地基上立了一根柱子,證明地基能承重。-**3. 自舉契約文檔。** 一個明確的文檔告訴後續會話:+**3. 自舉契約文件。** 一個明確的文件告訴後續工作階段:```markdown-# 初始化契约+# 初始化契約## 啟動命令-- 安装依赖:`make setup`+- 安裝相依:`make setup`- 啟動開發服務器:`make dev`- 執行測試:`make test`- 完整驗證:`make check`-## 当前狀態-- 所有依赖已安装並锁定+## 目前狀態+- 所有相依已安裝並鎖定- 測試框架已配置(Vitest + React Testing Library)- 示例測試通過(1/1)-- Lint 规则已配置(ESLint + Prettier)+- Lint 規則已配置(ESLint + Prettier)## 專案結構- src/ — 源程式碼-- src/components/ — React 组件-- src/api/ — API 客户端+- src/components/ — React 元件+- src/api/ — API 用戶端- tests/ — 測試檔案```-**4. 任務分解。** 把整個項目拆成有序的任務列表,每個任務有明確的驗收標準:+**4. 任務分解。** 把整個專案拆成有序的任務列表,每個任務有明確的驗收標準:```markdown# 任務分解## Task 1: 使用者認證基础-- 實作 JWT 認證中间件-- 添加登录/注册端点-- 验收標準:pytest tests/test_auth.py 全部通過+- 實作 JWT 認證中介層+- 添加登入/註冊端點+- 驗收標準:pytest tests/test_auth.py 全部通過-## Task 2: 使用者資料页面+## Task 2: 使用者資料頁面- 實作使用者資料 CRUD-- 添加資料编辑表單-- 验收標準:pytest tests/test_profile.py 全部通過+- 添加資料編輯表單+- 驗收標準:pytest tests/test_profile.py 全部通過## Task 3: 搜索功能- ...@@ -109,36 +109,36 @@ OpenAI 的 Codex harness engineering 指南也強調"倉庫作為操作記錄"**5. Git 提交作為檢查點。** 初始化完成後提交一個乾淨的 checkpoint。後續所有工作都從這個 checkpoint 開始。-**熱啟動策略**:不要從空目錄開始。用一個項目範本(create-react-app、fastapi-template 等)預置好標準的目錄結構、依賴配置和測試框架。把通用的初始化步驟預置到範本裡,只留下項目特有的初始化工作。就像在有通水通電的工地上開工,比從荒郊野嶺開始強一萬倍。+**熱啟動策略**:不要從空目錄開始。用一個專案範本(create-react-app、fastapi-template 等)預置好標準的目錄結構、依賴配置和測試框架。把通用的初始化步驟預置到範本裡,只留下專案特有的初始化工作。就像在有通水通電的工地上開工,比從荒郊野嶺開始強一萬倍。-**初始化的完成條件**:不是"寫了多少代碼",而是自舉契約的四個條件都滿足了——能啟動、能測試、能看進度、能接手下一步。用這個檢查清單驗收初始化:+**初始化的完成條件**:不是"寫了多少程式碼",而是自舉契約的四個條件都滿足了——能啟動、能測試、能看進度、能接手下一步。用這個檢查清單驗收初始化:```markdown-## 初始化验收清單+## 初始化驗收清單- [ ] `make setup` 從零開始能成功- [ ] `make test` 至少有一個測試通過-- [ ] 新的 agent 會話能只看倉庫回答"怎么跑"和"怎么測"+- [ ] 新的 agent 工作階段能只看儲存庫回答"怎麼跑"和"怎麼測"- [ ] 任務分解檔案存在且有至少 3 個任務- [ ] 所有内容已提交到 git```## 實際案例-一個 React 前端項目的兩種初始化方式對比:+一個 React 前端專案的兩種初始化方式對比:-**混合方式(邊打地基邊砌牆)**:agent 在第一個會話中同時做了項目腳手架創建和首個功能實現。會話結束時,倉庫有可運行的代碼,但:沒有顯式的啟動/測試命令文檔、沒有進度跟蹤檔案、沒有任務分解。第二個會話花了約 20 分鐘推斷項目結構、測試框架和構建流程——就像新來的施工隊看著一片工地,不知道地基打到什麼程度、水電管道走到哪了,只能一個個挖開來看。+**混合方式(邊打地基邊砌牆)**:agent 在第一個工作階段中同時做了專案腳手架建立和首個功能實作。工作階段結束時,儲存庫有可執行的程式碼,但:沒有顯式的啟動/測試命令文件、沒有進度跟蹤檔案、沒有任務分解。第二個工作階段花了約 20 分鐘推斷專案結構、測試框架和建構流程——就像新來的施工隊看著一片工地,不知道地基打到什麼程度、水電管道走到哪了,只能一個個挖開來看。-**獨立初始化(先打地基)**:第一個會話只做初始化——用項目範本創建目錄結構、配置測試框架(Vitest + React Testing Library)、寫一個示例測試並驗證通過、創建自舉契約文檔和任務分解檔案、提交初始檢查點。第二個會話的重建時間不到 3 分鐘,直接從任務列表開始工作——施工隊來了,看了一眼施工圖就知道從哪裡接著幹。+**獨立初始化(先打地基)**:第一個工作階段只做初始化——用專案範本建立目錄結構、配置測試框架(Vitest + React Testing Library)、寫一個示例測試並驗證通過、建立自舉契約文件和任務分解檔案、提交初始檢查點。第二個工作階段的重建時間不到 3 分鐘,直接從任務列表開始工作——施工隊來了,看了一眼施工圖就知道從哪裡接著幹。-整個項目週期對比:混合方式的總重建時間(跨所有會話)比獨立初始化多約 60%。獨立初始化多花的那 20 分鐘在後續會話中被成倍收回。就像地基打得紮實,上面蓋樓的效率反而更高——慢即是快。+整個專案週期對比:混合方式的總重建時間(跨所有工作階段)比獨立初始化多約 60%。獨立初始化多花的那 20 分鐘在後續工作階段中被成倍收回。就像地基打得紮實,上面蓋樓的效率反而更高——慢即是快。## 關鍵要點-- 初始化和實現的優化目標不同,混在一起只會互相拖後腿。先打地基,再砌牆。-- 初始化的產出不是代碼,是基礎設施:可運行的環境、可驗證的測試、自舉契約、任務分解。+- 初始化和實作的最佳化目標不同,混在一起只會互相拖後腿。先打地基,再砌牆。+- 初始化的產出不是程式碼,是基礎設施:可執行的環境、可驗證的測試、自舉契約、任務分解。- 用"自舉契約"的四個條件驗收初始化:能啟動、能測試、能看進度、能接手下一步。-- 熱啟動優於冷啟動。用項目範本預置標準化的基礎設施。-- 初始化投入的時間會在後續 3-4 個會話中完全收回。這不是額外的成本,是前期投資——地基打得越紮實,樓蓋得越快。+- 熱啟動優於冷啟動。用專案範本預置標準化的基礎設施。+- 初始化投入的時間會在後續 3-4 個工作階段中完全收回。這不是額外的成本,是前期投資——地基打得越紮實,樓蓋得越快。## 延伸閱讀@@ -150,8 +150,8 @@ OpenAI 的 Codex harness engineering 指南也強調"倉庫作為操作記錄"## 練習-1. **自舉契約設計**:為一個你正在開發的項目寫一個完整的自舉契約。然後開一個全新的 agent 會話,只給它看倉庫內容(不給任何口頭上下文),讓它嘗試啟動項目、跑測試、瞭解當前進度。記錄它遇到的問題——每個問題都對應自舉契約中缺失的一個條款。+1. **自舉契約設計**:為一個你正在開發的專案寫一個完整的自舉契約。然後開一個全新的 agent 工作階段,只給它看儲存庫內容(不給任何口頭脈絡),讓它嘗試啟動專案、跑測試、瞭解目前進度。記錄它遇到的問題——每個問題都對應自舉契約中缺失的一個條款。-2. **對比實驗**:選一箇中等複雜度的新項目。方式 A:讓 agent 初始化和首次實現同時做。方式 B:先花一個會話做獨立初始化,第二個會話開始實現。在 4 個會話後對比:首次驗證時間、重建成本、功能完成率。+2. **對比實驗**:選一箇中等複雜度的新專案。方式 A:讓 agent 初始化和首次實作同時做。方式 B:先花一個工作階段做獨立初始化,第二個工作階段開始實作。在 4 個工作階段後對比:首次驗證時間、重建成本、功能完成率。-3. **初始化驗收清單**:為你的項目設計一個初始化驗收清單。讓一個全新的 agent 會話執行清單上的每一項,記錄哪些項通過了、哪些沒通過。沒通過的項就是你的 harness 需要補強的地方。+3. **初始化驗收清單**:為你的專案設計一個初始化驗收清單。讓一個全新的 agent 工作階段執行清單上的每一項,記錄哪些項通過了、哪些沒通過。沒通過的項就是你的 harness 需要補強的地方。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 2bc1eaf..04e72f4 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@@ -1,134 +1,134 @@[English Version →](../../../en/lectures/lecture-07-why-agents-overreach-and-under-finish/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)-> 實戰練習:[Project 04. 用運行反饋修正 agent 的行為](./../../projects/project-04-incremental-indexing/index.md)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)+> 實戰練習:[Project 04. 用執行回饋修正代理的行為](./../../projects/project-04-incremental-indexing/index.md)# 第七講. 給 agent 劃清每次任務的邊界-你讓 Claude Code "給這個項目加上用戶認證功能",結果它同時開始改數據庫 schema、寫路由、改前端組件、還順手重構了錯誤處理中間件。兩個小時後你一看——12 個檔案被修改,800 行新代碼,但沒有一個功能是端到端跑通的。+你讓 Claude Code「給這個專案加上使用者認證功能」,結果它同時開始改資料庫 schema、寫路由、改前端元件、還順手重構了錯誤處理中介軟體。兩個小時後你一看——12 個檔案被修改,800 行新程式碼,但沒有一個功能是端到端跑通的。貪多嚼不爛,這句話放到 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 的真實行為很說明問題。你讓它"添加用戶註冊功能",它很可能這樣做:+Claude Code 的真實行為很說明問題。你讓它「新增使用者註冊功能」,它很可能這樣做:-1. 創建 User model+1. 建立 User model2. 寫註冊路由-3. 發現需要郵箱驗證,於是加郵件服務+3. 發現需要電子郵件驗證,於是加郵件服務4. 看到密碼需要加密,於是引入 bcrypt-5. 注意到錯誤處理不統一,於是重構全局錯誤中間件+5. 注意到錯誤處理不統一,於是重構全局錯誤中介軟體6. 看到測試檔案結構不清晰,於是重組目錄結構-6 步之後,每一個都是半成品。沒有端到端驗證,代碼之間耦合複雜,下一個會話來接手時會一臉懵。就像一個人同時炒六道菜,每道菜都下了鍋但沒有一道出鍋——全糊了。+6 步之後,每一個都是半成品。沒有端到端驗證,程式碼之間耦合複雜,下一個工作階段來接手時會一臉懵。就像一個人同時炒六道菜,每道菜都下了鍋但沒有一道出鍋——全糊了。-Anthropic 的實驗數據直接支持這一點:使用"小下一步"策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的代碼行數和實際完成的功能數量呈弱負相關——寫得越多,完成得越少。貪多嚼不爛,數據為證。+Anthropic 的實驗數據直接支援這一點:使用「小下一步」策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的程式碼行數和實際完成的功能數量呈弱負相關——寫得越多,完成得越少。貪多嚼不爛,數據為證。## WIP=1 工作流```mermaidflowchart LR- Queue["功能队列"] --> Pick["只選一個任務"]- Pick --> Active["仅允许一個 active"]+ Queue["功能佇列"] --> Pick["只選一個任務"]+ Pick --> Active["僅允許一個 active"]Active --> Verify["跑端到端驗證"]- Verify -->|通過| Commit["提交並解锁下一個任務"]+ Verify -->|通過| Commit["提交並解鎖下一個任務"]Verify -->|失敗| ActiveCommit --> Queue``````mermaidflowchart TB- Budget["可用推理预算 = C"] --> One["WIP = 1<br/>每個任務拿到 C / 1"]+ Budget["可用推理預算 = C"] --> One["WIP = 1<br/>每個任務拿到 C / 1"]Budget --> Many["WIP = 5<br/>每個任務只有 C / 5"]- One --> Finish["一個功能进入 passing"]+ One --> Finish["一個功能進入 passing"]Many --> Partial["五個功能都只做了一半"]- Partial --> VCR["已驗證完成率低<br/>下一會話返工高"]+ Partial --> VCR["已驗證完成率低<br/>下一工作階段返工高"]```## 核心概念-- **過度延伸(Overreach)**:agent 在一次會話中激活的任務數量超過最優值。它不是主觀判斷,而是可量化的——同時做 5 個功能但 0 個跑通,就是 overreach。-- **不足完成(Under-finish)**:已啟動的任務中,通過端到端驗證的比例低於閾值。寫了代碼但沒跑通測試,就是 under-finish。-- **WIP 限制(Work-in-Progress Limit)**:來自 Kanban 方法論。核心思想:限制同時在進行的任務數量。對於 agent,WIP=1 是最安全的默認值——做完一個再做下一個。就像自助餐廳不要一次拿太多盤子,吃完一盤再去拿下一盤。-- **完成證據(Completion Evidence)**:一個任務從"進行中"變成"已完成"必須滿足的可驗證條件。沒有這個,agent 會用"代碼看起來沒問題"代替"行為通過測試"。+- **過度延伸(Overreach)**:agent 在一次工作階段中啟動的任務數量超過最優值。它不是主觀判斷,而是可量化的——同時做 5 個功能但 0 個跑通,就是 overreach。+- **不足完成(Under-finish)**:已啟動的任務中,通過端到端驗證的比例低於閾值。寫了程式碼但沒跑通測試,就是 under-finish。+- **WIP 限制(Work-in-Progress Limit)**:來自 Kanban 方法論。核心思想:限制同時在進行的任務數量。對於 agent,WIP=1 是最安全的預設值——做完一個再做下一個。就像自助餐廳不要一次拿太多盤子,吃完一盤再去拿下一盤。+- **完成證據(Completion Evidence)**:一個任務從「進行中」變成「已完成」必須滿足的可驗證條件。沒有這個,agent 會用「程式碼看起來沒問題」代替「行為通過測試」。- **範圍表面(Scope Surface)**:一個 DAG 結構,每個節點是一個工作單元,邊是依賴關係。狀態只有四種:未開始、進行中、阻塞、已通過。-- **完成壓力(Completion Pressure)**:harness 通過 WIP 限制和完成證據要求共同產生的約束力,迫使 agent 先完成當前任務再開始新任務。+- **完成壓力(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 的注意力。就像在自助餐廳裡,每多拿一個盤子的邊際成本幾乎為零,但你的胃只有那麼大。## 怎麼做才對### 1. 強制 WIP=1-這是最直接有效的方法。在你的 harness 裡,明確告訴 agent:**任何時刻只允許一個任務處於"進行中"狀態。** 在 Claude Code 的 CLAUDE.md 或 Codex 的 AGENTS.md 裡寫:+這是最直接有效的方法。在你的 harness 裡,明確告訴 agent:**任何時刻只允許一個任務處於「進行中」狀態。** 在 Claude Code 的 CLAUDE.md 或 Codex 的 AGENTS.md 裡寫:```-## 工作规则-- 每次只做一個功能点-- 当前功能点端到端驗證通過後,才能開始下一個-- 不要在實作功能 A 時"顺便"重构功能 B+## 工作規則+- 每次只做一個功能項+- 目前功能項端到端驗證通過後,才能開始下一個+- 不要在實作功能 A 時「順便」重構功能 B```就像吃自助餐——一次只拿一盤,吃完再去拿。### 2. 給每個任務定義顯式的完成證據-完成不是"代碼寫完了",而是"行為驗證通過了"。在你的功能列表裡,每個條目都要有驗證命令:+完成不是「程式碼寫完了」,而是「行為驗證通過了」。在你的功能列表裡,每個條目都要有驗證命令:```-F01: 使用者注册+F01: 使用者註冊驗證: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201狀態: passing```### 3. 把範圍表面外部化-用一個機器可讀的檔案(JSON 或 Markdown)記錄所有任務的狀態。任何新會話都能直接讀這個檔案,知道:哪個任務在做?什麼行為算完成?已經通過了什麼驗證?+用一個機器可讀的檔案(JSON 或 Markdown)記錄所有任務的狀態。任何新工作階段都能直接讀這個檔案,知道:哪個任務在做?什麼行為算完成?已經通過了什麼驗證?-### 4. 監控驗證完成率+### 4. 追蹤驗證完成率harness 應該持續跟蹤 VCR(Verified Completion Rate)= 已通過驗證的任務數 / 已啟動的任務數。VCR < 1.0 時,阻止新任務啟動。## 實際案例-一個 8 個功能點的 REST API 項目,兩種策略對比:+一個 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 個因外部依賴被阻塞)。+**單盤模式(WIP=1)**:agent 在第一個工作階段只做使用者註冊。產出約 200 行程式碼,涉及 4 個檔案。端到端測試 100% 通過。提交乾淨的、已驗證的實現。到第 4 個工作階段結束,8 個功能完成 7 個(第 8 個因外部依賴被阻塞)。-結果:總代碼量更少(800 行 vs 1200 行),但有效代碼更多。完成率 87.5% vs 37.5%。一口一口吃,反而吃得最多。+結果:總程式碼量更少(800 行 vs 1200 行),但有效程式碼更多。完成率 87.5% vs 37.5%。一口一口吃,反而吃得最多。## 關鍵要點-- **WIP=1 是 agent harness 的默認安全設置**——做完一個再做下一個,不要試圖並行。一口吃不成胖子。-- **完成證據必須是可執行的**——"代碼看起來沒問題"不算完成,"curl 返回 201"才算。-- **範圍表面必須外部化為檔案**——不能只在對話裡說,必須在倉庫裡有機器可讀的記錄。+- **WIP=1 是 agent harness 的預設安全設置**——做完一個再做下一個,不要試圖並行。一口吃不成胖子。+- **完成證據必須是可執行的**——「程式碼看起來沒問題」不算完成,「curl 返回 201」才算。+- **範圍表面必須外部化為檔案**——不能只在對話裡說,必須在儲存庫裡有機器可讀的記錄。- **overreach 和 under-finish 是共生問題**——解決一個就解決了另一個。-- **"少做但做完"永遠優於"多做但做半"**——agent 代碼行數和功能完成率呈負相關。質量永遠比數量重要。+- **「少做但做完」永遠優於「多做但做半」**——agent 程式碼行數和功能完成率呈負相關。質量永遠比數量重要。## 延伸閱讀-- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropic 工程博客,詳細論述了"小下一步"策略+- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropic 工程部落格,詳細論述了「小下一步」策略- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — OpenAI 對 harness 工程的完整論述- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — WIP 限制的經典來源-- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — 範圍蔓延作為項目失敗首要原因的實證數據+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — 範圍蔓延作為專案失敗首要原因的實證資料## 練習-1. **任務原子化練習**:選一個寬泛需求(如"實現用戶管理系統"),把它拆成至少 5 個原子工作單元。每個單元寫清楚:(a) 單一行為描述,(b) 可執行的驗證命令,(c) 依賴關係。檢查是否滿足 WIP=1 的約束。+1. **任務原子化練習**:選一個寬泛需求(如「實現使用者管理系統」),把它拆成至少 5 個原子工作單元。每個單元寫清楚:(a) 單一行為描述,(b) 可執行的驗證命令,(c) 依賴關係。檢查是否滿足 WIP=1 的約束。-2. **對比實驗**:在同一個項目上跑兩次——一次不給約束,一次強制 WIP=1。比較:驗證完成率、總代碼行數、有效代碼比例。+2. **對比實驗**:在同一個專案上跑兩次——一次不給約束,一次強制 WIP=1。比較:驗證完成率、總程式碼行數、有效程式碼比例。-3. **完成證據審計**:回顧一個最近的 agent 運行結果,把每個代碼變更分類為"已完成行為"、"未完成行為"或"腳手架"。給每個未完成行為補充缺失的驗證命令。+3. **完成證據審計**:回顧一個最近的 agent 執行結果,把每個程式碼變更分類為「已完成行為」、「未完成行為」或「腳手架」。給每個未完成行為補充缺失的驗證命令。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 6bd4ef7..c84a30c 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@@ -1,41 +1,41 @@[English Version →](../../../en/lectures/lecture-08-why-feature-lists-are-harness-primitives/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)-> 實戰練習:[Project 04. 用運行反饋修正 agent 的行為](./../../projects/project-04-incremental-indexing/index.md)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)+> 實戰練習:[Project 04. 用執行回饋修正代理的行為](./../../projects/project-04-incremental-indexing/index.md)# 第八講. 用功能清單約束 agent 該做什麼-你讓 agent 做一個電商網站,跑完之後它告訴你"做完了"。你打開代碼一看——用戶認證有了,但購物車的結算按鈕點了沒反應,支付流程根本沒接上。問題是:你從來沒告訴它"做完"的標準是什麼,所以它用自己的標準——"代碼寫了不少,看起來挺完整"。+你讓 agent 做一個電商網站,跑完之後它告訴你「做完了」。你打開程式碼一看——使用者認證有了,但購物車的結算按鈕點了沒反應,支付流程根本沒接上。問題是:你從來沒告訴它「做完」的標準是什麼,所以它用自己的標準——「程式碼寫了不少,看起來挺完整」。功能清單(feature list)在很多人眼裡就是個備忘錄——寫下來怕忘了,寫完扔在一邊。但在 harness 的世界裡,功能清單不是給人看的備忘錄,而是整個 harness 的脊樑骨。調度器靠它選任務,驗證器靠它判完成,交接器靠它生成報告。脊樑骨斷了,全身都癱。-Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須是倉庫裡機器可讀的檔案,不能是對話裡的非結構化描述。+Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須是儲存庫裡機器可讀的檔案,不能是對話裡的非結構化描述。## Agent 不知道"做完"是什麼意思-Claude Code 和 Codex 都不會自動知道你心目中的"做完"是什麼意思。你說"加一個購物車功能",模型的理解可能是"寫一個 Cart 組件和 addToCart 方法"。而你的意思是"用戶能從瀏覽商品到下單支付完整走通"。+Claude Code 和 Codex 都不會自動知道你心目中的「做完」是什麼意思。你說「加一個購物車功能」,模型的理解可能是「寫一個 Cart 元件和 addToCart 方法」。而你的意思是「使用者能從瀏覽商品到下單支付完整走通」。-這個理解鴻溝在沒有功能清單的情況下會持續存在。agent 用自己的隱式標準判斷完成——通常是"代碼沒有明顯的語法錯誤"。而你需要的是端到端的行為驗證。就像你讓朋友幫你買菜,說"買點水果",他拎了一袋檸檬回來——他要的水果,你要的水果,不是一個水果。+這個理解鴻溝在沒有功能清單的情況下會持續存在。agent 用自己的隱式標準判斷完成——通常是「程式碼沒有明顯的語法錯誤」。而你需要的是端到端的行為驗證。就像你讓朋友幫你買菜,說「買點水果」,他拎了一袋檸檬回來——他要的水果,你要的水果,不是一個水果。看看這種常見的進度記錄:```-做了使用者認證、购物车基本完成了、还需要做支付+做了使用者認證、購物車基本完成了、還需要做支付```-新的 agent 會話看到這個記錄,能回答以下問題嗎?"基本完成"意味著什麼?購物車通過了哪些測試?支付的阻塞條件是什麼?答案都是"不知道"。就像你看病時跟醫生說"我肚子疼,最近還行",醫生能開出什麼藥來?+新的 agent 工作階段看到這個記錄,能回答以下問題嗎?「基本完成」意味著什麼?購物車通過了哪些測試?支付的阻塞條件是什麼?答案都是「不知道」。就像你看病時跟醫生說「我肚子疼,最近還行」,醫生能開出什麼藥來?-結果是:新會話花 20 分鐘推斷項目狀態,最終可能重複實現已完成的功能。Anthropic 的工程實踐數據表明,好的進度記錄可以減少 60-80% 的會話啟動診斷時間。+結果是:新工作階段花 20 分鐘推斷專案狀態,最終可能重複實現已完成的功能。Anthropic 的工程實踐數據表明,好的進度記錄可以減少 60-80% 的工作階段啟動診斷時間。## 功能狀態機```mermaidflowchart LR- Feature["一行功能项"] --> Behavior["行為<br/>例如:POST /cart/items 返回 201"]- Feature --> Check["驗證命令<br/>具体要跑什么檢查"]+ Feature["一行功能項"] --> Behavior["行為<br/>例如:POST /cart/items 返回 201"]+ Feature --> Check["驗證命令<br/>具體要跑什麼檢查"]Feature --> State["狀態<br/>not_started / active / blocked / passing"]- Behavior --> Complete["三列都齐了<br/>這行功能项才能用"]+ Behavior --> Complete["三列都齊了<br/>這行功能項才能用"]Check --> CompleteState --> Complete```@@ -43,36 +43,36 @@ flowchart LR```mermaidflowchart LRList["feature_list.json / features.md"] --> Scheduler["選下一個 not_started"]- Scheduler --> Agent["agent 只做這一项"]- Agent --> Verifier["跑這一项自己的驗證命令"]- Verifier -->|通過| Passing["寫成 passing<br/>並补上驗證證據"]- Verifier -->|失敗| Active["继續保持 active"]- Verifier -->|依赖問題| Blocked["標成 blocked"]- Passing --> Handoff["更新交接說明<br/>和当前進度"]+ Scheduler --> Agent["agent 只做這一項"]+ Agent --> Verifier["跑這一項自己的驗證命令"]+ Verifier -->|通過| Passing["寫成 passing<br/>並補上驗證證據"]+ Verifier -->|失敗| Active["繼續保持 active"]+ Verifier -->|依賴問題| Blocked["標成 blocked"]+ Passing --> Handoff["更新交接說明<br/>和目前進度"]Active --> Agent```## 核心概念-- **功能清單是 harness 原語**:它不是"可選的規劃工具",而是其他所有 harness 組件依賴的基礎數據結構。就像數據庫裡的表結構——你不能說"要不我們省掉主鍵吧",省掉了整個系統就散架了。-- **三元組結構**:每個功能項是 `(行為描述, 驗證命令, 当前狀態)` 的三元組。缺了任何一項,這個功能項就不完整。行為描述告訴 agent 做什麼,驗證命令告訴它怎麼算做完,狀態告訴它現在到哪了。+- **功能清單是 harness 原語**:它不是「可選的規劃工具」,而是其他所有 harness 元件依賴的基礎資料結構。就像資料庫裡的表結構——你不能說「要不我們省掉主索引鍵吧」,省掉了整個系統就解體了。+- **三元組結構**:每個功能項是 `(行為描述, 驗證命令, 目前狀態)` 的三元組。缺了任何一項,這個功能項就不完整。行為描述告訴 agent 做什麼,驗證命令告訴它怎麼算做完,狀態告訴它現在到哪了。- **狀態機模型**:每個功能項有四種狀態——`not_started`、`active`、`blocked`、`passing`。狀態轉移由 harness 控制,不是 agent 想改就能改。-- **通過狀態門控**:功能從 `active` 變成 `passing` 的唯一方式是驗證命令執行成功。這是不可逆的——`passing` 了就不能退回去。就像考試及格了就是及格了,不能事後改成分數。-- **單一權威來源**:項目裡關於"該做什麼"的所有信息,必須從一個功能清單派生。不能出現功能清單和對話記錄矛盾的情況。-- **反向壓力**:還沒通過的功能項數量就是 harness 對 agent 施加的壓力。壓力歸零 = 項目完成。+- **通過狀態門控**:功能從 `active` 變成 `passing` 的唯一方式是驗證命令執行成功。這是不可逆的——`passing` 了就不能退回去。就像考試及格了就是及格了,不能事後改分數。+- **單一權威來源**:專案裡關於「該做什麼」的所有資訊,必須從一個功能清單派生。不能出現功能清單和對話記錄矛盾的情況。+- **反向壓力**:還沒通過的功能項數量就是 harness 對 agent 施加的壓力。壓力歸零 = 專案完成。## 為什麼功能清單必須是"原語"-文檔是給人看的,原語是給系統用的。文檔可以被忽略,原語不能被繞過。+文件是給人看的,原語是給系統用的。文件可以被忽略,原語不能被繞過。-類比數據庫的觸發器約束和應用層的檢查邏輯:前者由數據庫引擎強制執行,任何 SQL 都無法跳過;後者依賴於應用代碼的正確性,可能被意外繞過。功能清單作為 harness 原語,就是數據庫級別的約束——agent 不能繞過它。+類比資料庫的觸發器約束和應用層的檢查邏輯:前者由資料庫引擎強制執行,任何 SQL 都無法跳過;後者依賴於應用程式碼的正確性,可能被意外繞過。功能清單作為 harness 原語,就是資料庫級別的約束——agent 不能繞過它。-具體來說,功能清單服務四個 harness 組件:+具體來說,功能清單服務四個 harness 元件:1. **調度器**:讀狀態,選下一個 `not_started` 的功能。就像工廠的排產系統——看完訂單才知道下一步做什麼。2. **驗證器**:執行驗證命令,判斷是否允許狀態轉移。就像質檢——不是你說合格就合格,得通過檢驗。-3. **交接報告器**:從功能清單自動生成會話交接摘要。就像換班時自動生成的交接表——不用手寫,系統自己出。-4. **進度追蹤器**:統計各狀態分佈,提供項目健康度指標。就像儀表盤——一眼看出項目走到哪了。+3. **交接報告器**:從功能清單自動生成工作階段交接摘要。就像換班時自動生成的交接表——不用手寫,系統自己出。+4. **進度追蹤器**:統計各狀態分佈,提供專案健康度指標。就像儀表盤——一眼看出專案走到哪了。## 怎麼做@@ -92,51 +92,51 @@ flowchart LR### 2. 讓 harness 控制狀態轉移-agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harness 執行驗證命令,根據結果決定是否允許狀態轉移。這就是"通過狀態門控"——不是你說考過了就考過了,得看成績單。+agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harness 執行驗證命令,根據結果決定是否允許狀態轉移。這就是「通過狀態門控」——不是你說考過了就考過了,得看成績單。### 3. 在 CLAUDE.md 裡寫清楚規則```-## 功能清單规则+## 功能清單規則- 功能清單檔案: /docs/features.md-- 每次只激活一個功能项-- 功能项驗證命令必須通過才能標為 passing-- 不要修改功能清單的狀態——由驗證脚本自動更新+- 每次只啟動一個功能項+- 功能項驗證命令必須通過才能標為 passing+- 不要修改功能清單的狀態——由驗證指令碼自動更新```### 4. 粒度校準-每個功能項應該是"一次會話能完成"的範圍。太粗了做不完,太細了管理開銷大。"用戶可以添加商品到購物車"是一個好粒度,"實現購物車"太粗了,"創建 Cart 模型的 name 字段"太細了。就像切牛排——不能整塊啃,也不能切成肉沫。+每個功能項應該是「一次工作階段能完成」的範圍。太粗了做不完,太細了管理開銷大。「使用者可以新增商品到購物車」是一個好粒度,「實現購物車」太粗了,「建立 Cart 模型的 name 欄位」太細了。就像切牛排——不能整塊啃,也不能切成肉末。## 實際案例-一個電商平臺的開發任務,10 個功能項。對比兩種追蹤方式:+一個電商平台的開發任務,10 個功能項。對比兩種追蹤方式:-**備忘錄模式**:agent 用非結構化筆記記錄進度。3 個會話後,筆記變成了"做了用戶認證和商品列表、購物車基本完成但還有 bug、支付沒開始"。新會話需要 20 分鐘推斷狀態,最終重複實現了已完成的功能。就像你的購物清單上寫著"牛奶、麵包、還有那個什麼來著"——到超市了你還是不知道要買什麼。+**備忘錄模式**:agent 用非結構化筆記記錄進度。3 個工作階段後,筆記變成了「做了使用者認證和商品列表、購物車基本完成但還有 bug、支付沒開始」。新工作階段需要 20 分鐘推斷狀態,最終重複實現了已完成的功能。就像你的購物清單上寫著「牛奶、麵包、還有那個什麼來著」——到超市了你還是不知道要買什麼。-**脊樑骨模式**:每個功能項有明確的狀態和驗證命令。新會話讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。+**脊樑骨模式**:每個功能項有明確的狀態和驗證命令。新工作階段讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。-定量結果:使用結構化功能清單的項目,功能完成率比自由形式高 45%,零重複實現。+定量結果:使用結構化功能清單的專案,功能完成率比自由形式高 45%,零重複實現。## 關鍵要點- **功能清單是 harness 的脊樑骨**,不是給人看的備忘錄。調度器、驗證器、交接器都依賴它。-- **每個功能項必須有三元組**:行為描述 + 驗證命令 + 當前狀態。缺一項就不完整——就像三條腿的凳子少一條腿。+- **每個功能項必須有三元組**:行為描述 + 驗證命令 + 目前狀態。缺一項就不完整——就像三條腿的凳子少一條腿。- **狀態轉移由 harness 控制**,agent 不能自己改狀態。通過驗證 = 唯一的升級路徑。-- **功能清單是項目的單一權威來源**——任何關於"該做什麼"的信息都從這裡派生。-- **粒度控制在"一次會話能完成"的範圍**。太粗做不完,太細管不過來。+- **功能清單是專案的單一權威來源**——任何關於「該做什麼」的資訊都從這裡派生。+- **粒度控制在「一次工作階段能完成」的範圍**。太粗做不完,太細管不過來。## 延伸閱讀-- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 明確指出功能列表是控制 agent 執行範圍的"核心數據結構"+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 明確指出功能清單是控制 agent 執行範圍的「核心資料結構」- [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) — 測試金字塔和行為規格的工程實踐## 練習-1. **功能清單設計**:定義一個最小化的功能清單 JSON schema。包含:id、行為描述、驗證命令、當前狀態、證據引用。用它描述一個包含 5 個功能的真實項目。+1. **功能清單設計**:定義一個最小化的功能清單 JSON schema。包含:id、行為描述、驗證命令、目前狀態、證據引用。用它描述一個包含 5 個功能的真實專案。-2. **驗證嚴格性對比**:選 3 個功能,分別設計"寬鬆"驗證(如"代碼無語法錯誤")和"嚴格"驗證(如"端到端測試通過")。對比兩種驗證下的假陽性率。+2. **驗證嚴格性對比**:選 3 個功能,分別設計「寬鬆」驗證(如「程式碼無語法錯誤」)和「嚴格」驗證(如「端到端測試通過」)。對比兩種驗證下的假陽性率。-3. **單一來源原則審查**:審查一個已有的 agent 項目,檢查是否存在與功能清單矛盾的範圍信息(對話裡的隱式需求、代碼裡的 TODO 註釋等)。設計一個方案,把所有信息統一到功能清單中。+3. **單一來源原則審查**:審查一個已有的 agent 專案,檢查是否存在與功能清單矛盾的範圍資訊(對話裡的隱式需求、程式碼裡的 TODO 注解等)。設計一個方案,把所有資訊統一到功能清單中。diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.mdindex 4d0e382..68e979b 100644--- a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md+++ b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md@@ -2,7 +2,7 @@此資料夾用於以下範例:-- 日誌作為反饋+- 日誌作為回饋- 執行狀態可視性- 乾淨狀態檢查- 恢復範例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 0c1551e..735598d 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@@ -1,21 +1,21 @@[English Version →](../../../en/lectures/lecture-09-why-agents-declare-victory-too-early/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/code/)> 實戰練習:[Project 05. 讓 agent 自己檢查自己做的對不對](./../../projects/project-05-grounded-qa-verification/index.md)# 第九講. 防止 agent 提前宣告完成-你讓 agent 實現"密碼重置"功能。它改了數據庫 schema、寫了 API 端點、加了郵件範本,跑了單元測試(全部通過),然後自信地告訴你"做完了"。你實際一跑——密碼重置鏈接發不出去(郵件服務配置缺失)、數據庫遷移半途失敗(schema 不一致)、端到端流程根本沒走過一遍。+你讓 agent 實現「密碼重置」功能。它改了資料庫 schema、寫了 API 端點、加了郵件範本,跑了單元測試(全部通過),然後自信地告訴你「做完了」。你實際一跑——密碼重置連結發不出去(郵件服務配置缺失)、資料庫遷移半途失敗(schema 不一致)、端到端流程根本沒走過一遍。這種感覺你一定不陌生——考試時把卷子寫得滿滿當當,信心滿滿地第一個交卷,結果成績出來不及格。卷子寫滿了,不代表做對了。-這不是偶然事件。Guo 等人 2017 年在 ICML 上的經典論文證明:**現代神經網絡系統性地過度自信**——模型自報的置信度顯著高於實際準確率。AI 編碼 agent 也一樣:它"覺得"做完了,但實際上差得遠。你的 harness 必須用外部化的、基於執行的驗證來替代 agent 的"感覺"。+這不是偶然事件。Guo 等人 2017 年在 ICML 上的經典論文證明:**現代神經網路系統性地過度自信**——模型自報的置信度顯著高於實際準確率。AI 程式碼代理也一樣:它「覺得」做完了,但實際上差得遠。你的 harness 必須用外部化的、基於執行的驗證來替代 agent 的「感覺」。## 滑坡效應-過早完成聲明幾乎總是一樣的套路:代碼看著還行——語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際運行或只跑了部分測試。跑了單元測試但跳過集成測試,跑了測試但沒檢查覆蓋率。最後"代碼看起來沒問題"就被當作了"功能已完成"的證據。交卷了。+過早完成聲明幾乎總是一樣的手法:程式碼看著還行——語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際執行或只跑了部分測試。跑了單元測試但跳過整合測試,跑了測試但沒檢查覆蓋率。最後「程式碼看起來沒問題」就被當作了「功能已完成」的證據。交卷了。-每一步都在丟失信息。從任務規範到代碼實現到運行時行為,每次轉換都可能引入偏差,而每次跳過的驗證都加劇了信息不對稱。+每一步都在遺失資訊。從任務規範到程式碼實現到執行時期行為,每次轉換都可能引入偏差,而每次跳過的驗證都加劇了資訊不對稱。## 三層終止檢查@@ -24,50 +24,50 @@ flowchart LRClaim["agent 說:做完了"] --> L1["先跑<br/>lint / typecheck"]L1 --> L2["再跑<br/>測試和啟動檢查"]L2 --> L3["最後跑<br/>完整使用者流程"]- L3 --> Done["三层都過才算完成"]+ L3 --> Done["三層都過才算完成"]``````mermaidflowchart LR- A["程式碼寫完了<br/>單測也绿了"] --> B["但應用没真正啟動<br/>完整流程也没跑"]- B --> C["配置、資料庫、外部服務問題<br/>还都藏着"]- C --> D["于是 agent 太早宣告完成"]+ A["程式碼寫完了<br/>單測也綠了"] --> B["但應用沒真正啟動<br/>完整流程也沒跑"]+ B --> C["配置、資料庫、外部服務問題<br/>還都藏著"]+ C --> D["於是 agent 太早宣告完成"]```## 核心概念-- **過早完成聲明**:agent 斷言任務完成,但實際上存在未滿足的正確性規範。核心問題:agent 依據代碼層面的局部信心做判斷,系統級正確性需要全局驗證。+- **過早完成聲明**:agent 斷言任務完成,但實際上存在未滿足的正確性規範。核心問題:agent 依據程式碼層面的局部信心做判斷,系統級正確性需要全局驗證。- **置信度校準偏差**:agent 自報的完成信心與實際完成質量之間的系統性差距。對複雜多檔案任務,這個偏差顯著為正——agent 總是比實際做得更自信。就像學生考完試估分總是偏高。-- **終止標準**:一組明確的、可執行的判定條件,定義在 harness 裡。agent 必須滿足所有條件才能聲明完成。"完成"從主觀判斷變成了客觀判定。-- **驗證-確認雙閘門**:第一層驗證檢查"代碼是否正確實現了指定行為";第二層確認檢查"系統級行為是否滿足端到端需求"。兩層都通過才算完成。-- **運行時反饋信號**:來自程序執行的日誌、進程狀態、健康檢查。這是 harness 判定完成質量的客觀基礎。-- **完成優先級約束**:先驗證功能正確性,再處理性能,最後管風格。核心功能沒驗證通過之前,不許做重構。+- **終止標準**:一組明確的、可執行的判定條件,定義在 harness 裡。agent 必須滿足所有條件才能聲明完成。「完成」從主觀判斷變成了客觀判定。+- **驗證-確認雙閘門**:第一層驗證檢查「程式碼是否正確實現了指定行為」;第二層確認檢查「系統級行為是否滿足端到端需求」。兩層都通過才算完成。+- **執行時期回饋信號**:來自程式執行的日誌、程式狀態、健康檢查。這是 harness 判定完成質量的客觀基礎。+- **完成優先級約束**:先驗證功能正確性,再處理效能,最後管風格。核心功能沒驗證通過之前,不許做重構。## 單元測試通過 ≠ 任務完成-這是最常見的陷阱,也是最危險的一個。agent 寫了代碼,跑了單元測試,全部綠色,然後說"做完了"。但單元測試的設計哲學——隔離被測單元、模擬依賴——恰好使其無法檢測跨組件問題:+這是最常見的陷阱,也是最危險的一個。agent 寫了程式碼,跑了單元測試,全部綠色,然後說「做完了」。但單元測試的設計哲學——隔離被測單元、模擬依賴——恰好使其無法檢測跨元件問題:-**接口不匹配**:渲染進程傳給預加載腳本的檔案路徑是相對路徑,但預加載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題。就像樂隊裡每個樂手各自練習都完美,但合在一起才發現定調不一樣。+**介面不相符**:渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題。就像樂隊裡每個樂手各自練習都完美,但合在一起才發現定調不一樣。-**狀態傳播錯誤**:數據庫遷移改了表結構,但 ORM 的緩存層還持有舊結構的緩存條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。+**狀態傳播錯誤**:資料庫遷移改了表結構,但 ORM 的快取層還持有舊結構的快取條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。-**環境依賴性**:代碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網絡延遲、服務不可用而失敗。就像在排練室唱得很好,上臺演出時音響設備出了問題。+**環境依賴性**:程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。就像在排練室唱得很好,上台演出時音響設備出了問題。### "順便重構"是完成判定的毒藥-Claude Code 有一個常見行為模式:在核心功能還沒驗證通過時就開始重構代碼、優化性能、改進風格。Knuth 說的"過早優化是萬惡之源"在 agent 場景中有了新含義——重構會改變已完成驗證和未完成驗證之間的邊界,可能破壞之前隱式正確的代碼路徑。就像你數學大題還沒做完,就跑去把前面選擇題的答案重新抄一遍格式——浪費時間不說,還可能抄錯了。+Claude Code 有一個常見行為模式:在核心功能還沒驗證通過時就開始重構程式碼、最佳化效能、改進風格。Knuth 說的「過早最佳化是萬惡之源」在 agent 場景中有了新含義——重構會改變已完成驗證和未完成驗證之間的邊界,可能破壞之前隱式正確的程式碼路徑。就像你數學大題還沒做完,就跑去把前面選擇題的答案重新抄一遍格式——浪費時間不說,還可能抄錯了。### 自我評價的系統性偏差Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**當 agent 被要求評估自己的工作時,它系統性地過度正面評價——即使人類觀察者認為質量明顯不達標。** 這就像讓學生自己給自己判卷——對自己的答案總是特別寬容。-這個問題在主觀任務(如設計審美)上尤其嚴重——"佈局是否精緻"是一個判斷題,agent 可靠地偏向正面。即使在有可驗證結果的任務上,agent 也會因為判斷失誤而影響表現。+這個問題在主觀任務(如設計美感)上尤其嚴重——「版面配置是否精緻」是一個判斷題,agent 可靠地偏向正面。即使在有可驗證結果的任務上,agent 也會因為判斷失誤而影響表現。-解決方案不是讓 agent "更客觀"——同一個模型既生成又評估,內在地傾向對自己慷慨。**解決方案是把"幹活的人"和"檢查的人"分開。** 就像考試不能讓學生自己批改自己的卷子——得有個獨立的閱卷老師。+解決方案不是讓 agent「更客觀」——同一個模型既生成又評估,內在地傾向對自己慷慨。**解決方案是把「幹活的人」和「檢查的人」分開。** 就像考試不能讓學生自己批改自己的卷子——得有個獨立的閱卷老師。一個獨立的評估 agent,經過專門調校為"挑剔"之後,比讓生成 agent 自我評估有效得多。Anthropic 的實驗數據:-| 架構 | 運行時長 | 成本 | 核心功能是否可用 |+| 架構 | 執行時期長 | 成本 | 核心功能是否可用 ||------|---------|------|---------------|| 單 agent 裸跑 | 20 分鐘 | $9 | 否(遊戲實體無法響應輸入) || 三 agent(planner + generator + evaluator) | 6 小時 | $200 | 是(遊戲可以正常遊玩) |@@ -80,66 +80,66 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**### 1. 外部化終止判定-完成判定不應該由 agent 自己做。harness 獨立執行終止校驗,輸入是運行時信號,不是 agent 的置信度。在 CLAUDE.md 裡寫清楚:+完成判定不應該由 agent 自己做。harness 獨立執行終止校驗,輸入是執行時期信號,不是 agent 的置信度。在 CLAUDE.md 裡寫清楚:```## 完成定義-- 功能完成 = 端到端驗證通過,不是"程式碼寫完了"+- 功能完成 = 端到端驗證通過,不是「程式碼寫完了」- 必須執行的驗證層級:1. 單元測試通過- 2. 集成測試通過+ 2. 整合測試通過3. 端到端流程驗證通過-- 在第 1 层没通過時,不许进入第 2 层-- 在第 2 层没通過時,不许进入第 3 层+- 在第 1 層沒通過時,不許進入第 2 層+- 在第 2 層沒通過時,不許進入第 3 層```### 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. 捕獲運行時信號+### 4. 捕獲執行時期信號-有效的運行時信號包括:+有效的執行時期信號包括:- 應用是否成功啟動並達到就緒狀態?-- 關鍵功能路徑在運行時是否執行成功?-- 數據庫寫入、檔案操作等副作用是否正確?+- 關鍵功能路徑在執行時期是否執行成功?+- 資料庫寫入、檔案操作等副作用是否正確?- 臨時資源是否被清理?## 實際案例-**任務**:實現用戶密碼重置功能。涉及數據庫操作、郵件發送和 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 系統性地過度自信**——置信度校準偏差是客觀存在的。卷子寫滿了不代表做對了。-- **完成判定必須外部化**——harness 獨立驗證,不信任 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) — 運行時證據在完成判定中的關鍵作用+- [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) — 測試方法層次和有效性的經典參考## 練習-1. **終止校驗函數設計**:為一個涉及數據庫遷移和 API 修改的任務設計完整的終止校驗。列出需要的運行時信號和每個信號的通過/失敗標準。在一個實際任務上運行,記錄它發現了哪些隱藏問題。+1. **終止校驗函數設計**:為一個涉及資料庫遷移和 API 修改的任務設計完整的終止校驗。列出需要的執行時期訊號和每個訊號的通過/失敗標準。在一個實際任務上執行,記錄它發現了哪些隱藏問題。-2. **校準偏差測量**:選 10 個不同類型的編碼任務,記錄 agent 的自報完成信心和實際完成質量。計算偏差值,分析它和任務複雜度的關係。+2. **校準偏差測量**:選 10 個不同類型的編碼任務,記錄 agent 的自報完成信心和實際完成品質。計算偏差值,分析它和任務複雜度的關係。3. **多層防禦實驗**:對同一組任務跑三種配置——(a) 僅靜態分析,(b) 加單元測試,(c) 完整三層校驗。比較過早完成聲明的比例和未捕獲缺陷的數量。diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.mdindex 2b3ec31..b0b1094 100644--- a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md@@ -4,5 +4,5 @@- 架構約束- 結構化測試-- 品味不變量+- 品味不變數- 以修復為導向的 lint 訊息diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.mdindex 300cba0..b79db5a 100644--- a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md@@ -1,4 +1,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 db5ec73..34ac40c 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@@ -1,95 +1,95 @@[English Version →](../../../en/lectures/lecture-10-why-end-to-end-testing-changes-results/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)> 實戰練習:[Project 05. 讓 agent 自己檢查自己做的對不對](./../../projects/project-05-grounded-qa-verification/index.md)# 第十講. 跑通完整流程才算真正驗證-你讓 agent 給 Electron 應用加一個檔案導出功能。它寫了渲染進程組件、預加載腳本、服務層邏輯,每個組件的單元測試都通過了。agent 說"做完了"。你實際一點擊導出按鈕——檔案路徑格式不對、進度條沒反應、大檔案導出時內存洩漏。5 個組件邊界缺陷,單元測試一個都沒發現。+你讓 agent 給 Electron 應用加一個檔案匯出功能。它寫了渲染程式元件、預載腳本、服務層邏輯,每個元件的單元測試都通過了。agent 說「做完了」。你實際一點擊匯出按鈕——檔案路徑格式不對、進度列沒反應、大檔案匯出時記憶體洩漏。5 個元件邊界缺陷,單元測試一個都沒發現。這就像一個合唱團排練——每個聲部單獨唱的時候都完美,但合在一起的時候,女高音比男低音快了半拍,伴奏的調子和主旋律差了半個音。每個部分都"對"了,但整體跑調了。-Google 的測試金字塔告訴我們:大量單元測試是基礎,但如果你止步於此,就會系統性地漏掉組件交互問題。對於 AI 編碼 agent 來說,這個問題更嚴重——agent 傾向於只跑最快的測試然後宣告完成。**只有端到端測試能證明系統級缺陷不存在**。+Google 的測試金字塔告訴我們:大量單元測試是基礎,但如果你止步於此,就會系統性地漏掉元件互動問題。對於 AI 程式碼代理來說,這個問題更嚴重——agent 傾向於只跑最快的測試然後宣告完成。**只有端到端測試能證明系統級缺陷不存在**。## 單元測試的盲區單元測試的設計哲學是隔離——模擬依賴,專注被測單元。這個哲學使單元測試快速且精確,但也製造了系統性的盲區。就像合唱排練時每個聲部戴著耳機對著伴奏唱——聽著都挺好,但真正合在一起才發現問題:-**接口不匹配**:渲染進程傳給預加載腳本的檔案路徑是相對路徑,但預加載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題——就像兩個聲部各自練的時候都覺得節奏沒問題,一合才發現一個用 4/4 拍一個用 3/4 拍。+**介面不相符**:渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題——就像兩個聲部各自練的時候都覺得節奏沒問題,一合才發現一個用 4/4 拍一個用 3/4 拍。-**狀態傳播錯誤**:數據庫遷移改了表結構,但 ORM 的緩存層還持有舊結構的緩存條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。就像換了一首歌的歌詞,但有人還在唱舊版本。+**狀態傳播錯誤**:資料庫遷移改了表結構,但 ORM 的快取層還持有舊結構的快取條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。就像換了一首歌的歌詞,但有人還在唱舊版本。-**資源生命週期問題**:檔案句柄、數據庫連接、網絡套接字的獲取和釋放跨越多個組件。單元測試為每個測試創建和銷燬獨立資源,不會暴露資源競爭或洩漏。就像排練時每個聲部輪流用麥克風,但演出時所有聲部同時上臺——話筒不夠用了。+**資源生命週期問題**:檔案描述符、資料庫連線、網路通訊端的獲取和釋放跨越多個元件。單元測試為每個測試建立和銷毀獨立資源,不會暴露資源競爭或洩漏。就像排練時每個聲部輪流用麥克風,但演出時所有聲部同時上台——麥克風不夠用了。-**環境依賴性**:代碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網絡延遲、服務不可用而失敗。就像排練廳裡唱得好好的,到了戶外音樂節風一吹話筒一嘯叫就全亂了。+**環境依賴性**:程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。就像排練廳裡唱得好好的,到了戶外音樂節風一吹麥克風一嘯叫就全亂了。## 端到端測試不僅改變結果,還改變行為這是很多人沒意識到的一點:當 agent 知道它的工作要過端到端測試時,它的編碼行為會改變。-1. **考慮組件交互**:寫代碼時會想"這個接口和上游怎麼對接",而不是隻關注單個函數。就像知道最終要合在一起唱,練習的時候就會注意聽其他聲部。-2. **尊重架構邊界**:有架構約束的系統裡,端到端測試迫使 agent 遵守邊界規則。就像樂譜上標註了"此處漸強",你得跟著來。-3. **處理錯誤路徑**:端到端測試通常包含故障場景,迫使 agent 考慮異常處理。就像排練時模擬了"話筒突然沒聲了"的情況,你知道該怎麼做。+1. **考慮元件互動**:寫程式碼時會想「這個介面和上游怎麼對接」,而不是只關注單個函式。就像知道最終要合在一起唱,練習的時候就會注意聽其他聲部。+2. **尊重架構邊界**:有架構約束的系統裡,端到端測試迫使 agent 遵守邊界規則。就像樂譜上標注了「此處漸強」,你得跟著來。+3. **處理錯誤路徑**:端到端測試通常包含故障場景,迫使 agent 考慮例外處理。就像排練時模擬了「麥克風突然沒聲了」的情況,你知道該怎麼做。-## 測試金字塔與審查反饋提升+## 測試金字塔與審查回饋提升```mermaidflowchart TBsubgraph Unit["單元測試只看孤立部件"]- U1["渲染层測試"]+ U1["渲染層測試"]U2["Preload 測試"]- U3["服務层測試"]+ U3["服務層測試"]endsubgraph E2E["端到端執行會穿過真實系統"]- R["点击渲染层按钮"] --> P["Preload 桥"]- P --> S["服務层"]- S --> F["檔案系統 / 操作系統"]- F --> Result["真實导出檔案"]+ R["點擊渲染層按鈕"] --> P["Preload 橋"]+ P --> S["服務層"]+ S --> F["檔案系統 / 作業系統"]+ F --> Result["真實匯出檔案"]end``````mermaidflowchart LR- Review["審查意见:<br/>renderer 不能直接 import fs"] --> Rule["加一条 direct fs import 檢查"]- Rule --> Message["报錯裡直接告诉 agent<br/>把檔案访问移到 preload"]- Message --> Harness["把這条檢查加入 harness"]- Harness --> Stronger["以後再犯會第一時间报錯"]+ Review["審查意見:<br/>renderer 不能直接 import fs"] --> Rule["加一條 direct fs import 檢查"]+ Rule --> Message["報錯裡直接告訴 agent<br/>把檔案存取移到 preload"]+ Message --> Harness["把這條檢查加入 harness"]+ Harness --> 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 小節進入」。## 核心概念-- **組件邊界缺陷**:組件 A 和 B 各自單元測試通過,但它們的交互產生了不正確的行為。這是端到端測試最擅長捕獲的問題類型——合唱裡各聲部單獨都對但合起來跑調的那種。-- **測試充分性梯度**:單元測試能檢測的缺陷 <= 集成測試能檢測的缺陷 <= 端到端測試能檢測的缺陷。每往上一層,檢測能力增強。-- **架構邊界執行規則**:把架構文檔裡的規則(如"渲染進程不能直接訪問檔案系統")變成可執行的自動化檢查。從"寫在紙上"變成"跑在 CI 裡"。-- **審查反饋提升**:把重複出現的代碼審查意見轉化為自動化測試。每次發現重複問題就加一條規則,harness 會自動變強。就像合唱排練時指揮把常見的錯誤編成練習曲——下次再犯同樣的錯誤,不用指揮說,練習曲自己就暴露了。-- **面向 agent 的錯誤消息**:失敗信息不只是說"出了什麼問題",還要告訴 agent 具體怎麼修。這把測試失敗變成自我修正的反饋循環。+- **元件邊界缺陷**:元件 A 和 B 各自單元測試通過,但它們的互動產生了不正確的行為。這是端到端測試最擅長捕獲的問題類型——合唱裡各聲部單獨都對但合起來跑調的那種。+- **測試充分性梯度**:單元測試能檢測的缺陷 <= 整合測試能檢測的缺陷 <= 端到端測試能檢測的缺陷。每往上一層,檢測能力增強。+- **架構邊界執行規則**:把架構文件裡的規則(如「渲染程式不能直接存取檔案系統」)變成可執行的自動化檢查。從「寫在紙上」變成「跑在 CI 裡」。+- **審查回饋提升**:把重複出現的程式碼審查意見轉化為自動化測試。每次發現重複問題就加一條規則,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/)### 1. harness 必須包含端到端層-在你的驗證流程裡明確:對於涉及跨組件修改的任務,端到端測試通過是完成的前置條件:+在你的驗證流程裡明確:對於涉及跨元件修改的任務,端到端測試通過是完成的前置條件:```## 驗證層級- 層級 1: 單元測試 (必須通過)-- 層級 2: 集成測試 (必須通過)-- 層級 3: 端到端測試 (涉及跨组件修改時必須通過)+- 層級 2: 整合測試 (必須通過)+- 層級 3: 端到端測試 (涉及跨元件修改時必須通過)- 跳過任何必須層級的任務 = 未完成```@@ -98,13 +98,13 @@ OpenAI 採用了"分層領域架構"——每個業務領域被分成固定的每條架構約束都應該有對應的測試或 lint 規則:```bash-# 檢查渲染进程是否直接調用 Node.js API+# 檢查渲染程式是否直接呼叫 Node.js APIgrep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"```-### 3. 設計面向 agent 的錯誤消息+### 3. 設計面向 agent 的錯誤訊息-失敗信息要包含三要素:什麼出了問題、為什麼、怎麼修:+失敗資訊要包含三要素:什麼出了問題、為什麼、怎麼修:```ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12@@ -112,35 +112,35 @@ WHY: Renderer process has no access to Node.js APIs for securityFIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()```-### 4. 建立審查反饋提升流程+### 4. 建立審查回饋提升流程-每次在代碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。就像合唱團的排練筆記——每次排練發現的問題都記下來,下次排練前先檢查這些點。久而久之,常見錯誤越來越少,音樂越來越和諧。+每次在程式碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。就像合唱團的排練筆記——每次排練發現的問題都記下來,下次排練前先檢查這些點。久而久之,常見錯誤越來越少,音樂越來越和諧。## 實際案例-**任務**:在 Electron 應用中實現檔案導出功能。涉及渲染進程 UI、預加載腳本檔案系統代理、服務層數據轉換。+**任務**:在 Electron 應用中實現檔案匯出功能。涉及渲染程式 UI、預載腳本檔案系統代理、服務層資料轉換。-**各聲部單獨唱(單元測試通過)**:渲染組件測試(通過,mock 檔案操作)、預加載腳本測試(通過,mock 檔案系統)、服務層測試(通過,mock 數據源)。agent 聲明完成。+**各聲部單獨唱(單元測試通過)**:渲染元件測試(通過,mock 檔案操作)、預載腳本測試(通過,mock 檔案系統)、服務層測試(通過,mock 資料來源)。agent 聲明完成。**合唱合在一起(端到端測試揭示的缺陷)**:| 缺陷 | 描述 | 單元測試 | 端到端 ||------|------|---------|--------|-| 接口不匹配 | 檔案路徑格式不一致 | 未檢測 | 檢測 |-| 狀態傳播 | 導出進度未通過 IPC 傳回 UI | 未檢測 | 檢測 |-| 資源洩漏 | 大檔案導出句柄未釋放 | 未檢測 | 檢測 |+| 介面不相符 | 檔案路徑格式不一致 | 未檢測 | 檢測 |+| 狀態傳播 | 匯出進度未通過 IPC 傳回 UI | 未檢測 | 檢測 |+| 資源洩漏 | 大檔案匯出描述符未釋放 | 未檢測 | 檢測 || 權限問題 | 打包環境權限不同 | 未檢測 | 檢測 |-| 錯誤傳播 | 服務層異常未到 UI 層 | 未檢測 | 檢測 |+| 錯誤傳播 | 服務層例外未到 UI 層 | 未檢測 | 檢測 |5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。代價是測試時間從 2 秒增加到 15 秒——在 agent 工作流裡完全可以接受。每個聲部單獨唱得再好,也比不上一次完整的合唱排練。## 關鍵要點-- **單元測試對組件邊界缺陷系統性盲視**——它們的隔離設計恰好使其無法檢測交互問題。每個人唱得都對,不代表合唱不跑調。-- **端到端測試不僅檢測缺陷,還改變 agent 的編碼行為**——讓它更關注集成和邊界。-- **架構規則必須可執行**——不是寫在文檔裡等人來看,而是每次提交自動檢查。-- **錯誤消息要面向 agent 設計**——包含"怎麼修"的具體步驟,形成自我修正閉環。-- **審查反饋提升讓 harness 自動變強**——每個被捕獲的缺陷類別都變成永久防線。+- **單元測試對元件邊界缺陷系統性盲視**——它們的隔離設計恰好使其無法檢測互動問題。每個人唱得都對,不代表合唱不跑調。+- **端到端測試不僅檢測缺陷,還改變 agent 的編碼行為**——讓它更關注整合和邊界。+- **架構規則必須可執行**——不是寫在文件裡等人來看,而是每次提交自動檢查。+- **錯誤訊息要面向 agent 設計**——包含「怎麼修」的具體步驟,形成自我修正閉環。+- **審查回饋提升讓 harness 自動變強**——每個被捕獲的缺陷類別都變成永久防線。## 延伸閱讀@@ -151,8 +151,8 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea## 練習-1. **跨組件缺陷檢測**:選一個涉及至少三個組件的修改任務。先只跑單元測試記錄結果,再跑端到端測試。分析每個額外發現的缺陷屬於哪種跨層交互問題。+1. **跨元件缺陷檢測**:選一個涉及至少三個元件的修改任務。先只跑單元測試記錄結果,再跑端到端測試。分析每個額外發現的缺陷屬於哪種跨層互動問題。-2. **架構規則自動化**:選項目裡的一條架構約束,把它變成可執行檢查(含面向 agent 的錯誤消息)。集成到 harness 裡,用基準任務驗證效果。+2. **架構規則自動化**:選專案裡的一條架構約束,把它變成可執行檢查(含面向 agent 的錯誤訊息)。整合到 harness 裡,用基準任務驗證效果。-3. **審查反饋提升**:從代碼審查歷史中找一個重複出現的意見類型,按五步流程轉化為自動化檢查。比較提升前後該類問題的出現頻率。+3. **審查回饋提升**:從程式碼審查歷史中找一個重複出現的意見類型,按五步流程轉化為自動化檢查。比較提升前後該類問題的出現頻率。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 a2bb66a..9814c24 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@@ -1,35 +1,35 @@[English Version →](../../../en/lectures/lecture-11-why-observability-belongs-inside-the-harness/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)> 實戰練習:[Project 06. 搭建一套完整的 agent 工作環境](./../../projects/project-06-runtime-observability-and-debugging/index.md)-# 第十一講. 讓 agent 的運行過程可觀測+# 第十一講. 讓 agent 的執行過程可觀測-你讓 agent 做一個功能,它跑了 20 分鐘,改了一堆檔案,然後告訴你"做完了但有兩個測試失敗"。你問它為什麼失敗,它說"不太確定,可能是時序問題"。你問它改了哪些關鍵路徑,它說"讓我看看代碼……"。+你讓 agent 做一個功能,它跑了 20 分鐘,改了一堆檔案,然後告訴你「做完了但有兩個測試失敗」。你問它為什麼失敗,它說「不太確定,可能是時序問題」。你問它改了哪些關鍵路徑,它說「讓我看看程式碼……」。這不是 agent 能力不夠,是你的 harness 沒有給它裝儀表盤。想象你在開一輛沒有儀表盤的車——沒有速度表、沒有油量表、沒有發動機故障燈。你能開,但你不知道開多快、還剩多少油、發動機是不是快爆了。技術再好的司機,蒙著眼也得出事。-**沒有可觀測性,agent 在不確定狀態中做決策,評估變成主觀判斷,重試變成盲目摸索。** OpenAI 和 Anthropic 都將可靠性定義為證據問題——harness 必須以可指導下一步決策的形式暴露運行時行為和評估信號。+**沒有可觀測性,agent 在不確定狀態中做決策,評估變成主觀判斷,重試變成盲目摸索。** OpenAI 和 Anthropic 都將可靠性定義為證據問題——harness 必須以可指導下一步決策的形式暴露執行時期行為和評估訊號。## 可觀測性缺失的真實代價當 harness 缺乏可觀測性時,四類問題系統性出現:-**無法區分"正確"和"看似正確"**:一個函數在代碼審查時看起來完全正確——語法對、邏輯通。但運行時因為邊界條件處理錯誤,在特定輸入下產生了不正確結果。只有運行時追蹤能揭示實際執行路徑偏離了預期。就像一個演員排練時臺詞全對了,但上臺演出時燈光一打,表情和走位全都變了——你不看現場是發現不了的。+**無法區分「正確」和「看似正確」**:一個函式在程式碼審查時看起來完全正確——語法對、邏輯通。但執行時期因為邊界條件處理錯誤,在特定輸入下產生了不正確結果。只有執行時期追蹤能揭示實際執行路徑偏離了預期。就像一個演員排練時臺詞全對了,但上台演出時燈光一打,表情和走位全都變了——你不看現場是發現不了的。**評估變成玄學**:沒有評分標準和驗收條件時,評估者(人或 agent)依賴隱式假設。同一個輸出,不同評估者可能給出截然不同的評價。質量評估不可復現。就像體操比賽沒有評分標準——這個裁判覺得你的動作優雅,那個裁判覺得你落地不穩,誰說了算?-**重試變成盲猜**:agent 不知道為什麼失敗時,重試方向是隨機的。它可能在錯誤的方向上反覆嘗試——修復了不相關的代碼路徑而忽略真正的故障根源。就像你開車發現車跑偏了,但你沒有儀表盤——你猜是輪胎的問題換了輪胎,實際是方向盤的 alignment 出了問題。每次盲重試都消耗 token 和時間。+**重試變成盲猜**:agent 不知道為什麼失敗時,重試方向是隨機的。它可能在錯誤的方向上反覆嘗試——修復了不相關的程式碼路徑而忽略真正的故障根源。就像你開車發現車跑偏了,但你沒有儀表盤——你猜是輪胎的問題換了輪胎,實際是方向盤的 alignment 出了問題。每次盲重試都消耗 token 和時間。-**會話交接信息斷崖**:當未完成的工作移交給下一個會話時,缺乏可觀測性意味著新會話必須從零診斷系統狀態。Anthropic 的長期運行 agent 觀察表明,這種重複診斷可能佔會話總時間的 30-50%。就像換班司機上車發現沒有交接記錄——他得花半小時檢查油量、胎壓、發動機狀態才能出發。+**工作階段交接資訊斷崖**:當未完成的工作移交給下一個工作階段時,缺乏可觀測性意味著新工作階段必須從零診斷系統狀態。Anthropic 的長期執行 agent 觀察表明,這種重複診斷可能佔工作階段總時間的 30-50%。就像換班司機上車發現沒有交接記錄——他得花半小時檢查油量、胎壓、發動機狀態才能出發。## Claude Code 的真實場景-想象一個使用"計劃者-生成者-評估者"三角色工作流的 harness,執行"為應用添加暗色模式"任務。+想象一個使用「計劃者-生成者-評估者」三角色工作流的 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 倍。區別只在可觀測性——給車裝上了儀表盤。@@ -39,67 +39,67 @@```mermaidflowchart LR- Contract["先把這次任務寫清楚<br/>改哪些檔案 / 不改哪些部分 / 怎么算通過"] --> Generator["生成器"]- Generator --> Signals["執行時收集<br/>日誌 / 追踪 / 健康檢查"]- Contract --> Review["按檢查表逐项看<br/>功能 / 測試 / 邊界"]+ Contract["先把這次任務寫清楚<br/>改哪些檔案 / 不改哪些部分 / 怎麼算通過"] --> Generator["生成器"]+ Generator --> Signals["執行時收集<br/>日誌 / 追蹤 / 健康檢查"]+ Contract --> Review["按檢查表逐項看<br/>功能 / 測試 / 邊界"]Signals --> Review- Review --> Verdict["指出哪一项没過<br/>以及应該去改哪裡"]+ Review --> Verdict["指出哪一項沒過<br/>以及應該去改哪裡"]Verdict --> Generator```-**運行時可觀測性**:系統層的信號——日誌、追蹤、進程事件、健康檢查。回答"系統做了什麼"。這是你車上的儀表盤——速度、油量、發動機溫度。+**執行時期可觀測性**:系統層的訊號——日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。這是你車上的儀表盤——速度、油量、發動機溫度。-**過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答"為什麼這個變更應該被接受"。這是你的導航系統——不光知道現在在哪,還知道為什麼走這條路。+**過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。這是你的導航系統——不光知道現在在哪,還知道為什麼走這條路。## 核心概念-- **運行時可觀測性**:系統層的信號——日誌、追蹤、進程事件、健康檢查。回答"系統做了什麼"。-- **過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答"為什麼這個變更應該被接受"。-- **任務軌跡**:一個任務從開始到完成的完整決策路徑記錄,類似分佈式系統中的請求追蹤。agent 的每一步操作及其上下文都被記錄。就像黑匣子——出了問題可以回放完整過程。-- **衝刺合同**:編碼開始前協商的短期協議——明確任務範圍、驗證標準、排除項。是過程可觀測性的核心工具。+- **執行時期可觀測性**:系統層的訊號——日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。+- **過程可觀測性**:harness 決策工件的可見性——計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。+- **任務軌跡**:一個任務從開始到完成的完整決策路徑記錄,類似分佈式系統中的請求追蹤。agent 的每一步操作及其脈絡都被記錄。就像黑匣子——出了問題可以重播完整過程。+- **衝刺合約**:編碼開始前協商的短期協定——明確任務範圍、驗證標準、排除項。是過程可觀測性的核心工具。- **評估評分標準**:把質量評估從主觀判斷變成基於證據的結構化評分。使不同評估者對同一輸出產生相似結論。就像體操比賽的評分標準——有了它,十個裁判的分才不會差太遠。-- **雙層可觀測性**:系統層和過程層同時設計、相互增強。運行時信號解釋行為,過程工件解釋意圖。+- **雙層可觀測性**:系統層和過程層同時設計、相互增強。執行時期信號解釋行為,過程工件解釋意圖。## 為什麼 agent 自己解決不了這個問題你可能在想:"agent 不能自己打日誌嗎?" 問題在於:-1. **agent 不知道它不知道什麼**——它不會主動記錄自己沒意識到需要的信號。就像你不知道油箱快漏了的時候,你不會去看油量表——因為你壓根不知道該看。-2. **日誌格式不統一**——不同會話用不同的日誌格式,無法做系統化分析。就像十個司機各寫各的交接記錄,格式都不一樣,下一個司機看不懂。-3. **過程可觀測性不是日誌能解決的**——衝刺合同和評分標準是結構化的工件,需要 harness 層面的支持。不是多 print 幾行就能搞定的。+1. **agent 不知道它不知道什麼**——它不會主動記錄自己沒意識到需要的訊號。就像你不知道油箱快漏了的時候,你不會去看油量表——因為你壓根不知道該看。+2. **日誌格式不統一**——不同工作階段用不同的日誌格式,無法做系統化分析。就像十個司機各寫各的交接記錄,格式都不一樣,下一個司機看不懂。+3. **過程可觀測性不是日誌能解決的**——衝刺合約和評分標準是結構化的工件,需要 harness 層面的支援。不是多 print 幾行就能搞定的。## 怎麼裝儀表盤-### 1. 在 harness 裡內置運行時信號採集+### 1. 在 harness 裡內置執行時期信號採集不要依賴 agent 自己打日誌。harness 應該自動採集以下信號:-- **應用生命週期**:啟動、就緒、運行、關閉各階段狀態+- **應用生命週期**:啟動、就緒、執行、關閉各階段狀態- **功能路徑執行**:關鍵路徑的執行記錄,包括入口、檢查點和出口-- **數據流**:數據在組件間的流轉記錄-- **資源利用**:異常的資源使用模式(如內存持續增長)-- **錯誤和異常**:完整的錯誤上下文,不只是錯誤消息+- **資料流**:資料在元件間的流轉記錄+- **資源利用**:異常的資源使用模式(如記憶體持續增長)+- **錯誤和例外**:完整的錯誤脈絡,不只是錯誤訊息-### 2. 實施衝刺合同+### 2. 實施衝刺合約-在每個任務開始前,生成者和評估者(可能是同一個 agent 的不同調用)協商一份合同——就像施工隊開工前籤的施工協議:+在每個任務開始前,生成者和評估者(可能是同一個 agent 的不同呼叫)協商一份合約——就像施工隊開工前籤的施工協定:```markdown-# 冲刺合同: 暗色模式支持+# 衝刺合約: 暗色模式支援## 範圍-- 修改主题切換组件-- 更新全局 CSS 變量-- 添加暗色模式測試+- 修改主題切換元件+- 更新全局 CSS 變數+- 新增暗色模式測試## 驗證標準-- 每個组件的视觉回歸測試通過+- 每個元件的視覺回歸測試通過- 主流程端到端測試通過-- 无样式闪烁 (FOUC)+- 無樣式閃爍 (FOUC)-## 排除项-- 不處理打印样式-- 不處理第三方组件暗色模式+## 排除項+- 不處理列印樣式+- 不處理第三方元件暗色模式```### 3. 建立評估評分標準@@ -109,20 +109,20 @@ flowchart LR```markdown# 評分標準-| 维度 | A | B | C | D |+| 維度 | A | B | C | D ||------|---|---|---|---|-| 程式碼正确性 | 所有測試通過 | 主流程通過 | 部分通過 | 编译失敗 |-| 架构合规 | 完全合规 | 轻微偏离 | 明顯偏离 | 严重违反 |-| 測試覆盖 | 主流程+邊缘 | 仅主流程 | 仅有骨架 | 无測試 |+| 程式碼正確性 | 所有測試通過 | 主流程通過 | 部分通過 | 編譯失敗 |+| 架構合規 | 完全合規 | 輕微偏離 | 明顯偏離 | 嚴重違反 |+| 測試覆蓋 | 主流程+邊緣 | 僅主流程 | 僅有骨架 | 無測試 |```### 4. 用 OpenTelemetry 標準化-為每個 harness 會話創建一個 trace,每個任務創建一個 span,每個驗證步驟創建子 span。使用標準屬性標註關鍵信息。這樣可觀測性數據可以和標準工具鏈(Jaeger、Zipkin)集成。+為每個 harness 工作階段建立一個 trace,每個任務建立一個 span,每個驗證步驟建立子 span。使用標準屬性標注關鍵資訊。這樣可觀測性資料可以和標準工具鏈(Jaeger、Zipkin)整合。## Anthropic 的三 agent 架構實驗-Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們用三種架構跑同一個任務("用 Web Audio API 做一個瀏覽器端 DAW"),記錄了詳細的階段數據:+Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們用三種架構跑同一個任務(「用 Web Audio API 做一個瀏覽器端 DAW」),記錄了詳細的階段資料:| Agent 和階段 | 時長 | 成本 ||------------|------|------|@@ -137,13 +137,13 @@ 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 收到詳細回饋後修復。就像驗收工程師拿著驗收標準逐項檢查——不達標就打回去重做。-QA 第 1 輪反饋的示例——"這是一個視覺上令人印象深刻的應用,AI 集成工作良好,但核心 DAW 功能有幾個是展示性的,沒有交互深度:剪輯不能拖拽/移動,沒有樂器 UI 面板(合成器旋鈕、鼓墊),沒有視覺效果編輯器(EQ 曲線、壓縮器儀表)"。這些不是邊緣情況——它們是讓 DAW 可用的核心交互。具體的、有證據的反饋,不是"感覺不對"。+QA 第 1 輪回饋的示例——「這是一個視覺上令人印象深刻的應用,AI 整合工作良好,但核心 DAW 功能有幾個是展示性的,沒有互動深度:剪輯不能拖拽/移動,沒有樂器 UI 面板(合成器旋鈕、鼓墊),沒有視覺效果編輯器(EQ 曲線、壓縮器儀表)」。這些不是邊緣情況——它們是讓 DAW 可用的核心互動。具體的、有證據的回饋,不是「感覺不對」。Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題,然後說服自己這些問題不嚴重,最終批準工作。調校方式是:讀 evaluator 的日誌,找到它的判斷和人類判斷分叉的地方,更新 QA 的 prompt 解決那些問題。經過幾輪這種開發循環,evaluator 的評分才變得合理。就像訓練一個新驗收工程師——一開始他太寬容,出了幾次事故後學會了嚴格。@@ -151,23 +151,23 @@ Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題## 關鍵要點-- **可觀測性是 harness 的架構屬性**——不是事後添加的功能,而是設計時必須考慮的核心能力。儀表盤不是可選配件,是出廠標配。-- **雙層可觀測性缺一不可**——運行時信號解釋"發生了什麼",過程工件解釋"為什麼這樣做"。速度表和導航系統各有各的用處。-- **衝刺合同前置對齊工作**——防止"生成者做了評估者因可預見原因立即拒絕的東西"。施工協議要在開工前籤,不是完工後補。+- **可觀測性是 harness 的架構屬性**——不是事後新增的功能,而是設計時必須考慮的核心能力。儀表盤不是可選配件,是出廠標配。+- **雙層可觀測性缺一不可**——執行時期訊號解釋「發生了什麼」,過程工件解釋「為什麼這樣做」。速度表和導航系統各有各的用處。+- **衝刺合約前置對齊工作**——防止「生成者做了評估者因可預見原因立即拒絕的東西」。施工協定要在開工前簽,不是完工後補。- **評分標準讓評估可復現**——不同評估者對同一輸出產生相似評分。有了評分標準,十個裁判的分才不會差太遠。-- **可觀測性缺失導致 30-50% 的會話時間浪費在重複診斷上**。+- **可觀測性缺失導致 30-50% 的工作階段時間浪費在重複診斷上**。## 延伸閱讀- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — 現代可觀測性工程的理論和實踐框架- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — 大規模分佈式追蹤的開創性實踐-- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — 引入衝刺合同和評估評分標準+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — 引入衝刺合約和評估評分標準- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — 可觀測性在生產系統中的系統化應用## 練習-1. **可觀測性差距分析**:審查你當前的 harness,評估系統層和過程層可觀測性。找出無法從現有信號區分的系統狀態,提出補充方案。+1. **可觀測性差距分析**:審查你目前的 harness,評估系統層和過程層可觀測性。找出無法從現有訊號區分的系統狀態,提出補充方案。-2. **衝刺合同實踐**:為一個真實任務寫衝刺合同。讓 agent 按合同執行,對比沒有合同時的效率和質量差異。+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/code/cleanup-loop.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.mdindex 6f81fef..917314d 100644--- a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md@@ -2,7 +2,7 @@週期性清理任務:-- 掃描過時的文件+- 掃描過時的檔案- 掃描結構性違規- 更新品質評分- 開啟針對性的清理 PRdiff --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 bb5193e..4ecab2b 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@@ -1,27 +1,27 @@[English Version →](../../../en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)-> 本篇代碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)+> 本篇程式碼示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)> 實戰練習:[Project 06. 搭建一套完整的 agent 工作環境](./../../projects/project-06-runtime-observability-and-debugging/index.md)-# 第十二講. 每次會話結束前都做好交接+# 第十二講. 每次工作階段結束前都做好交接-你的 agent 跑了一下午,改了 20 個檔案,提交了代碼,會話結束。下一個 agent 會話開始,一上來就發現:構建失敗了、測試紅了、臨時調試檔案到處都是、功能清單沒更新、進度完全不清楚。新會話的前 30 分鐘全花在"搞清楚上一個會話到底幹了什麼"上。+你的 agent 跑了一下午,改了 20 個檔案,提交了程式碼,工作階段結束。下一個 agent 工作階段開始,一上來就發現:建構失敗了、測試紅了、臨時調試檔案到處都是、功能清單沒更新、進度完全不清楚。新工作階段的前 30 分鐘全花在「搞清楚上一個工作階段到底幹了什麼」上。這就像大學宿舍——你不倒垃圾,下一個室友進來就得替你收拾。他本來的計劃是複習考試,結果先花半小時收拾你留下的爛攤子。更要命的是,收拾完了他也不想複習了——環境太差,心情也差。-OpenAI 和 Anthropic 都明確指出:**長期可靠性取決於操作紀律,不僅是單次運行的成功。** 每個會話結束時的狀態質量,直接決定下一個會話的效率。+OpenAI 和 Anthropic 都明確指出:**長期可靠性取決於操作紀律,不僅是單次執行的成功。** 每個工作階段結束時的狀態品質,直接決定下一個工作階段的效率。-## 熵增是默認狀態+## 熵增是預設狀態-Lehman 的軟件演化定律告訴我們:持續變更的系統,除非主動管理,否則複雜性必然增加。這對 AI 編碼 agent 尤其成立——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 都被轉化為文件更新或直接編碼到工具中。當文件不夠用時,把規則提升為程式碼。就像把宿舍公約從「口頭約定」變成「貼在門上的檢查表」。這個機制就像垃圾回收——技術債是高息貸款,持續小額還清幾乎總是比攢到一次性爆發好得多。@@ -29,7 +29,7 @@ OpenAI 團隊最初花每週五(20% 的工作時間)手動清理 "AI slop"## 清潔狀態:不只看地上有沒有垃圾-清潔狀態不是單一的"代碼能編譯"。代碼能無錯構建——這是最基本的,下一個會話不應該先修構建錯誤。就像你搬出去的時候水電不能是斷的。所有測試也得通過,包括會話之前就存在的測試——會話有責任不破壞已有功能。而且要在 CI 環境驗證,不是"在我機器上通過"。+清潔狀態不是單一的「程式碼能編譯」。程式碼能無錯建構——這是最基本的,下一個工作階段不應該先修建構錯誤。就像你搬出去的時候水電不能是斷的。所有測試也得通過,包括工作階段之前就存在的測試——工作階段有責任不破壞已有功能。而且要在 CI 環境驗證,不是「在我機器上通過」。```mermaidflowchart LR@@ -38,68 +38,68 @@ flowchart LRBuild -->|否| Fix["先修好再退出"]Test -->|是| Record["更新功能清單 + 進度"]Test -->|否| Fix- Record --> Cleanup["清理临時工件 / 調試程式碼"]+ Record --> Cleanup["清理臨時工件 / 調試程式碼"]Cleanup --> Startup{"標準啟動路徑可用?"}- Startup -->|是| Clean["干净交接"]+ Startup -->|是| Clean["乾淨交接"]Startup -->|否| FixFix --> Build```-但這還不夠。當前進度必須記錄在機器可讀的工件中——已完成的子任務和通過標準、進行中但未完成的子任務和當前狀態、尚未開始的子任務。好的進度記錄減少 60-80% 的會話啟動診斷時間。調試日誌、臨時檔案、註釋掉的代碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個會話的認知負擔。標準啟動路徑也必須可用——下一個會話能不能不人工干預就開始工作?環境初始化、代碼庫加載、上下文獲取、任務選擇,這些路徑不能被破壞。+但這還不夠。目前進度必須記錄在機器可讀的工件中——已完成的子任務和通過標準、進行中但未完成的子任務和目前狀態、尚未開始的子任務。好的進度記錄減少 60-80% 的工作階段啟動診斷時間。調試日誌、臨時檔案、註解掉的程式碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個工作階段的認知負擔。標準啟動路徑也必須可用——下一個工作階段能不能不人工干預就開始工作?環境初始化、程式碼庫載入、脈絡獲取、任務選擇,這些路徑不能被破壞。```mermaidflowchart LR- Dirty["這次退出時<br/>測試是红的、临時檔案没删、進度也没寫"] --> Diagnose["下個會話先花時间<br/>搞清楚發生了什么"]- Diagnose --> Fragile["接着在一個很乱的倉庫上继續改"]- Fragile --> More["更多調試檔案、更多坏檢查、<br/>更多說不清的進度"]+ Dirty["這次退出時<br/>測試是紅的、臨時檔案沒刪、進度也沒寫"] --> Diagnose["下個工作階段先花時間<br/>搞清楚發生了什麼"]+ Diagnose --> Fragile["接著在一個很亂的儲存庫上繼續改"]+ Fragile --> More["更多調試檔案、更多壞檢查、<br/>更多說不清的進度"]More --> Dirty- Clean["這次退出前<br/>測試是绿的、進度寫了、临時檔案删了"] --> Fast["下個會話打開倉庫就能继續寫程式碼"]+ Clean["這次退出前<br/>測試是綠的、進度寫了、臨時檔案刪了"] --> Fast["下個工作階段打開儲存庫就能繼續寫程式碼"]Fast --> Stable["不用先救火"]Stable --> Clean```## 核心概念-- **清潔狀態**:會話結束時系統滿足五個條件——構建通過、測試通過、進度已記錄、無過時工件、啟動路徑可用。缺一個都不算"做完"。-- **會話完整性**:類比數據庫事務——要麼全部提交併留下清潔狀態,要麼回滾到上一致狀態。沒有中間地帶。-- **質量文檔**:對每個模塊的質量等級做持續記錄的活躍工件。不是一次性評估,而是跟蹤代碼庫是變強了還是變弱了。-- **清理循環**:定期的維護會話,目標是系統性減少代碼庫中的熵。不是緊急修復,而是常規運維——就像宿舍的每週值日表。-- **harness 簡化**:隨著模型能力提升,定期移除不再必要的 harness 組件。今天必要的約束,三個月後可能是多餘的開銷。+- **清潔狀態**:工作階段結束時系統滿足五個條件——建構通過、測試通過、進度已記錄、無過時工件、啟動路徑可用。缺一個都不算「做完」。+- **工作階段完整性**:類比資料庫事務——要麼全部提交並留下清潔狀態,要麼回溯到上一致狀態。沒有中間地帶。+- **品質文件**:對每個模塊的品質等級做持續記錄的活躍工件。不是一次性評估,而是追蹤程式碼庫是變強了還是變弱了。+- **清理循環**:定期的維護工作階段,目標是系統性減少程式碼庫中的熵。不是緊急修復,而是常規運維——就像宿舍的每週值日表。+- **harness 簡化**:隨著模型能力提升,定期移除不再必要的 harness 元件。今天必要的約束,三個月後可能是多餘的開銷。- **冪等清理**:清理操作無論執行多少次都產生相同結果。確保清理在失敗重試場景中仍然安全。## "以後再清理"是永遠不清理-最常見的心理陷阱是"這次來不及清理了,下次再弄"。但下次的 agent 不知道你上次留下了什麼——它看到的是一堆混亂的代碼和不確定的狀態。它會花大量時間推斷"這堆代碼裡哪些是有意的,哪些是臨時的"。+最常見的心理陷阱是「這次來不及清理了,下次再弄」。但下次的 agent 不知道你上次留下了什麼——它看到的是一堆混亂的程式碼和不確定的狀態。它會花大量時間推斷「這堆程式碼裡哪些是有意的,哪些是臨時的」。-更糟的是,每個會話都有自己的任務目標。新會話來的時候是要做新功能的,不是來清理上一個會話的爛攤子的。它會忽略混亂直接開始新工作,然後在混亂的基礎上引入更多混亂。這是熵增的正反饋循環——就像宿舍越亂你越不想收拾,越不收拾越亂,最後誰都不想回宿舍了。+更糟的是,每個工作階段都有自己的任務目標。新工作階段來的時候是要做新功能的,不是來清理上一個工作階段的爛攤子的。它會忽略混亂直接開始新工作,然後在混亂的基礎上引入更多混亂。這是熵增的正回饋循環——就像宿舍越亂你越不想收拾,越不收拾越亂,最後誰都不想回宿舍了。-數據為證。一個使用 agent 持續開發 12 周的項目,沒有清潔策略的情況下:+資料為證。一個使用 agent 持續開發 12 週的專案,沒有清潔策略的情況下:-- 第 1 周:構建通過率 100%,測試通過率 100%,新會話啟動 5 分鐘-- 第 4 周:構建 95%,測試 92%,啟動 15 分鐘-- 第 8 周:構建 82%,測試 78%,啟動 35 分鐘-- 第 12 周:構建 68%,測試 61%,啟動 60+ 分鐘+- 第 1 週:建構通過率 100%,測試通過率 100%,新工作階段啟動 5 分鐘+- 第 4 週:建構 95%,測試 92%,啟動 15 分鐘+- 第 8 週:建構 82%,測試 78%,啟動 35 分鐘+- 第 12 週:建構 68%,測試 61%,啟動 60+ 分鐘-同樣的項目,有清潔策略的情況下:+同樣的專案,有清潔策略的情況下:-- 第 1 周:100%,100%,5 分鐘-- 第 12 周:97%,95%,9 分鐘+- 第 1 週:100%,100%,5 分鐘+- 第 12 週:97%,95%,9 分鐘-12 周後,構建通過率差 29 個百分點,新會話啟動時間差 85%。這不是理論推導,是實際可觀測到的差異。每週不倒垃圾的宿舍和每週倒垃圾的宿舍,12 周後的差距是驚人的。+12 週後,建構通過率差 29 個百分點,新工作階段啟動時間差 85%。這不是理論推導,是實際可觀測到的差異。每週不倒垃圾的宿舍和每週倒垃圾的宿舍,12 週後的差距是驚人的。## 怎麼做### 1. 清潔狀態是完成的必要條件-在 harness 裡明確定義:**會話完成 = 任務通過驗證 AND 清潔狀態檢查通過。** 缺任何一個,會話不算完成。在 CLAUDE.md 裡寫:+在 harness 裡明確定義:**工作階段完成 = 任務通過驗證 AND 清潔狀態檢查通過。** 缺任何一個,工作階段不算完成。在 CLAUDE.md 裡寫:```-## 會話退出檢查清單+## 工作階段退出檢查清單- [ ] 建構通過 (npm run build)- [ ] 所有測試通過 (npm test)- [ ] 功能清單已更新-- [ ] 无調試程式碼残留 (console.log, debugger, TODO)+- [ ] 無調試程式碼殘留 (console.log, debugger, TODO)- [ ] 標準啟動路徑可用 (npm run dev)```@@ -107,43 +107,43 @@ flowchart LR結合兩種清理模式:-**即時清理(每個會話結束時)**:清理本次會話創建的臨時工件、更新功能清單狀態、確保構建和測試通過。這是"引用計數式"清理——用完就清。就像吃完飯馬上洗碗,不留到第二天。+**即時清理(每個工作階段結束時)**:清理本次工作階段建立的臨時工件、更新功能清單狀態、確保建構和測試通過。這是「引用計數式」清理——用完就清。就像吃完飯馬上洗碗,不留到第二天。-**定期清理(每週一次)**:全系統掃描——處理累積的結構性問題、更新質量文檔、運行基準測試檢測漂移。這是"追蹤式"清理——定期做一次大掃除。+**定期清理(每週一次)**:全系統掃描——處理累積的結構性問題、更新品質文件、執行基準測試檢測漂移。這是「追蹤式」清理——定期做一次大掃除。### 3. 維護質量文檔質量文檔是對每個模塊持續評分的活躍工件——就像宿舍的衛生檢查評分表:```markdown-# 品質文檔+# 品質文件-## 使用者認證模块 (品質: A)+## 使用者認證模組 (品質: A)- 驗證通過: 是- agent 可理解: 是-- 測試稳定性: 稳定-- 架构邊界: 合规+- 測試穩定性: 穩定+- 架構邊界: 合規- 程式碼規範: 遵循-## 支付模块 (品質: C)+## 支付模組 (品質: C)- 驗證通過: 部分(支付回調未測試)-- agent 可理解: 困难(逻辑分散在 3 個檔案)-- 測試稳定性: 不稳定(2 個 flaky 測試)-- 架构邊界: 有违规+- agent 可理解: 困難(邏輯分散在 3 個檔案)+- 測試穩定性: 不穩定(2 個 flaky 測試)+- 架構邊界: 有違規- 程式碼規範: 部分遵循```-新會話讀這個文檔就知道優先處理哪裡。質量評分最低的模塊先修。就像衛生檢查表上標記了"需要重點打掃的區域"——下一個值日生知道重點在哪裡。+新工作階段讀這個文件就知道優先處理哪裡。品質評分最低的模組先修。就像衛生檢查表上標記了「需要重點打掃的區域」——下一個值日生知道重點在哪裡。### 4. 定期簡化 harness-harness 裡的每個組件之所以存在,是因為模型無法獨立做好某件事。但隨著模型改進,這些假設會過時。就像你大一的時候需要學長帶著選課,到了大三你自己就知道怎麼選了——學長的作用變小了,但有些事情你還是需要問。+harness 裡的每個元件之所以存在,是因為模型無法獨立做好某件事。但隨著模型改進,這些假設會過時。就像你大一的時候需要學長帶著選課,到了大三你自己就知道怎麼選了——學長的作用變小了,但有些事情你還是需要問。Anthropic 的實驗直接展示了這一點。他們最初的 harness 包含 sprint 拆分機制——把工作分成小塊讓 Sonnet 4.5 逐個完成。當 Opus 4.6 發佈後,模型的原生能力已經可以自主處理工作分解,sprint 構造變成了不必要的開銷。移除後,builder agent 能連續工作超過兩小時而不會跑偏,反而更流暢。但 evaluator 的情況不同。即使 Opus 4.6 能力更強,在任務接近模型能力邊界時,evaluator 仍然提供了實際價值——捕獲 generator 的遺漏功能和存根實現。這意味著 evaluator 不是一個固定的是/否決策,而是取決於任務難度相對於模型能力的位置。-**推薦做法**:每月挑一個 harness 組件,暫時禁用它,跑基準任務。如果結果沒退化,永久移除。如果退化了,恢復或用更輕量的替代。就像定期檢查宿舍公約——大四了還在執行"每天 10 點熄燈"就不太合理了。+**推薦做法**:每月挑一個 harness 元件,暫時停用它,跑基準任務。如果結果沒退化,永久移除。如果退化了,恢復或用更輕量的替代。就像定期檢查宿舍公約——大四了還在執行「大一的宿舍公約」就不太合理了。一個更具體的原則:**隨著模型改進,harness 的有趣組合不是變少了,而是移動了。** 以前必須解決的問題被模型能力覆蓋了,但新的能力邊界打開了以前不可能的 harness 設計。AI 工程師的工作是持續找到下一個有價值的組合。@@ -152,47 +152,47 @@ Anthropic 的實驗直接展示了這一點。他們最初的 harness 包含 spr清理腳本要能安全地重複執行——就像打掃衛生,掃兩遍比掃一遍更乾淨,但不會更髒:```bash-# 幂等的清理操作-rm -f /tmp/debug-*.log # -f 确保檔案不存在時不报錯-git checkout -- .env.local # 恢复到已知狀態-npm run test # 驗證清理未破坏功能+# 冪等的清理操作+rm -f /tmp/debug-*.log # -f 確保檔案不存在時不報錯+git checkout -- .env.local # 恢復到已知狀態+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 持續開發的 Electron 應用,12 周演化過程的對比數據:+一個使用 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 周後省下了幾十個小時的混亂時間。+到第 12 週,實驗組的建構通過率比對照組高 29 個百分點,測試通過率高 34 個百分點,新工作階段啟動時間減少 85%。每天多花 5 分鐘打掃衛生,12 週後省下了幾十個小時的混亂時間。## 關鍵要點-- **清潔狀態是會話完成的必要條件**——不是可選的善後工作,是"完成定義"的一部分。你不倒垃圾,下一個室友就得替你倒。-- **五個維度缺一不可**——構建、測試、進度、工件、啟動,每個都要顯式檢查。-- **質量文檔讓代碼庫健康可追蹤**——知道哪裡在退化才能主動修復。衛生檢查表不是形式主義,是讓你知道哪塊地還沒拖。+- **清潔狀態是工作階段完成的必要條件**——不是可選的善後工作,是「完成定義」的一部分。你不倒垃圾,下一個室友就得替你倒。+- **五個維度缺一不可**——建構、測試、進度、工件、啟動,每個都要顯式檢查。+- **品質文件讓程式碼庫健康可追蹤**——知道哪裡在退化才能主動修復。衛生檢查表不是形式主義,是讓你知道哪塊地還沒拖。- **定期簡化 harness**——隨著模型能力提升,移除不再必要的約束。大四了就別執行大一的宿舍公約了。-- **"以後再清理"等於永遠不清理**——熵增是默認狀態,只有主動的清潔操作才能對抗它。+- **「以後再清理」等於永遠不清理**——熵增是預設狀態,只有主動的清潔操作才能對抗它。## 延伸閱讀-- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — 代碼清潔性的系統化原則+- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — 程式碼清潔性的系統化原則- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 可重複性作為 harness 設計的核心要求-- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — 清潔會話退出對長期可靠性的關鍵作用-- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — 軟件演化定律,證明系統複雜性在無主動維護時必然增長+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — 清潔工作階段退出對長期可靠性的關鍵作用+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — 軟體演化定律,證明系統複雜性在無主動維護時必然增長## 練習-1. **清潔狀態檢查表**:為你的代碼庫設計一個會話退出檢查表,涵蓋五個維度。在 5 個連續會話中應用,記錄每個維度上的違反次數。+1. **清潔狀態檢查表**:為你的程式碼庫設計一個工作階段退出檢查表,涵蓋五個維度。在 5 個連續工作階段中應用,記錄每個維度上的違反次數。2. **基準對比實驗**:固定任務集,兩種 harness 變體(有/無清潔狀態要求)各跑一遍。比較完成率、重試次數和缺陷逃逸率。-3. **harness 簡化實踐**:選一個 harness 組件,暫時禁用,跑基準任務。比較有無該組件的結果。決定保留、移除還是替換。+3. **harness 簡化實踐**:選一個 harness 元件,暫時停用,跑基準任務。比較有無該元件的結果。決定保留、移除還是替換。diff --git a/docs/zh-TW/projects/index.md b/docs/zh-TW/projects/index.mdindex beb52de..176990d 100644--- a/docs/zh-TW/projects/index.md+++ b/docs/zh-TW/projects/index.md@@ -1,17 +1,17 @@# 歡迎來到專案實戰-這裡是 Learn Harness Engineering 的動手實踐部分。僅僅閱讀講義是不夠的,你需要親自搭建環境,觀察 Codex 或 Claude Code 等 Agent 在不同規則下的真實表現。+這裡是 Learn Harness Engineering 的動手實踐部分。僅僅閱讀講義是不夠的,你需要親自搭建環境,觀察 Codex 或 Claude Code 等代理在不同規則下的真實表現。## 專案概覽-本課程包含 6 個漸進式的實戰專案,帶你從零開始建構一個完整的 Agent 工作環境:+本課程包含 6 個漸進式的實戰專案,帶你從零開始建構完整的代理工作環境:-1. **提示詞驅動 vs 規則驅動**:對比一個純 Prompt 驅動的 Agent 和帶有基礎 Harness 的 Agent 在表現上的差異。-2. **讓專案可讀並接住上次工作**:學習如何重構程式碼倉庫結構,使其對 AI 更加友好,並建立工作交接機制。-3. **跨會話工作連續性**:設計狀態檔案和初始化腳本,讓 Agent 可以在多次對話中斷後無縫恢復工作。-4. **執行回饋與行為修正**:引入執行時回饋機制,讓 Agent 能夠自己檢查程式碼是否能跑通,並修正錯誤。-5. **工作評審與自我驗證**:建立獨立的評審與驗證環節,防止 Agent 產生「幻覺」或提前宣告勝利。-6. **綜合 Agent 工作環境**:搭建一套完整的、帶有可觀測性的最終 Agent 工作環境(綜合演練)。+1. **提示詞驅動 vs 規則驅動**:對比純提示詞驅動的代理和帶有基礎 harness 的代理在表現上的差異。+2. **讓專案可讀並接住上次工作**:學習如何重構儲存庫結構,使其對 AI 更加友好,並建立工作交接機制。+3. **跨工作階段工作連續性**:設計狀態檔案和初始化腳本,讓代理可以在多次對話中斷後無縫恢復工作。+4. **執行回饋與行為修正**:引入執行時期回饋機制,讓代理能夠自行檢查程式碼是否能正常執行,並修正錯誤。+5. **工作評審與自我驗證**:建立獨立的評審與驗證環節,防止代理產生「幻覺」或提前宣告完成。+6. **綜合代理工作環境**:搭建一套完整且具備可觀測性的代理工作環境(綜合演練)。## 如何進行@@ -20,4 +20,4 @@- `solution/`:參考的最終實作(如果你卡住了可以參考)。- 相關的指導檔案,說明本次任務的具體背景和目標。-請使用你習慣的 AI Coding Agent(如 Claude Code、Cursor、Trae 等)在每個專案的 `starter/` 目錄下完成任務。+請使用你習慣的 AI 程式設計代理(如 Claude Code、Cursor、Trae 等)在每個專案的 `starter/` 目錄下完成任務。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 97842d1..5c296f9 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@@ -1,13 +1,13 @@-# Project 01. 只寫提示詞讓 agent 做,和定好規則再讓它做,差多少+# Project 01. 只寫提示詞讓代理做,和定好規則再讓它做,差多少> 相關講義:[L01. 模型能力強,不等於執行可靠](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [L02. Harness 到底是什麼](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)## 你要做什麼-用 Electron 搭一個最簡的知識庫應用殼子——能啟動窗口、左邊顯示文檔列表、右邊顯示問答面板、本地有一個數據目錄。任務本身不復雜,複雜的是你怎麼讓 agent 完成它。+用 Electron 搭一個最簡的知識庫應用殼子——能啟動視窗、左側顯示文件清單、右側顯示問答面板、本地有一個資料目錄。任務本身不複雜,複雜的是你如何讓代理完成它。-你需要跑兩次。第一次只給一段提示詞,什麼都不準備,看 agent 能做到什麼程度。第二次提前在倉庫裡放好 `AGENTS.md`、`init.sh`、`feature_list.json`,用結構化的方式告訴 agent 該幹什麼、怎麼驗證、什麼時候算做完。然後對比兩次結果。+你需要執行兩次。第一次只給一段提示詞,什麼都不準備,看代理能做到什麼程度。第二次提前在儲存庫裡放好 `AGENTS.md`、`init.sh`、`feature_list.json`,用結構化的方式告訴代理該做什麼、怎麼驗證、什麼時候算做完。然後對比兩次結果。課程場景使用一小段準備或重新探索時間作為示例,不依賴固定測量值。@@ -17,7 +17,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`。 | 把 prompt 交給 coding agent,量測它在沒有額外結構時完成了什麼。 |+| [`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`。@@ -26,53 +26,53 @@- Claude Code 或 Codex(選一個,兩次都用同一個)- Git(管理分支和對比)-- Node.js + Electron(項目技術棧)-- 一個計時器(記錄每次運行時間)+- Node.js + Electron(專案技術堆疊)+- 一個計時器(記錄每次執行時期間)## 具體步驟### 準備工作1. 從一個乾淨的 commit 出發,記錄 commit hash。-2. 創建兩個分支:`p01-baseline` 和 `p01-improved`。-3. 準備同一段任務提示詞,內容是:"用 Electron 做一個知識庫應用,窗口左邊是文檔列表區域,右邊是問答面板區域,應用需要創建並使用本地數據目錄。"+2. 建立兩個分支:`p01-baseline` 和 `p01-improved`。+3. 準備一段相同的任務提示詞,內容為「用 Electron 做一個知識庫應用,視窗左側是文件清單區域,右側是問答面板區域,應用需要建立並使用本地資料目錄。」-### 第一次運行(弱 harness)+### 第一次執行(弱 harness)切到 `p01-baseline` 分支。-1. 只用上面那段提示詞啟動 agent。+1. 只用上述提示詞啟動代理。2. 不提供 `AGENTS.md`,不提供啟動腳本,不提供驗收標準。3. 設定相同的時間上限和輪次上限(建議 30 分鐘 / 20 輪)。-4. agent 停下後,運行 `npm start`(或對應啟動命令),看應用能不能跑起來。-5. 記錄:終端輸出、關鍵 diff、agent 的最終總結。-6. **不要手動修代碼**。跑不起來就是跑不起來,如實記錄。+4. 代理停止後,執行 `npm start`(或對應啟動命令),確認應用是否能正常啟動。+5. 記錄:終端輸出、關鍵 diff、代理的最終總結。+6. **不要手動修改程式碼**。無法啟動就如實記錄。-### 第二次運行(強 harness)+### 第二次執行(強 harness)-切到 `p01-improved` 分支。在啟動 agent 之前,先在倉庫裡準備好:+切換至 `p01-improved` 分支。在啟動代理之前,先在儲存庫裡準備好:-- `AGENTS.md`:寫明項目結構、啟動命令、Electron 層邊界規則-- `init.sh`:一鍵恢復可運行狀態(`npm install && npm start`)+- `AGENTS.md`:說明專案結構、啟動命令、Electron 層邊界規則+- `init.sh`:一鍵恢復可執行狀態(`npm install && npm start`)- `feature_list.json`:列出四個功能點及其完成狀態-然後用和第一次相同的提示詞啟動 agent,同樣的時間上限和輪次上限。agent 停下後,跑 `./init.sh`,記錄結果。+然後使用與第一次相同的提示詞啟動代理,同樣的時間上限和輪次上限。代理停止後,執行 `./init.sh`,記錄結果。## 怎麼衡量結果| 指標 | 說明 ||------|------|| 完成狀態 | 完全完成 / 部分完成 / 失敗 |-| 首次成功啟動時間 | 從開始到 `npm start` 第一次成功運行 |-| 重試次數 | 中間需要人工干預幾次才能跑起來 |-| 遺漏項 | agent 宣佈完成時還有哪些功能沒做 |-| 過早停止 | agent 是否在不可運行狀態就宣佈完成 |+| 首次成功啟動時間 | 從開始到 `npm start` 第一次成功執行 |+| 重試次數 | 中間需要人工介入幾次才能成功啟動 |+| 遺漏項 | 代理宣告完成時仍有哪些功能尚未實作 |+| 過早停止 | 代理是否在應用尚無法執行時便宣告完成 |## 要交什麼-- 弱 harness 運行記錄:提示詞、日誌/對話記錄、最終 diff、啟動證據-- 強 harness 運行記錄:同上,加上你準備的 harness 檔案-- 一份對比筆記(1-2 頁):兩次運行的差異、數據、結論+- 弱 harness 執行記錄:提示詞、日誌/對話記錄、最終 diff、啟動證據+- 強 harness 執行記錄:同上,加上你準備的 harness 檔案+- 一份對比筆記(1-2 頁):兩次執行的差異、資料、結論## 對應講義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 319d02e..44b7953 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@@ -1,15 +1,15 @@-# Project 02. 讓 agent 看懂項目、接住上次的工作+# Project 02. 讓代理看懂專案、銜接上次的工作> 相關講義:[L03. 讓代碼倉庫成為唯一的事實來源](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [L04. 為什麼一個巨大的指令檔案會失敗](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)## 你要做什麼-P01 證明了準備規則有用。但 P01 的任務一次會話就幹完了。真實開發不是這樣的——你昨天干了一半,今天開新會話,agent 得從倉庫狀態裡搞清楚"做了什麼、沒做什麼、接下來幹什麼"。+P01 證明了準備規則有用。但 P01 的任務一次工作階段就完成了。真實開發不是這樣的——你昨天做了一半,今天開啟新工作階段,代理得從儲存庫狀態中釐清「做了什麼、尚未完成什麼、接下來要做什麼」。-這個項目要求你給倉庫加上"可讀性":讓一個全新的 agent 打開倉庫後,能快速理解項目結構、知道當前進度、接手上次的工作。具體任務是給知識庫應用加上三個功能:文檔導入、文檔詳情頁、導入後的本地持久化。這些功能必須跨至少兩個 agent 會話完成。+這個專案要求你為儲存庫加上「可讀性」:讓一個全新的代理開啟儲存庫後,能快速理解專案結構、知道目前進度、銜接上次的工作。具體任務是給知識庫應用加上三個功能:文件匯入、文件詳情頁面、匯入後的本地持久化。這些功能必須跨至少兩個代理工作階段完成。-你需要跑兩次。第一次不給 agent 任何幫助,看它在第二個會話裡要花多久才能"接上"。第二次提前放好 `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md`,讓它快速對齊上下文。+你需要執行兩次。第一次不給代理任何幫助,看它在第二個工作階段裡要花多久才能「銜接上」。第二次提前放好 `ARCHITECTURE.md`、`PRODUCT.md`、`session-handoff.md`,讓它快速對齊脈絡。## 使用倉庫內建專案@@ -17,81 +17,81 @@ P01 證明了準備規則有用。但 P01 的任務一次會話就幹完了。| 目錄 | 內容 | 比較什麼 ||------|------|------|-| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/starter) | 基於 Project 01 solution 的代碼,但導入/詳情/持久化仍未完整;文檔更薄,且缺少 `session-handoff.md`。 | 新開會話時,agent 需要做多少重新探索才能接上進度。 |-| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/solution) | 同一產品切片已完成,並在 [`projects/project-02/solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/solution) 下補齊核心文檔(以及 [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-02/solution/feature_list.json)、[`session-handoff.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-02/solution/session-handoff.md))等可接手產物。 | 只依靠倉庫狀態,能否快速續寫而不靠口頭上下文。 |+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/starter) | 基於 Project 01 解答版本的程式碼,但匯入/詳情/持久化仍未完整;文件較少,且缺少 `session-handoff.md`。 | 開啟新工作階段時,代理需要重新探索多少才能銜接進度。 |+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/solution) | 同一產品切片已完成,並在 [`projects/project-02/solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/solution) 下補齊核心文件(以及 [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-02/solution/feature_list.json)、[`session-handoff.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-02/solution/session-handoff.md))等可接手產物。 | 只依靠儲存庫狀態,能否快速續寫而不靠口頭脈絡。 |## 用什麼工具- Claude Code 或 Codex(和 P01 保持一致)- Git- Node.js + Electron-- 文本編輯器(寫文檔用)+- 文字編輯器(撰寫文件用)## 具體步驟### 準備工作-1. 基於 P01 完成後的代碼,從同一個 commit 出發。-2. 創建兩個分支:`p02-baseline` 和 `p02-improved`。-3. 列出要實現的三個功能:文檔導入流程、文檔詳情視圖、文檔持久化。兩條分支任務範圍完全一致。+1. 以 P01 完成後的程式碼為基礎,從同一個 commit 出發。+2. 建立兩個分支:`p02-baseline` 和 `p02-improved`。+3. 列出要實作的三個功能:文件匯入流程、文件詳情檢視、文件持久化。兩條分支任務範圍完全一致。-### 第一次運行(弱 harness)+### 第一次執行(弱 harness)切到 `p02-baseline` 分支。-**會話 A:**+**工作階段 A:**-1. 啟動 agent,只給任務描述,不給架構文檔,不給進度檔案。-2. 故意在功能完成之前停止會話(比如只完成文檔導入)。-3. 不寫任何交接檔案。直接結束。+1. 啟動代理,只提供任務描述,不提供架構文件,不提供進度檔案。+2. 刻意在功能完成之前結束工作階段(例如只完成文件匯入)。+3. 不撰寫任何交接檔案。直接結束。-**會話 B:**+**工作階段 B:**-1. 開一個全新的 agent 會話。-2. 只說"繼續開發",不給額外上下文。-3. 記錄 agent 花了多久才做出第一個有意義的代碼修改。-4. 記錄 agent 哪些時候在"重新發現"本來已經知道的東西。+1. 開啟一個全新的代理工作階段。+2. 只告知「繼續開發」,不提供額外脈絡。+3. 記錄代理花了多久才做出第一個有意義的程式碼修改。+4. 記錄代理哪些時候在「重新發現」本來已經知道的東西。-### 第二次運行(強 harness)+### 第二次執行(強 harness)-切到 `p02-improved` 分支。在第一個會話之前,先在倉庫裡準備好:+切換至 `p02-improved` 分支。在第一個工作階段之前,先在儲存庫中準備好:-- `ARCHITECTURE.md`:描述項目結構、Electron 各層職責、數據流-- `PRODUCT.md`:描述產品功能範圍和當前階段目標+- `ARCHITECTURE.md`:描述專案結構、Electron 各層職責、資料流+- `PRODUCT.md`:描述產品功能範圍和目前階段目標- `AGENTS.md`:啟動命令、工作規則、驗證方式-- `init.sh`:一鍵恢復可運行狀態+- `init.sh`:一鍵恢復可執行狀態-**會話 A:**+**工作階段 A:**-1. 啟動 agent,讓它開始工作。+1. 啟動代理,讓它開始工作。2. 同樣在功能完成之前停止。-3. **這次要求 agent 更新 `session-handoff.md`**:記錄做了什麼、沒做什麼、下一步是什麼。+3. **這次要求代理更新 `session-handoff.md`**:記錄做了什麼、沒做什麼、下一步是什麼。-**會話 B:**+**工作階段 B:**-1. 開一個全新的 agent 會話。-2. 讓 agent 讀 `session-handoff.md` 和 `feature_list.json`,然後繼續。-3. 同樣記錄接手速度和重複工作比例。+1. 開啟一個全新的代理工作階段。+2. 讓代理讀取 `session-handoff.md` 和 `feature_list.json`,然後繼續。+3. 同樣記錄銜接速度和重複工作比例。## 怎麼衡量結果| 指標 | 說明 ||------|------|-| 會話 B 接手時間 | 從開始到第一個有效代碼修改的時間 |-| 重新發現次數 | agent 重新瞭解架構、命令、狀態等已有信息的次數 |-| 交接檔案質量 | 交接記錄是否完整、準確、可操作 |-| 重複工作比例 | 會話 B 中有多少工作量是在重複會話 A 已做過的事 |+| 工作階段 B 銜接時間 | 從開始到第一個有效程式碼修改的時間 |+| 重新發現次數 | 代理重新瞭解架構、命令、狀態等既有資訊的次數 |+| 交接檔案品質 | 交接記錄是否完整、準確、可操作 |+| 重複工作比例 | 工作階段 B 中有多少工作量是在重複工作階段 A 已做過的事 || 最終完成狀態 | 三個功能是否全部完成 |## 要交什麼-- 弱 harness 的會話 A + B 日誌/對話記錄-- 強 harness 的會話 A + B 日誌/對話記錄-- 兩次運行中產生的交接檔案-- 一份對比筆記:重點比較接手速度和上下文恢復質量+- 弱 harness 的工作階段 A + B 日誌/對話記錄+- 強 harness 的工作階段 A + B 日誌/對話記錄+- 兩次執行中產生的交接檔案+- 一份對比筆記:重點比較銜接速度和脈絡恢復品質## 對應講義- [Lecture 03 — 為什麼倉庫必須成為唯一事實來源](../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)- [Lecture 04 — 為什麼一個大而全的指令檔案不行](../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)-- [Lecture 05 — 為什麼長任務會丟失連續性](../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)+- [Lecture 05 — 為什麼長任務會遺失連續性](../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.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 422bef9..1f027ed 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@@ -1,15 +1,15 @@-# Project 03. 讓 agent 關掉再打開還能接著幹+# Project 03. 讓代理重啟後還能繼續執行-> 相關講義:[L05. 為什麼長時任務會丟失上下文](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [L06. 為什麼初始化需要單獨一個階段](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)+> 相關講義:[L05. 為什麼長時任務會遺失脈絡](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [L06. 為什麼初始化需要單獨一個階段](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)## 你要做什麼-P02 解決了"接手"的問題,但 agent 接手之後能不能把活幹完、幹對了,又是另一回事。這個項目要你給 agent 加上範圍控制和驗證關卡。+P02 解決了「銜接」的問題,但代理銜接之後能否完整且正確地完成任務,則是另一回事。這個專案要你為代理加上範圍控制和驗證關卡。-你要實現的知識庫功能是:文檔分塊、元數據提取、索引進度顯示、帶引用的問答流程。這些功能比前兩個項目複雜,agent 更容易跑偏——要麼多做了不該做的,要麼說做完了但其實沒通過驗證。+你要實作的知識庫功能是:文件分塊、元資料提取、索引進度顯示、附引用的問答流程。這些功能比前兩個專案複雜,代理更容易偏離目標,可能多做了不在範圍內的事,或是宣稱完成卻未通過驗證。-你需要一個 `feature_list.json`,每個功能有明確的狀態(failing / passing)。規則很簡單:一次只做一個功能,沒有可運行的驗證證據就不能標成 passing。跑兩次,一次不給這些約束,一次嚴格執行,看結果差多少。+你需要一個 `feature_list.json`,每個功能有明確的狀態(failing / passing)。規則很簡單:一次只做一個功能,沒有可執行的驗證證據就不能標成 passing。執行兩次,一次不給這些約束,一次嚴格執行,觀察結果差距。## 使用倉庫內建專案@@ -17,7 +17,7 @@ P02 解決了"接手"的問題,但 agent 接手之後能不能把活幹完、| 目錄 | 內容 | 比較什麼 ||------|------|------|-| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-03/starter) | Project 02 代碼基礎上,索引與 grounded QA 尚未完善;有初版 [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/starter/feature_list.json),但缺少最終的重啟/交接與乾淨狀態產物。 | 多次重啟/多功能任務下,agent 是否漂移、是否丟狀態。 |+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-03/starter) | 以 Project 02 程式碼為基礎,索引與 grounded QA 尚未完善;有初版 [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/starter/feature_list.json),但缺少最終的重啟/交接與乾淨狀態產物。 | 多次重啟或多功能任務下,代理是否偏移、是否遺失狀態。 || [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-03/solution) | 完整的 chunking、metadata、indexing status、citation-based QA,並補齊 [`init.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/init.sh)、[`session-handoff.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/session-handoff.md)、[`claude-progress.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/claude-progress.md)、[`clean-state-checklist.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/clean-state-checklist.md)。 | 是否能做到“一次只做一個功能”,且每個功能都有可執行證據才標記通過。 |## 用什麼工具@@ -31,50 +31,50 @@ P02 解決了"接手"的問題,但 agent 接手之後能不能把活幹完、### 準備工作-1. 基於 P02 完成後的代碼,從同一個 commit 出發。-2. 創建兩個分支:`p03-baseline` 和 `p03-improved`。-3. 定義四個功能:文檔分塊、元數據提取、索引進度 UI 顯示、帶引用的問答。兩條分支的功能定義完全一致。+1. 以 P02 完成後的程式碼為基礎,從同一個 commit 出發。+2. 建立兩個分支:`p03-baseline` 和 `p03-improved`。+3. 定義四個功能:文件分塊、元資料提取、索引進度 UI 顯示、附引用的問答。兩條分支的功能定義完全一致。-### 第一次運行(弱 harness)+### 第一次執行(弱 harness)切到 `p03-baseline` 分支。-1. 啟動 agent,給一段模糊的任務提示詞。+1. 啟動代理,給一段模糊的任務提示詞。2. 不提供 `feature_list.json`,沒有狀態追蹤。-3. 不限制 agent 一次做幾個功能。-4. 沒有明確的驗證標準——agent 自己說"完成了"就算。-5. 運行結束後,手動檢查每個功能是否真的能用。-6. 記錄哪些功能 agent 聲稱完成但實際沒通過驗證。+3. 不限制代理一次做幾個功能。+4. 沒有明確的驗證標準,代理自行宣告「完成了」便算數。+5. 執行結束後,手動確認每個功能是否確實可用。+6. 記錄哪些功能代理聲稱完成,但實際上未通過驗證。-### 第二次運行(強 harness)+### 第二次執行(強 harness)-切到 `p03-improved` 分支。在啟動 agent 之前:+切換至 `p03-improved` 分支。在啟動代理之前:-- 在倉庫根目錄放好 `feature_list.json`,四個功能全部標為 `failing`。+- 在儲存庫根目錄放好 `feature_list.json`,四個功能全部標為 `failing`。- 在 `AGENTS.md` 裡寫明規則:一次只做一個功能;狀態只能從 `failing` 切到 `passing`,且必須有驗證證據。- 準備好 `init.sh`。-然後啟動 agent:+然後啟動代理:-1. agent 開始工作,每完成一個功能必須更新 `feature_list.json` 並附上驗證證據(截圖、測試輸出等)。+1. 代理開始工作,每完成一個功能必須更新 `feature_list.json` 並附上驗證證據(截圖、測試輸出等)。2. 至少要有一個功能展示從 `failing` 到 `passing` 的完整轉換過程。3. 問答功能的驗證必須檢查引用是否存在、引用是否相關,不能只看有沒有輸出。-4. 運行結束後歸檔所有驗證證據。+4. 執行結束後歸檔所有驗證證據。## 怎麼衡量結果| 指標 | 說明 ||------|------|-| 範圍漂移次數 | agent 做了功能清單之外的事的次數 |-| 虛假完成率 | agent 聲稱完成但驗證不通過的功能比例 |+| 範圍漂移次數 | 代理做了功能清單之外的事的次數 |+| 虛假完成率 | 代理聲稱完成但驗證未通過的功能比例 || 驗證覆蓋率 | 有明確驗證證據的功能佔總功能的百分比 || 問答質量 | 引用是否存在、引用是否相關 || 重試次數 | 從開始到所有功能 passing 總共重試了幾次 |## 要交什麼-- 弱 harness 運行記錄:提示詞、日誌、驗證結果-- 強 harness 運行記錄:`feature_list.json` 變更歷史、日誌、驗證證據+- 弱 harness 執行記錄:提示詞、日誌、驗證結果+- 強 harness 執行記錄:`feature_list.json` 變更歷史、日誌、驗證證據- 至少一個功能從 `failing` 到 `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 56f93e8..5f5519f 100644--- a/docs/zh-TW/projects/project-04-incremental-indexing/index.md+++ b/docs/zh-TW/projects/project-04-incremental-indexing/index.md@@ -1,15 +1,15 @@-# Project 04. 用運行反饋修正 agent 的行為+# Project 04. 用執行回饋修正代理的行為> 相關講義:[L07. 為什麼 agent 會多做或少做](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [L08. 為什麼功能清單是 harness 原語](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)## 你要做什麼-前三個項目關注的是"讓 agent 把活幹完"。這個項目關注的是"出了問題怎麼修"——而且不是你修,是讓 agent 自己通過運行時信號來修。+前三個專案關注的是「讓代理把任務做完」。這個專案關注的是「出了問題怎麼修」——而且不是你修,是讓代理自己透過執行時期訊號來修。-你要做兩件事。第一,給知識庫應用加上運行時可觀測性:啟動日誌、導入和索引的日誌、問答失敗時的用戶可見錯誤狀態。第二,在倉庫裡編碼架構約束,讓 agent 不可能靜默地跨層違規(main / preload / renderer / services 之間的邊界)。+你要做兩件事。第一,給知識庫應用加上執行時期可觀測性:啟動日誌、匯入和索引的日誌、問答失敗時的使用者可見錯誤狀態。第二,在儲存庫中明確定義架構約束,讓代理不可能靜默地跨層違規(main / preload / renderer / services 之間的邊界)。-然後你會在代碼裡埋一個運行時 bug,讓 agent 去修。跑兩次:一次不給日誌和約束,看 agent 怎麼修;一次給好日誌和架構規則,看差別。+然後你會在程式碼裡植入一個執行時期 bug,讓代理去修。執行兩次:一次不給日誌和約束,觀察代理如何修正;一次給好日誌和架構規則,看差別。## 使用倉庫內建專案@@ -17,8 +17,8 @@| 目錄 | 內容 | 比較什麼 ||------|------|------|-| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-04/starter) | Project 03 代碼,但診斷較弱;存在一個種子缺陷,可能導致大文件 chunking/索引失敗;也沒有架構檢查腳本。 | 沒有運行時信號時,定位根因需要多久、改動是否擴散。 |-| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-04/solution) | 結構化 logger、架構邊界文檔與腳本、修復 chunking/索引邏輯,並補齊 [`clean-state-checklist.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/clean-state-checklist.md)。 | 有日誌與邊界檢查後,修復是否更快、更可控、可復現。 |+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-04/starter) | 以 Project 03 程式碼為基礎,但診斷能力較弱;存在一個種子缺陷,可能導致大型文件 chunking/索引失敗;也沒有架構檢查腳本。 | 沒有執行時期訊號時,定位根本原因需要多久、改動是否擴散。 |+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-04/solution) | 結構化 logger、架構邊界文件與腳本、修復 chunking/索引邏輯,並補齊 [`clean-state-checklist.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/clean-state-checklist.md)。 | 有日誌與邊界檢查後,修復是否更快、更可控、可復現。 |## 用什麼工具@@ -26,60 +26,60 @@- Git- Node.js + Electron- 日誌庫(如 `electron-log` 或簡單的 console 封裝)-- 結構化檢查工具(ESLint 自定義規則、guard 腳本、或測試)+- 結構化檢查工具(ESLint 自訂規則、guard 腳本、或測試)## 具體步驟### 準備工作-1. 基於 P03 完成後的代碼,從同一個 commit 出發。-2. 創建兩個分支:`p04-baseline` 和 `p04-improved`。-3. 在兩個分支中埋入同一個運行時 bug(比如:索引時 chunk 大小讀取錯誤導致問答返回空結果)。-4. 記錄 bug 的位置和表現,但不要告訴 agent bug 在哪。+1. 以 P03 完成後的程式碼為基礎,從同一個 commit 出發。+2. 建立兩個分支:`p04-baseline` 和 `p04-improved`。+3. 在兩個分支中植入同一個執行時期 bug(例如:索引時 chunk 大小讀取錯誤導致問答回傳空結果)。+4. 記錄 bug 的位置和表現,但不要告知代理 bug 所在。-### 第一次運行(弱 harness)+### 第一次執行(弱 harness)-切到 `p04-baseline` 分支。+切換至 `p04-baseline` 分支。-1. 啟動 agent,告訴它"問答功能返回空結果,請修復"。-2. 倉庫裡沒有運行時日誌,沒有架構約束檔案。-3. 記錄 agent 花了多久找到根因、怎麼確認修復的、修復過程中是否引入了新的層邊界違規。-4. 修復後重啟應用,確認是否能幹淨啟動。+1. 啟動代理,告知「問答功能回傳空結果,請修復」。+2. 儲存庫中沒有執行時期日誌,也沒有架構約束檔案。+3. 記錄代理花了多久找到根本原因、如何確認修復成效、修復過程中是否引入了新的層邊界違規。+4. 修復後重啟應用,確認是否能乾淨啟動。-### 第二次運行(強 harness)+### 第二次執行(強 harness)-切到 `p04-improved` 分支。在啟動 agent 之前,先在倉庫裡準備好:+切換至 `p04-improved` 分支。在啟動代理之前,先在儲存庫中準備好:-- **運行時日誌**:啟動時打印初始化步驟,導入時打印檔案數量和 chunk 結果,索引時打印進度,問答失敗時打印錯誤原因。-- **架構約束**:在 `AGENTS.md` 裡明確寫 Electron 四層邊界(main / preload / renderer / services),說明哪些調用路徑是允許的。用 ESLint 規則或 guard 腳本檢查違規。-- **乾淨狀態要求**:最終交付前必須能幹淨重啟。+- **執行時期日誌**:啟動時輸出初始化步驟,匯入時輸出檔案數量和 chunk 結果,索引時輸出進度,問答失敗時輸出錯誤原因。+- **架構約束**:在 `AGENTS.md` 裡明確寫 Electron 四層邊界(main / preload / renderer / services),說明哪些呼叫路徑是允許的。用 ESLint 規則或 guard 腳本檢查違規。+- **乾淨狀態要求**:最終交付前必須能乾淨重啟。-然後啟動 agent:+然後啟動代理:-1. 先讓 agent 加上日誌和結構化檢查(這是任務的一部分)。-2. 然後告訴它"問答功能返回空結果,請修復"。-3. 這次 agent 有日誌可以看,有架構規則可以參照。-4. 記錄診斷速度、修復質量、是否引入了邊界違規。+1. 先讓代理加上日誌和結構化檢查(這是任務的一部分)。+2. 然後告知「問答功能回傳空結果,請修復」。+3. 這次代理有日誌可以查看,有架構規則可以參照。+4. 記錄診斷速度、修復品質、是否引入了邊界違規。5. 修復後重啟應用,確認乾淨啟動。## 怎麼衡量結果| 指標 | 說明 ||------|------|-| 根因定位時間 | 從開始到 agent 準確描述 bug 原因 |+| 根因定位時間 | 從開始到代理準確描述 bug 根本原因 || 修復確認時間 | 從定位到驗證修復成功 || 邊界違規數 | 修復過程中引入的跨層違規次數 || 日誌有用性 | 日誌是否直接指向了失敗原因 |-| 乾淨重啟 | 修復後是否能幹淨重啟、無報錯 |+| 乾淨重啟 | 修復後是否能乾淨重啟且無報錯 |## 要交什麼-- 弱 harness 的調試記錄:診斷過程、修復 diff、啟動證據-- 強 harness 的調試記錄:同上,加上日誌和架構約束檔案+- 弱 harness 的除錯記錄:診斷過程、修復 diff、啟動證據+- 強 harness 的除錯記錄:同上,加上日誌和架構約束檔案- 結構化檢查產物(lint 規則、guard 腳本、或測試檔案)- 一份對比筆記:重點比較診斷速度和修復健壯性## 對應講義- [Lecture 11 — 為什麼可觀測性屬於 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)-- [Lecture 12 — 為什麼每個會話都必須留下乾淨狀態](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+- [Lecture 12 — 為什麼每個工作階段都必須留下乾淨狀態](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)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 2c86c35..e7e5b43 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@@ -1,15 +1,15 @@-# Project 05. 讓 agent 自己檢查自己做的對不對+# Project 05. 讓代理自己檢查自己做得對不對> 相關講義:[L09. 為什麼 agent 會提前宣告完成](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [L10. 為什麼端到端測試會改變結果](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)## 你要做什麼-前四個項目裡,"檢查做得對不對"這件事要麼是你手動做的,要麼是靠檔案規則強制執行的。這個項目要讓 agent 自己來檢查。+前四個專案裡,「檢查做得對不對」這件事要麼是你手動做的,要麼是靠檔案規則強制執行的。這個專案要讓代理自行檢查。-方法是角色分離。以前是同一個 agent 既寫代碼又判斷質量。現在拆開:一個 agent 負責實現(生成者),另一個 agent 負責審查(評估者)。更進一步,還可以加一個負責規劃的角色(規劃者)。你要跑三次,看每加一層角色分離,結果好多少。+方法是角色分離。以前是同一個代理既寫程式碼又判斷品質。現在拆開:一個代理負責實作(生成者),另一個代理負責審查(評估者)。更進一步,還可以加一個負責規劃的角色(規劃者)。你要執行三次,看每加一層角色分離,結果好多少。-選一個實質性的功能升級(比如多輪對話歷史、引用面板重設計、文檔集合與篩選),三次都做同一個升級,唯一變量是 harness 的角色分工。+選一個實質性的功能升級(如多輪對話歷史、引用面板重新設計、文件集合與篩選),三次都做同一個升級,唯一變數是 harness 的角色分工。## 使用倉庫內建專案@@ -17,15 +17,15 @@| 目錄 | 內容 | 比較什麼 ||------|------|------|-| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/starter) | 基於 Project 04 的應用,尚未做 ConversationHistory(多輪對話歷史)升級。 | 若你要自己重跑三種變體,從這裡開始。 |-| [`solution/single-role/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/solution/single-role) | 單角色:同一個 agent 規劃/實作/自查。 | [`evaluator-rubric.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/single-role/evaluator-rubric.md) 低分與缺陷清單。 |+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/starter) | 以 Project 04 的應用為基礎,尚未實作 ConversationHistory(多輪對話歷史)升級。 | 若你要自己重跑三種變體,從這裡開始。 |+| [`solution/single-role/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/solution/single-role) | 單角色:同一個代理負責規劃/實作/自查。 | [`evaluator-rubric.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/single-role/evaluator-rubric.md) 低分與缺陷清單。 || [`solution/gen-eval/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/solution/gen-eval) | 生成者 + 評估者:有修訂與回饋證據。 | [`evaluator-rubric.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/gen-eval/evaluator-rubric.md) 分數與 revision 記錄。 || [`solution/plan-gen-eval/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/solution/plan-gen-eval) | 規劃者 + 生成者 + 評估者:有 sprint contract。 | [`sprint-contract.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/plan-gen-eval/sprint-contract.md) 與 [`evaluator-rubric.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/plan-gen-eval/evaluator-rubric.md) 高分證據。 |## 用什麼工具- Claude Code 或 Codex(用於生成和規劃角色)-- 同一個或另一個 agent 實例(用於評估角色)+- 同一個或另一個代理實例(用於評估角色)- 評估量表(參考 `docs/zh-TW/resources/templates/evaluator-rubric.md`)- Sprint contract 範本(參考 `docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md`)@@ -33,48 +33,48 @@### 準備工作-1. 基於 P04 完成後的代碼,從同一個 commit 出發。-2. 創建三個分支:`p05-single`、`p05-gen-eval`、`p05-plan-gen-eval`。-3. 選定一個功能升級,寫清楚驗收標準。三次運行的功能範圍和驗收標準完全一致。-4. 寫好評估量表,打分維度至少包括:正確性、可靠性、可維護性、用戶體驗。+1. 以 P04 完成後的程式碼為基礎,從同一個 commit 出發。+2. 建立三個分支:`p05-single`、`p05-gen-eval`、`p05-plan-gen-eval`。+3. 選定一個功能升級,寫清楚驗收標準。三次執行的功能範圍和驗收標準完全一致。+4. 制定評估量表,評分維度至少包括:正確性、可靠性、可維護性、用戶體驗。-### 第一次運行(弱 harness — 單角色)+### 第一次執行(弱 harness — 單角色)切到 `p05-single` 分支。-1. 一個 agent 包攬規劃、實現、自查。-2. 沒有外部評估量表,agent 自己判斷做得好不好。+1. 一個代理包攬規劃、實作、自查。+2. 沒有外部評估量表,代理自行判斷品質。3. 記錄最終產出和未解決的缺陷。-### 第二次運行(強 harness — 生成者 + 評估者)+### 第二次執行(強 harness — 生成者 + 評估者)切到 `p05-gen-eval` 分支。1. 生成者和評估者先用 sprint contract 對齊:做什麼、怎麼驗證、什麼不算在範圍內。-2. 生成者實現功能。-3. 評估者用評估量表打分,反饋問題。-4. 生成者根據反饋修改。至少經過一輪修訂。+2. 生成者實作功能。+3. 評估者用評估量表評分,並回饋問題。+4. 生成者根據回饋修改。至少經過一輪修訂。5. 記錄評估者抓住了多少缺陷、修訂了多少內容。-### 第三次運行(更強 harness — 規劃者 + 生成者 + 評估者)+### 第三次執行(更強 harness — 規劃者 + 生成者 + 評估者)切到 `p05-plan-gen-eval` 分支。1. 規劃者先拆解任務、定義步驟和依賴關係。-2. 生成者按規劃實現。+2. 生成者按規劃實作。3. 評估者用同一份評估量表打分。4. 至少經過一輪修訂。5. 記錄規劃是否減少了返工。### 評估者調優-評估者不是一次就能用好的。初始版本的評估者往往會"發現問題然後自己說服自己通過"。你需要:+評估者不是一次就能用好的。初始版本的評估者可能會「發現問題,卻自行說服自己通過」。你需要:-1. 讓評估者給一個已完成的 sprint 打分。-2. 和你自己的判斷對比。+1. 讓評估者給一個已完成的 sprint 評分。+2. 與你自己的判斷相比對。3. 哪裡有分歧,就把量表寫得更具體。-4. 重新跑評估者,檢查對齊程度。-5. 重複 3-5 輪,直到評估者判斷和你的判斷基本一致。記錄每一輪調優的內容。+4. 重新執行評估者,檢查對齊程度。+5. 重複 3 至 5 輪,直到評估者的判斷與你的判斷大致一致。記錄每一輪調優的內容。## 怎麼衡量結果@@ -83,19 +83,19 @@| 範圍定義質量 | 編碼前的任務拆解清晰度 || 缺陷檢出數 | 交付前被評估者抓到的缺陷數量和嚴重程度 || 量表評分 | 各維度的得分(正確性、可靠性、可維護性、UX) |-| 返工量 | 評估反饋後需要重做的比例 |-| 最終健壯性 | 升級後功能在實際運行中的穩定程度 |+| 返工量 | 評估回饋後需要重做的比例 |+| 最終健壯性 | 升級後功能在實際執行中的穩定程度 || 評估者調優輪數 | 評估者判斷與你對齊需要的迭代次數 |-| Sprint contract 效果 | 合同是否減少了評估中的模糊地帶 |+| Sprint contract 效果 | 合約是否減少了評估中的模糊地帶 |## 要交什麼-- Sprint contract 文檔+- Sprint contract 文件- 評估者調優日誌(每輪改了什麼、為什麼改)-- 單角色運行記錄:提示詞、日誌、可運行證據-- 生成者+評估者運行記錄:含量表評分和修訂記錄-- 規劃者+生成者+評估者運行記錄:含規劃文檔、量表評分、修訂記錄-- 一份對比筆記:質量提升幅度和協調成本+- 單角色執行記錄:提示詞、日誌、可執行證據+- 生成者+評估者執行記錄:含量表評分和修訂記錄+- 規劃者+生成者+評估者執行記錄:含規劃文件、量表評分、修訂記錄+- 一份對比筆記:品質提升幅度和協調成本## 對應講義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 059f4b3..c6506d9 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@@ -1,13 +1,13 @@-# Project 06. 搭建一套完整的 agent 工作環境+# Project 06. 搭建完整的代理工作環境-> 相關講義:[L11. 為什麼可觀測性屬於 harness](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [L12. 為什麼每次會話都要留乾淨狀態](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+> 相關講義:[L11. 為什麼可觀測性屬於 harness](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [L12. 為什麼每次工作階段都要留乾淨狀態](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)> 本篇範本檔案:[templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh-TW/resources/templates/)## 你要做什麼-這是結業項目。把前五個項目學到的所有東西組裝起來,跑一次完整的基準測試,然後做一輪清理,驗證質量是可以持續維護的。+這是結業專案。把前五個專案學到的所有東西組裝起來,執行一次完整的基準測試,然後做一輪清理,驗證品質是可以持續維護的。-你要用一套固定的多功能任務集,覆蓋知識庫應用的完整產品切片:導入文檔、構建索引、帶引用的問答、運行時可觀測性、可讀可重啟的倉庫狀態。先跑一次弱 harness 基線,再跑一次你組裝的最強 harness,然後做一輪清理和重跑。最後還要做一次 harness 精簡實驗——刪掉一個組件看看結果會不會變差,判斷哪些組件是真正有用的、哪些是多餘的開銷。+你要用一套固定的多功能任務集,涵蓋知識庫應用的完整產品切片:匯入文件、建構索引、附引用的問答、執行時期可觀測性、可讀可重啟的儲存庫狀態。先執行一次弱 harness 基線,再執行一次你組裝的最強 harness,然後做一輪清理和重新執行。最後還要做一次 harness 精簡實驗——刪掉一個組件,觀察結果是否變差,判斷哪些組件是真正有用的、哪些是多餘的開銷。## 使用倉庫內建專案@@ -23,61 +23,60 @@- Claude Code 或 Codex- Git- Node.js + Electron-- 質量文檔範本(`docs/zh-TW/resources/templates/quality-document.md`)+- 品質文件範本(`docs/zh-TW/resources/templates/quality-document.md`)- 評估量表(`docs/zh-TW/resources/templates/evaluator-rubric.md`)-- 前五個項目積累的所有 harness 組件+- 前五個專案積累的所有 harness 組件## 具體步驟### 準備工作-1. 基於 P05 完成後的代碼,從同一個 commit 出發。-2. 創建兩個分支:`p06-baseline` 和 `p06-improved`。-3. 用質量文檔範本給當前代碼打一次初始評分(每個產品領域和架構層的等級)。-4. 定義一套固定的基準任務集和評分表——在跑任何 agent 之前就定好,跑的過程中不改。+1. 以 P05 完成後的程式碼為基礎,從同一個 commit 出發。+2. 建立兩個分支:`p06-baseline` 和 `p06-improved`。+3. 以品質文件範本為目前程式碼進行初始評分(每個產品領域和架構層的等級)。+4. 定義一套固定的基準任務集和評分表——在執行任何代理之前先定好,執行過程中不更改。基準任務集至少包括:-- 導入一篇文檔-- 構建或刷新索引-- 回答一個帶引用的問題-- 查看運行時日誌確認可觀測性-- 關掉重開後狀態仍在+- 匯入一篇文件+- 建構或重新整理索引+- 回答一個附引用的問題+- 查看執行時期日誌確認可觀測性+- 關閉再重新啟動後狀態仍保留-### 第一次運行(弱 harness)+### 第一次執行(弱 harness)切到 `p06-baseline` 分支。1. 用課程早期階段的弱 harness(沒有完整交接檔案、沒有嚴格驗證、可觀測性不足)。-2. 用 agent 跑完整個基準任務集。+2. 以代理執行完整個基準任務集。3. 立刻評分。記錄每個任務的完成狀態、重試次數、缺陷數。-4. 更新質量文檔,記錄每個領域和層的等級變化。+4. 更新品質文件,記錄每個領域和層的等級變化。-### 第二次運行(強 harness)+### 第二次執行(強 harness)切到 `p06-improved` 分支。-1. 用你在這門課裡組裝的最強 harness:交接檔案和啟動腳本、明確的範圍和驗證關卡、運行時信號和架構約束、評估者或多角色審查、質量文檔追蹤。+1. 用你在這門課裡組裝的最強 harness:交接檔案和啟動腳本、明確的範圍和驗證關卡、執行時期訊號和架構約束、評估者或多角色審查、品質文件追蹤。2. 同樣的基準任務集,同樣的模型和預算。-3. 立刻評分。記錄結果。-4. 更新質量文檔。+3. 立刻評分,記錄結果,更新品質文件。### 清理和重跑在 `p06-improved` 分支上:-1. 做一輪清理:刪死代碼、修不清楚的文檔、理順不穩定的運行路徑。-2. 清理後重跑同樣的基準任務集,重新評分。-3. 更新質量文檔。+1. 做一輪清理:刪除無用程式碼、修正不清楚的文件、理順不穩定的執行路徑。+2. 清理後重新執行同樣的基準任務集,重新評分。+3. 更新品質文件。-對比三個快照的質量文檔:基線、強 harness、清理後。+比對三個快照的品質文件:基線、強 harness、清理後。### Harness 精簡實驗1. 從 `p06-improved` 分支中刪掉一個 harness 組件(比如刪掉 sprint contract,或者刪掉顯式範圍關卡)。-2. 重跑基準任務集。-3. 如果結果沒變差——說明這個組件是多餘的開銷,可以去掉。-4. 如果結果變差了——說明這個組件是承重的,必須保留。+2. 重新執行基準任務集。+3. 如果結果沒變差,表示這個組件是多餘的開銷,可以去掉。+4. 如果結果變差了,表示這個組件是承重的,必須保留。5. 記錄實驗結果。可以多試幾個組件。## 怎麼衡量結果@@ -88,16 +87,16 @@| 重試次數 | 每個任務需要重試幾次 || 缺陷數 | 人工干預前發現的缺陷數量 || 清理工作量 | 清理花了多長時間、改了多少檔案 |-| 清理後可讀性和重啟成功率 | 清理後倉庫的可維護程度 |+| 清理後可讀性和重啟成功率 | 清理後儲存庫的可維護程度 || 質量文檔等級變化 | 三個快照的等級對比 || Harness 精簡結果 | 哪些組件可以刪、哪些是承重的 |## 要交什麼-- 質量文檔的三個快照(基線、強 harness、清理後)+- 品質文件的三個快照(基線、強 harness、清理後)- 基線基準測試記錄:評分和證據- 強 harness 基準測試記錄:評分和證據-- 清理運行記錄:清理前後評分變化+- 清理執行記錄:清理前後評分變化- Harness 精簡日誌:刪了什麼組件、基準結果、決定保留還是刪- 最終結業總結:關鍵經驗教訓@@ -107,4 +106,4 @@- [Lecture 03 — 為什麼倉庫必須成為唯一事實來源](../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)- [Lecture 08 — 為什麼 feature list 是 harness 的基礎原語](../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)- [Lecture 11 — 為什麼可觀測性屬於 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)-- [Lecture 12 — 為什麼每個會話都必須留下乾淨狀態](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)+- [Lecture 12 — 為什麼每個工作階段都必須留下乾淨狀態](../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)diff --git a/docs/zh-TW/resources/index.md b/docs/zh-TW/resources/index.mdindex b410cb0..b2000ec 100644--- a/docs/zh-TW/resources/index.md+++ b/docs/zh-TW/resources/index.md@@ -7,9 +7,9 @@## 適合什麼時候用-當你準備讓 Codex、Claude Code 或其他 coding agent 在一個倉庫裡持續工作時,就可以從這裡開始。它特別適合這些場景:+當你準備讓 Codex、Claude Code 或其他 coding agent 在一個儲存庫裡持續工作時,就可以從這裡開始。它特別適合這些場景:-- 多輪會話開發,擔心上下文斷裂+- 多輪工作階段開發,擔心脈絡斷裂- 功能多,容易出現做一半就停的半成品- 常常提前宣布完成,但實際沒測透- 每次開工都要重新摸索啟動方式@@ -25,19 +25,19 @@然後按需要補上:-- 會話交接範本:[`templates/session-handoff.md`](./templates/session-handoff.md)+- 工作階段交接範本:[`templates/session-handoff.md`](./templates/session-handoff.md)- 收尾檢查清單:[`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)- 評審範本:[`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)-如果你想直接採用 OpenAI 那篇 harness engineering 文章裡更完整的倉庫組織方式,可以繼續看:+如果你想直接採用 OpenAI 那篇 harness engineering 文章裡更完整的儲存庫組織方式,可以繼續看:- [`openai-advanced/index.md`](./openai-advanced/index.md)## 資源庫結構-- [`templates/`](./templates/index.md):可以直接複製到真實倉庫裡的範本+- [`templates/`](./templates/index.md):可以直接複製到真實儲存庫裡的範本- [`reference/`](./reference/index.md):方法說明、啟動流程和問題對照表-- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 風格高階資源包,包括倉庫骨架、品質檔案、執行計畫和系統級治理檔案+- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 風格高階資源包,包括儲存庫骨架、品質檔案、執行計畫和系統級治理檔案## 推薦最小組合@@ -48,5 +48,5 @@先把這四樣放進專案裡,再開始讓 agent 持續工作,通常就已經能明顯降低返工和瞎猜。-如果你的倉庫已經進入多模組、多階段、多角色協作,可以直接升級到+如果你的儲存庫已經進入多模組、多階段、多角色協作,可以直接升級到[`openai-advanced/`](./openai-advanced/index.md) 這一套高階結構,而不是繼續把最小範本硬撐成一個大而亂的系統。diff --git a/docs/zh-TW/resources/openai-advanced/index.md b/docs/zh-TW/resources/openai-advanced/index.mdindex faad135..bd4a553 100644--- a/docs/zh-TW/resources/openai-advanced/index.md+++ b/docs/zh-TW/resources/openai-advanced/index.md@@ -1,22 +1,22 @@# OpenAI 高級資源包這個檔案夾把 OpenAI 那篇《Harness engineering: leveraging Codex in an-agent-first world》裡更完整、更高階的倉庫組織方式整理成可以直接參考和複製的範本。+agent-first world》裡更完整、更高階的儲存庫組織方式整理成可以直接參考和複製的範本。-當最小 harness 已經不夠用,而你的倉庫開始需要下面這些能力時,就該看這一套:+當最小 harness 已經不夠用,而你的儲存庫開始需要下面這些能力時,就該看這一套:- 一個簡短、負責路由的 `AGENTS.md`-- 放在倉庫裡的“唯一事實來源”文檔體系-- 活躍執行計劃與已完成計劃的分層管理+- 放在儲存庫裡的“唯一事實來源”文件體系+- 活躍執行計畫與已完成計畫的分層管理- 明確的產品、可靠性、安全、前端治理檔案-- 按產品領域和架構層持續更新的質量評分+- 按產品領域和架構層持續更新的品質評分- 面向模型閱讀的參考材料目錄-- 針對架構、知識沉澱、運行驗證的標準 SOP+- 針對架構、知識沉澱、執行驗證的標準 SOP## 包含的目錄骨架[`repo-template/`](./repo-template/index.md) 裡提供了一套可直接複製的起步-結構,核心佈局如下:+結構,核心結構如下:```textAGENTS.md@@ -49,28 +49,28 @@ docs/## 怎麼用-1. 如果倉庫還小,先用最小資源包。-2. 一旦進入多模塊、多輪會話、長期演化階段,就把- [`repo-template/`](./repo-template/index.md) 裡的骨架複製到你的倉庫。+1. 如果儲存庫還小,先用最小資源包。+2. 一旦進入多模組、多輪工作階段、長期演化階段,就把+ [`repo-template/`](./repo-template/index.md) 裡的骨架複製到你的儲存庫。3. 保持 `AGENTS.md` 很短,把深層規則拆到 `docs/` 裡。-4. 把質量文檔、可靠性文檔、執行計劃當成日常開發的一部分,而不是事後補寫。-5. 把生成物和外部參考材料明確收進倉庫,避免 agent 依賴聊天上下文或人的記憶。+4. 把品質文件、可靠性文件、執行計畫當成日常開發的一部分,而不是事後補寫。+5. 把生成物和外部參考材料明確收進儲存庫,避免 agent 依賴聊天脈絡或人的記憶。## SOP 資料庫[`sops/`](./sops/index.md) 把文章裡的幾張關鍵圖,整理成可以逐步執行的標準流程:- 分層領域架構搭建 SOP-- 把不可見知識編碼進倉庫的 SOP-- 本地可觀測性棧與反饋迴路 SOP+- 把不可見知識編碼進儲存庫的 SOP+- 本地可觀測性棧與回饋迴路 SOP- 用 Chrome DevTools 做 UI 驗證閉環的 SOP## 設計原則-- 短入口,深鏈接-- 倉庫就是唯一事實來源+- 短入口,深連結+- 儲存庫就是唯一事實來源- 機械約束優先於口頭約定-- 計劃、質量和技術債都和代碼一起版本化+- 計畫、品質和技術債都和程式碼一起版本化- 清理與 harness 簡化是常規工作,不是臨時救火-這套資源包是有傾向性的範本,不是必須逐字照抄。最好的用法是把它當成一套高質量起點,再按你的項目改造。+這套資源包是有傾向性的範本,不是必須逐字照抄。最好的用法是把它當成一套高品質起點,再按你的專案改造。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md b/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.mdindex 8146785..f96d425 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md@@ -1,38 +1,38 @@# AGENTS.md-這個倉庫面向長時運行的 coding-agent 工作流。保持這個檔案簡短,把它當成“唯一事實來源”文檔的入口和路由層,而不是一個不斷膨脹的大說明書。+這個儲存庫面向長時執行的 coding-agent 工作流。保持這個檔案簡短,把它當成“唯一事實來源”文件的入口和路由層,而不是一個不斷膨脹的大說明書。## 開工流程-改代碼前先做這些事:+改程式碼前先做這些事:-1. 用 `pwd` 確認倉庫根目錄。-2. 讀取 `ARCHITECTURE.md`,理解當前系統地圖和硬性依賴規則。+1. 用 `pwd` 確認儲存庫根目錄。+2. 讀取 `ARCHITECTURE.md`,理解目前系統地圖和硬性依賴規則。3. 讀取 `docs/QUALITY_SCORE.md`,先知道最弱的產品領域和架構層。-4. 讀取 `docs/PLANS.md`,再打開當前要執行的 active plan。-5. 讀取相關的 `docs/product-specs/` 規格文檔。-6. 跑這個倉庫約定的 bootstrap 與驗證路徑。+4. 讀取 `docs/PLANS.md`,再打開目前要執行的 active plan。+5. 讀取相關的 `docs/product-specs/` 規格文件。+6. 跑這個儲存庫約定的 bootstrap 與驗證路徑。7. 如果基礎驗證先失敗,先修 baseline,再加新範圍。## 路由地圖- `ARCHITECTURE.md`:領域地圖、分層模型、依賴規則- `docs/design-docs/index.md`:設計決策與核心信念-- `docs/product-specs/index.md`:當前產品行為與驗收目標-- `docs/PLANS.md`:計劃生命週期與執行計劃規則+- `docs/product-specs/index.md`:目前產品行為與驗收目標+- `docs/PLANS.md`:計畫生命週期與執行計畫規則- `docs/QUALITY_SCORE.md`:產品領域與架構層健康度-- `docs/RELIABILITY.md`:運行信號、benchmark、重啟要求-- `docs/SECURITY.md`:密鑰、沙箱、數據和外部動作規則-- `docs/FRONTEND.md`:UI 約束、設計系統規則、可訪問性檢查+- `docs/RELIABILITY.md`:執行信號、benchmark、重啟要求+- `docs/SECURITY.md`:密鑰、沙箱、資料和外部動作規則+- `docs/FRONTEND.md`:UI 約束、設計系統規則、無障礙檢查## 工作約定-- 一次只圍繞一個有邊界的計劃或功能切片工作。-- 不能只靠讀代碼就宣佈完成,必須有可運行證據。-- 只要改了行為,就同步更新對應的產品、計劃或可靠性文檔。+- 一次只圍繞一個有邊界的計畫或功能切片工作。+- 不能只靠讀程式碼就宣佈完成,必須有可執行證據。+- 只要改了行為,就同步更新對應的產品、計畫或可靠性文件。- 如果某類 review feedback 反覆出現,把它升級成機械規則、檢查或 linter,不要一直在聊天裡重複解釋。- 生成物放進 `docs/generated/`,外部 reference 放進 `docs/references/`。-- 需要更多細節時,優先補小而新的文檔,而不是繼續把這個檔案寫長。+- 需要更多細節時,優先補小而新的文件,而不是繼續把這個檔案寫長。## 完成定義@@ -40,16 +40,16 @@- 目標行為已實現- 要求的驗證真的跑過-- 證據已經掛到相關 plan 或質量文檔裡-- 受影響的文檔仍然是最新的-- 倉庫能按標準啟動路徑乾淨重啟+- 證據已經掛到相關 plan 或品質文件裡+- 受影響的文件仍然是最新的+- 儲存庫能按標準啟動路徑乾淨重啟## 收尾-結束會話前:+結束工作階段前:-1. 更新當前 active execution plan。+1. 更新目前 active execution plan。2. 如果產品領域或架構層有明顯變化,更新 `docs/QUALITY_SCORE.md`。3. 如果有延期處理的債務,記到 `docs/exec-plans/tech-debt-tracker.md`。-4. 已完成的計劃及時移到 `docs/exec-plans/completed/`。-5. 保證倉庫可重啟,並留下清晰的下一步動作。+4. 已完成的計畫及時移到 `docs/exec-plans/completed/`。+5. 保證儲存庫可重啟,並留下清晰的下一步動作。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.mdindex ddcd6a8..4d39ae1 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -1,20 +1,20 @@# ARCHITECTURE.md-這份檔案是系統的頂層地圖。它應該保持簡短,只提供最關鍵的結構信息,並把更深的內容指向其他文檔。+這份檔案是系統的頂層地圖。它應該保持簡短,只提供最關鍵的結構資訊,並把更深的內容指向其他文件。## 系統形態-- 產品:`[替換成产品名]`-- 主用戶流程:`[替換成核心流程]`-- 運行面:`[desktop / web / cli / services / workers]`+- 產品:`[替換成產品名稱]`+- 主使用者流程:`[替換成核心流程]`+- 執行面:`[desktop / web / cli / services / workers]`- 產品行為真相來源:`docs/product-specs/`## 領域地圖| 領域 | 負責什麼 | 主要入口 | 對應規格 ||------|---------|---------|---------|-| `[domain-a]` | `[职责]` | `[模块 / 路由 / 命令]` | `[spec path]` |-| `[domain-b]` | `[职责]` | `[模块 / 路由 / 命令]` | `[spec path]` |+| `[domain-a]` | `[職責]` | `[模組 / 路由 / 命令]` | `[spec path]` |+| `[domain-b]` | `[職責]` | `[模組 / 路由 / 命令]` | `[spec path]` |## 分層模型@@ -22,13 +22,13 @@`Types -> Config -> Repo -> Service -> Runtime -> UI`-跨領域關注點應該通過明確的 provider 或 adapter 邊界進入,而不是直接跨層穿透。+跨領域關注點應該透過明確的 provider 或 adapter 邊界進入,而不是直接跨層穿透。## 硬性依賴規則- 低層不能依賴高層。- UI 不能繞過 runtime 或 service 契約。-- 數據訪問必須通過 repo 或等價 adapter 進入。+- 資料存取必須透過 repo 或等價 adapter 進行。- 共享 util 必須保持通用,不能慢慢堆成領域邏輯垃圾桶。- 新依賴要在對應 plan 或 design doc 裡說明理由。@@ -36,20 +36,20 @@| 關注點 | 允許的邊界 | 備註 ||-------|-----------|------|-| 日誌與 tracing | `[provider / utility path]` | `[只允许結構化日誌,不允许临時 console]` |-| Auth | `[provider path]` | `[token/session 规则]` |-| 外部 API | `[client 或 provider path]` | `[限流 / 重試原则]` |-| Feature flags | `[flag boundary]` | `[歸属]` |+| 日誌與 tracing | `[provider / utility path]` | `[只允許結構化日誌,不允許臨時 console]` |+| Auth | `[provider path]` | `[token/session 規則]` |+| 外部 API | `[client 或 provider path]` | `[限流 / 重試原則]` |+| Feature flags | `[flag boundary]` | `[歸屬]` |-## 當前熱點+## 目前熱點-- `[最难安全修改的区域]`-- `[邊界最弱或測試最脆的区域]`+- `[最難安全修改的區域]`+- `[邊界最弱或測試最脆的區域]`## 變更檢查-當你修改了會影響架構的代碼:+當你修改了會影響架構的程式碼:1. 如果領域地圖或允許邊界變了,就更新這份檔案。-2. 如果背後的設計理由變了,就更新 `docs/design-docs/` 裡的相關文檔。+2. 如果背後的設計理由變了,就更新 `docs/design-docs/` 裡的相關文件。3. 如果規則應該機械執行,就補一個可執行檢查。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/DESIGN.mdindex d0cd37f..6356319 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/DESIGN.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/DESIGN.md@@ -1,6 +1,6 @@# DESIGN.md-這份檔案是設計文檔入口。保持簡短,把更細的內容路由到+這份檔案是設計文件入口。保持簡短,把更細的內容路由到`docs/design-docs/` 裡的具體檔案。## 目的@@ -9,18 +9,18 @@## 什麼時候先看它-- 你需要理解當前的設計哲學+- 你需要理解目前的設計哲學- 你準備引入新模式- 你要判斷哪些設計已經定了,哪些還在開放狀態-## 核心設計文檔+## 核心設計文件-- `docs/design-docs/index.md`:accepted / proposed / deprecated 文檔索引-- `docs/design-docs/core-beliefs.md`:項目級 agent-first 核心信念+- `docs/design-docs/index.md`:accepted / proposed / deprecated 文件索引+- `docs/design-docs/core-beliefs.md`:專案級 agent-first 核心信念## 設計規則-- 設計文檔要小而新。-- 一個決策領域儘量對應一份文檔。-- 某個改動依賴設計文檔時,要在 plan 和 spec 裡顯式鏈接它。-- 如果某條設計規則已經變成運行上的硬要求,就把它升級成自動化檢查或更新到 `ARCHITECTURE.md`。+- 設計文件要小而新。+- 一個決策領域儘量對應一份文件。+- 某個改動依賴設計文件時,要在 plan 和 spec 裡顯式連結它。+- 如果某條設計規則已經變成執行上的硬要求,就把它升級成自動化檢查或更新到 `ARCHITECTURE.md`。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 b38d6ad..4c03e69 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@@ -5,19 +5,19 @@## UI 原則- 先保證清晰,再追求新鮮感。-- 交互流程要可發現、可重走、可重啟。-- 優先沉澱少量可複用組件,而不是到處長一次性變體。-- 可訪問性檢查屬於正常驗證,不是最後的美化工作。+- 互動流程要可發現、可重走、可重啟。+- 優先沉澱少量可複用元件,而不是到處長一次性變體。+- 無障礙檢查屬於正常驗證,不是最後的美化工作。## 護欄-- 把設計系統或組件庫參考材料放進 `docs/references/`。-- 顯式記錄關鍵用戶狀態:empty、loading、success、error、retry。+- 把設計系統或元件庫參考材料放進 `docs/references/`。+- 顯式記錄關鍵使用者狀態:empty、loading、success、error、retry。- 在不同流程裡保持文案、鍵盤行為、視覺層級一致。- 修復 UI bug 後,順手補上對應驗證步驟。## 驗證要求-- 為關鍵用戶旅程留下證據。-- 把瀏覽器或運行時驗證步驟寫進相關 plan。+- 為關鍵使用者旅程留下證據。+- 把瀏覽器或執行時期驗證步驟寫進相關 plan。- 如果視覺迴歸常見,就標準化截圖或 DOM 檢查。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 41534ed..fa5d5f7 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@@ -1,20 +1,20 @@# PLANS.md-這份檔案定義執行計劃如何創建、更新、完成和歸檔。+這份檔案定義執行計畫如何建立、更新、完成和歸檔。## 什麼時候必須有 plan-當工作滿足以下任一條件時,就創建 execution plan:+當工作滿足以下任一條件時,就建立 execution plan:-- 會跨越多個會話+- 會跨越多個工作階段- 會同時影響多個子系統- 驗證或上線風險不小- 存在需要顯式記錄的開放決策-## 計劃放哪+## 計畫放哪-- `docs/exec-plans/active/`:當前正在驅動工作的計劃-- `docs/exec-plans/completed/`:已完成但仍然要保留上下文的計劃+- `docs/exec-plans/active/`:目前正在驅動工作的計畫+- `docs/exec-plans/completed/`:已完成但仍然要保留脈絡的計畫- `docs/exec-plans/tech-debt-tracker.md`:延期處理的債務與 follow-up## 最少要包含的部分@@ -26,9 +26,9 @@- 進度日誌- 開放決策-## 運行規則+## 執行規則-- 一份 active plan 同一時間應該只有一個清晰的當前步驟。+- 一份 active plan 同一時間應該只有一個清晰的目前步驟。- plan 要隨著工作推進而更新,不要把它當成靜態散文。- 只要某個決策改變了實現方向,就記到 plan 裡。-- 已完成的計劃要移到 `completed/`,讓後續 agent 仍然能發現歷史上下文。+- 已完成的計畫要移到 `completed/`,讓後續 agent 仍然能發現歷史脈絡。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.mdindex c0ea13b..5f75947 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md@@ -1,24 +1,24 @@# PRODUCT_SENSE.md-這份檔案記錄那些代碼本身並不能可靠表達出來的產品判斷。+這份檔案記錄那些程式碼本身並不能可靠表達出來的產品判斷。## 產品核心-- 主要用戶:`[替換]`+- 主要使用者:`[替換]`- 要完成的任務:`[替換]`- 最想解決的核心痛點:`[替換]`-- 可接受質量門檻:`[替換]`+- 可接受品質門檻:`[替換]`## 產品規則-- 優先保證用戶可感知的可靠性,而不是一味加功能。-- 行為有歧義時,把它當成 spec 缺口,不要默認允許猜。-- 只要實現改變了用戶看見或信任的東西,就更新對應 spec。+- 優先保證使用者可感知的可靠性,而不是一味加功能。+- 行為有歧義時,把它當成 spec 缺口,不要預設允許猜。+- 只要實現改變了使用者看見或信任的東西,就更新對應 spec。- 具體流程寫在 product spec 裡,跨流程的產品優先級寫在這裡。## 禁區模式- 隱蔽的破壞性操作-- 沒有用戶反饋的靜默失敗-- 用戶可見狀態沒有明確真相來源+- 沒有使用者回饋的靜默失敗+- 使用者可見狀態沒有明確真相來源- 不能用一句話解釋清楚的功能diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.mdindex 060fea9..85e8778 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md@@ -1,6 +1,6 @@# QUALITY_SCORE.md-這份文檔用來跟蹤倉庫是在變強還是變弱。+這份文件用來跟蹤儲存庫是在變強還是變弱。## 評級標準@@ -34,6 +34,6 @@## 簡化實驗日誌-| 日期 | 移除的組件 | 結果 | 決策 |+| 日期 | 移除的元件 | 結果 | 決策 ||------|-----------|------|------|| YYYY-MM-DD | `[component]` | `[degraded / unchanged]` | `[restore / keep removed]` |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 1c5b4cf..1a4cf03 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@@ -7,14 +7,14 @@- Bootstrap:`[command]`- Verification:`[command]`- 啟動應用或服務:`[command]`-- 調試或查看運行態:`[command]`+- 除錯或查看執行態:`[command]`-## 必需運行信號+## 必需執行信號- 啟動與關鍵流程的結構化日誌- 關鍵服務的 health check-- 條件允許時為慢路徑提供 trace 或 timing 數據-- 對可恢復失敗提供用戶可見的錯誤狀態+- 條件允許時為慢路徑提供 trace 或 timing 資料+- 對可恢復失敗提供使用者可見的錯誤狀態## 黃金旅程@@ -27,6 +27,6 @@## 可靠性規則- 只要系統不能幹淨重啟,功能就不能算完成。-- 運行失敗必須能從 repo-local 信號裡定位。+- 執行失敗必須能從 repo-local 信號裡定位。- 某類失敗模式一旦反覆出現,就給它補 benchmark 或 guardrail。- cleanup 屬於可靠性的一部分,不是另外一件事。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/SECURITY.mdindex ef80922..af40bf2 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/SECURITY.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/SECURITY.md@@ -4,9 +4,9 @@## Secrets 與憑證-- 絕不把 secrets 硬編碼進源碼或文檔。+- 絕不把 secrets 硬編碼進原始碼或文件。- 在這裡記錄允許的 secret 加載路徑。-- 從日誌和截圖裡去掉 token、API key 與個人數據。+- 從日誌和截圖裡去掉 token、API key 與個人資料。## 不可信輸入@@ -17,8 +17,8 @@## 外部動作- 列出哪些動作必須顯式批準。-- 記錄哪些生產或破壞性命令默認不能跑。-- 調試和驗證優先走 sandbox-safe 路徑。+- 記錄哪些生產或破壞性命令預設不能跑。+- 除錯和驗證優先走 sandbox-safe 路徑。## 依賴與評審規則diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.mdindex daba7fa..dbc9bf8 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md@@ -1,9 +1,9 @@# 核心信念-- 倉庫就是 agent 的唯一事實來源。+- 儲存庫就是 agent 的唯一事實來源。- `AGENTS.md` 是路由器,不是百科全書。- 驗證證據比自信更重要。- 一次做好一個有邊界的任務,勝過同時開很多半成品。-- 反覆出現的人類反饋要升級成可複用的 harness 規則。+- 反覆出現的人類回饋要升級成可複用的 harness 規則。- 清理與簡化都是交付的一部分,不是事後補救。-- 如果 agent 不能在倉庫裡發現某個事實,就把這個事實視為運行上不存在。+- 如果 agent 不能在儲存庫裡發現某個事實,就把這個事實視為執行上不存在。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/index.mdindex e20b47e..21e94ae 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/index.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/design-docs/index.md@@ -1,21 +1,21 @@-# 設計文檔索引+# 設計文件索引把這份索引當成設計歷史的可發現地圖。## Accepted-- `core-beliefs.md`:agent-first 的運行信念與持久項目規範+- `core-beliefs.md`:agent-first 的執行信念與持久專案規範## Proposed-- `[在這裡添加新的設計文檔路徑]`+- `[在此新增設計文件路徑]`## Deprecated-- `[把被替代或過期的設計文檔移到這裡,並给出替代鏈接]`+- `[把被替代或過期的設計文件移到這裡,並给出替代連結]`## 維護規則-- 每份設計文檔都應該有 owner 或更新觸發條件。-- 過期文檔要麼刪除,要麼明確標成 deprecated,不要讓它悄悄漂移。-- active execution plan 要鏈接自己依賴的設計文檔。+- 每份設計文件都應該有 owner 或更新觸發條件。+- 過期文件要麼刪除,要麼明確標成 deprecated,不要讓它悄悄漂移。+- active execution plan 要連結自己依賴的設計文件。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/active/index.mdindex e06af85..07e8964 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md@@ -1,9 +1,9 @@-# 當前執行計劃+# 目前執行計畫-這個檔案夾裡每一份 markdown 都代表一份當前仍在執行的計劃。+這個檔案夾裡每一份 markdown 都代表一份目前仍在執行的計畫。建議檔案名格式:- `YYYY-MM-DD-short-topic.md`-每份 active plan 都應該足夠新,讓一個沒有聊天上下文的新 agent 也能只靠倉庫繼續推進。+每份 active plan 都應該足夠新,讓一個沒有聊天脈絡的新 agent 也能只靠儲存庫繼續推進。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.mdindex 9bd8a1c..ae3980d 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md@@ -1,3 +1,3 @@-# 已完成計劃+# 已完成計畫-已完成的計劃移動到這裡,不要直接刪掉。完成計劃也是倉庫記憶面的一部分,後續 agent 需要靠它理解代碼為什麼會變成現在這樣。+已完成的計畫移動到這裡,不要直接刪掉。完成計畫也是儲存庫記憶面的一部分,後續 agent 需要靠它理解程式碼為什麼會變成現在這樣。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/generated/db-schema.mdindex f974f01..db0d4b6 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/generated/db-schema.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/generated/db-schema.md@@ -1,11 +1,11 @@-# 數據庫結構+# 資料庫結構-這個目錄用來存放那些生成出來但又值得 agent 直接閱讀的工件,避免它每次都去源碼裡反推。+這個目錄用來存放那些生成出來但又值得 agent 直接閱讀的工件,避免它每次都去原始碼裡反推。## 來源- 生成命令或來源:`[command or source path]`-- 最近刷新時間:`YYYY-MM-DD`+- 最近重新整理時間:`YYYY-MM-DD`## 備註diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/index.mdindex 8d3b423..b7f277f 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/index.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/index.md@@ -1,13 +1,13 @@# 產品規格索引-這個目錄用來放當前仍然有效的用戶可見行為規格。+這個目錄用來放目前仍然有效的使用者可見行為規格。-## 當前有效規格+## 目前有效規格- `new-user-onboarding.md`## 規則-- spec 重點描述用戶可見行為和驗收標準。-- 如果實現和 spec 不一致,要在同一輪會話裡更新其中一方。+- spec 重點描述使用者可見行為和驗收標準。+- 如果實現和 spec 不一致,要在同一輪工作階段裡更新其中一方。- 保持這份索引是最新的,讓新 agent 能快速發現產品範圍。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.mdindex 9498ffd..d14e09d 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md@@ -1,14 +1,14 @@-# 新用戶引導+# 新使用者引導## 目標-描述一個新用戶第一次進入產品時應該經歷的流程。+描述一個新使用者第一次進入產品時應該經歷的流程。## 起始條件- `[流程開始前的狀態]`-## 用戶流程+## 使用者流程1. `[步骤一]`2. `[步骤二]`diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/index.mdindex 808e303..4dfd062 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/index.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/index.md@@ -1,22 +1,22 @@-# 高級倉庫範本+# 高級儲存庫範本-當你希望把倉庫升級成更接近 OpenAI 文中那種 agent-first 文檔面,而不只是一個最小 harness 時,就複製這套起步範本。+當你希望把儲存庫升級成更接近 OpenAI 文中那種 agent-first 文件面,而不只是一個最小 harness 時,就複製這套起步範本。## 推薦複製順序-1. 先把 `AGENTS.md` 和 `ARCHITECTURE.md` 放到倉庫根目錄。+1. 先把 `AGENTS.md` 和 `ARCHITECTURE.md` 放到儲存庫根目錄。2. 再複製整個 `docs/` 目錄樹。3. 優先把 `docs/PRODUCT_SENSE.md`、`docs/QUALITY_SCORE.md`、`docs/RELIABILITY.md` 填起來。-4. 在 `docs/exec-plans/active/` 下創建你的第一份 active plan。-5. 始終保持入口檔案很短,詳細規則拆到鏈接文檔裡。+4. 在 `docs/exec-plans/active/` 下建立你的第一份 active plan。+5. 始終保持入口檔案很短,詳細規則拆到連結文件裡。-## 這套範本主要優化什麼+## 這套範本主要最佳化什麼-- 持久、repo-local 的上下文+- 持久、repo-local 的脈絡- 漸進披露,而不是一個超長 instruction 檔案-- 明確的計劃生命週期-- 隨時間演化的質量追蹤+- 明確的計畫生命週期+- 隨時間演化的品質追蹤- 對 agent 和人都更可讀的邊界-這裡的每個檔案都只是起點。真正投入使用前,把佔位文字、示例命令和樣例規則替換成你自己的項目現實。+這裡的每個檔案都只是起點。真正投入使用前,把佔位文字、示例命令和樣例規則替換成你自己的專案現實。diff --git a/docs/zh-TW/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/zh-TW/resources/openai-advanced/sops/chrome-devtools-validation-loop.mdindex 04fd9a3..47a1b36 100644--- a/docs/zh-TW/resources/openai-advanced/sops/chrome-devtools-validation-loop.md+++ b/docs/zh-TW/resources/openai-advanced/sops/chrome-devtools-validation-loop.md@@ -1,10 +1,10 @@# SOP:Chrome DevTools 驗證閉環-當 UI 改動必須經過真實交互、截圖、DOM 狀態和 console 輸出來判斷,而不是隻靠讀代碼時,就用這份 SOP。+當 UI 改動必須經過真實互動、截圖、DOM 狀態和 console 輸出來判斷,而不是隻靠讀程式碼時,就用這份 SOP。## 目標-把 UI 驗證變成 agent 可以反覆執行的交互閉環,直到這條用戶旅程變乾淨。+把 UI 驗證變成 agent 可以反覆執行的互動閉環,直到這條使用者旅程變乾淨。## 核心閉環@@ -12,7 +12,7 @@2. 清掉舊的 console 噪聲。3. 記錄 BEFORE 狀態。4. 觸發 UI 路徑。-5. 觀察交互過程中的 runtime events。+5. 觀察互動過程中的 runtime events。6. 記錄 AFTER 狀態。7. 修復問題,必要時重啟 app。8. 反覆重跑驗證,直到這條旅程 clean。@@ -27,8 +27,8 @@## 執行 SOP1. 把目標旅程寫進 active plan。-2. 用可觀察行為定義成功:文本出現、按鈕可點、錯誤消失、console 乾淨、請求成功。-3. 交互前先拍初始狀態。+2. 用可觀察行為定義成功:文字出現、按鈕可點、錯誤消失、console 乾淨、請求成功。+3. 互動前先拍初始狀態。4. 一次只觸發一條路徑。5. 記錄 runtime event、DOM 變化和可見輸出。6. 如果失敗,只修最小負責層,然後重啟。@@ -41,8 +41,8 @@- console 噪聲已理解或清理- 重跑同一路徑結果一致-## 需要同步更新的倉庫工件+## 需要同步更新的儲存庫工件-- 當前 active execution plan+- 目前 active execution plan- 如果它變成黃金旅程,更新 `docs/RELIABILITY.md`- 如果可見行為改變了,更新 product specdiff --git a/docs/zh-TW/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/zh-TW/resources/openai-advanced/sops/encode-knowledge-into-repo.mdindex 37ac582..b110a0a 100644--- a/docs/zh-TW/resources/openai-advanced/sops/encode-knowledge-into-repo.md+++ b/docs/zh-TW/resources/openai-advanced/sops/encode-knowledge-into-repo.md@@ -1,6 +1,6 @@-# SOP:把不可見知識編碼進倉庫+# SOP:把不可見知識編碼進儲存庫-當重要上下文還散落在 Google Docs、聊天記錄、ticket 或人的腦子裡時,就用這份 SOP。+當重要脈絡還散落在 Google Docs、聊天記錄、ticket 或人的腦子裡時,就用這份 SOP。## 目標@@ -10,33 +10,33 @@- agent 總在追問系統到底怎麼運作。- 人開始說“這個是 Slack 裡定過的”或“按某某上週說的做”。-- review 裡經常引用倉庫裡根本沒寫下來的產品、安全或架構規則。-- 新會話總在重複那些本該已經穩定下來的發現工作。+- review 裡經常引用儲存庫裡根本沒寫下來的產品、安全或架構規則。+- 新工作階段總在重複那些本該已經穩定下來的發現工作。## 執行 SOP-1. 先列出所有不可見知識來源:外部文檔、聊天、默認團隊規則、口頭決策。-2. 對每條知識判斷:它屬於架構、產品行為、安全策略、可靠性要求、執行上下文,還是參考材料?-3. 按類別編碼到對應倉庫工件:+1. 先列出所有不可見知識來源:外部文件、聊天、預設團隊規則、口頭決策。+2. 對每條知識判斷:它屬於架構、產品行為、安全策略、可靠性要求、執行脈絡,還是參考材料?+3. 按類別編碼到對應儲存庫工件:- 架構 -> `ARCHITECTURE.md`- 產品行為 -> `docs/product-specs/`- 設計理由 -> `docs/design-docs/`- 執行狀態 -> `docs/exec-plans/`- 外部參考材料 -> `docs/references/`- - 質量或可靠性要求 -> `docs/QUALITY_SCORE.md` 或 `docs/RELIABILITY.md`-4. 把模糊表達改寫成運行上真正有用的表達。-5. 刪除或廢棄舊副本,保證倉庫裡有一個可發現的真相來源。+ - 品質或可靠性要求 -> `docs/QUALITY_SCORE.md` 或 `docs/RELIABILITY.md`+4. 把模糊表達改寫成執行上真正有用的表達。+5. 刪除或廢棄舊副本,保證儲存庫裡有一個可發現的真相來源。## 好的編碼規則- 為“可發現”而寫,不是為“寫得很全”而寫。- 檔案儘量短,名字儘量明確。-- 相關工件要互相鏈接。+- 相關工件要互相連結。- 記錄耐久規則,不要把會議流水賬原封不動塞進來。-- 決策形成的同一輪會話裡,就把倉庫更新掉。+- 決策形成的同一輪工作階段裡,就把儲存庫更新掉。## 完成定義- 一個全新 agent 不問人也能找到相關規則。- 同一個事實不會散落在多個互相打架的檔案裡。-- 新工件放在離它所治理的代碼或流程最近的地方。+- 新工件放在離它所治理的程式碼或流程最近的地方。diff --git a/docs/zh-TW/resources/openai-advanced/sops/index.md b/docs/zh-TW/resources/openai-advanced/sops/index.mdindex 9f43735..1ccfe05 100644--- a/docs/zh-TW/resources/openai-advanced/sops/index.md+++ b/docs/zh-TW/resources/openai-advanced/sops/index.md@@ -7,17 +7,17 @@- [`layered-domain-architecture.md`](./layered-domain-architecture.md):搭建顯式分層與跨領域邊界- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):- 把聊天、外部文檔、腦內知識變成 repo-local 文檔+ 把聊天、外部文件、腦內知識變成 repo-local 文件- [`observability-feedback-loop.md`](./observability-feedback-loop.md):- 給 agent 提供 logs、metrics、traces 與可重複的調試閉環+ 給 agent 提供 logs、metrics、traces 與可重複的除錯閉環- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):用瀏覽器自動化和快照反覆驗證 UI,直到 clean## 怎麼用-1. 先選和你當前瓶頸最匹配的 SOP。+1. 先選和你目前瓶頸最相符的 SOP。2. 按檢查清單補齊缺失工件或工具。-3. 把得到的規則編碼回 `repo-template/` 裡的文檔。+3. 把得到的規則編碼回 `repo-template/` 裡的文件。4. 把反覆出現的 review 評論升級成檢查、腳本或 guardrail。這些 SOP 不是讓你機械照抄,而是為了讓 harness 更可讀、更可執行、更可複用。diff --git a/docs/zh-TW/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/zh-TW/resources/openai-advanced/sops/layered-domain-architecture.mdindex ff201f9..32b464b 100644--- a/docs/zh-TW/resources/openai-advanced/sops/layered-domain-architecture.md+++ b/docs/zh-TW/resources/openai-advanced/sops/layered-domain-architecture.md@@ -1,6 +1,6 @@# SOP:分層領域架構-當 agent 反覆跨層亂連、在不同層重複邏輯、或者幾輪會話後代碼越來越難審時,就用這份 SOP。+當 agent 反覆跨層亂連、在不同層重複邏輯、或者幾輪工作階段後程式碼越來越難審時,就用這份 SOP。## 目標@@ -12,25 +12,25 @@`Types -> Config -> Repo -> Service -> Runtime -> UI`-跨領域關注點通過明確的 provider 或 adapter 進入。共享 utils 保持在領域之外,不能慢慢長成業務邏輯垃圾場。+跨領域關注點透過明確的 provider 或 adapter 進入。共享 utils 保持在領域之外,不能慢慢長成業務邏輯垃圾場。## 建設檢查清單-- 在 `ARCHITECTURE.md` 裡列清當前 domains。+- 在 `ARCHITECTURE.md` 裡列清目前 domains。- 在 `ARCHITECTURE.md` 裡寫清允許的依賴方向。- 記錄 auth、telemetry、外部 API 等 cross-cutting interface。-- 為當前最難處理的邊界違規寫一條短說明。+- 為目前最難處理的邊界違規寫一條短說明。- 決定哪些規則應該升級成 lint、test 或 script。## 執行 SOP-1. 先給代碼庫畫 domain map,再談實現風格。+1. 先給程式碼庫畫 domain map,再談實現風格。2. 對每個 domain,明確允許的 layer sequence。3. 找出所有橫切關注點,並把它們改走 provider 或 adapter。4. 把含糊的 shared logic 重新放回所屬 domain,或抽成真正通用的 utils。5. 把規則寫進 `ARCHITECTURE.md`。6. 先為代價最高的一類違規補一個可執行 guardrail。-7. 改完後更新質量評分。+7. 改完後更新品質評分。## 完成定義@@ -39,9 +39,9 @@- 橫切能力都有明確入口。- 至少一條重要邊界已經被機械執行。-## 需要同步更新的倉庫工件+## 需要同步更新的儲存庫工件- `ARCHITECTURE.md`- `docs/QUALITY_SCORE.md`- 如果設計理由變了,更新 `docs/design-docs/`-- `docs/PLANS.md` 或當前 active execution plan+- `docs/PLANS.md` 或目前 active execution plandiff --git a/docs/zh-TW/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/zh-TW/resources/openai-advanced/sops/observability-feedback-loop.mdindex fea7238..f3ec7f7 100644--- a/docs/zh-TW/resources/openai-advanced/sops/observability-feedback-loop.md+++ b/docs/zh-TW/resources/openai-advanced/sops/observability-feedback-loop.md@@ -1,10 +1,10 @@-# SOP:可觀測性反饋閉環+# SOP:可觀測性回饋閉環-當調試太慢、agent 總在沒證據的情況下宣佈成功、或者運行時行為比代碼本身還難看懂時,就用這份 SOP。+當除錯太慢、agent 總在沒證據的情況下宣佈成功、或者執行時期行為比程式碼本身還難看懂時,就用這份 SOP。## 目標-給 agent 一套本地閉環,讓它可以基於 logs、metrics、traces 和可重複 workload 來判斷系統,而不是隻靠看代碼猜。+給 agent 一套本地閉環,讓它可以基於 logs、metrics、traces 和可重複 workload 來判斷系統,而不是隻靠看程式碼猜。## 最小可用棧@@ -16,7 +16,7 @@## 執行 SOP-1. 先定義最重要的黃金運行旅程。+1. 先定義最重要的黃金執行旅程。2. 給啟動流程和關鍵路徑補結構化日誌。3. 在合適位置補 latency、failure count、queue depth 之類的 metrics。4. 為慢路徑或多階段流程補 traces 或 timing 標記。@@ -25,7 +25,7 @@7. 強制執行這條閉環:query -> correlate -> reason -> implement -> restart-> rerun -> verify。-## 調試會話檢查清單+## 除錯工作階段檢查清單- 到底哪裡失敗了?- 哪條信號能證明它失敗?@@ -36,7 +36,7 @@## 完成定義-- agent 能用運行證據解釋失敗模式。+- agent 能用執行證據解釋失敗模式。- 每次改動後都能重跑同一 workload。- restart 與 rerun 已經成為正常任務循環的一部分。- 可靠性信號已經記錄到 `docs/RELIABILITY.md`。diff --git a/docs/zh-TW/resources/reference/coding-agent-startup-flow.md b/docs/zh-TW/resources/reference/coding-agent-startup-flow.mdindex aa01f4b..4683b50 100644--- a/docs/zh-TW/resources/reference/coding-agent-startup-flow.md+++ b/docs/zh-TW/resources/reference/coding-agent-startup-flow.md@@ -1,14 +1,14 @@# 編碼代理開工流程-初始化完成後,每輪編碼會話都按這個流程開始。+初始化完成後,每輪編碼工作階段都按這個流程開始。## 固定開工範本-1. 運行 `pwd`,確認倉庫根目錄+1. 執行 `pwd`,確認儲存庫根目錄2. 讀取 `claude-progress.md`3. 讀取 `feature_list.json`4. 用 `git log --oneline -5` 查看最近提交-5. 運行 `./init.sh`+5. 執行 `./init.sh`6. 跑一條基礎 smoke test 或端到端路徑7. 如果基礎狀態已壞,先修這個8. 選擇最高優先級的未完成功能@@ -24,10 +24,10 @@## 對應的收尾流程-同一輪會話結束時,也應該鏡像地做這些事:+同一輪工作階段結束時,也應該鏡像地做這些事:1. 記錄進度2. 更新功能狀態3. 必要時寫交接摘要-4. 提交安全狀態的代碼+4. 提交安全狀態的程式碼5. 留下可直接重啟的乾淨環境diff --git a/docs/zh-TW/resources/reference/index.md b/docs/zh-TW/resources/reference/index.mdindex 040b2ab..8d01efe 100644--- a/docs/zh-TW/resources/reference/index.md+++ b/docs/zh-TW/resources/reference/index.md@@ -11,17 +11,17 @@## 重點參考文章-這裡的篩選標準很窄:只保留能直接解釋 harness 機制的文章。Harness 在這裡指模型外部的運行系統,包括 agent loop、工具執行、沙箱、狀態、上下文、驗證、終止條件、控制平面和觀測反饋;不是泛泛的 prompt engineering 或 agent 框架介紹。+這裡的篩選標準很窄:只保留能直接解釋 harness 機制的文章。Harness 在這裡指模型外部的執行系統,包括 agent loop、工具執行、沙箱、狀態、脈絡、驗證、終止條件、控制平面和觀測回饋;不是泛泛的 prompt engineering 或 agent 框架介紹。保留原始三篇作為課程主軸:-- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)(2026-02-11):agent-first 倉庫、repo-local context、custom lint、結構性 guardrail。-- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)(2025-11-26):initializer agent、coding agent、feature list、progress log、跨上下文窗口交接。-- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)(2026-03-24):planner / generator / evaluator 三角色、context reset、harness 簡化和組件過期問題。+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)(2026-02-11):agent-first 儲存庫、repo-local context、custom lint、結構性 guardrail。+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)(2025-11-26):initializer agent、coding agent、feature list、progress log、跨脈絡窗口交接。+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)(2026-03-24):planner / generator / evaluator 三角色、context reset、harness 簡化和元件過期問題。-額外只加入幾篇高相關、高含金量的 2026 文章:+額外只加入幾篇高相關、高價值的 2026 文章:-- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)(2026-01-23):解釋 Codex runtime harness 的核心循環、工具調用、上下文增長和終止狀態。+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)(2026-01-23):解釋 Codex runtime harness 的核心循環、工具呼叫、脈絡增長和終止狀態。- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)(2026-01-09):明確評估 agent 時評的是 model + harness,並區分 evaluation harness 與 agent harness。- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)(2026-02-17):同一模型不變,只改 system prompt、tools、middleware、tracing 和 self-verification,讓 coding agent 在 Terminal Bench 2.0 上從 Top 30 進到 Top 5。- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)(2026-04-02):把 coding-agent user harness 拆成 feedforward guides 和 feedback sensors,並區分 deterministic controls 與 inferential controls。@@ -29,9 +29,9 @@## 2026 擴展參考-這些文章不作為課程主軸,但在設計特定 harness 模塊時很有借鑑價值。只保留文章正文直接涉及 agent loop、工具執行、上下文管理、驗證、沙箱、控制層、迴歸治理等機制的材料;純 agent 產品、平臺發佈、團隊實踐或 benchmark 不放進這裡。+這些文章不作為課程主軸,但在設計特定 harness 模組時很有借鑑價值。只保留文章正文直接涉及 agent loop、工具執行、脈絡管理、驗證、沙箱、控制層、迴歸治理等機制的材料;純 agent 產品、平臺發佈、團隊實踐或 benchmark 不放進這裡。-- [OpenAI: Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/)(2026-02-04):把 harness 抽象成 App Server 協議,覆蓋 thread lifecycle、resume、fork、diff 和客戶端集成。+- [OpenAI: Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/)(2026-02-04):把 harness 抽象成 App Server 協定,覆蓋 thread lifecycle、resume、fork、diff 和客戶端整合。- [OpenAI Developers: Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex)(2026-02-23):長時任務中的 durable project memory、milestone validation 和 done-when 例子。- [OpenAI: The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/)(2026-04-15):model-native harness、sandbox execution、檔案與命令執行能力。- [OpenAI: An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/)(2026-04-27):把 issue tracker / Linear 變成多 agent 控制平面。@@ -45,7 +45,7 @@- [Google: Announcing ADK for Java 1.0.0](https://developers.googleblog.com/announcing-adk-for-java-100-building-the-future-of-ai-agents-in-java/)(2026-03-30):插件、event compaction、HITL、session/memory service、A2A 等可複用 harness primitives。- [GitHub: Automate repository tasks with GitHub Agentic Workflows](https://github.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflows/)(2026-02-13):把 GitHub Actions 變成 agentic workflow runner,包含 safe outputs、sandboxing、permissions、review。- [AWS: AI agents in enterprises: Best practices with Amazon Bedrock AgentCore](https://aws.amazon.com/blogs/machine-learning/ai-agents-in-enterprises-best-practices-with-amazon-bedrock-agentcore/)(2026-02-03):Runtime、Memory、Gateway、Identity/Policy、Observability、Evaluations 的企業級 harness 分層。-- [Stripe: Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)(2026-02-09)和 [Part 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2)(2026-02-19):devbox 隔離、custom agent harness、blueprints 狀態機、規則檔案、MCP tool curation、安全控制、pre-push/CI 反饋循環。+- [Stripe: Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents)(2026-02-09)和 [Part 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2)(2026-02-19):devbox 隔離、custom agent harness、blueprints 狀態機、規則檔案、MCP tool curation、安全控制、pre-push/CI 回饋循環。- [Cognition: What We Learned Building Cloud Agents](https://cognition.ai/blog/what-we-learned-building-cloud-agents)(2026-04-23):雲端 agent runtime 的 VM 隔離、session snapshot/resume、orchestration、governance、audit logging 和 integrations。- [Cognition: Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working)(2026-04-22):generator-verifier loop、clean-context reviewer、smart-friend routing、manager-child coordination 和跨 agent 通信邊界。- [Replit: Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance)(2026-01-20,2026-01-23 更新):用輕量分類器在關鍵決策點注入短指令,而不是把所有規則塞進系統提示詞。diff --git a/docs/zh-TW/resources/reference/initializer-agent-playbook.md b/docs/zh-TW/resources/reference/initializer-agent-playbook.mdindex ac38751..17eae06 100644--- a/docs/zh-TW/resources/reference/initializer-agent-playbook.md+++ b/docs/zh-TW/resources/reference/initializer-agent-playbook.md@@ -1,10 +1,10 @@# 初始化代理操作手冊-這個手冊用於倉庫裡的第一輪重要會話,也就是正式開始增量開發之前的初始化階段。+這個手冊用於儲存庫裡的第一輪重要工作階段,也就是正式開始增量開發之前的初始化階段。## 目標-先搭出穩定的工作面,讓後續會話不必重新推導啟動命令、當前狀態和任務邊界。+先搭出穩定的工作面,讓後續工作階段不必重新推導啟動命令、目前狀態和任務邊界。## 必需產出@@ -26,9 +26,9 @@## 成功標準-一個完全沒有前文聊天上下文的新會話,應該能回答:+一個完全沒有前文聊天脈絡的新工作階段,應該能回答:-- 這個倉庫是做什麼的+- 這個儲存庫是做什麼的- 怎麼啟動- 怎麼驗證- 還有什麼沒做完diff --git a/docs/zh-TW/resources/reference/method-map.md b/docs/zh-TW/resources/reference/method-map.mdindex 3c3ea37..8204bdc 100644--- a/docs/zh-TW/resources/reference/method-map.md+++ b/docs/zh-TW/resources/reference/method-map.md@@ -4,13 +4,13 @@| 失敗模式 | 實際表現 | 首要修復 | 主要工件 || --- | --- | --- | --- |-| 冷啟動混亂 | 新會話花大量時間重新摸索狀態和啟動方式 | 讓倉庫成為唯一事實來源 | `claude-progress.md` |-| 範圍蔓延 | 一次啟動多個功能,最後沒有一個完整收尾 | 限制當前活躍範圍 | `feature_list.json` |-| 提前宣佈完成 | 代碼改了就說“完成了”,但沒有可運行證據 | 把完成綁定到驗證證據 | `clean-state-checklist.md` |-| 啟動脆弱 | 每輪會話都要重新學怎麼啟動項目 | 統一啟動與驗證路徑 | `init.sh` |+| 冷啟動混亂 | 新工作階段花大量時間重新摸索狀態和啟動方式 | 讓儲存庫成為唯一事實來源 | `claude-progress.md` |+| 範圍蔓延 | 一次啟動多個功能,最後沒有一個完整收尾 | 限制目前活躍範圍 | `feature_list.json` |+| 提前宣佈完成 | 程式碼改了就說“完成了”,但沒有可執行證據 | 把完成綁定到驗證證據 | `clean-state-checklist.md` |+| 啟動脆弱 | 每輪工作階段都要重新學怎麼啟動專案 | 統一啟動與驗證路徑 | `init.sh` || 交接薄弱 | 下一輪看不出哪裡可用、哪裡壞了、接下來做什麼 | 明確寫交接摘要 | `session-handoff.md` |-| 評審主觀 | 質量判斷依賴個人記憶和感覺 | 用固定維度做評分 | `evaluator-rubric.md` |+| 評審主觀 | 品質判斷依賴個人記憶和感覺 | 用固定維度做評分 | `evaluator-rubric.md` |## 使用原則-優先補最能直接消除當前失敗模式的那個工件,不要一出問題就把更多規則堆進一個超長 instruction 檔案裡。+優先補最能直接消除目前失敗模式的那個工件,不要一出問題就把更多規則堆進一個超長 instruction 檔案裡。diff --git a/docs/zh-TW/resources/reference/prompt-calibration.md b/docs/zh-TW/resources/reference/prompt-calibration.mdindex 37cae1e..d966fdf 100644--- a/docs/zh-TW/resources/reference/prompt-calibration.md+++ b/docs/zh-TW/resources/reference/prompt-calibration.md@@ -4,20 +4,20 @@## 應該留在根檔案裡的內容-- 倉庫用途和範圍+- 儲存庫用途和範圍- 啟動路徑- 驗證路徑- 不可違反的約束- 必需的狀態工件-- 會話結束規則+- 工作階段結束規則## 應該移出根檔案的內容- 過長的歷史邊角案例- 只屬於某個子系統的細節實現說明-- 更適合貼在代碼附近的局部架構筆記-- 只對單一模塊成立的示例+- 更適合貼在程式碼附近的局部架構筆記+- 只對單一模組成立的示例## 工作原則-根檔案的職責是讓新會話快速建立方向感。如果它開始變成“過去每次失敗都往裡加一句”的堆疊場,就應該把細節拆到更小、更明確的文檔裡,再從根檔案跳轉過去。+根檔案的職責是讓新工作階段快速建立方向感。如果它開始變成“過去每次失敗都往裡加一句”的堆疊場,就應該把細節拆到更小、更明確的文件裡,再從根檔案跳轉過去。diff --git a/docs/zh-TW/resources/templates/AGENTS.md b/docs/zh-TW/resources/templates/AGENTS.mdindex 2cbbce1..f43a415 100644--- a/docs/zh-TW/resources/templates/AGENTS.md+++ b/docs/zh-TW/resources/templates/AGENTS.md@@ -1,16 +1,16 @@# AGENTS.md-這個倉庫面向長時運行的 coding agent 工作流。目標不是儘可能快地產出代碼,而是讓每一輪會話結束後,下一個會話仍然能無猜測地繼續工作。+這個儲存庫面向長時執行的 coding agent 工作流。目標不是儘可能快地產出程式碼,而是讓每一輪工作階段結束後,下一個工作階段仍然能無猜測地繼續工作。## 開工流程-寫代碼前先做這些事:+寫程式碼前先做這些事:-1. 用 `pwd` 確認當前目錄。+1. 用 `pwd` 確認目前目錄。2. 讀取 `claude-progress.md`,瞭解最新已驗證狀態和下一步。3. 讀取 `feature_list.json`,選擇優先級最高的未完成功能。4. 用 `git log --oneline -5` 看最近提交。-5. 運行 `./init.sh`。+5. 執行 `./init.sh`。6. 在開始新功能前,先跑必需的 smoke test 或端到端驗證。如果基礎驗證一開始就失敗,先修基礎狀態,不要在壞的起點上繼續疊新功能。@@ -18,17 +18,17 @@## 工作規則- 一次只做一個功能。-- 不要因為“代碼已經寫了”就把功能標記為完成。-- 除非為了消除當前 blocker 的窄範圍修復,否則不要擴大到其他功能。+- 不要因為“程式碼已經寫了”就把功能標記為完成。+- 除非為了消除目前 blocker 的窄範圍修復,否則不要擴大到其他功能。- 實現過程中不要悄悄改弱驗證規則。-- 優先依賴倉庫裡的持久化檔案,而不是聊天記錄。+- 優先依賴儲存庫裡的持久化檔案,而不是聊天記錄。## 必需檔案- `feature_list.json`:功能狀態的唯一事實來源-- `claude-progress.md`:會話進度和當前已驗證狀態+- `claude-progress.md`:工作階段進度和目前已驗證狀態- `init.sh`:統一的啟動與驗證入口-- `session-handoff.md`:較長會話可選的交接摘要+- `session-handoff.md`:較長工作階段可選的交接摘要## 完成定義@@ -37,14 +37,14 @@- 目標行為已經實現- 要求的驗證真的跑過- 證據記錄在 `feature_list.json` 或 `claude-progress.md`-- 倉庫仍然能按標準啟動路徑重新開始工作+- 儲存庫仍然能按標準啟動路徑重新開始工作## 收尾-結束會話前:+結束工作階段前:1. 更新 `claude-progress.md`2. 更新 `feature_list.json`3. 記錄仍未解決的風險或 blocker-4. 在工作處於安全狀態後,用清晰的提交信息提交-5. 保證下一輪會話可以直接運行 `./init.sh`+4. 在工作處於安全狀態後,用清晰的提交資訊提交+5. 保證下一輪工作階段可以直接執行 `./init.sh`diff --git a/docs/zh-TW/resources/templates/CLAUDE.md b/docs/zh-TW/resources/templates/CLAUDE.mdindex 58293de..41f0212 100644--- a/docs/zh-TW/resources/templates/CLAUDE.md+++ b/docs/zh-TW/resources/templates/CLAUDE.md@@ -1,16 +1,16 @@# CLAUDE.md-你正在一個為長時實現工作設計的倉庫中工作。優先保證可靠完成、跨會話連續性和顯式驗證,而不是表面上的速度。+你正在一個為長時實現工作設計的儲存庫中工作。優先保證可靠完成、跨工作階段連續性和顯式驗證,而不是表面上的速度。## 固定工作循環-每輪會話開始時:+每輪工作階段開始時:-1. 運行 `pwd`,確認當前在正確的倉庫根目錄+1. 執行 `pwd`,確認目前在正確的儲存庫根目錄2. 讀取 `claude-progress.md`3. 讀取 `feature_list.json`4. 用 `git log --oneline -5` 查看最近提交-5. 運行 `./init.sh`+5. 執行 `./init.sh`6. 檢查基礎 smoke test 或端到端路徑是否已經損壞然後只選擇一個未完成功能,圍繞它工作,直到它被驗證通過,或者被明確記錄為 blocked。@@ -18,10 +18,10 @@## 規則- 同一時間只能有一個 active feature-- 沒有可運行證據時,不要聲稱完成-- 不要通過重寫功能清單來隱藏未完成工作+- 沒有可執行證據時,不要聲稱完成+- 不要透過重寫功能清單來隱藏未完成工作- 不要為了“看起來完成”而刪除或削弱測試-- 以倉庫內檔案作為唯一事實來源+- 以儲存庫內檔案作為唯一事實來源## 必需檔案@@ -39,5 +39,5 @@1. 更新進度日誌2. 更新功能狀態3. 記錄仍然損壞或未驗證的內容-4. 在倉庫可安全恢復後提交-5. 給下一輪會話留下乾淨的重啟路徑+4. 在儲存庫可安全恢復後提交+5. 給下一輪工作階段留下乾淨的重啟路徑diff --git a/docs/zh-TW/resources/templates/claude-progress.md b/docs/zh-TW/resources/templates/claude-progress.mdindex c4aac3f..c927744 100644--- a/docs/zh-TW/resources/templates/claude-progress.md+++ b/docs/zh-TW/resources/templates/claude-progress.md@@ -1,21 +1,21 @@# 進度日誌-## 當前已驗證狀態+## 目前已驗證狀態-- 倉庫根目錄:+- 儲存庫根目錄:- 標準啟動路徑:- 標準驗證路徑:-- 當前最高優先級未完成功能:-- 當前 blocker:+- 目前最高優先級未完成功能:+- 目前 blocker:-## 會話記錄+## 工作階段記錄### Session 001- 日期:- 本輪目標:- 已完成:-- 運行過的驗證:+- 執行過的驗證:- 已記錄證據:- 提交記錄:- 更新過的檔案或工件:@@ -27,7 +27,7 @@- 日期:- 本輪目標:- 已完成:-- 運行過的驗證:+- 執行過的驗證:- 已記錄證據:- 提交記錄:- 更新過的檔案或工件:diff --git a/docs/zh-TW/resources/templates/clean-state-checklist.md b/docs/zh-TW/resources/templates/clean-state-checklist.mdindex edf0839..566129a 100644--- a/docs/zh-TW/resources/templates/clean-state-checklist.md+++ b/docs/zh-TW/resources/templates/clean-state-checklist.md@@ -1,8 +1,8 @@# 乾淨狀態檢查清單- [ ] 標準啟動路徑仍然可用-- [ ] 標準驗證路徑仍然可運行-- [ ] 當前進度已經記錄到進度日誌+- [ ] 標準驗證路徑仍然可執行+- [ ] 目前進度已經記錄到進度日誌- [ ] 功能狀態真實反映了 passing 和未驗證的邊界- [ ] 沒有任何半成品步驟處於未記錄狀態-- [ ] 下一輪會話無需人工修復即可繼續+- [ ] 下一輪工作階段無需人工修復即可繼續diff --git a/docs/zh-TW/resources/templates/evaluator-rubric.md b/docs/zh-TW/resources/templates/evaluator-rubric.mdindex 456a715..3018538 100644--- a/docs/zh-TW/resources/templates/evaluator-rubric.md+++ b/docs/zh-TW/resources/templates/evaluator-rubric.md@@ -8,8 +8,8 @@| 驗證 | 要求的檢查是否真的跑過,並留下證據? | | || 範圍紀律 | 這一輪是否基本保持在選定功能範圍內? | | || 可靠性 | 結果是否能在重啟或重跑後繼續工作? | | |-| 可維護性 | 代碼和文檔是否清楚到足以交給下一輪會話? | | |-| 交接準備度 | 新會話是否能只靠倉庫內工件繼續推進? | | |+| 可維護性 | 程式碼和文件是否清楚到足以交給下一輪工作階段? | | |+| 交接準備度 | 新工作階段是否能只靠儲存庫內工件繼續推進? | | |## 結論diff --git a/docs/zh-TW/resources/templates/index.md b/docs/zh-TW/resources/templates/index.mdindex 6db4c84..7286845 100644--- a/docs/zh-TW/resources/templates/index.md+++ b/docs/zh-TW/resources/templates/index.md@@ -1,28 +1,28 @@# 範本使用指南-這些範本可以直接複製到你的項目裡用。每個檔案在 agent 的工作流程中各有分工。複製過去後,把裡面的命令、路徑、功能名稱和驗證步驟換成你自己項目的。+這些範本可以直接複製到你的專案裡用。每個檔案在 agent 的工作流程中各有分工。複製過去後,把裡面的命令、路徑、功能名稱和驗證步驟換成你自己專案的。## 怎麼開始-先把這四個檔案複製到項目根目錄:+先把這四個檔案複製到專案根目錄:1. `AGENTS.md` 或 `CLAUDE.md`2. `init.sh`3. `claude-progress.md`4. `feature_list.json`-等項目變複雜了,再補其餘的檔案。+等專案變複雜了,再補其餘的檔案。---## AGENTS.md-根指令檔案。agent 每次開工會先讀這個檔案。它定義了工作規則:寫代碼前要做什麼、工作過程中怎麼守規矩、收尾時要檢查什麼。+根指令檔案。agent 每次開工會先讀這個檔案。它定義了工作規則:寫程式碼前要做什麼、工作過程中怎麼守規矩、收尾時要檢查什麼。**怎麼用:**-- 複製到項目根目錄-- 把開工流程裡的步驟換成你自己項目的路徑和命令+- 複製到專案根目錄+- 把開工流程裡的步驟換成你自己專案的路徑和命令- 工作規則按你們團隊的約定調整- 完成定義那一段別改——那是整個 harness 最關鍵的部分@@ -37,12 +37,12 @@## init.sh-啟動腳本。一條命令完成依賴安裝、驗證和打印啟動命令。+啟動腳本。一條命令完成依賴安裝、驗證和列印啟動命令。**怎麼用:**-- 複製到項目根目錄-- 改頂部這三個變量:+- 複製到專案根目錄+- 改頂部這三個變數:- `INSTALL_CMD` — 你的依賴安裝命令(比如 `npm install`、`pip install -r requirements.txt`)- `VERIFY_CMD` — 你的基礎驗證命令(比如 `npm test`、`pytest`)- `START_CMD` — 你的開發服務器啟動命令(比如 `npm run dev`)@@ -50,32 +50,32 @@**它做什麼:**-1. 打印當前目錄(確認跑在正確的地方)+1. 列印目前目錄(確認跑在正確的地方)2. 安裝依賴3. 跑驗證命令-4. 打印啟動命令(如果設了 `RUN_START_COMMAND=1` 就直接啟動)+4. 列印啟動命令(如果設了 `RUN_START_COMMAND=1` 就直接啟動)如果驗證失敗了,agent 應該停下來先修基礎狀態,不要在壞的基礎上繼續疊新功能。## claude-progress.md-進度日誌。每輪會話往裡寫,每輪新會話先讀它。+進度日誌。每輪工作階段往裡寫,每輪新工作階段先讀它。**怎麼用:**-- 複製到項目根目錄-- 把"當前已驗證狀態"那段填上你的項目信息-- 每輪會話結束後更新會話記錄+- 複製到專案根目錄+- 把"目前已驗證狀態"那段填上你的專案資訊+- 每輪工作階段結束後更新工作階段記錄**每個字段的意思:**-- **當前已驗證狀態** — 項目當前進展的唯一真相- - `倉庫根目录` — 項目在哪- - `標準啟動路徑` — 把項目跑起來的命令+- **目前已驗證狀態** — 專案目前進展的唯一真相+ - `儲存庫根目录` — 專案在哪+ - `標準啟動路徑` — 把專案跑起來的命令- `標準驗證路徑` — 跑測試的命令- `当前最高優先級未完成功能` — 下一輪該做什麼- `当前 blocker` — 哪裡卡住了-- **會話記錄** — 每輪一條+- **工作階段記錄** — 每輪一條- `本輪目標` — 打算做什麼- `已完成` — 實際做了什麼- `執行過的驗證` — 跑了什麼測試@@ -90,14 +90,14 @@**怎麼用:**-- 複製到項目根目錄+- 複製到專案根目錄- 把示例功能換成你自己的- 每個功能需要填:- `id` — 短的唯一標識- `priority` — 整數,越小越優先- `area` — 屬於應用的哪塊(比如 "chat"、"import"、"search")- `title` — 簡短描述- - `user_visible_behavior` — 功能正常時用戶能看到什麼+ - `user_visible_behavior` — 功能正常時使用者能看到什麼- `status` — 四種狀態之一:`not_started`、`in_progress`、`blocked`、`passing`- `verification` — 逐步驗證步驟- `evidence` — 驗證通過的記錄(agent 填)@@ -106,7 +106,7 @@**狀態規則:**- `not_started` — 還沒碰-- `in_progress` — 當前正在做的那個(同一時間只能有一個)+- `in_progress` — 目前正在做的那個(同一時間只能有一個)- `blocked` — 有記錄的阻塞問題,推不動- `passing` — 驗證通過,證據已記錄@@ -114,31 +114,31 @@ agent 任何時候只能有一個功能處於 `in_progress`。## session-handoff.md-會話交接摘要。一輪會話結束時寫,下一輪開始時讀。讓接手的人(或 agent)快速瞭解現狀。+工作階段交接摘要。一輪工作階段結束時寫,下一輪開始時讀。讓接手的人(或 agent)快速瞭解現狀。**怎麼用:**-- 複製到項目根目錄-- 每輪會話結束時填寫(也可以讓 agent 自己填)+- 複製到專案根目錄+- 每輪工作階段結束時填寫(也可以讓 agent 自己填)**每段寫什麼:**-- **當前已驗證** — 哪些是確認能用的,跑過什麼驗證-- **本輪改動** — 改了什麼代碼或基礎設施+- **目前已驗證** — 哪些是確認能用的,跑過什麼驗證+- **本輪改動** — 改了什麼程式碼或基礎設施- **仍損壞或未驗證** — 已知問題和風險區- **下一步最佳動作** — 下一輪該做什麼,哪些東西不要動-- **命令** — 啟動、驗證、調試命令,方便快速參考+- **命令** — 啟動、驗證、除錯命令,方便快速參考-短會話可以不寫這個檔案。會話長了或者項目有多個並行區域時,它就很關鍵了。+短工作階段可以不寫這個檔案。工作階段長了或者專案有多個並行區域時,它就很關鍵了。## clean-state-checklist.md-收尾檢查清單。每次會話結束前過一遍,確保倉庫處於下一輪可以直接開工的狀態。+收尾檢查清單。每次工作階段結束前過一遍,確保儲存庫處於下一輪可以直接開工的狀態。**怎麼用:**-- 複製到項目根目錄-- 關掉會話前逐項檢查+- 複製到專案根目錄+- 關掉工作階段前逐項檢查- agent 的收尾流程裡也應該包含這些檢查**檢查什麼:**@@ -148,16 +148,16 @@ agent 任何時候只能有一個功能處於 `in_progress`。- 進度日誌已更新- 功能清單真實反映了 passing 和未驗證的邊界(沒有假 passing)- 沒有半成品處於未記錄狀態-- 下一輪會話不需要人工修復就能繼續+- 下一輪工作階段不需要人工修復就能繼續## evaluator-rubric.md-評審評分表。會話結束後或到裡程碑時,用它評估 agent 做的東西夠不夠格。+評審評分表。工作階段結束後或到裡程碑時,用它評估 agent 做的東西夠不夠格。**怎麼用:**-- 複製到項目根目錄-- 一輪(或幾輪)會話後,按六個維度打分+- 複製到專案根目錄+- 一輪(或幾輪)工作階段後,按六個維度打分- 每個維度 0-2 分**六個維度:**@@ -166,8 +166,8 @@ agent 任何時候只能有一個功能處於 `in_progress`。2. **驗證** — 要求的檢查是否真的跑過,並留下證據3. **範圍紀律** — 是否基本保持在選定功能範圍內4. **可靠性** — 結果是否能在重啟或重跑後繼續工作-5. **可維護性** — 代碼和文檔是否清楚到足以交給下一輪會話-6. **交接準備度** — 新會話是否能只靠倉庫內檔案繼續推進+5. **可維護性** — 程式碼和文件是否清楚到足以交給下一輪工作階段+6. **交接準備度** — 新工作階段是否能只靠儲存庫內檔案繼續推進**結論選項:**@@ -187,40 +187,40 @@ agent 任何時候只能有一個功能處於 `in_progress`。## quality-document.md-質量快照。給項目的每個產品領域和架構層打分,跟蹤代碼庫隨時間是變強了還是變弱了。+品質快照。給專案的每個產品領域和架構層打分,跟蹤程式碼庫隨時間是變強了還是變弱了。**怎麼用:**-- 複製到項目根目錄-- 開始會話前:讀它,瞭解代碼庫哪裡最弱-- 會話結束後:更新評級-- 長期:對比不同時間點的快照,看哪些 harness 改動真正改善了代碼庫健康度+- 複製到專案根目錄+- 開始工作階段前:讀它,瞭解程式碼庫哪裡最弱+- 工作階段結束後:更新評級+- 長期:對比不同時間點的快照,看哪些 harness 改動真正改善了程式碼庫健康度**評什麼:**-- **產品領域**(如文檔導入、問答流程、索引):每個領域按驗證狀態、Agent 可讀性、測試穩定性、關鍵缺口打分+- **產品領域**(如文件導入、問答流程、索引):每個領域按驗證狀態、Agent 可讀性、測試穩定性、關鍵缺口打分- **架構層**(如 Main Process、Preload、Renderer、Services):每層按邊界執行和 Agent 可讀性打分**為什麼需要它:**-Evaluator rubric 評的是單次 agent 輸出的質量。Quality document 評的是代碼庫本身的質量。它們回答的是不同的問題:+Evaluator rubric 評的是單次 agent 輸出的品質。Quality document 評的是程式碼庫本身的品質。它們回答的是不同的問題:- Evaluator rubric:"這輪 agent 做得好不好?"-- Quality document:"這個項目是在變強還是變弱?"+- Quality document:"這個專案是在變強還是變弱?"**什麼時候更新:**-- 每輪重要會話之後+- 每輪重要工作階段之後- 做基準對比之前- 做清理或簡化之後- 換新 agent 或新模型時**和 harness 簡化的關係:**-Quality document 也可以用來驗證 harness 是否可以簡化。Harness 裡的每個組件都編碼了一個假設——"模型做不到這件事"。模型變強後,這些假設就過時了。檢查某個組件是否還有必要:+Quality document 也可以用來驗證 harness 是否可以簡化。Harness 裡的每個元件都編碼了一個假設——"模型做不到這件事"。模型變強後,這些假設就過時了。檢查某個元件是否還有必要:1. 拍一份 quality document 快照。-2. 移除一個 harness 組件。+2. 移除一個 harness 元件。3. 跑基準測試。4. 再拍一份快照。-5. 對比——評級沒降,說明那個組件是多餘的。降了,就恢復。+5. 對比——評級沒降,說明那個元件是多餘的。降了,就恢復。diff --git a/docs/zh-TW/resources/templates/quality-document.md b/docs/zh-TW/resources/templates/quality-document.mdindex 170c7f3..ef99ba4 100644--- a/docs/zh-TW/resources/templates/quality-document.md+++ b/docs/zh-TW/resources/templates/quality-document.md@@ -1,14 +1,14 @@-# 質量文檔+# 品質文件-每個產品領域和架構層的質量快照。agent 和人都能通過這份文檔快速瞭解項目哪裡強、哪裡弱。+每個產品領域和架構層的品質快照。agent 和人都能透過這份文件快速瞭解專案哪裡強、哪裡弱。-**更新時機:** 每輪重要會話結束後,或開始新一階段工作前。+**更新時機:** 每輪重要工作階段結束後,或開始新一階段工作前。**評級標準:**- **A**:驗證全部通過,架構乾淨,agent 能讀懂,測試穩定- **B**:驗證通過,基本乾淨,可讀性或測試覆蓋有少量缺口-- **C**:部分可用,有已知缺口,部分代碼 agent 不容易理解+- **C**:部分可用,有已知缺口,部分程式碼 agent 不容易理解- **D**:不可用,或存在重大結構問題---@@ -17,9 +17,9 @@| 領域 | 評級 | 驗證狀態 | Agent 可讀性 | 測試穩定性 | 關鍵缺口 | 上次更新 ||------|------|---------|-------------|-----------|---------|---------|-| 文檔導入 | - | - | - | - | - | - |-| 文檔管理 | - | - | - | - | - | - |-| 文檔索引 | - | - | - | - | - | - |+| 文件導入 | - | - | - | - | - | - |+| 文件管理 | - | - | - | - | - | - |+| 文件索引 | - | - | - | - | - | - || 問答流程 | - | - | - | - | - | - || 引用式回答 | - | - | - | - | - | - |diff --git a/docs/zh-TW/resources/templates/session-handoff.md b/docs/zh-TW/resources/templates/session-handoff.mdindex 7d7f2f9..90a8bd4 100644--- a/docs/zh-TW/resources/templates/session-handoff.md+++ b/docs/zh-TW/resources/templates/session-handoff.md@@ -1,20 +1,20 @@-# 會話交接+# 工作階段交接-## 當前已驗證+## 目前已驗證- 現在明確可用的部分:- 這輪實際跑過的驗證:## 本輪改動-- 新增了哪些代碼或行為:+- 新增了哪些程式碼或行為:- 基礎設施或 harness 發生了哪些變化:## 仍損壞或未驗證- 已知缺陷:- 未驗證路徑:-- 下一輪會話需要注意的風險:+- 下一輪工作階段需要注意的風險:## 下一步最佳動作@@ -27,4 +27,4 @@- 啟動命令:- 驗證命令:-- 定向調試命令:+- 定向除錯命令:diff --git a/docs/zh-TW/skills/index.md b/docs/zh-TW/skills/index.mdindex 907b576..b77d1ea 100644--- a/docs/zh-TW/skills/index.md+++ b/docs/zh-TW/skills/index.md@@ -1,21 +1,21 @@# Skills(技能集)-本目錄包含課程附帶的 AI agent 技能。每個技能都是自包含的提示詞範本,可被 AI 程式設計智慧體(Claude Code、Codex、Cursor、Windsurf 等)載入以執行專業任務。+本目錄包含課程附帶的 AI 代理技能。每個技能都是自包含的提示詞範本,可被 AI 程式設計代理(Claude Code、Codex、Cursor、Windsurf 等)載入以執行專業任務。## harness-creator-面向 AI 程式設計智慧體的生產級 harness 工程技能。幫助建立、評估和改進五個核心 harness 子系統:指令、狀態、驗證、範圍和會話生命週期。+面向 AI 程式設計代理的生產級 harness 工程技能。幫助建立、評估和改進五個核心 harness 子系統:指令、狀態、驗證、範圍和工作階段生命週期。### 它能做什麼- **從零建立 harness** — AGENTS.md、功能清單、驗證工作流- **改進已有 harness** — 五子系統評分 + 優先級改進建議-- **設計會話連續性** — 記憶持久化、進度追蹤、交接機制-- **應用生產級模式** — 記憶、上下文工程、工具安全、多智慧體協調+- **設計工作階段連續性** — 記憶持久化、進度追蹤、交接機制+- **應用生產級模式** — 記憶、脈絡工程、工具安全、多智慧體協調### 快速開始-技能檔案位於倉庫的 [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator) 目錄。+技能檔案位於儲存庫的 [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator) 目錄。```bashnpx skills add walkinglabs/learn-harness-engineering --skill harness-creator@@ -29,13 +29,13 @@ npx skills add walkinglabs/learn-harness-engineering --skill harness-creator| 模式 | 適用場景 ||------|----------|-| 記憶持久化 | agent 在會話間遺忘專案知識 |+| 記憶持久化 | 代理在工作階段間遺忘專案知識 || Skill Runtime | 將可重用 workflow 打包成技能 |-| 上下文工程 | 上下文預算管理、按需載入、委託隔離 |+| 脈絡工程 | 脈絡預算管理、按需載入、委託隔離 || 工具註冊 | 工具安全、併發控制、權限管道 || 多智慧體協調 | 平行化、專業化、研究員→實作者工作流 || 生命週期與引導 | 鉤子、背景任務、初始化序列 |-| 常見陷阱 | 15 個容易踩坑的失敗模式及修復方案 |+| 常見陷阱 | 15 個常見失敗模式及修復方案 |### 範本@@ -44,12 +44,12 @@ npx skills add walkinglabs/learn-harness-engineering --skill harness-creator- `agents.md` — AGENTS.md 腳手架,包含工作規則- `feature-list.json` — JSON Schema + 功能列表示例- `init.sh` — 標準初始化腳本-- `progress.md` — 會話進度日誌範本-- `session-handoff.md` — 會話交接範本+- `progress.md` — 工作階段進度日誌範本+- `session-handoff.md` — 工作階段交接範本### 腳本-技能也包含純 Node.js 腳本,可用於腳手架生成、校驗、HTML 評估報告與結構化 benchmark 報告。+技能也包含純 Node.js 腳本,可用於骨架生成、驗證、HTML 評估報告與結構化基準測試報告。### 開發過程