Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
i18n(zh-TW): align zh-TW content with English source
Jim Chen8fc2e811141b
diff --git a/docs-readme/zh-TW/README.md b/docs-readme/zh-TW/README.mdindex cc9847b..9055f9e 100644--- a/docs-readme/zh-TW/README.md+++ b/docs-readme/zh-TW/README.md@@ -72,7 +72,7 @@ Learn Harness Engineering 是一門專注於 AI 程式設計代理工程化的## 模型很聰明,Harness 讓它可靠-大多數人都是慘痛教訓後才明白一個殘酷的事實:**世界上最強大的模型,如果你不在它周圍建構適當的環境,它在真實工程任務上仍然會失敗。**+大多數人都是慘痛教訓後才明白,**世界上最強大的模型,如果你不在它周圍建構適當的環境,它在真實工程任務上仍然會失敗。**你可能自己也見過這種情況。你讓 Claude 或 GPT 在你的儲存庫中執行一項任務。它一開始表現不錯,讀取檔案、撰寫程式碼,看起來很有效率。然後出了問題。它跳過了一個步驟。它破壞了一個測試。它說「完成了」,但實際上什麼都不能用。你最後花的時間比自己動手做還多。diff --git a/docs/zh-TW/index.md b/docs/zh-TW/index.mdindex 202f9cc..260029b 100644--- a/docs/zh-TW/index.md+++ b/docs/zh-TW/index.md@@ -58,7 +58,7 @@ graph TD<li>用明確的規則和邊界<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、claude-progress.md 等),直接用於你的專案。</li></ul>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 c43e283..27c15b1 100644--- a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -5,13 +5,9 @@# 第一講. 模型能力強,不等於執行可靠-你說你也算見過世面的人了,Claude Pro 訂著,GPT-4o 的 API key 也有,SWE-bench 排行榜上的數字你比誰都清楚。有一天你終於想讓 AI agent 幫你改一個真實的專案,信心滿滿地交代下去。結果呢?加了功能但測試掛了,改了 bug 但引入了新 bug,跑了 20 分鐘然後自信滿滿地說「完成了」,你一看程式碼,根本不是你要的東西。+截至 2025 年底,最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這個數字乍看還行,但別急著慶祝。那都是精心挑選過的、有明確 issue 描述和現成測試用例的任務。換到你日常開發的場景——需求模糊、沒有現成測試、隱含的業務規則散落在各處——這個數字只會更低。你信心滿滿地交代任務,agent 跑了 20 分鐘告訴你「完成了」,你一看程式碼:加了功能但測試掛了,改了 bug 但引入了新 bug,根本不是你要的東西。-這時候你的第一反應是什麼?「這模型不行,得換一個更貴的。」且慢。先別急著掏錢包。問題可能根本不在模型身上。--讓我們先看一組資料。截至 2025 年底,最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這還是精心挑選過的、有明確 issue 描述和測試用例的任務。換到你日常開發的場景,需求模糊、沒有現成測試、隱含的業務規則散落在各處,這個數字只會更低。--但這組資料背後藏著一個反直覺的事實。+遇到這種情況,大部分人的第一反應是「這模型不行,得換一個更貴的。」先別急著掏錢包。問題可能根本不在模型身上。## 同一匹馬,兩種命運@@ -19,19 +15,19 @@ 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 把寶貴的脈絡視窗花在了 `pip install` 失敗、Node 版本不對這些事上,而不是解決你的核心任務。就好比你讓一個木匠來幹活,結果錘子沒帶、釘子找不到、工作臺還是歪的,手藝再好也使不上勁。+環境也是個坑。開發環境配置不完整、依賴缺了、工具版本不對。Agent 把寶貴的脈絡視窗花在了 `pip install` 失敗、Node 版本不對這些事上,而不是解決你的核心任務。-更常見的問題是壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完程式碼,自己看了看覺得沒問題,就說完成了。讓學生交作業但不給答案檢查,結果是他自己覺得做對了,批改時卻一堆錯誤。Anthropic 還觀察到一個有意思的現象,當 agent 感覺脈絡快滿了,它們會匆忙結束目前工作,跳過驗證步驟,選一個簡單的方案而不是最優方案。他們把這叫「脈絡焦慮」,跟你考試時發現時間快到了趕緊隨便選幾個選擇題是一回事。+更常見的問題是壓根沒有驗證手段。沒有測試、沒有 lint、或者驗證命令根本沒告訴 agent。Agent 寫完程式碼,自己看了看覺得沒問題,就說完成了。Anthropic 還觀察到一個有意思的現象,當 agent 感覺脈絡快滿了,它們會匆忙結束目前工作,跳過驗證步驟,選一個簡單的方案而不是最優方案。他們把這叫「脈絡焦慮」。長任務跨工作階段就更慘了,上次工作階段的發現全丟了,每個新工作階段都得重新探索專案結構、理解程式碼組織。缺乏持久化狀態的 agent 在超過 30 分鐘的任務中失敗率急劇上升。@@ -40,7 +36,7 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code理解了上面的場景,這些概念就不再是一堆術語了:- **能力鴻溝(Capability Gap)**:模型在基準測試上的表現和真實任務上的表現之間的巨大落差。SWE-bench Verified 上 50-60% 的通過率意味著近一半的真實 issue 解不了。-- **Harness**:模型之外的一切,指令、工具、環境、狀態管理、驗證回饋。不是模型權重的部分,全是 harness。也就是我們說的「馬具」。+- **Harness**:模型之外的一切,指令、工具、環境、狀態管理、驗證回饋。不是模型權重的部分,全是 harness。- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。Anthropic 的對照實驗已經證明了這一點。- **驗證缺口**:agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說「我做完了」但實際沒做完,這是最常見的失敗模式。- **診斷循環**:執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。@@ -48,7 +44,7 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code## 遇到失敗,先修 harness-核心原則,**遇到失敗,先別換模型,先檢查 harness。** 如果同一個模型在類似的結構良好的任務中能成功,那優先假設是 harness 的問題。汽車拋錨時,你不會第一時間懷疑是發動機壞了,你會先看看是不是沒油了。+核心原則,**遇到失敗,先別換模型,先檢查 harness。** 如果同一個模型在類似的結構良好的任務中能成功,那優先假設是 harness 的問題。具體怎麼做。@@ -66,7 +62,7 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code**建立 AGENTS.md 檔案。** 在儲存庫根目錄放一個檔案,告訴 agent 這個專案的技術堆疊、架構約定、驗證命令。這是 harness 工程的第一步,也是投入產出比最高的一步。一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效,這不是誇張。-**建立診斷循環。** 不要把失敗當作「模型又犯傻了」,而是當作「harness 又暴露了一個缺陷」的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來,你的 harness 會越來越強,agent 的表現會穩定提升。每修補一個缺陷,後續執行就更穩定。+**建立診斷循環。** 不要把失敗當作「模型又犯傻了」,而是當作「harness 又暴露了一個缺陷」的信號。每次失敗 → 定位層 → 修補 → 下次不再犯。幾輪下來,你的 harness 會越來越強,agent 的表現會穩定提升。**量化改進。** 記個簡單的日誌,每個任務成功了沒有,失敗了是哪一層的問題。跑幾輪之後你就能看出來哪個層是瓶頸,集中火力修那個層。@@ -97,8 +93,8 @@ OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git- 模型能力和執行可靠性是兩回事。千里馬也得配上好馬具。- 失敗的時候先看 harness,再看模型。換模型是成本最高的選擇,而且很多時候根本不是模型的問題。- 每次失敗都是一個信號:你的 harness 有結構性缺陷。把它找出來、修掉。-- 五層防禦:任務規範、脈絡供給、執行環境、驗證回饋、狀態管理。逐層排查,優先從最常見的失敗原因入手。-- 一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效。真的。+- 別只說「模型不行」。逐層排查五個防禦層:任務沒說清楚、脈絡不足、環境配置有問題、缺少驗證、工作階段之間狀態丟失。十次裡有九次,問題出在這五層之中的某一層。+- 一個 `AGENTS.md` 檔案可能比你換一個更貴的模型更有效。## 延伸閱讀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 7622895..0b18d37 100644--- a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -5,13 +5,13 @@# 第二講. Harness 到底是什麼-「harness」這個詞在 AI coding agent 的圈子裡被用得越來越多了,但說實話,大部分人說的 harness 其實就只是「一個 prompt 檔案」。這不是 harness。你開了一家餐廳,只有食材,沒有灶臺、沒有刀具、沒有菜譜、沒有出菜流程,那不叫餐廳,那叫冰箱。+「harness」這個詞在 AI coding agent 的圈子裡被用得越來越多了,但說實話,大部分人說的 harness 其實就只是「一個 prompt 檔案」。這不是 harness。-這節課要給你一個精確的、可操作的 harness 定義。這個框架可以直接使用,不同於學術論文裡的抽象概念,harness 由五個子系統組成,分別對應廚房的五個功能區,菜譜架、刀具架、灶臺、備菜臺、和出菜檢查口。每個子系統都有明確的職責和評判標準。+這節課要給你一個精確的、可操作的 harness 定義。這個框架可以直接使用,不同於學術論文裡的抽象概念,harness 由五個子系統組成。每個子系統都有明確的職責和評判標準。## 以一個類比出發-想象你是一個剛入職的工程師,被丟進一個沒有任何文件的專案裡。沒有 README,程式碼裡沒有註釋,沒有人告訴你怎麼跑測試,CI 配置檔案藏在某個角落裡。你能寫出好程式碼嗎?也許能,如果你足夠聰明又足夠有耐心。但你會花大量時間在「搞清楚這個專案是怎麼回事」上,而不是在「解決問題」上。+想像你是一個剛入職的工程師,被丟進一個沒有任何文件的專案裡。沒有 README,程式碼裡沒有註釋,沒有人告訴你怎麼跑測試,CI 配置檔案藏在某個角落裡。你能寫出好程式碼嗎?也許能,如果你足夠聰明又足夠有耐心。但你會花大量時間在「搞清楚這個專案是怎麼回事」上,而不是在「解決問題」上。AI agent 面對的困境一模一樣。而且更糟,你至少可以問同事,agent 只能看到你放在它面前的檔案和它能執行的命令。它不能拍拍同事的肩膀問「哎,這個專案的 ORM 用的是哪個版本?」@@ -19,13 +19,13 @@ OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表看看幾個你熟悉的工具。-**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` 和明確驗證命令的儲存庫裡,表現遠超在「裸」儲存庫裡。-**AutoGPT** 則是反面教材,缺乏結構化的狀態管理導致長任務中脈絡不斷累積,缺乏精確的回饋機制導致 agent 陷入循環。很多人說 AutoGPT 「不行」,但其實是它的 harness 不行,你給它一個破灶臺,再好的食材也做不出菜來。+**AutoGPT** 則是反面教材,缺乏結構化的狀態管理導致長任務中脈絡不斷累積,缺乏精確的回饋機制導致 agent 陷入循環。很多人說 AutoGPT 「不行」,但其實是它的 harness 不行。## 核心概念@@ -37,7 +37,7 @@ OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表## Harness 五子系統模型-回到廚房的類比。一個完整的廚房有五個功能區,harness 也有五個子系統。+harness 有五個子系統:```mermaidflowchart LR@@ -49,15 +49,15 @@ flowchart LRChecks --> Agent```-**指令子系統(菜譜架)**:建立 `AGENTS.md`(或 `CLAUDE.md`),內容包括專案概覽和目的(一句話說清楚這是什麼)、技術堆疊和版本(Python 3.11、FastAPI 0.100+、PostgreSQL 15)、首次執行命令(`make setup`、`make test`)、不可違反的硬約束(「所有 API 必須走 OAuth 2.0」)、指向更詳細文件的連結。+**指令子系統**:建立 `AGENTS.md`(或 `CLAUDE.md`),內容包括專案概覽和目的(一句話說清楚這是什麼)、技術堆疊和版本(Python 3.11、FastAPI 0.100+、PostgreSQL 15)、首次執行命令(`make setup`、`make test`)、不可違反的硬約束(「所有 API 必須走 OAuth 2.0」)、指向更詳細文件的連結。-**工具子系統(刀具架)**:讓 agent 有足夠的工具訪問權限。不要因為「安全考慮」把 shell 給禁了,agent 連 `pip install` 都跑不了,還怎麼幹活?但也別什麼都開放,按最小權限原則來。+**工具子系統**:讓 agent 有足夠的工具訪問權限。不要因為「安全考慮」把 shell 給禁了,agent 連 `pip install` 都跑不了,還怎麼幹活?但也別什麼都開放,按最小權限原則來。-**環境子系統(灶臺)**:讓環境狀態自描述。用 `pyproject.toml` 或 `package.json` 鎖定依賴,用 `.nvmrc` 或 `.python-version` 指定執行時期版本,用 Docker 或 devcontainer 讓環境可重現。+**環境子系統**:讓環境狀態自描述。用 `pyproject.toml` 或 `package.json` 鎖定依賴,用 `.nvmrc` 或 `.python-version` 指定執行時期版本,用 Docker 或 devcontainer 讓環境可重現。-**狀態子系統(備菜臺)**:長任務必須有進度跟蹤。用一個簡單的 `PROGRESS.md` 檔案記錄:哪些做完了,哪些在做,哪些被阻塞。每個工作階段結束前更新,下一個工作階段開始時讀取。+**狀態子系統**:長任務必須有進度跟蹤。用一個簡單的 `PROGRESS.md` 檔案記錄:哪些做完了,哪些在做,哪些被阻塞。每個工作階段結束前更新,下一個工作階段開始時讀取。-**回饋子系統(出菜檢查口)**:這是投入產出比最高的子系統。在 `AGENTS.md` 裡顯式列出驗證命令:+**回饋子系統**:這是投入產出比最高的子系統。在 `AGENTS.md` 裡顯式列出驗證命令:```驗證命令:- 測試:pytest tests/ -x@@ -66,29 +66,29 @@ flowchart LR- 完整驗證:make check(包含以上全部)```-五個子系統缺一個,廚房裡少了一個功能區,菜還是能做,但總是彆扭。+五個子系統缺任何一個,harness 都是不完整的。**量化 harness 組件價值的方法**:用「等模型對照下的組件拆除實驗」。保持模型不變,逐個移除五個子系統,看哪個子系統缺失時效能下降最多。下降最多的組件,說明它在目前任務裡邊際貢獻最大,值得優先保留;是否要加強它,取決於失敗歸因,而不是只看下降幅度。幾乎沒有影響的組件,也不能直接判定為無用,它可能是冗餘、設計失效,或還沒有被這個任務充分觸發。這個實驗回答的是「目前哪個組件最有價值」,不能單獨證明「瓶頸在哪裡」。真正定位瓶頸,要先看失敗記錄和歸因,包含任務沒說清楚、脈絡不足、環境不可復現、驗證回饋缺失,還是狀態管理斷裂;組件拆除結果只能作為輔助證據。## 一個團隊的真實經歷-一個團隊用 GPT-4o 開發一個 TypeScript + React 前端應用(約 20,000 行程式碼)。他們經歷了四個階段,其實就是在一件一件地添置廚具。+一個團隊用 GPT-4o 開發一個 TypeScript + React 前端應用(約 20,000 行程式碼)。他們經歷了四個階段。-**階段 1,空廚房**:只有 README 裡的基本專案描述。5 次執行成功 1 次(20%)。主要失敗在於選錯了包管理器(npm vs yarn)、沒遵循組件命名約定、跑不了測試。+**階段 1**:只有 README 裡的基本專案描述。5 次執行成功 1 次(20%)。主要失敗在於選錯了包管理器(npm vs yarn)、沒遵循組件命名約定、跑不了測試。-**階段 2,裝上菜譜架**:添加 `AGENTS.md`,寫明技術堆疊版本、命名約定、關鍵架構決策。成功率升到 60%。剩餘失敗主要來自環境問題和驗證缺失。+**階段 2**:添加 `AGENTS.md`,寫明技術堆疊版本、命名約定、關鍵架構決策。成功率升到 60%。剩餘失敗主要來自環境問題和驗證缺失。-**階段 3,開起出菜檢查口**:在 `AGENTS.md` 裡列出驗證命令 `yarn test && yarn lint && yarn build`。成功率升到 80%。+**階段 3**:在 `AGENTS.md` 裡列出驗證命令 `yarn test && yarn lint && yarn build`。成功率升到 80%。-**階段 4,備菜臺就位**:引入進度檔案範本,agent 在每次執行中記錄完成和未完成的工作。成功率穩定在 80-100%。+**階段 4**:引入進度檔案範本,agent 在每次執行中記錄完成和未完成的工作。成功率穩定在 80-100%。-四次迭代,模型一個字沒改,成功率從 20% 到接近 100%。這就是 harness 工程的力量。你沒有換更貴的食材,你只是把廚房收拾俐落了。+四次迭代,模型一個字沒改,成功率從 20% 到接近 100%。這就是 harness 工程的力量。## 關鍵要點-- Harness = 指令 + 工具 + 環境 + 狀態 + 回饋。五個子系統,分別對應廚房的五個功能區,缺一不可。+- Harness = 指令 + 工具 + 環境 + 狀態 + 回饋。五個子系統,缺一不可。- 不是模型權重的部分全是 harness。你的 harness 決定了模型能力能被發揮多少。-- 五個子系統中,回饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚,出菜檢查口是最值得先裝的。+- 五個子系統中,回饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚。- 用「等模型對照下的組件拆除實驗」量化各子系統的邊際貢獻;定位真正瓶頸要靠失敗記錄和歸因,不能只靠拆除實驗。- Harness 和程式碼一樣會腐化。定期審計,像還技術債一樣還 harness 債。diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 7b99926..2b30387 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@@ -19,7 +19,7 @@ Anthropic 的 long-running agents 文件也強調了類似的觀點:持久化你可能會想:「我們團隊人少,知識都在大家腦子裡,這不也工作得好好的嗎?」沒錯,對人類來說確實可以。但你要用 agent,就得接受一個事實:agent 不能問人。所有它需要知道的東西,都必須寫下來,放在它能找到的地方。-這不是「寫更多文件」的問題。這是「把決策資訊放到正確的位置」的問題。一份在 `src/api/` 目錄下、50 行的 `ARCHITECTURE.md`,比一份在 Confluence 裡、500 頁但沒人維護的設計文件有用一萬倍。就好比一張貼在你工位上的、手畫的辦公室走法圖,比一份精美的、放在檔案室裡的建築藍圖實用得多,因為前者在你需要的時候就在手邊。+這不是「寫更多文件」的問題。這是「把決策資訊放到正確的位置」的問題。一份在 `src/api/` 目錄下、50 行的 `ARCHITECTURE.md`,比一份在 Confluence 裡、500 頁但沒人維護的設計文件有用得多。## 知識可見性@@ -56,7 +56,7 @@ flowchart TB## 核心概念- **知識可見性缺口**:專案總知識中不在儲存庫裡的比例。缺口越大,agent 失敗的概率越高。你腦子裡有多少關於這個專案的隱性知識?把它們全算上,再看有多少寫進了儲存庫,兩者的差距就是你的可見性缺口。-- **系統記錄(System of Record)**:程式碼儲存庫作為專案決策、架構約束、執行狀態和驗證標準的權威資訊源。儲存庫說了算,別的地方說了不算。地圖上標出「此路不通」,走的人自然繞行;但這個資訊若只留在老張腦子裡,每次都得去問老張。+- **系統記錄(System of Record)**:程式碼儲存庫作為專案決策、架構約束、執行狀態和驗證標準的權威資訊源。儲存庫說了算,別的地方說了不算。- **冷啟動測試**:上一節說的五個問題。能回答幾個,你的地圖就畫了幾分。- **發現成本**:agent 為了在儲存庫裡找到一條關鍵資訊需要消耗多少脈絡。資訊放得越隱蔽,發現成本越高,留給實際任務的預算越少。把關鍵資訊藏在十層目錄深處的 README 裡,不是沒有,是用的時候找不到。- **知識衰減率**:儲存庫中單位時間內變得過時的知識條目比例。文件和程式碼脫節是最大的敵人,比沒有文件更危險的是過時的文件。@@ -64,7 +64,7 @@ flowchart TB## 怎麼畫好這張地圖-**原則 1:知識靠近程式碼。** 一條關於 API 端點認證的規則,應該放在 API 程式碼旁邊,而不是藏在一個巨大的全域文件裡。每個模組目錄下放一個簡短的文件,說清楚這個模組的職責、介面和特殊約束。圖書館按主題分類書架,找歷史類書籍直接去歷史書架,不用翻遍整個圖書館。+**原則 1:知識靠近程式碼。** 一條關於 API 端點認證的規則,應該放在 API 程式碼旁邊,而不是藏在一個巨大的全域文件裡。每個模組目錄下放一個簡短的文件,說清楚這個模組的職責、介面和特殊約束。**原則 2:用標準化的入口檔案。** `AGENTS.md`(或 `CLAUDE.md`)是 agent 的「著陸頁」。它不需要包含所有資訊,但必須能讓 agent 快速回答「這是什麼專案」、「怎麼跑」、「怎麼驗證」這三個問題。50-100 行就夠了。@@ -94,15 +94,15 @@ project/這個類比來自資料庫的事務管理,你可能覺得這是在把簡單的事情搞複雜,但實際上它給了你一個非常實用的框架。- **原子性**:每次「邏輯操作」(比如「添加新端點並更新測試」)用一個 git commit 原子化。中途掛了就 `git stash` 回溯。要麼全做,要麼不做,沒有「做了一半」。-- **一致性**:定義「一致狀態」的驗證謂詞,所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。銀行轉帳不能只扣款不入帳。-- **隔離性**:多個 agent 併發工作時,狀態檔案要避免競爭條件。簡單方案:每個 agent 用獨立的進度檔案,或者用 git 分支隔離。兩個廚師不能同時往同一口鍋裡放鹽,放重了誰負責?-- **持久性**:關鍵的專案知識用 git 跟蹤的檔案持久化。臨時狀態可以只在工作階段的記憶體中,但跨工作階段必須的知識必須寫到檔案裡。腦子裡的不算,寫在紙上的才算。+- **一致性**:定義「一致狀態」的驗證謂詞,所有測試通過、lint 無報錯。Agent 每次操作後跑驗證,不一致的中間狀態不要 commit。+- **隔離性**:多個 agent 併發工作時,狀態檔案要避免競爭條件。簡單方案:每個 agent 用獨立的進度檔案,或者用 git 分支隔離。+- **持久性**:關鍵的專案知識用 git 跟蹤的檔案持久化。臨時狀態可以只在工作階段的記憶體中,但跨工作階段必須的知識必須寫到檔案裡。## 一個真實的改造故事一個團隊維護一個包含約 30 個微服務的電商平臺。架構決策(服務間通信協定、資料一致性策略、API 版本化規則)散落在:Confluence(部分過時)、Slack(難以搜尋)、幾個資深工程師的腦子裡(不可擴展)、以及零星的程式碼註釋(不繫統)。-引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個「所有人都知道但從未寫入儲存庫」的隱性約束。新員工不知道「中午點外賣要在群裡接龍」的規矩,只能猜;猜錯了被罵,被罵了也還是沒人明說。+引入 AI agent 後,70% 的任務需要人工干預。幾乎每次失敗都涉及 agent 違反了某個「所有人都知道但從未寫入儲存庫」的隱性約束。團隊執行了改造:1. 儲存庫根目錄建立 `AGENTS.md`,寫明專案概覽、技術堆疊版本、全域硬約束@@ -114,7 +114,7 @@ project/## 關鍵要點-- 不在儲存庫裡的知識對 agent 來說等於不存在。把關鍵決策資訊放進儲存庫是最基本的 harness 投資,畫好地圖,才不會迷路。+- 不在儲存庫裡的知識對 agent 來說等於不存在。把關鍵決策資訊放進儲存庫是最基本的 harness 投資。- 用「冷啟動測試」檢驗儲存庫品質:全新工作階段能不能只看儲存庫回答五個基本問題。- 知識要靠近程式碼、最小但完備、跟程式碼一起更新。不是寫更多文件,是把資訊放到正確的位置。- 用 ACID 原則管理 agent 狀態:原子提交、一致性驗證、隔離併發、持久化關鍵知識。diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex b4f1ed1..13120e7 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@@ -91,7 +91,7 @@ Python 3.11 FastAPI 後端,PostgreSQL 15 資料庫。如果某條指令必須在入口檔案裡,放頂部或底部,不要放中間。「中間迷失」效應告訴我們,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。但更好的做法是把指令放到專題文件裡,讓 agent 按需加載。-OpenAI 和 Anthropic 都隱性支援拆分的做法。OpenAI 說入口檔案應「短小且以路由為導向」,Anthropic 說長執行 agent 的控制資訊應「簡潔且高優先級」。兩家都在說同一件事,別把什麼都塞進一個檔案裡。指令系統得整理,不能只靠不斷追加。+OpenAI 和 Anthropic 都隱性支援拆分的做法。OpenAI 說入口檔案應「短小且以路由為導向」,Anthropic 說長執行 agent 的控制資訊應「簡潔且高優先級」。兩家都在說同一件事,別把什麼都塞進一個檔案裡。## 實際案例diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.mdindex df1c065..3bea85a 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@@ -7,9 +7,7 @@你讓 Claude Code 幫你實作一個完整的功能,它跑了 30 分鐘,做了大部分工作,但脈絡快滿了。你開個新工作階段繼續,然後發現,它不記得上次做了什麼決策、為什麼選了方案 A 而不是方案 B、哪些檔案已經改過、測試跑到什麼狀態了。它得花 15 分鐘重新探索一遍專案,而且可能跟上次的做法不一致。-想象一下,如果你是一個工匠,每天早上醒來都不記得昨天幹了什麼。你得重新認識整個工地,哪面牆砌了一半、為什麼用的是紅磚而不是青磚、水電管道走到哪了。更糟的是,你可能會把昨天已經裝好的窗戶拆了重來,因為你不記得它已經裝過了。--這就是 AI coding agent 在跨工作階段任務中面對的困境。本節課講為什麼 agent 會「斷片」,以及如何透過結構化的狀態持久化讓它像一個每天堅持寫日記的工匠,雖然還是會失憶,但日記本裡記著一切。+這就是 AI coding agent 在跨工作階段任務中面對的困境。本節課講為什麼 agent 會「斷片」,以及如何透過結構化的狀態持久化讓它快速恢復到可執行狀態。## 脈絡視窗:不是無限的@@ -51,7 +49,7 @@ flowchart LR## 核心概念- **脈絡視窗是有限的**:不管模型吹多大的視窗(128K、200K、1M),長任務總會用完。用完之後要麼壓縮(丟資訊),要麼重置(開新工作階段)。兩種方式都會丟東西。-- **連續性工件**:持久化的狀態檔案,讓新工作階段能無歧義地恢復到上次離開的地方。最基本的形式:進度日誌 + 驗證記錄 + 下一步行動。就是那個工匠的日記本。+- **連續性工件**:持久化的狀態檔案,讓新工作階段能無歧義地恢復到上次離開的地方。最基本的形式:進度日誌 + 驗證記錄 + 下一步行動。- **重建成本**:新工作階段恢復到可執行狀態所需的時間。好的 harness 能把重建成本從 15 分鐘壓到 3 分鐘。- **漂移(Drift)**:agent 的理解跟程式碼儲存庫實際狀態之間的偏差。每次工作階段邊界都會引入漂移,不加控制會越漂越遠。- **脈絡焦慮**:Anthropic 觀察到的現象,agent 在接近脈絡限制時表現異常,過早結束任務以避免資訊遺失。是一種非理性的資源焦慮。@@ -61,7 +59,7 @@ flowchart LR上個工作階段花了很多脈絡預算分析了三種方案的優劣,最終選了方案 B。這個工作階段的 agent 不知道這個分析過程,可能基於不完整的資訊重新做了決策,而且可能選了方案 A。新工作階段的 agent 不知道上個工作階段的分析過程,可能基於不完整的資訊重新決策,結果選了不同的方案。-更要命的是重複勞動。Agent 不確定某項工作是否已完成,重新做了一遍。或者更糟,做了一半發現跟已有的實作衝突,需要返工。工地上不能兩撥人同時砌同一面牆,但在沒有進度記錄的情況下,新來的人完全不知道這面牆已經有人在砌了。+更要命的是重複勞動。Agent 不確定某項工作是否已完成,重新做了一遍。或者更糟,做了一半發現跟已有的實作衝突,需要返工。幾個工作階段累積下來,實作方向可能已經悄悄偏離了原始需求。每個新工作階段對專案目標的理解都略有偏差,每次偏差微小,累積起來卻可能大相徑庭。@@ -69,11 +67,11 @@ flowchart LROpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化的重要性。OpenAI 的 harness engineering 文章把儲存庫當作「操作記錄」,每次操作的結果都應該在儲存庫裡留下可追溯的痕跡。Anthropic 的 long-running agents 文件則更具體地建議使用「交接檔案」,包含目前狀態、已知問題和下一步行動的結構化文件。-## 給失憶工匠的日記本+## 狀態持久化的實踐方法核心思路,**把 agent 當成一個會失憶的超級工程師來管理。** 每次它要「下班」之前,必須把關鍵資訊寫下來,讓下一個「接班」的 agent 能快速上手。-**工具 1:進度檔案(PROGRESS.md)**。這是最基本的連續性工件,日記本的核心部分:+**工具 1:進度檔案(PROGRESS.md)**。這是最基本的連續性工件:```markdown# 專案進度@@ -101,7 +99,7 @@ OpenAI 和 Anthropic 都在他們的文件裡強調了結構化狀態持久化3. 更新 API 文件```-**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文件,只需要「什麼決策、為什麼、什麼時候做的」,這是日記本裡的備忘:+**工具 2:決策日誌(DECISIONS.md)**。記錄重要的設計決策和原因。不需要詳細的設計文件,只需要「什麼決策、為什麼、什麼時候做的」:```markdown# 設計决策@@ -153,11 +151,11 @@ Anthropic 的實際資料:對於 Sonnet 4.5,脈絡焦慮足夠嚴重,以**有日記本的對照**:使用進度檔案、決策日誌、驗證記錄和 git 檢查點。每個工作階段結束時自動更新狀態報告。工作階段 2 的重建成本降到約 3 分鐘。到工作階段 5,所有 12 個功能點完成且通過驗證。-定量對比,重建時間減少約 78%,功能完成率從 58% 提升到 100%,隱含缺陷率從 43% 降到 8%。工匠還是那個會失憶的工匠,但有了日記本,他的每一天都從昨天停下的地方開始,而不是從零開始。+定量對比,重建時間減少約 78%,功能完成率從 58% 提升到 100%,隱含缺陷率從 43% 降到 8%。## 關鍵要點-- 脈絡視窗是有限的資源。長任務一定會跨工作階段,跨工作階段一定會丟資訊,跨工作階段一定會丟資訊,這是客觀現實。+- 脈絡視窗是有限的資源。長任務一定會跨工作階段,跨工作階段一定會丟資訊,這是客觀現實。- 解決方案在於更好的狀態持久化,而非更大的視窗。進度檔案 + 決策日誌 + git 檢查點,讓每個工作階段都能從可靠的記錄起步。- 把 agent 當成會失憶的工程師來管理:每次「下班」前寫清楚做了什麼、為什麼、下一步做什麼。- 重建成本是關鍵指標。好的 harness 應該讓新工作階段在 3 分鐘內恢復到可執行狀態。diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.mdindex 2c0507c..6db3393 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@@ -7,15 +7,15 @@你開了一個新的 agent 工作階段,讓它「幫我加個搜尋功能」。它上來就開始改程式碼,精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現資料庫遷移腳本格式不對,又折騰了一會兒。最後搜尋功能倒是加了,但整個工作階段的效率很低,大部分時間花在了「搞清楚這個專案怎麼運作」上,而不是寫搜尋功能。-更好的做法是在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、專案結構搞清楚。蓋房子必須先打地基,地基幹了再砌牆;若同時進行,牆砌到一半地基未固,整棟樓都得推倒重來。+更好的做法是在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、專案結構搞清楚。這節課講的就是為什麼初始化必須是獨立的階段,不能跟實作混在一起。-## 地基和牆:兩種完全不同的工作+## 兩種截然不同的工作目標初始化和實作的最佳化目標完全不同。實作階段的目標是最大化已驗證功能的數量和品質。初始化階段的目標是最大化後續所有實作的可靠性和效率。-當你把初始化和實作混在一起的時候,agent 面臨一個多目標最佳化問題,它要同時搭基礎設施和寫功能程式碼。在沒有顯式優先級設定的情況下,agent 自然傾向於寫程式碼(因為那是直接可見的產出),而犧牲基礎設施(因為它的價值只能在後續工作階段中體現)。施工隊若同時打地基和砌牆,往往會急著砌牆,因為牆看得見、能交差。但地基沒打好,後面出的問題是系統性的。+當你把初始化和實作混在一起的時候,agent 面臨一個多目標最佳化問題,它要同時搭基礎設施和寫功能程式碼。在沒有顯式優先級設定的情況下,agent 自然傾向於寫程式碼(因為那是直接可見的產出),而犧牲基礎設施(因為它的價值只能在後續工作階段中體現)。## 初始化生命週期@@ -37,15 +37,15 @@ flowchart TB## 混在一起做會怎樣-最直接的問題:基礎設施不紮實。Agent 花了 80% 的精力寫功能程式碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了,新 agent 不知道專案怎麼跑、怎麼測、做到哪了。基礎薄弱,後患無窮。+最直接的問題:基礎設施不紮實。Agent 花了 80% 的精力寫功能程式碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了,新 agent 不知道專案怎麼跑、怎麼測、做到哪了。更隱蔽的代價是「未驗證的累積」,在測試框架配好之前寫的功能程式碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實作。等回頭補測試時才發現設計有問題,要重構才能讓測試通過。-脈絡預算也在被浪費。初始化工作(配環境、配測試、理解專案結構)消耗了大量預算,留給實際功能實作的反而不夠了。結果第一個工作階段只完成了一半的功能,第二個工作階段還得從頭理解專案。預算花在了打地基上,但地基也沒打好,兩頭都沒佔著。+脈絡預算也在被浪費。初始化工作(配環境、配測試、理解專案結構)消耗了大量預算,留給實際功能實作的反而不夠了。結果第一個工作階段只完成了一半的功能,第二個工作階段還得從頭理解專案。-最容易被忽略的是隱式假設埋下的雷。Agent 在初始化過程中做的決策(用什麼測試框架、目錄怎麼組織、依賴怎麼管理)如果不顯式記錄下來,後續工作階段就可能做出矛盾的選擇。第一個施工隊用的是水泥地基,第二個施工隊不知道,往上面打了木樁,地基直接裂了。+最容易被忽略的是隱式假設埋下的雷。Agent 在初始化過程中做的決策(用什麼測試框架、目錄怎麼組織、依賴怎麼管理)如果不顯式記錄下來,後續工作階段就可能做出矛盾的選擇。-Anthropic 在他們的長執行應用開發研究中明確建議把初始化和實作分離。他們的實驗資料顯示,使用獨立初始化階段的專案,多工作階段場景中的功能完成率比混合方式高 31%。關鍵是,初始化階段投入的時間在後續 3-4 個工作階段中就能完全收回。地基打得越紮實,上面的樓蓋得越快。+Anthropic 在他們的長執行應用開發研究中明確建議把初始化和實作分離。他們的實驗資料顯示,使用獨立初始化階段的專案,多工作階段場景中的功能完成率比混合方式高 31%。關鍵是,初始化階段投入的時間在後續 3-4 個工作階段中就能完全收回。OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記錄」的原則,第一次執行就要建立有效的操作結構,否則每次新工作階段都得重新推斷專案約定。@@ -53,7 +53,7 @@ OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記- **初始化階段**:agent 生命週期中的第一個階段,不做功能實作,只建立後續所有實作階段的執行前提。輸出的是基礎設施,不是功能程式碼。- **自舉契約**:一個專案能被全新 agent 工作階段無歧義操作的條件,能啟動、能測試、能看進度、能接手下一步。四個條件缺一不可。-- **冷啟動 vs 熱啟動**:冷啟動是從空目錄開始,agent 要猜專案結構;熱啟動是從範本或已有專案開始,基礎設施已經就位。熱啟動的效果遠好於冷啟動,從有基礎設施的工地開工,效率遠高於在空地從零搭建。+- **冷啟動 vs 熱啟動**:冷啟動是從空目錄開始,agent 要猜專案結構;熱啟動是從範本或已有專案開始,基礎設施已經就位。熱啟動的效果遠好於冷啟動。- **交接就緒性**:專案在任何時刻都處於「可以被全新 agent 接手」的狀態。不需要口頭解釋,只看儲存庫內容就能接著幹。- **首次驗證時間**:從專案開始到第一個功能點通過驗證的時間。這是衡量初始化效率的核心指標。- **下游可用性**:初始化品質的最佳衡量標準,後續工作階段不需要依賴隱式知識就能成功執行任務的比例。@@ -62,7 +62,7 @@ OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記**把初始化當作一個獨立的階段來執行。** 第一個工作階段只做初始化,不寫任何業務功能程式碼。初始化的產出是:-**1. 可執行的環境。** 專案能啟動、依賴都裝好、沒有環境問題。地基澆好了,沒裂縫。+**1. 可執行的環境。** 專案能啟動、依賴都裝好、沒有環境問題。**2. 可驗證的測試框架。** 至少有一個示例測試能通過。這是對測試框架本身配對的驗證。@@ -109,7 +109,7 @@ OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記**5. Git 提交作為檢查點。** 初始化完成後提交一個乾淨的 checkpoint。後續所有工作都從這個 checkpoint 開始。-**熱啟動策略**:不要從空目錄開始。用一個專案範本(create-react-app、fastapi-template 等)預置好標準的目錄結構、依賴配置和測試框架。把通用的初始化步驟預置到範本裡,只留下專案特有的初始化工作。在已有通用基礎設施的基礎上開工,效率遠高於從空白目錄起步。+**熱啟動策略**:不要從空目錄開始。用一個專案範本(create-react-app、fastapi-template 等)預置好標準的目錄結構、依賴配置和測試框架。把通用的初始化步驟預置到範本裡,只留下專案特有的初始化工作。**初始化的完成條件**:自舉契約的四個條件都滿足了,能啟動、能測試、能看進度、能接手下一步。用這個檢查清單驗收初始化:@@ -128,17 +128,17 @@ OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記**混合方式(邊打地基邊砌牆)**:agent 在第一個工作階段中同時做了專案腳手架建立和首個功能實作。工作階段結束時,儲存庫有可執行的程式碼,但沒有顯式的啟動/測試命令文件、沒有進度跟蹤檔案、沒有任務分解。第二個工作階段花了約 20 分鐘重新推斷專案結構、測試框架和建構流程,耗費大量時間。-**獨立初始化(先打地基)**:第一個工作階段只做初始化,用專案範本建立目錄結構、配置測試框架(Vitest + React Testing Library)、寫一個示例測試並驗證通過、建立自舉契約文件和任務分解檔案、提交初始檢查點。第二個工作階段的重建時間不到 3 分鐘,直接從任務列表開始工作,施工隊來了,看了一眼施工圖就知道從哪裡接著幹。+**獨立初始化(獨立第一階段)**:第一個工作階段只做初始化,用專案範本建立目錄結構、配置測試框架(Vitest + React Testing Library)、寫一個示例測試並驗證通過、建立自舉契約文件和任務分解檔案、提交初始檢查點。第二個工作階段的重建時間不到 3 分鐘,直接從任務列表開始工作。-整個專案週期對比:混合方式的總重建時間(跨所有工作階段)比獨立初始化多約 60%。獨立初始化多花的那 20 分鐘在後續工作階段中被成倍收回。前期投入的時間在後續工作階段中被成倍收回,慢即是快。+整個專案週期對比:混合方式的總重建時間(跨所有工作階段)比獨立初始化多約 60%。獨立初始化多花的那 20 分鐘在後續工作階段中被成倍收回。## 關鍵要點-- 初始化和實作的最佳化目標不同,混在一起只會互相拖後腿。先打地基,再砌牆。+- 初始化和實作的最佳化目標不同,混在一起只會互相拖後腿。- 初始化的產出不是程式碼,是基礎設施:可執行的環境、可驗證的測試、自舉契約、任務分解。- 用「自舉契約」的四個條件驗收初始化:能啟動、能測試、能看進度、能接手下一步。- 熱啟動優於冷啟動。用專案範本預置標準化的基礎設施。-- 初始化投入的時間會在後續 3-4 個工作階段中完全收回。這不是額外的成本,是前期投資,初始化越紮實,後續工作效率越高。+- 初始化投入的時間會在後續 3-4 個工作階段中完全收回。## 延伸閱讀diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.mdindex 55ee28c..fa2b939 100644--- a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md@@ -1,14 +1,14 @@-# 範圍範例+# 範圍表面範例任務:- 為 Electron 知識庫應用程式新增索引功能-不良的範圍定義:+不良的範圍形狀:- 「實作索引功能」-較好的範圍定義:+較好的範圍形狀:- 解析已匯入的文件- 將文件分割為區塊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 190f38b..6fd05e1 100644--- a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md@@ -7,13 +7,13 @@你讓 Claude Code「給這個專案加上使用者認證功能」,結果它同時開始改資料庫 schema、寫路由、改前端元件、還順手重構了錯誤處理中介軟體。兩個小時後你一看——12 個檔案被修改,800 行新程式碼,但沒有一個功能是端到端跑通的。-貪多嚼不爛,這句話放到 AI agent 身上格外貼切。Agent 天生就有「多做一點」的衝動,看到相關的事情就順手一起做了,和那種在超市本來只打算買瓶醬油、結果推著滿滿一車出來的人一個德行。問題是,人類買了太多東西最多浪費錢,agent 同時做太多事情則是每一件都做不好。+Agent 天生就有「多做一點」的衝動,看到相關的事情就順手一起做了。問題是,同時做太多事情,幾乎保證每一件都做不好。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 的真實行為很說明問題。你讓它「新增使用者註冊功能」,它很可能這樣做:@@ -24,7 +24,7 @@ Claude Code 的真實行為很說明問題。你讓它「新增使用者註冊5. 注意到錯誤處理不統一,於是重構全局錯誤中介軟體6. 看到測試檔案結構雜亂,於是重組目錄結構-6 步之後,每一個都是半成品。沒有端到端驗證,程式碼之間耦合複雜,下一個工作階段來接手時會一臉懵。就像一個人同時炒六道菜,每道菜都下了鍋但沒有一道出鍋,全糊了。+6 步之後,每一個都是半成品。沒有端到端驗證,程式碼之間耦合複雜,下一個工作階段來接手時將完全無從下手。Anthropic 的實驗資料直接支援這一點:使用「小下一步」策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的程式碼行數和實際完成的功能數量呈弱負相關,寫得越多,完成得越少。貪多嚼不爛,資料為證。@@ -54,18 +54,18 @@ flowchart TB- **過度延伸(Overreach)**:agent 在一次工作階段中啟動的任務數量超過最優值。它可以量化——同時做 5 個功能但 0 個跑通,就是 overreach。- **不足完成(Under-finish)**:已啟動的任務中,通過端到端驗證的比例低於閾值。寫了程式碼但沒跑通測試,就是 under-finish。-- **WIP 限制(Work-in-Progress Limit)**:來自 Kanban 方法論。核心思想:限制同時在進行的任務數量。對於 agent,WIP=1 是最安全的預設值,做完一個再做下一個。就像自助餐廳不要一次拿太多盤子,吃完一盤再去拿下一盤。+- **WIP 限制(Work-in-Progress Limit)**:來自 Kanban 方法論。核心思想:限制同時在進行的任務數量。對於 agent,WIP=1 是最安全的預設值,做完一個再做下一個。- **完成證據(Completion Evidence)**:一個任務從「進行中」變成「已完成」必須滿足的可驗證條件。沒有這個,agent 會用「程式碼看起來沒問題」代替「行為通過測試」。- **範圍表面(Scope Surface)**:一個 DAG 結構,每個節點是一個工作單元,邊是依賴關係。狀態只有四種:未開始、進行中、阻塞、已通過。- **完成壓力(Completion Pressure)**:harness 通過 WIP 限制和完成證據要求共同產生的約束力,迫使 agent 先完成目前任務再開始新任務。-## Overreach 和 Under-finish 是一對難兄難弟+## Overreach 與 Under-finish 相互放大這兩個問題互相加劇。overreach 導致注意力分散,注意力分散導致 under-finish,under-finish 留下的半成品程式碼又增加了系統複雜度,進一步導致下一個任務的 overreach。惡性循環。用 Kanban 的語言說:Little 法則告訴我們 L = lambda * W。如果在製品數量 L 過大(同時做太多事),每個任務的前置時間 W 必然增加。對於 agent 來說,這意味著每個功能從開始到驗證通過的時間被拉長,失敗概率被放大。-這在人類世界也是老問題了。Steve McConnell 在《Rapid Development》中記錄,範圍蔓延是專案失敗的首要原因。但人類至少有「我已經做得夠多了」的直覺,agent 完全沒有。生成下一個想法的成本對模型來說太低了,寫一行「順便把這個也改了」幾乎不消耗額外 token,但每個額外的修改都會稀釋 agent 的注意力。就像在自助餐廳裡,每多拿一個盤子的邊際成本幾乎為零,但你的胃只有那麼大。+這在人類世界也是老問題了。Steve McConnell 在《Rapid Development》中記錄,範圍蔓延是專案失敗的首要原因。但人類至少有「我已經做得夠多了」的直覺,agent 完全沒有。生成下一個想法的成本對模型來說太低了,寫一行「順便把這個也改了」幾乎不消耗額外 token,但每個額外的修改都會稀釋 agent 的注意力。## 怎麼做才對@@ -80,8 +80,6 @@ flowchart TB- 不要在實作功能 A 時「順便」重構功能 B```-就像吃自助餐,一次只拿一盤,吃完再去拿。-### 2. 給每個任務定義顯式的完成證據完成的標準是「行為驗證通過了」,不是「程式碼寫完了」。在你的功能列表裡,每個條目都要有驗證命令:@@ -104,15 +102,15 @@ harness 應該持續跟蹤 VCR(Verified Completion Rate)= 已通過驗證的一個 8 個功能項的 REST API 專案,兩種策略對比:-**自助餐模式(無約束)**:agent 在第一個工作階段同時啟動 5 個功能。產出約 800 行程式碼,涉及 12 個檔案。端到端測試通過率只有 20%,只有使用者註冊跑通了。其餘 4 個功能:資料庫 schema 建了但缺驗證邏輯,路由定義了但返回格式錯誤。就像一個人同時炒六道菜,只有一道勉強能吃。到第 3 個工作階段結束,8 個功能只完成 3 個。+**無約束模式**:agent 在第一個工作階段同時啟動 5 個功能。產出約 800 行程式碼,涉及 12 個檔案。端到端測試通過率只有 20%,只有使用者註冊跑通了。其餘 4 個功能:資料庫 schema 建了但缺驗證邏輯,路由定義了但返回格式錯誤。到第 3 個工作階段結束,8 個功能只完成 3 個。-**單盤模式(WIP=1)**:agent 在第一個工作階段只做使用者註冊。產出約 200 行程式碼,涉及 4 個檔案。端到端測試 100% 通過。提交乾淨的、已驗證的實現。到第 4 個工作階段結束,8 個功能完成 7 個(第 8 個因外部依賴被阻塞)。+**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 的預設安全設置**,做完一個再做下一個,不要試圖並行。一口吃不成胖子。+- **WIP=1 是 agent harness 的預設安全設置**,做完一個再做下一個,不要試圖並行。- **完成證據必須是可執行的**,「程式碼看起來沒問題」不算完成,「curl 返回 201」才算。- **範圍表面必須外部化為檔案**,不能只在對話裡說,必須在儲存庫裡有機器可讀的記錄。- **overreach 和 under-finish 是共生問題**,解決一個就解決了另一個。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 a47414e..369ec26 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@@ -7,7 +7,7 @@你讓 agent 做一個電商網站,跑完之後它告訴你「做完了」。你打開程式碼一看——使用者認證有了,但購物車的結算按鈕點了沒反應,支付流程根本沒接上。問題是:你從來沒告訴它「做完」的標準是什麼,所以它用自己的標準,「程式碼寫了不少,看起來挺完整」。-功能清單(feature list)在很多人眼裡就是個備忘錄,寫下來怕忘了,寫完扔在一邊。但在 harness 的世界裡,功能清單是整個 harness 的脊樑骨,不只是一份給人看的備忘錄。調度器靠它選任務,驗證器靠它判完成,交接器靠它生成報告。脊樑骨斷了,全身都癱。+功能清單(feature list)在很多人眼裡就是個備忘錄,寫下來怕忘了,寫完扔在一邊。但在 harness 的世界裡,功能清單是整個 harness 的基礎結構,不只是一份給人看的備忘錄。調度器靠它選任務,驗證器靠它判完成,交接器靠它生成報告。缺少它,這些元件就沒有共同的共識可以依賴。Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須是儲存庫裡機器可讀的檔案,不能是對話裡的非結構化描述。@@ -15,7 +15,7 @@ Anthropic 和 OpenAI 都強調:**工件必須外部化**。功能狀態必須Claude Code 和 Codex 都不會自動知道你心目中的「做完」是什麼意思。你說「加一個購物車功能」,模型的理解可能是「寫一個 Cart 元件和 addToCart 方法」。而你的意思是「使用者能從瀏覽商品到下單支付完整走通」。-這個理解鴻溝在沒有功能清單的情況下會持續存在。agent 用自己的隱式標準判斷完成,通常是「程式碼沒有明顯的語法錯誤」。而你需要的是端到端的行為驗證。就像你讓朋友幫你買菜,說「買點水果」,他拎了一袋檸檬回來,他要的水果,你要的水果,不是一個水果。+這個理解鴻溝在沒有功能清單的情況下會持續存在。agent 用自己的隱式標準判斷完成,通常是「程式碼沒有明顯的語法錯誤」。而你需要的是端到端的行為驗證。看看這種常見的進度記錄:@@ -23,7 +23,7 @@ Claude Code 和 Codex 都不會自動知道你心目中的「做完」是什麼做了使用者認證、購物車基本完成了、還需要做支付```-新的 agent 工作階段看到這個記錄,能回答以下問題嗎?「基本完成」意味著什麼?購物車通過了哪些測試?支付的阻塞條件是什麼?答案都是「不知道」。就像你看病時跟醫生說「我肚子疼,最近還行」,醫生能開出什麼藥來?+新的 agent 工作階段看到這個記錄,能回答以下問題嗎?「基本完成」意味著什麼?購物車通過了哪些測試?支付的阻塞條件是什麼?答案都是「不知道」。結果是:新工作階段花 20 分鐘推斷專案狀態,最終可能重複實現已完成的功能。Anthropic 的工程實踐資料表明,好的進度記錄可以減少 60-80% 的工作階段啟動診斷時間。@@ -54,10 +54,10 @@ flowchart LR## 核心概念-- **功能清單是 harness 原語**:它是其他所有 harness 元件依賴的基礎資料結構,不是「可選的規劃工具」。就像資料庫裡的表結構,你不能說「要不我們省掉主索引鍵吧」,省掉了整個系統就解體了。+- **功能清單是 harness 原語**:它是其他所有 harness 元件依賴的基礎資料結構,不是「可選的規劃工具」。- **三元組結構**:每個功能項是 `(行為描述, 驗證命令, 目前狀態)` 的三元組。缺了任何一項,這個功能項就不完整。行為描述告訴 agent 做什麼,驗證命令告訴它怎麼算做完,狀態告訴它現在到哪了。- **狀態機模型**:每個功能項有四種狀態——`not_started`、`active`、`blocked`、`passing`。狀態轉移由 harness 控制,不是 agent 想改就能改。-- **通過狀態門控**:功能從 `active` 變成 `passing` 的唯一方式是驗證命令執行成功。這是不可逆的,`passing` 了就不能退回去。就像考試及格了就是及格了,不能事後改分數。+- **通過狀態門控**:功能從 `active` 變成 `passing` 的唯一方式是驗證命令執行成功。這是不可逆的,`passing` 了就不能退回去。- **單一權威來源**:專案裡關於「該做什麼」的所有資訊,必須從一個功能清單派生。不能出現功能清單和對話記錄矛盾的情況。- **反向壓力**:還沒通過的功能項數量就是 harness 對 agent 施加的壓力。壓力歸零 = 專案完成。@@ -69,10 +69,10 @@ flowchart LR具體來說,功能清單服務四個 harness 元件:-1. **調度器**:讀狀態,選下一個 `not_started` 的功能。就像工廠的排產系統,看完訂單才知道下一步做什麼。-2. **驗證器**:執行驗證命令,判斷是否允許狀態轉移。就像質檢,不是你說合格就合格,得通過檢驗。-3. **交接報告器**:從功能清單自動生成工作階段交接摘要。就像換班時自動生成的交接表,不用手寫,系統自己出。-4. **進度追蹤器**:統計各狀態分佈,提供專案健康度指標。就像儀表盤,一眼看出專案走到哪了。+1. **調度器**:讀狀態,選下一個 `not_started` 的功能。+2. **驗證器**:執行驗證命令,判斷是否允許狀態轉移。+3. **交接報告器**:從功能清單自動生成工作階段交接摘要。+4. **進度追蹤器**:統計各狀態分佈,提供專案健康度指標。## 怎麼做@@ -106,22 +106,22 @@ agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harn### 4. 粒度校準-每個功能項應該是「一次工作階段能完成」的範圍。太粗了做不完,太細了管理開銷大。「使用者可以新增商品到購物車」是一個好粒度,「實現購物車」太粗了,「建立 Cart 模型的 name 欄位」太細了。就像切牛排,不能整塊啃,也不能切成肉末。+每個功能項應該是「一次工作階段能完成」的範圍。太粗了做不完,太細了管理開銷大。「使用者可以新增商品到購物車」是一個好粒度,「實現購物車」太粗了,「建立 Cart 模型的 name 欄位」太細了。## 實際案例一個電商平台的開發任務,10 個功能項。對比兩種追蹤方式:-**備忘錄模式**:agent 用非結構化筆記記錄進度。3 個工作階段後,筆記變成了「做了使用者認證和商品列表、購物車基本完成但還有 bug、支付沒開始」。新工作階段需要 20 分鐘推斷狀態,最終重複實現了已完成的功能。就像你的購物清單上寫著「牛奶、麵包、還有那個什麼來著」,到超市了你還是不知道要買什麼。+**備忘錄模式**:agent 用非結構化筆記記錄進度。3 個工作階段後,筆記變成了「做了使用者認證和商品列表、購物車基本完成但還有 bug、支付沒開始」。新工作階段需要 20 分鐘推斷狀態,最終重複實現了已完成的功能。-**脊樑骨模式**:每個功能項有明確的狀態和驗證命令。新工作階段讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。+**結構化模式**:每個功能項有明確的狀態和驗證命令。新工作階段讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。定量結果:使用結構化功能清單的專案,功能完成率比自由形式高 45%,零重複實現。## 關鍵要點-- **功能清單是 harness 的脊樑骨**,不是給人看的備忘錄。調度器、驗證器、交接器都依賴它。-- **每個功能項必須有三元組**:行為描述 + 驗證命令 + 目前狀態。缺一項就不完整,就像三條腿的凳子少一條腿。+- **功能清單是 harness 的基礎結構**,不是給人看的備忘錄。調度器、驗證器、交接器都依賴它。+- **每個功能項必須有三元組**:行為描述 + 驗證命令 + 目前狀態。缺一項就不完整。- **狀態轉移由 harness 控制**,agent 不能自己改狀態。通過驗證 = 唯一的升級路徑。- **功能清單是專案的單一權威來源**,任何關於「該做什麼」的資訊都從這裡派生。- **粒度控制在「一次工作階段能完成」的範圍**。太粗做不完,太細管不過來。diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.mdindex 5ad15b9..7a9e4a0 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@@ -7,13 +7,11 @@你讓 agent 實現「密碼重置」功能。它改了資料庫 schema、寫了 API 端點、加了郵件範本,跑了單元測試(全部通過),然後自信地告訴你「做完了」。你實際一跑,密碼重置連結發不出去(郵件服務配置缺失)、資料庫遷移半途失敗(schema 不一致)、端到端流程根本沒走過一遍。-這種感覺你一定不陌生,考試時把卷子寫得滿滿當當,信心滿滿地第一個交卷,結果成績出來不及格。卷子寫滿了,不代表做對了。-這不是偶然事件。Guo 等人 2017 年在 ICML 上的經典論文證明:**現代神經網路一致性地過度自信**——模型自報的置信度顯著高於實際準確率。AI 程式碼代理也一樣,它「覺得」做完了,但實際上差得遠。你的 harness 必須用外部化的、基於執行的驗證來替代 agent 的「感覺」。## 滑坡效應-過早完成聲明幾乎總是一樣的手法,程式碼看著還行,語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際執行或只跑了部分測試。跑了單元測試但跳過整合測試,跑了測試但沒檢查覆蓋率。最後「程式碼看起來沒問題」就被當作了「功能已完成」的證據。交卷了。+過早完成聲明幾乎總是一樣的手法,程式碼看著還行,語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際執行或只跑了部分測試。跑了單元測試但跳過整合測試,跑了測試但沒檢查覆蓋率。最後「程式碼看起來沒問題」就被當作了「功能已完成」的證據。每一步都在遺失資訊。從任務規範到程式碼實現到執行時期行為,每次轉換都可能引入偏差,而每次跳過的驗證都加劇了資訊不對稱。@@ -76,7 +74,7 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**> 來源:[Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)-## 怎麼防止提前交卷+## 如何防止過早完成聲明### 1. 外部化終止判定@@ -99,9 +97,9 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**- **第二層:執行時期行為驗證**。測試執行、應用啟動檢查、關鍵路徑驗證。這是核心完成證據。不僅要寫了,還要能跑。- **第三層:系統級確認**。端到端測試、整合驗證、使用者場景模擬。防止過早聲明的最後一道防線。不僅要能跑,還要跑對。-### 3. 為 agent 設計好的「紅筆批註」+### 3. 為 agent 提供可執行的錯誤回饋-OpenAI 在 Codex 實踐中提出了一個特別有效的模式,**給 agent 寫的錯誤訊息要包含修復指導**。不要像閱卷老師只畫個大紅叉,要像好老師一樣在旁邊寫上「這裡應該怎麼改」。不要用 `「Test failed」`,而用 `「Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html.」` 這種具體的、可操作的回饋讓 agent 能自我修正,而不需要人類介入。+OpenAI 在 Codex 實踐中提出了一個特別有效的模式,**給 agent 寫的錯誤訊息要包含修復指導**。不要用 `「Test failed」`,而用 `「Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html.」` 這種具體的、可操作的回饋讓 agent 能自我修正,而不需要人類介入。### 4. 捕獲執行時期信號@@ -115,18 +113,18 @@ OpenAI 在 Codex 實踐中提出了一個特別有效的模式,**給 agent 寫**任務**,實現使用者密碼重置功能。涉及資料庫操作、郵件發送和 API 端點修改。-**提前交卷路徑**,agent 修改資料庫 schema、編寫 API 端點、新增郵件範本、跑單元測試(通過)、聲明完成。卷子寫得滿滿當當。+**提前聲明完成路徑**,agent 修改資料庫 schema、編寫 API 端點、新增郵件範本、跑單元測試(通過)、聲明完成。核心步驟全部跳過了。**實際扣分項**,(1) 端到端流程未測試,重置連結的實際發送和驗證未確認。(2) 資料庫遷移在部分執行後失敗,導致 schema 不一致。(3) 郵件服務配置在目標環境中缺失。-**harness 介入**,終止校驗強制執行,(1) 啟動完整應用驗證重置端點可訪問;(2) 執行完整重置流程;(3) 驗證資料庫狀態一致性。所有缺陷在工作階段內被發現,節省了 5-10 倍的後續修復成本。獨立閱卷老師批出了真正的問題。+**harness 介入**,終止校驗強制執行,(1) 啟動完整應用驗證重置端點可訪問;(2) 執行完整重置流程;(3) 驗證資料庫狀態一致性。所有缺陷在工作階段內被發現,節省了 5-10 倍的後續修復成本。## 關鍵要點-- **agent 普遍過度自信**,置信度校準偏差是客觀存在的。卷子寫滿了不代表做對了。-- **完成判定必須外部化**——harness 獨立驗證,不信任 agent 的「感覺」。不能讓學生自己批自己的卷子。+- **agent 普遍過度自信**,置信度校準偏差是客觀存在的。+- **完成判定必須外部化**——harness 獨立驗證,不信任 agent 的「感覺」。- **三層校驗缺一不可**,語法通過、行為通過、系統通過,層層遞進。-- **錯誤訊息要像好老師的紅筆批注**,包含具體修復步驟,讓 agent 能自我修正。+- **錯誤訊息要包含具體修復步驟**,讓 agent 能自我修正。- **核心功能驗證通過之前不許重構**,完成優先級約束是防止過早最佳化的關鍵。## 延伸閱讀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 a29f4f3..c2a0d0b 100644--- a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md@@ -7,29 +7,29 @@你讓 agent 給 Electron 應用加一個檔案匯出功能。它寫了渲染程式元件、預載腳本、服務層邏輯,每個元件的單元測試都通過了。agent 說「做完了」。你實際一點擊匯出按鈕,檔案路徑格式不對、進度列沒反應、大檔案匯出時記憶體洩漏。5 個元件邊界缺陷,單元測試一個都沒發現。-這就像一個合唱團排練——每個聲部單獨唱的時候都完美,但合在一起的時候,女高音比男低音快了半拍,伴奏的調子和主旋律差了半個音。每個部分都「對」了,但整體跑調了。+每個部分各自「正確」,但真正串連起來後,問題才會浮現。Google 的測試金字塔告訴我們:大量單元測試是基礎,但如果你止步於此,就會持續漏掉元件互動問題。對於 AI 程式碼代理來說,這個問題更嚴重,agent 傾向於只跑最快的測試然後宣告完成。**只有端到端測試能證明系統級缺陷不存在**。## 單元測試的盲區-單元測試的設計哲學是隔離,模擬依賴,專注被測單元。這個哲學使單元測試快速且精確,但也製造了系統性的盲區。就像合唱排練時每個聲部戴著耳機對著伴奏唱,聽著都挺好,但真正合在一起才發現問題:+單元測試的設計哲學是隔離,模擬依賴,專注被測單元。這個哲學使單元測試快速且精確,但也製造了系統性的盲區:-**介面不相符**:渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題,就像兩個聲部各自練的時候都覺得節奏沒問題,一合才發現一個用 4/4 拍一個用 3/4 拍。+**介面不相符**:渲染程式傳給預載腳本的檔案路徑是相對路徑,但預載腳本期望絕對路徑。各自的單元測試都用了 mock,都通過了。只有端到端跑通時才發現問題。-**狀態傳播錯誤**:資料庫遷移改了表結構,但 ORM 的快取層還持有舊結構的快取條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。就像換了一首歌的歌詞,但有人還在唱舊版本。+**狀態傳播錯誤**:資料庫遷移改了表結構,但 ORM 的快取層還持有舊結構的快取條目。單元測試每次都是全新的 mock 環境,不會暴露這種跨層狀態不一致。-**資源生命週期問題**:檔案描述符、資料庫連線、網路通訊端的獲取和釋放跨越多個元件。單元測試為每個測試建立和銷毀獨立資源,不會暴露資源競爭或洩漏。就像排練時每個聲部輪流用麥克風,但演出時所有聲部同時上台,麥克風不夠用了。+**資源生命週期問題**:檔案描述符、資料庫連線、網路通訊端的獲取和釋放跨越多個元件。單元測試為每個測試建立和銷毀獨立資源,不會暴露資源競爭或洩漏。-**環境依賴性**:程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。就像排練廳裡唱得好好的,到了戶外音樂節風一吹麥克風一嘯叫就全亂了。+**環境依賴性**:程式碼在測試環境(一切 mock)行為正確,在真實環境因配置差異、網路延遲、服務不可用而失敗。## 端到端測試不僅改變結果,還改變行為這是很多人沒意識到的一點:當 agent 知道它的工作要過端到端測試時,它的編碼行為會改變。-1. **考慮元件互動**:寫程式碼時會想「這個介面和上游怎麼對接」,而不是只關注單個函式。就像知道最終要合在一起唱,練習的時候就會注意聽其他聲部。-2. **尊重架構邊界**:有架構約束的系統裡,端到端測試迫使 agent 遵守邊界規則。就像樂譜上標注了「此處漸強」,你得跟著來。-3. **處理錯誤路徑**:端到端測試通常包含故障場景,迫使 agent 考慮例外處理。就像排練時模擬了「麥克風突然沒聲了」的情況,你知道該怎麼做。+1. **考慮元件互動**:寫程式碼時會想「這個介面和上游怎麼對接」,而不是只關注單個函式。+2. **尊重架構邊界**:有架構約束的系統裡,端到端測試迫使 agent 遵守邊界規則。+3. **處理錯誤路徑**:端到端測試通常包含故障場景,迫使 agent 考慮例外處理。## 測試金字塔與審查回饋提升@@ -57,27 +57,27 @@ flowchart LRHarness --> Stronger["以後再犯會第一時間報錯"]```-OpenAI 在 Codex 工程實踐中強調:**為 agent 寫的錯誤訊息必須包含修復指導**。不寫 `「Direct filesystem access in renderer」`,而寫 `「Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api.」` 這把架構規則變成了自動修正的閉環。就像合唱排練時指揮不只說「你唱錯了」,而是說「這裡你快了半拍,聽一下女低音的節奏,在第 32 小節進入」。+OpenAI 在 Codex 工程實踐中強調:**為 agent 寫的錯誤訊息必須包含修復指導**。不寫 `「Direct filesystem access in renderer」`,而寫 `「Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api.」` 這把架構規則變成了自動修正的閉環。## 核心概念-- **元件邊界缺陷**:元件 A 和 B 各自單元測試通過,但它們的互動產生了不正確的行為。這是端到端測試最擅長捕獲的問題類型,合唱裡各聲部單獨都對但合起來跑調的那種。+- **元件邊界缺陷**:元件 A 和 B 各自單元測試通過,但它們的互動產生了不正確的行為。這是端到端測試最擅長捕獲的問題類型。- **測試充分性梯度**:單元測試能檢測的缺陷 <= 整合測試能檢測的缺陷 <= 端到端測試能檢測的缺陷。每往上一層,檢測能力增強。- **架構邊界執行規則**:把架構文件裡的規則(如「渲染程式不能直接存取檔案系統」)變成可執行的自動化檢查。從「寫在紙上」變成「跑在 CI 裡」。-- **審查回饋提升**:把重複出現的程式碼審查意見轉化為自動化測試。每次發現重複問題就加一條規則,harness 會自動變強。就像合唱排練時指揮把常見的錯誤編成練習曲,下次再犯同樣的錯誤,不用指揮說,練習曲自己就暴露了。+- **審查回饋提升**:把重複出現的程式碼審查意見轉化為自動化測試。每次發現重複問題就加一條規則,harness 會自動變強。- **面向 agent 的錯誤訊息**:失敗資訊不只是說「出了什麼問題」,還要告訴 agent 具體怎麼修。這把測試失敗變成自我修正的回饋循環。## 怎麼做### 0. 先定好架構邊界,再寫端到端測試-端到端測試的前提是系統有明確的邊界。如果架構是一團麵條,端到端測試只會證明「這團麵條整體能跑」,不會告訴你哪裡違反了設計意圖。就像合唱團如果連分聲部都沒分好,排練再多也是亂唱。+端到端測試的前提是系統有明確的邊界。如果架構本身缺乏清楚邊界,端到端測試只能驗證整體能執行,無法指出哪裡違反了設計意圖。-OpenAI 的經驗:**對 agent 生成的程式碼庫,架構約束必須是第一天就建立的早期前置條件,不是等團隊規模大了再考慮的事。** 原因很直接,agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。沒有架構約束,agent 會在每次工作階段中引入更多偏差。+OpenAI 的工程實踐表明,**對 agent 生成的程式碼庫,架構約束必須是第一天就建立的早期前置條件,不是等團隊規模大了再考慮的事。** 原因很直接,agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。沒有架構約束,agent 會在每次工作階段中引入更多偏差。OpenAI 採用了「分層領域架構」,每個業務領域被分成固定的層:Types → Config → Repo → Service → Runtime → UI。依賴方向嚴格向前,跨領域關注點通過顯式的 Providers 介面進入。任何其他依賴都是禁止的,並且通過自訂 lint 機械執行。-關鍵原則:**執行不變數,不微管實現。** 比如要求「資料在邊界解析」,但不規定用哪個程式庫。錯誤訊息要包含修復指導,不只是說「違規了」,還要告訴 agent 具體怎麼改。+關鍵原則是**執行不變數,不微管實現**。比如要求「資料在邊界解析」,但不規定用哪個程式庫。錯誤訊息要包含修復指導,不只是說「違規了」,還要告訴 agent 具體怎麼改。> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)@@ -114,15 +114,15 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea### 4. 建立審查回饋提升流程-每次在程式碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。就像合唱團的排練筆記,每次排練發現的問題都記下來,下次排練前先檢查這些點。久而久之,常見錯誤越來越少,音樂越來越和諧。+每次在程式碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。## 實際案例**任務**:在 Electron 應用中實現檔案匯出功能。涉及渲染程式 UI、預載腳本檔案系統代理、服務層資料轉換。-**各聲部單獨唱(單元測試通過)**:渲染元件測試(通過,mock 檔案操作)、預載腳本測試(通過,mock 檔案系統)、服務層測試(通過,mock 資料來源)。agent 聲明完成。+**單元測試階段**:渲染元件測試(通過,mock 檔案操作)、預載腳本測試(通過,mock 檔案系統)、服務層測試(通過,mock 資料來源)。agent 聲明完成。-**合唱合在一起(端到端測試揭示的缺陷)**:+**端到端測試揭示的缺陷**:| 缺陷 | 描述 | 單元測試 | 端到端 ||------|------|---------|--------|@@ -132,11 +132,11 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea| 權限問題 | 打包環境權限不同 | 未檢測 | 檢測 || 錯誤傳播 | 服務層例外未到 UI 層 | 未檢測 | 檢測 |-5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。代價是測試時間從 2 秒增加到 15 秒,在 agent 工作流裡完全可以接受。每個聲部單獨唱得再好,也比不上一次完整的合唱排練。+5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。代價是測試時間從 2 秒增加到 15 秒,在 agent 工作流裡完全可以接受。## 關鍵要點-- **單元測試對元件邊界缺陷系統性盲視**,它們的隔離設計恰好使其無法檢測互動問題。每個人唱得都對,不代表合唱不跑調。+- **單元測試對元件邊界缺陷系統性盲視**,它們的隔離設計恰好使其無法檢測互動問題。- **端到端測試不僅檢測缺陷,還改變 agent 的編碼行為**——讓它更關注整合和邊界。- **架構規則必須可執行**,要每次提交自動檢查,不應只寫在文件裡等人查看。- **錯誤訊息要面向 agent 設計**,包含「怎麼修」的具體步驟,形成自我修正閉環。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 bc4f3a0..8ebf45b 100644--- a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md@@ -7,7 +7,7 @@你讓 agent 做一個功能,它跑了 20 分鐘,改了一堆檔案,然後告訴你「做完了但有兩個測試失敗」。你問它為什麼失敗,它說「不太確定,可能是時序問題」。你問它改了哪些關鍵路徑,它說「讓我看看程式碼……」。-harness 沒有給 agent 裝上所需的儀表盤,才導致這種困境。想象你在開一輛沒有儀表盤的車,沒有速度表、沒有油量表、沒有發動機故障燈。你能開,但你不知道開多快、還剩多少油、發動機是不是快爆了。技術再好的司機,蒙著眼也得出事。+這種情況的根源不在於 agent 的能力,而在於 harness 缺少可觀測性。當 agent 在沒有執行時期狀態可見性的情況下執行任務時,它做出的每一個決策本質上都是猜測。**沒有可觀測性,agent 在不確定狀態中做決策,評估變成主觀判斷,重試變成盲目摸索。** OpenAI 和 Anthropic 都將可靠性定義為證據問題,harness 必須以可指導下一步決策的形式暴露執行時期行為和評估訊號。@@ -27,11 +27,11 @@ harness 沒有給 agent 裝上所需的儀表盤,才導致這種困境。想想象一個使用「計劃者-生成者-評估者」三角色工作流的 harness,執行「為應用添加暗色模式」任務。-**沒有儀表盤**,計劃者輸出模糊描述。生成者根據模糊描述實現暗色模式,但和計劃者的隱式預期不一致。評估者基於自己的隱式標準拒絕,但說不出具體哪裡不對,「感覺不太對」。生成者基於模糊拒絕理由盲重試。循環 3-4 次,總耗時約 45 分鐘,最終勉強產出。+**缺乏可觀測性**,計劃者輸出模糊描述。生成者根據模糊描述實現暗色模式,但和計劃者的隱式預期不一致。評估者基於自己的隱式標準拒絕,但說不出具體哪裡不對,「感覺不太對」。生成者基於模糊拒絕理由盲重試。循環 3-4 次,總耗時約 45 分鐘,最終勉強產出。-**有完整儀表盤**,計劃者輸出衝刺合約,列明要改哪些元件、每個元件的驗證標準、排除項(不處理列印樣式)。生成者按合約實現。執行時期可觀測性記錄每個元件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用,「按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)」。一次迭代出高品質結果,總耗時約 15 分鐘。+**具備完整可觀測性**,計劃者輸出衝刺合約,列明要改哪些元件、每個元件的驗證標準、排除項(不處理列印樣式)。生成者按合約實現。執行時期可觀測性記錄每個元件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用,「按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)」。一次迭代出高品質結果,總耗時約 15 分鐘。-效率差 3 倍。區別只在可觀測性,給車裝上了儀表盤。+效率差 3 倍。區別只在可觀測性。## 雙層可觀測性@@ -47,9 +47,9 @@ flowchart LRVerdict --> Generator```-**執行時期可觀測性**,系統層的訊號——日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。這是你車上的儀表盤,速度、油量、發動機溫度。+**執行時期可觀測性**,系統層的訊號——日誌、追蹤、程式事件、健康檢查。回答「系統做了什麼」。-**過程可觀測性**,harness 決策工件的可見性,計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。這是你的導航系統,不光知道現在在哪,還知道為什麼走這條路。+**過程可觀測性**,harness 決策工件的可見性,計劃、評分標準、驗收條件。回答「為什麼這個變更應該被接受」。## 核心概念@@ -68,7 +68,7 @@ flowchart LR2. **日誌格式不統一**,不同工作階段用不同的日誌格式,無法做系統化分析。格式各異的日誌無法在工作階段間做系統化比對分析。3. **過程可觀測性不是日誌能解決的**,衝刺合約和評分標準是結構化的工件,需要 harness 層面的支援。不是多 print 幾行就能搞定的。-## 怎麼裝儀表盤+## 如何建立可觀測性### 1. 在 harness 裡內置執行時期信號採集@@ -151,10 +151,10 @@ Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題## 關鍵要點-- **可觀測性是 harness 的架構屬性**,是設計時必須考慮的核心能力。儀表盤不是可選配件,是出廠標配。-- **雙層可觀測性缺一不可**,執行時期訊號解釋「發生了什麼」,過程工件解釋「為什麼這樣做」。速度表和導航系統各有各的用處。+- **可觀測性是 harness 的架構屬性**,是設計時必須考慮的核心能力。+- **雙層可觀測性缺一不可**,執行時期訊號解釋「發生了什麼」,過程工件解釋「為什麼這樣做」。- **衝刺合約前置對齊工作**,防止「生成者做了評估者因可預見原因立即拒絕的東西」。施工協定要在開工前簽,不是完工後補。-- **評分標準讓評估可復現**,不同評估者對同一輸出產生相似評分。有了評分標準,十個裁判的分才不會差太遠。+- **評分標準讓評估可復現**,不同評估者對同一輸出產生相似評分。- **可觀測性缺失導致 30-50% 的工作階段時間浪費在重複診斷上**。## 延伸閱讀diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.mdindex 583cd94..1aa7925 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@@ -13,7 +13,7 @@ OpenAI 和 Anthropic 都明確指出:**長期可靠性取決於操作紀律,## 熵增是預設狀態-Lehman 的軟體演化定律表明,持續變更的系統,除非主動管理,否則複雜性必然增加。這對 AI 程式碼代理尤其成立,agent 每次工作階段都會引入變更,如果不在退出時清理,技術債務會指數級累積。宿舍不打掃,髒衣服和外賣盒只會越堆越多,不會自己消失。+Lehman 的軟體演化定律表明,持續變更的系統,除非主動管理,否則複雜性必然增加。這對 AI 程式碼代理尤其成立,agent 每次工作階段都會引入變更,如果不在退出時清理,技術債務會指數級累積。OpenAI 在 5 個月的 Codex 實驗中觀察到,**agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。** 隨著時間的推移,這種複製必然導致漂移。初始的模式不均勻性在反覆複製後會逐漸放大,最終導致程式碼庫明顯漂移。@@ -27,7 +27,7 @@ OpenAI 團隊最初花每週五(20% 的工作時間)手動清理「AI slop> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## 清潔狀態:不只看地上有沒有垃圾+## 清潔狀態:不只是「程式碼能編譯」清潔狀態不是單一的「程式碼能編譯」。程式碼能無錯建構——這是最基本的,下一個工作階段不應該先修建構錯誤。可建構是移交狀態的最低門檻,不可跳過。所有測試也得通過,包括工作階段之前就存在的測試,工作階段有責任不破壞已有功能。而且要在 CI 環境驗證,不是「在我機器上通過」。@@ -86,7 +86,7 @@ flowchart LR- 第 1 週:100%,100%,5 分鐘- 第 12 週:97%,95%,9 分鐘-12 週後,建構通過率差 29 個百分點,新工作階段啟動時間差 85%。以上資料源自實際觀測,有明確的可重現紀錄。每週不倒垃圾的宿舍和每週倒垃圾的宿舍,12 週後的差距是驚人的。+12 週後,建構通過率差 29 個百分點,新工作階段啟動時間差 85%。以上資料源自實際觀測,有明確的可重現紀錄。## 怎麼做@@ -168,18 +168,18 @@ npm run test # 驗證清理未破壞功能一個使用 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**,隨著模型能力提升,移除不再必要的約束。大四了就別執行大一的宿舍公約了。+- **品質文件讓程式碼庫健康可追蹤**,知道哪裡在退化才能主動修復。+- **定期簡化 harness**,隨著模型能力提升,移除不再必要的約束。- **「以後再清理」等於永遠不清理**,熵增是預設狀態,主動的清潔操作是對抗熵增的唯一途徑。## 延伸閱讀diff --git a/docs/zh-TW/projects/index.md b/docs/zh-TW/projects/index.mdindex 176990d..158b38c 100644--- a/docs/zh-TW/projects/index.md+++ b/docs/zh-TW/projects/index.md@@ -9,8 +9,8 @@1. **提示詞驅動 vs 規則驅動**:對比純提示詞驅動的代理和帶有基礎 harness 的代理在表現上的差異。2. **讓專案可讀並接住上次工作**:學習如何重構儲存庫結構,使其對 AI 更加友好,並建立工作交接機制。3. **跨工作階段工作連續性**:設計狀態檔案和初始化腳本,讓代理可以在多次對話中斷後無縫恢復工作。-4. **執行回饋與行為修正**:引入執行時期回饋機制,讓代理能夠自行檢查程式碼是否能正常執行,並修正錯誤。-5. **工作評審與自我驗證**:建立獨立的評審與驗證環節,防止代理產生「幻覺」或提前宣告完成。+4. **執行回饋與範圍控制**:引入執行時期回饋機制,讓代理能夠自行檢查程式碼是否能正常執行,並修正錯誤。+5. **自我驗證與角色分離**:建立獨立的評審與驗證環節,防止代理產生「幻覺」或提前宣告完成。6. **綜合代理工作環境**:搭建一套完整且具備可觀測性的代理工作環境(綜合演練)。## 如何進行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 d018a1a..d0900b0 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@@ -29,6 +29,10 @@- Node.js + Electron(專案技術堆疊)- 一個計時器(記錄每次執行時期間)+## Harness 機制++最小 harness:`AGENTS.md` + `init.sh` + `feature_list.json`+## 具體步驟### 準備工作diff --git a/docs/zh-TW/projects/project-02-agent-readable-workspace/index.md b/docs/zh-TW/projects/project-02-agent-readable-workspace/index.mdindex a6d72f6..2392cd1 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@@ -20,6 +20,8 @@ P01 證明了準備規則有用。但 P01 的任務一次工作階段就完成| [`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))等可接手產物。 | 只依靠儲存庫狀態,能否快速續寫而不靠口頭脈絡。 |+產品功能包含文件匯入、完整文件詳情與內容載入,以及重啟後的資料持久化。harness 功能是可供工作階段交接的可讀工作區。+## 用什麼工具- Claude Code 或 Codex(和 P01 保持一致)@@ -27,6 +29,10 @@ P01 證明了準備規則有用。但 P01 的任務一次工作階段就完成- Node.js + Electron- 文字編輯器(撰寫文件用)+## Harness 機制++可讀的代理工作區 + 持久化狀態檔案+## 具體步驟### 準備工作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 2709119..6a54a8d 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@@ -20,6 +20,8 @@ P02 解決了「銜接」的問題,但代理銜接之後能否完整且正確| [`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)。 | 是否能做到“一次只做一個功能”,且每個功能都有可執行證據才標記通過。 |+本專案不是通用的「跨工作階段」練習。檢入的解答版本對應四個具體的產品功能:文件分塊、元資料提取、索引進度 UI 顯示,以及附引用的 grounded 問答。+## 用什麼工具- Claude Code 或 Codex@@ -27,6 +29,10 @@ P02 解決了「銜接」的問題,但代理銜接之後能否完整且正確- Node.js + Electron- `feature_list.json`(範本參考 `docs/zh-TW/resources/templates/feature_list.json`)+## Harness 機制++進度日誌 + 工作階段交接 + 跨工作階段連續性 + 單次一功能驗證+## 具體步驟### 準備工作diff --git a/docs/zh-TW/projects/project-04-incremental-indexing/index.md b/docs/zh-TW/projects/project-04-incremental-indexing/index.mdindex 4214c62..714fc62 100644--- a/docs/zh-TW/projects/project-04-incremental-indexing/index.md+++ b/docs/zh-TW/projects/project-04-incremental-indexing/index.md@@ -20,6 +20,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)。 | 有日誌與邊界檢查後,修復是否更快、更可控、可復現。 |+可供檢閱的具體檔案為 [`projects/project-04/solution/src/services/logger.ts`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/src/services/logger.ts)、[`projects/project-04/solution/scripts/check-architecture.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/scripts/check-architecture.sh)、[`projects/project-04/solution/docs/ARCHITECTURE.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/docs/ARCHITECTURE.md) 和 [`projects/project-04/solution/src/services/indexing-service.ts`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/src/services/indexing-service.ts)。+## 用什麼工具- Claude Code 或 Codex@@ -28,6 +30,10 @@- 日誌庫(如 `electron-log` 或簡單的 console 封裝)- 結構化檢查工具(ESLint 自訂規則、guard 腳本、或測試)+## Harness 機制++執行時期回饋 + 範圍控制 + 漸進式索引+## 具體步驟### 準備工作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 7b682be..ab64219 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@@ -18,9 +18,11 @@| 目錄 | 內容 | 比較什麼 ||------|------|------|| [`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) 高分證據。 |+| [`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) 1.6/5 分與缺陷清單。 |+| [`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) 3.3/5 分與修訂記錄。 |+| [`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) 4.9/5 分。 |++檢入的功能為多輪問答對話歷史。在三個變體中保持此功能不變,使唯一的變數為角色分離。## 用什麼工具@@ -29,6 +31,10 @@- 評估量表(參考 `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`)+## Harness 機制++自我驗證 + 有依據的問答 + 以證據為基礎的完成判定+## 具體步驟### 準備工作diff --git a/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md b/docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.mdindex 021dadb..06faa20 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@@ -15,9 +15,11 @@| 目錄 | 內容 | 怎麼用 / 比較什麼 ||------|------|------|-| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-06/starter) | 產品功能基本完整,但 harness 表面刻意削弱(只有基礎 [`AGENTS.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/starter/AGENTS.md),沒有 `feature_list.json` / `session-handoff.md` / `clean-state-checklist.md`,也沒有 benchmark/cleanup 腳本)。 | 手動記錄弱 harness 基線行為(錯誤定位速度、是否過早宣告完成等)。 |+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-06/starter) | 產品功能基本完整,但 harness 表面刻意削弱(只有基礎 [`AGENTS.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/starter/AGENTS.md),沒有 `feature_list.json` / `session-handoff.md` / `clean-state-checklist.md`,也沒有 benchmark/cleanup 腳本)。 | 起始版本刻意不包含基準測試腳本。手動記錄弱 harness 基線行為(錯誤定位速度、是否過早宣告完成等)。 || [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-06/solution) | 最大化 harness:[`AGENTS.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/AGENTS.md)、[`CLAUDE.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/CLAUDE.md)、[`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/feature_list.json)、[`init.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/init.sh)、[`session-handoff.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/session-handoff.md)、[`clean-state-checklist.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/clean-state-checklist.md)、品質/評估文檔、benchmark 與 cleanup 腳本。 | 在 [`projects/project-06/solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-06/solution) 下跑 `./scripts/benchmark.sh` 與 `./scripts/cleanup-scanner.sh`,再對照品質文檔證據。 |+與前幾個專案不同,這份結業起始版本在產品功能上基本完整,主要缺口在於應用外圍的 harness 運作機制。+## 用什麼工具- Claude Code 或 Codex@@ -27,6 +29,10 @@- 評估量表(`docs/zh-TW/resources/templates/evaluator-rubric.md`)- 前五個專案積累的所有 harness 組件+## Harness 機制++完整 harness:所有機制 + 可觀測性 + 消融實驗+## 具體步驟### 準備工作diff --git a/docs/zh-TW/resources/index.md b/docs/zh-TW/resources/index.mdindex 9e4fd26..c36cd79 100644--- a/docs/zh-TW/resources/index.md+++ b/docs/zh-TW/resources/index.md@@ -1,43 +1,42 @@# 繁體中文資源庫-這個資料夾把課程裡的方法整理成可以直接參考和複用的材料,重點回答兩個問題,而不是再講一遍概念:--- 我現在應該先抄哪些檔案-- 這些檔案分別解決什麼問題+這個資料夾把課程方法整理成可直接複製的範本與精簡參考資料,讓你能在真實儲存庫中使用。## 適合什麼時候用-當你準備讓 Codex、Claude Code 或其他 coding agent 在一個儲存庫裡持續工作時,就可以從這裡開始。它特別適合這些場景:+當你想讓 Codex、Claude Code 或其他程式設計代理跨多個工作階段工作,而不必每次都重新整理設定、狀態與範圍時,就從這裡開始。++它特別適合這些場景:-- 多輪工作階段開發,擔心脈絡斷裂-- 功能多,容易出現做一半就停的半成品-- 常常提前宣布完成,但實際沒測透-- 每次開工都要重新摸索啟動方式+- 工作跨越多個工作階段+- 功能很多,容易做到一半就停住+- 代理容易過早宣告完成+- 每次開工都要重新摸索啟動步驟## 從這裡開始-如果你想先搭一個最小可用版本,優先看這些檔案:+如果你要先建立最小配置,先看這些檔案:-- 根指令檔案:[`templates/AGENTS.md`](./templates/AGENTS.md) 或 [`templates/CLAUDE.md`](./templates/CLAUDE.md)-- 功能狀態檔案:[`templates/feature_list.json`](./templates/feature_list.json)-- 進度日誌:[`templates/claude-progress.md`](./templates/claude-progress.md)-- 啟動腳本參考:`docs/zh-TW/resources/templates/init.sh`+- 根目錄指令: [`templates/AGENTS.md`](./templates/AGENTS.md) 或 [`templates/CLAUDE.md`](./templates/CLAUDE.md)+- 功能狀態: [`templates/feature_list.json`](./templates/feature_list.json)+- 進度日誌: [`templates/claude-progress.md`](./templates/claude-progress.md)+- 啟動腳本參考: `docs/zh-TW/resources/templates/init.sh`-然後按需要補上:+接著再加入:-- 工作階段交接範本:[`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)+- 工作階段交接: [`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 文章中更完整的儲存庫結構,請改看:- [`openai-advanced/index.md`](./openai-advanced/index.md)## 資源庫結構-- [`templates/`](./templates/index.md):可以直接複製到真實儲存庫裡的範本-- [`reference/`](./reference/index.md):方法說明、啟動流程和問題對照表-- [`openai-advanced/`](./openai-advanced/index.md):更完整的 OpenAI 風格高階資源包,包括儲存庫骨架、品質檔案、執行計畫和系統級治理檔案+- [`templates/`](./templates/index.md):可直接複製到真實儲存庫的範本+- [`reference/`](./reference/index.md):方法說明、啟動流程與失敗模式對照+- [`openai-advanced/`](./openai-advanced/index.md):進階儲存庫骨架、系統記錄文件,以及以代理為優先的治理範本## 推薦最小組合@@ -46,7 +45,6 @@- `claude-progress.md`- `init.sh`-先把這四樣放進專案裡,再開始讓 agent 持續工作,通常就已經能明顯降低返工和瞎猜。+這四個檔案已足以讓多數代理工作流程穩定許多。-如果你的儲存庫已經進入多模組、多階段、多角色協作,可以直接升級到-[`openai-advanced/`](./openai-advanced/index.md) 這一套高階結構,而不是繼續把最小範本硬撐成一個大而亂的系統。+當儲存庫成長成涵蓋多個領域、活躍計畫、品質評分與可靠性規則的長期系統時,請升級到 [`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 9252730..e4fb78c 100644--- a/docs/zh-TW/resources/openai-advanced/index.md+++ b/docs/zh-TW/resources/openai-advanced/index.md@@ -1,22 +1,20 @@-# OpenAI 高級資源包+# OpenAI 高階資源包-這個檔案夾把 OpenAI 那篇《Harness engineering: leveraging Codex in an-agent-first world》裡更完整、更高階的儲存庫組織方式整理成可以直接參考和複製的範本。+這個資料夾把 OpenAI〈Harness engineering: leveraging Codex in an agent-first world〉一文中較具傾向性的儲存庫結構,整理成可直接複製的起步檔案。-當最小 harness 已經不夠用,而你的儲存庫開始需要下面這些能力時,就該看這一套:+當最小執行環境已經不夠用,而你的儲存庫開始需要下列能力時,就可以改用這一套:-- 一個簡短、負責路由的 `AGENTS.md`-- 放在儲存庫裡的“唯一事實來源”文件體系-- 活躍執行計畫與已完成計畫的分層管理-- 明確的產品、可靠性、安全、前端治理檔案-- 按產品領域和架構層持續更新的品質評分-- 面向模型閱讀的參考材料目錄-- 針對架構、知識沉澱、執行驗證的標準 SOP+- 簡短、以路由為主的 `AGENTS.md`+- 存放在儲存庫內、可持續維護的系統記錄文件+- 進行中與已完成的執行計畫+- 明確的產品、可靠性、安全與前端政策文件+- 依產品領域與架構層進行的品質評分+- 適合模型閱讀的參考資料目錄+- 處理架構、知識記錄與執行階段驗證的標準作業程序-## 包含的目錄骨架+## 包含的起步結構-[`repo-template/`](./repo-template/index.md) 裡提供了一套可直接複製的起步-結構,核心結構如下:+[`repo-template/`](./repo-template/index.md) 內的起步資源包,對應下列結構:```textAGENTS.md@@ -47,30 +45,29 @@ docs/└── SECURITY.md```-## 怎麼用+## 如何採用-1. 如果儲存庫還小,先用最小資源包。-2. 一旦進入多模組、多輪工作階段、長期演化階段,就把- [`repo-template/`](./repo-template/index.md) 裡的骨架複製到你的儲存庫。-3. 保持 `AGENTS.md` 很短,把深層規則拆到 `docs/` 裡。-4. 把品質文件、可靠性文件、執行計畫當成日常開發的一部分,而不是事後補寫。-5. 把生成物和外部參考材料明確收進儲存庫,避免 agent 依賴聊天脈絡或人的記憶。+1. 如果你的儲存庫還小,先使用最小資源包。+2. 當你需要更強的結構時,再把 [`repo-template/`](./repo-template/index.md) 內的檔案複製到自己的儲存庫。+3. 保持 `AGENTS.md` 簡短,把它當成通往較深層文件的路由,而不是百科全書。+4. 把品質、可靠性與計畫文件視為日常工作的一部分,不要留到之後集中補寫。+5. 把產生物與外部參考資料分開標示,讓代理不必依賴聊天記錄也能找到它們。-## SOP 資料庫+## SOP 資源庫-[`sops/`](./sops/index.md) 把文章裡的幾張關鍵圖,整理成可以逐步執行的標準流程:+[`sops/`](./sops/index.md) 把文章中的圖示整理成逐步操作程序:-- 分層領域架構搭建 SOP-- 把不可見知識編碼進儲存庫的 SOP-- 本地可觀測性堆疊與回饋迴路 SOP-- 用 Chrome DevTools 做 UI 驗證閉環的 SOP+- 分層領域架構設定+- 把未被看見的知識編碼進儲存庫+- 本地可觀測性堆疊與回饋迴路工作流程+- 針對 UI 工作的 Chrome DevTools 驗證迴圈## 設計原則-- 短入口,深連結-- 儲存庫就是唯一事實來源-- 機械約束優先於口頭約定-- 計畫、品質和技術債都和程式碼一起版本化-- 清理與 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 0274227..2b44d6b 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md@@ -1,55 +1,53 @@# AGENTS.md-這個儲存庫面向長時執行的 coding-agent 工作流。保持這個檔案簡短,把它當成“唯一事實來源”文件的入口和路由層,而不是一個不斷膨脹的大說明書。+這個儲存庫針對長時間執行的程式設計代理工作做了最佳化。保持這個檔案簡短。把它當成通往系統記錄文件的路由層,不要把所有指令都堆在這裡。## 開工流程-改程式碼前先做這些事:+改動程式碼前,先做這些事:1. 用 `pwd` 確認儲存庫根目錄。-2. 讀取 `ARCHITECTURE.md`,理解目前系統地圖和硬性依賴規則。-3. 讀取 `docs/QUALITY_SCORE.md`,先知道最弱的產品領域和架構層。-4. 讀取 `docs/PLANS.md`,再打開目前要執行的 active plan。-5. 讀取相關的 `docs/product-specs/` 規格文件。-6. 跑這個儲存庫約定的 bootstrap 與驗證路徑。-7. 如果基礎驗證先失敗,先修 baseline,再加新範圍。+2. 讀取 `ARCHITECTURE.md`,了解目前的系統地圖與硬性相依規則。+3. 讀取 `docs/QUALITY_SCORE.md`,確認目前最弱的領域或分層。+4. 讀取 `docs/PLANS.md`,再打開你目前依循的進行中計畫。+5. 讀取 `docs/product-specs/` 內相關的產品規格。+6. 執行這個儲存庫的標準啟動與驗證流程。+7. 如果基線驗證失敗,先修復基線,再新增範圍。## 路由地圖-- `ARCHITECTURE.md`:領域地圖、分層模型、依賴規則+- `ARCHITECTURE.md`:領域地圖、分層模型、相依規則- `docs/design-docs/index.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/PLANS.md`:計畫生命週期與執行計畫政策+- `docs/QUALITY_SCORE.md`:產品領域與分層健康度+- `docs/RELIABILITY.md`:執行訊號、基準與重新啟動要求+- `docs/SECURITY.md`:密鑰、沙箱、資料與外部動作規則+- `docs/FRONTEND.md`:UI 約束、設計系統規則與無障礙檢查## 工作約定-- 一次只圍繞一個有邊界的計畫或功能切片工作。-- 不能只靠讀程式碼就宣佈完成,必須有可執行證據。-- 只要改了行為,就同步更新對應的產品、計畫或可靠性文件。-- 如果某類 review feedback 反覆出現,把它升級成機械規則、檢查或 linter,不要一直在聊天裡重複解釋。-- 生成物放進 `docs/generated/`,外部 reference 放進 `docs/references/`。-- 需要更多細節時,優先補小而新的文件,而不是繼續把這個檔案寫長。+- 一次只處理一個有邊界的計畫或功能切片。+- 不要只靠閱讀程式碼就判定完成,必須有可執行的證據。+- 如果你改動了行為,就在同一個工作階段更新對應的產品、計畫或可靠性文件。+- 如果某類 review feedback 反覆出現,就把它升級成機械規則、檢查或 linter,不要在聊天裡重複解釋。+- 把產生物放在 `docs/generated/`,把來源參考資料放在 `docs/references/`。+- 優先新增小而且保持最新的文件,不要持續擴大這個檔案。## 完成定義-一個改動只有在以下條件都滿足時才算完成:+只有在下列條件都成立時,改動才算完成:-- 目標行為已實現-- 要求的驗證真的跑過-- 證據已經掛到相關 plan 或品質文件裡-- 受影響的文件仍然是最新的-- 儲存庫能按標準啟動路徑乾淨重啟+- 目標行為已經實作+- 要求的驗證已實際執行+- 證據已連結到相關計畫或品質文件+- 受影響的文件仍是最新狀態+- 儲存庫可依標準啟動路徑乾淨重啟-## 收尾+## 工作階段結束前-結束工作階段前:--1. 更新目前 active execution plan。-2. 如果產品領域或架構層有明顯變化,更新 `docs/QUALITY_SCORE.md`。-3. 如果有延期處理的債務,記到 `docs/exec-plans/tech-debt-tracker.md`。-4. 已完成的計畫及時移到 `docs/exec-plans/completed/`。-5. 保證儲存庫可重啟,並留下明確的下一步動作。+1. 更新目前的進行中執行計畫。+2. 如果任何領域或分層有明顯變化,更新 `docs/QUALITY_SCORE.md`。+3. 如果你延後處理新的技術債,記錄到 `docs/exec-plans/tech-debt-tracker.md`。+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 4d39ae1..8fe9bf9 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/ARCHITECTURE.md@@ -1,55 +1,55 @@# ARCHITECTURE.md-這份檔案是系統的頂層地圖。它應該保持簡短,只提供最關鍵的結構資訊,並把更深的內容指向其他文件。+這份檔案是系統的頂層地圖。內容應保持簡短,並在需要時指向更深入的文件。## 系統形態-- 產品:`[替換成產品名稱]`-- 主使用者流程:`[替換成核心流程]`-- 執行面:`[desktop / web / cli / services / workers]`-- 產品行為真相來源:`docs/product-specs/`+- 產品: `[替換成產品名稱]`+- 主要使用者流程: `[替換成核心流程]`+- 執行介面: `[desktop / web / cli / services / workers]`+- 產品行為的真相來源: `docs/product-specs/`## 領域地圖-| 領域 | 負責什麼 | 主要入口 | 對應規格 |-|------|---------|---------|---------|-| `[domain-a]` | `[職責]` | `[模組 / 路由 / 命令]` | `[spec path]` |-| `[domain-b]` | `[職責]` | `[模組 / 路由 / 命令]` | `[spec path]` |+| 領域 | 負責內容 | 主要入口點 | 對應規格 |+|------|----------|------------|----------|+| `[domain-a]` | `[負責範圍]` | `[modules / routes / commands]` | `[spec path]` |+| `[domain-b]` | `[負責範圍]` | `[modules / routes / commands]` | `[spec path]` |## 分層模型-用固定方向的分層模型,避免 agent 臨場發明架構:+使用固定方向的分層模型,避免代理臨時拼出任意架構:`Types -> Config -> Repo -> Service -> Runtime -> UI`-跨領域關注點應該透過明確的 provider 或 adapter 邊界進入,而不是直接跨層穿透。+橫切關注點應透過明確的 provider 或 adapter 邊界進入,不要直接跨層延伸。-## 硬性依賴規則+## 硬性相依規則-- 低層不能依賴高層。-- UI 不能繞過 runtime 或 service 契約。-- 資料存取必須透過 repo 或等價 adapter 進行。-- 共享 util 必須保持通用,不能慢慢堆成領域邏輯垃圾桶。-- 新依賴要在對應 plan 或 design doc 裡說明理由。+- 低層不得依賴高層。+- UI 不得繞過 runtime 或 service 契約。+- 資料存取必須透過 repositories 或等價的 adapter 進入。+- 共用 utilities 必須維持通用性,不得累積領域邏輯。+- 新增相依時,應在對應的計畫或設計文件中說明理由。-## 橫切接口+## 橫切介面-| 關注點 | 允許的邊界 | 備註 |-|-------|-----------|------|-| 日誌與 tracing | `[provider / utility path]` | `[只允許結構化日誌,不允許臨時 console]` |-| Auth | `[provider path]` | `[token/session 規則]` |-| 外部 API | `[client 或 provider path]` | `[限流 / 重試原則]` |+| 關注點 | 核准邊界 | 備註 |+|--------|----------|------|+| Logging and tracing | `[provider / utility path]` | `[僅限結構化記錄,不可臨時使用 console]` |+| Auth | `[provider path]` | `[token / session 規則]` |+| External APIs | `[client or provider path]` | `[rate limit / retry 原則]` || Feature flags | `[flag boundary]` | `[歸屬]` |## 目前熱點-- `[最難安全修改的區域]`-- `[邊界最弱或測試最脆的區域]`+- `[代理最難安全修改的區域]`+- `[邊界薄弱或測試脆弱的區域]`-## 變更檢查+## 變更檢查清單-當你修改了會影響架構的程式碼:+當你改動與架構相關的程式碼時:-1. 如果領域地圖或允許邊界變了,就更新這份檔案。-2. 如果背後的設計理由變了,就更新 `docs/design-docs/` 裡的相關文件。-3. 如果規則應該機械執行,就補一個可執行檢查。+1. 如果領域地圖或允許的邊界改變,就更新這份檔案。+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 6356319..3512e96 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,26 +1,26 @@# DESIGN.md-這份檔案是設計文件入口。保持簡短,把更細的內容路由到-`docs/design-docs/` 裡的具體檔案。+這份檔案是設計文件的入口。內容要保持簡短,並把更詳細的內容導向+`docs/design-docs/` 下面的具體檔案。## 目的-記錄那些應該跨越單次聊天、單個 sprint、單個 reviewer 記憶而持續存在的產品與系統設計決策。+記錄應該跨越單次聊天、單個 sprint 與單個 reviewer 記憶而持續存在的產品與系統設計決策。## 什麼時候先看它-- 你需要理解目前的設計哲學+- 你需要理解目前的設計理念- 你準備引入新模式-- 你要判斷哪些設計已經定了,哪些還在開放狀態+- 你要知道哪些設計決策已經定案,哪些仍然開放## 核心設計文件-- `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`:專案層級的代理優先核心信念## 設計規則-- 設計文件要小而新。-- 一個決策領域儘量對應一份文件。-- 某個改動依賴設計文件時,要在 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 e308ef5..8098b00 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@@ -1,23 +1,23 @@# FRONTEND.md-這份檔案定義穩定的前端預期,避免 agent 每次都臨場發明一套 UI 模式。+這份檔案定義穩定的前端預期,避免代理不可預測地建立不同的 UI 模式。## UI 原則-- 先保證易懂,再追求新鮮感。-- 互動流程要可發現、可重走、可重啟。-- 優先沉澱少量可複用元件,而不是到處長一次性變體。-- 無障礙檢查屬於正常驗證,不是最後的美化工作。+- 先以易懂為優先,再考慮新穎性。+- 互動流程要容易被發現,並且可以重新開始。+- 優先使用少量可重複使用的元件,避免建立一次性的變體。+- 無障礙檢查屬於一般驗證的一部分,也要納入日常工作流程。## 護欄-- 把設計系統或元件庫參考材料放進 `docs/references/`。-- 顯式記錄關鍵使用者狀態:empty、loading、success、error、retry。-- 在不同流程裡保持文案、鍵盤行為、視覺層級一致。-- 修復 UI bug 後,順手補上對應驗證步驟。+- 在 `docs/references/` 記錄設計系統或元件函式庫。+- 記錄關鍵的使用者可見狀態,包含 empty、loading、success、error、retry。+- 在不同流程中維持文案、鍵盤行為與視覺層級一致。+- 修復 UI bug 後,要新增或更新對應的驗證步驟。## 驗證要求-- 為關鍵使用者旅程留下證據。-- 把瀏覽器或執行時期驗證步驟寫進相關 plan。-- 如果視覺迴歸常見,就標準化截圖或 DOM 檢查。+- 為關鍵使用者旅程保留證據。+- 把瀏覽器或執行階段的驗證步驟寫進相關 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 9d682d6..6121c52 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,26 +1,26 @@# PLANS.md-這份檔案定義執行計畫如何建立、更新、完成和歸檔。+這份檔案定義執行計畫如何建立、更新、完成與歸檔。## 什麼時候必須有 plan-當工作滿足以下任一條件時,就建立 execution plan:+當工作符合以下任一條件時,就建立 execution plan:- 會跨越多個工作階段-- 會同時影響多個子系統-- 驗證或上線風險不小-- 存在需要顯式記錄的開放決策+- 會變更多個子系統+- 存在不可忽略的驗證或上線風險+- 依賴應該記錄下來的開放決策## 計畫放哪-- `docs/exec-plans/active/`:目前正在驅動工作的計畫-- `docs/exec-plans/completed/`:已完成但仍然要保留脈絡的計畫-- `docs/exec-plans/tech-debt-tracker.md`:延期處理的債務與 follow-up+- `docs/exec-plans/active/`:目前正在推動工作的計畫+- `docs/exec-plans/completed/`:已完成,但為了後續代理脈絡而保留的計畫+- `docs/exec-plans/tech-debt-tracker.md`:延後處理的工作與 follow-up## 最少要包含的部分- 目標-- 範圍與明確不做什麼+- 範圍與明確排除的項目- 驗證路徑- 風險與 blocker- 進度日誌@@ -28,7 +28,7 @@## 執行規則-- 一份 active plan 同一時間應該只有一個明確的目前步驟。-- plan 要隨著工作推進而更新,不要把它當成靜態散文。-- 只要某個決策改變了實現方向,就記到 plan 裡。-- 已完成的計畫要移到 `completed/`,讓後續 agent 仍然能發現歷史脈絡。+- 每一份 active plan 在同一時間都應該只有一個明確負責的目前步驟。+- plan 要隨著工作推進而更新,不要把它視為靜態說明文件。+- 如果某個決策改變了實作方向,就把它記到 plan 裡。+- 已完成的計畫要移到 `completed/`,讓後續代理仍然能找到先前的脈絡。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 5f75947..02802ba 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。-- 具體流程寫在 product 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 85e8778..840dbe1 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,17 +1,17 @@# QUALITY_SCORE.md-這份文件用來跟蹤儲存庫是在變強還是變弱。+這份文件用來追蹤儲存庫是隨時間變強還是變弱。## 評級標準-- `A`:驗證通過、可讀、穩定、邊界執行到位+- `A`:已驗證、可讀、穩定,而且邊界有落實- `B`:可用,只有少量缺口- `C`:部分可用,存在明顯混亂或不穩定-- `D`:損壞、不安全,或結構上說不清楚+- `D`:損壞、不安全,或結構不明## 產品領域-| 領域 | 評級 | 驗證狀態 | Agent 可讀性 | 測試穩定性 | 關鍵缺口 | 上次更新 |+| 領域 | 評級 | 驗證狀態 | 代理可讀性 | 測試穩定性 | 關鍵缺口 | 上次更新 ||------|------|---------|-------------|-----------|---------|---------|| `[domain-a]` | - | - | - | - | - | - || `[domain-b]` | - | - | - | - | - | - |@@ -19,7 +19,7 @@## 架構層-| 層級 | 評級 | 邊界執行 | Agent 可讀性 | 關鍵缺口 | 上次更新 |+| 層級 | 評級 | 邊界落實情況 | 代理可讀性 | 關鍵缺口 | 上次更新 ||------|------|---------|-------------|---------|---------|| Types | - | - | - | - | - || Services | - | - | - | - | - |@@ -28,7 +28,7 @@## Benchmark 快照-| 日期 | Harness 變體 | 完成率 | 重試次數 | Review 前缺陷數 | 備註 |+| 日期 | 執行環境變體 | 完成率 | 重試次數 | Review 前缺陷數 | 備註 ||------|-------------|-------|---------|----------------|------|| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |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 61d21a9..0f10e52 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@@ -1,20 +1,20 @@# RELIABILITY.md-這份檔案定義系統如何證明自己健康、可診斷、可重啟。+這份檔案定義系統如何證明自己健康且可重啟。## 標準路徑- Bootstrap:`[command]`- Verification:`[command]`-- 啟動應用或服務:`[command]`-- 除錯或查看執行態:`[command]`+- 啟動應用程式或服務:`[command]`+- 除錯或檢查執行階段:`[command]`## 必需執行信號- 啟動與關鍵流程的結構化日誌-- 關鍵服務的 health check-- 條件允許時為慢路徑提供 trace 或 timing 資料-- 對可恢復失敗提供使用者可見的錯誤狀態+- 關鍵服務的健康檢查+- 在可用時,為慢路徑提供 trace 或 timing 資料+- 針對可恢復的失敗,提供使用者可見的錯誤狀態## 黃金旅程@@ -22,11 +22,11 @@- `[journey 2]`- `[journey 3]`-每條黃金旅程都應該有可重複的驗證路徑和明確的失敗信號。+每一條黃金旅程都應該有可重複的驗證路徑與明確的失敗信號。## 可靠性規則-- 只要系統不能乾淨重啟,功能就不能算完成。-- 執行失敗必須能從 repo-local 信號裡定位。-- 某類失敗模式一旦反覆出現,就給它補 benchmark 或 guardrail。-- cleanup 屬於可靠性的一部分,不是另外一件事。+- 如果系統之後無法乾淨重啟,功能就不算完成。+- 執行階段失敗應該能從儲存庫內的信號診斷。+- 如果某類失敗模式重複出現,就新增對應的 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 af40bf2..0cf372a 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@@ -1,27 +1,27 @@# SECURITY.md-這份檔案定義那些 agent 絕不能靠猜來處理的安全規則。+這份檔案定義代理不能靠猜測處理的安全與保護規則。## Secrets 與憑證-- 絕不把 secrets 硬編碼進原始碼或文件。-- 在這裡記錄允許的 secret 加載路徑。-- 從日誌和截圖裡去掉 token、API key 與個人資料。+- 絕不把 secrets 硬編碼到原始碼或文件裡。+- 在這裡記錄允許的 secret 載入路徑。+- 從日誌與截圖中移除 token、API key 與個人資料。## 不可信輸入-- 外部內容在驗證前一律視為不可信。-- 把允許的抓取或執行邊界寫在這裡。-- 如果存在 prompt injection 或 command injection 風險,要把 guardrail 記錄清楚。+- 外部內容在驗證前都視為不可信。+- 在這裡記錄允許的抓取或執行邊界。+- 如果存在 prompt injection 或 command injection 風險,就記錄對應的 guardrail。## 外部動作-- 列出哪些動作必須顯式批準。-- 記錄哪些生產或破壞性命令預設不能跑。-- 除錯和驗證優先走 sandbox-safe 路徑。+- 列出哪些動作需要明確批准。+- 記錄哪些正式環境或破壞性命令預設不能執行。+- 除錯與驗證優先使用 sandbox-safe 的工作流程。## 依賴與評審規則-- 新依賴必須在 active plan 裡說明理由。-- 涉及安全的改動必須有顯式驗證步驟。-- 反覆出現的安全 review 評論要升級成檢查,而不是變成口口相傳的經驗。+- 新依賴需要在 active plan 裡說明理由。+- 涉及安全的改動需要明確的驗證步驟。+- 反覆出現的安全 review 評論應該轉成檢查,不要只靠口耳相傳。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 dbc9bf8..d869267 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 的唯一事實來源。+- 儲存庫是代理的唯一事實來源。- `AGENTS.md` 是路由器,不是百科全書。- 驗證證據比自信更重要。-- 一次做好一個有邊界的任務,勝過同時開很多半成品。-- 反覆出現的人類回饋要升級成可複用的 harness 規則。-- 清理與簡化都是交付的一部分,不是事後補救。-- 如果 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 21e94ae..b488685 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,10 +1,10 @@# 設計文件索引-把這份索引當成設計歷史的可發現地圖。+把這份索引當成可查找的設計歷史索引。## Accepted-- `core-beliefs.md`:agent-first 的執行信念與持久專案規範+- `core-beliefs.md`:以代理為先的執行信念與長期專案規範## Proposed@@ -12,10 +12,10 @@## Deprecated-- `[把被替代或過期的設計文件移到這裡,並给出替代連結]`+- `[把舊的或已被取代的設計文件移到這裡,並給出替代連結]`## 維護規則-- 每份設計文件都應該有 owner 或更新觸發條件。-- 過期文件要麼刪除,要麼明確標成 deprecated,不要讓它悄悄漂移。-- active execution plan 要連結自己依賴的設計文件。+- 每份設計文件都應該有負責人或更新觸發條件。+- 移除過期文件,或明確標示為 deprecated,不要讓內容持續偏離現況。+- 目前執行計畫要連結它依賴的設計文件。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 07e8964..c9a0428 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 也能只靠儲存庫繼續推進。+每份目前執行計畫都應維持最新,讓新的代理工作階段只靠儲存庫也能接續工作。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 ae3980d..d94172f 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 需要靠它理解程式碼為什麼會變成現在這樣。+把已完成的計畫移到這裡,不要直接刪除。已完成計畫是儲存庫記憶的一部分,也能幫助後續代理理解程式碼為什麼會變成現在這樣。diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.mdindex 2f29987..b1c5c3b 100644--- a/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md+++ b/docs/zh-TW/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md@@ -1,6 +1,6 @@-# 技術債跟蹤+# 技術債追蹤-這份檔案只記錄那些真實存在、已經確認、並且被有意識延後的技術債。+這份檔案只記錄真實存在、已被承認,而且是刻意延後處理的技術債。| 日期 | 區域 | 債務 | 為什麼延後 | 風險 | 下次觸發點 ||------|------|------|-----------|------|-----------|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 db0d4b6..7945f1c 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,13 +1,13 @@# 資料庫結構-這個目錄用來存放那些生成出來但又值得 agent 直接閱讀的工件,避免它每次都去原始碼裡反推。+這個目錄用來放代理應能直接檢視的生成或衍生工件,讓它不必每次都從程式碼反推。## 來源-- 生成命令或來源:`[command or source path]`+- 產生命令或來源:`[command or source path]`- 最近重新整理時間:`YYYY-MM-DD`## 備註-- 生成部分不要手改。-- 底層 schema 一變,就重新生成這份檔案。+- 不要手動修改生成區段。+- 底層 schema 變更時,重新產生這份檔案。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 b7f277f..099c95f 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,6 +1,6 @@# 產品規格索引-這個目錄用來放目前仍然有效的使用者可見行為規格。+這個目錄用來放目前有效的使用者可見行為規格。## 目前有效規格@@ -8,6 +8,6 @@## 規則-- 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 d14e09d..97b40a8 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@@ -2,7 +2,7 @@## 目標-描述一個新使用者第一次進入產品時應該經歷的流程。+描述新使用者第一次使用產品時應有的體驗。## 起始條件@@ -10,9 +10,9 @@## 使用者流程-1. `[步骤一]`-2. `[步骤二]`-3. `[步骤三]`+1. `[步驟一]`+2. `[步驟二]`+3. `[步驟三]`## 驗收標準@@ -22,5 +22,5 @@## 失敗狀態-- `[可恢复錯誤與使用者反馈]`-- `[被阻塞狀態與兜底方案]`+- `[可恢復的錯誤與使用者回饋]`+- `[受阻狀態與備援做法]`diff --git a/docs/zh-TW/resources/openai-advanced/repo-template/index.md b/docs/zh-TW/resources/openai-advanced/repo-template/index.mdindex 4dfd062..7c65219 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,21 @@-# 高級儲存庫範本+# 高階儲存庫範本-當你希望把儲存庫升級成更接近 OpenAI 文中那種 agent-first 文件面,而不只是一個最小 harness 時,就複製這套起步範本。+當你想在真實儲存庫裡採用 OpenAI 風格、以代理為優先的文件面,而不再只靠最小執行環境時,就複製這套起步範本。-## 推薦複製順序+## 複製順序-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. 始終保持入口檔案很短,詳細規則拆到連結文件裡。+1. 把 `AGENTS.md` 和 `ARCHITECTURE.md` 複製到儲存庫根目錄。+2. 複製整個 `docs/` 目錄樹。+3. 優先填寫 `docs/PRODUCT_SENSE.md`、`docs/QUALITY_SCORE.md` 與 `docs/RELIABILITY.md`。+4. 在 `docs/exec-plans/active/` 下加入第一份進行中的計畫。+5. 讓入口檔案保持簡短,並把細節導向連結文件。-## 這套範本主要最佳化什麼+## 這套範本優先處理什麼-- 持久、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 47a1b36..ce31f87 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,48 +1,48 @@-# SOP:Chrome DevTools 驗證閉環+# SOP:Chrome DevTools 驗證循環-當 UI 改動必須經過真實互動、截圖、DOM 狀態和 console 輸出來判斷,而不是隻靠讀程式碼時,就用這份 SOP。+當 UI 工作需要真實的執行階段互動,而且截圖、DOM 狀態與 console 輸出比單看程式碼更重要時,就使用這份 SOP。## 目標-把 UI 驗證變成 agent 可以反覆執行的互動閉環,直到這條使用者旅程變乾淨。+把 UI 驗證變成代理可重複執行的互動循環,直到流程乾淨。-## 核心閉環+## 核心循環-1. 選定目標頁面或 app 實例。-2. 清掉舊的 console 噪聲。+1. 選定目標頁面或應用程式實例。+2. 清除舊的 console 噪聲。3. 記錄 BEFORE 狀態。4. 觸發 UI 路徑。-5. 觀察互動過程中的 runtime events。+5. 觀察互動期間的執行階段事件。6. 記錄 AFTER 狀態。-7. 修復問題,必要時重啟 app。-8. 反覆重跑驗證,直到這條旅程 clean。+7. 套用修正,必要時重新啟動應用程式。+8. 重跑驗證,直到流程乾淨。-## 必需輸入+## 必要輸入- 穩定的啟動命令-- 可重複的 UI journey-- 能抓 DOM、console 或截圖的方式-- 明確“什麼算 clean”的規則+- 可重現的 UI 流程+- 可擷取 DOM、console 或截圖的方法+- 判定「乾淨」狀態的規則## 執行 SOP-1. 把目標旅程寫進 active plan。-2. 用可觀察行為定義成功:文字出現、按鈕可點、錯誤消失、console 乾淨、請求成功。-3. 互動前先拍初始狀態。-4. 一次只觸發一條路徑。-5. 記錄 runtime event、DOM 變化和可見輸出。-6. 如果失敗,只修最小負責層,然後重啟。-7. 重跑同一路徑,對比 BEFORE/AFTER 證據。+1. 把目標流程寫進目前執行計畫。+2. 用可觀察的結果定義成功,像是文字出現、按鈕可點擊、錯誤消失、console 乾淨、請求成功。+3. 在互動前記錄初始狀態。+4. 每次只觸發一條路徑。+5. 記錄執行階段事件、DOM 變化與可見輸出。+6. 如果流程失敗,只修正最小的責任層,然後重新啟動。+7. 重跑同一路徑,並比較 BEFORE/AFTER 證據。-## Clean 標準+## 乾淨標準-- 目標可見狀態已經出現-- 沒有意外錯誤-- console 噪聲已理解或清理-- 重跑同一路徑結果一致+- 目標可見狀態已出現+- 沒有非預期錯誤+- console 噪聲已被理解或清除+- 重跑同一路徑會得到相同結果## 需要同步更新的儲存庫工件-- 目前 active execution plan-- 如果它變成黃金旅程,更新 `docs/RELIABILITY.md`-- 如果可見行為改變了,更新 product spec+- 目前執行計畫+- 如果流程成為黃金路徑,更新 `docs/RELIABILITY.md`+- 如果可見行為改變,更新產品規格diff --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 87a8e95..f35d849 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,42 +1,42 @@# SOP:把不可見知識編碼進儲存庫-當重要脈絡還散落在 Google Docs、聊天記錄、ticket 或人的腦子裡時,就用這份 SOP。+當重要脈絡仍散落在 Google Docs、聊天記錄、ticket 或人的記憶中時,就使用這份 SOP。## 目標-讓那些 agent 以前看不見的知識,變成 codebase 裡可發現、可讀取、可執行的事實。+讓代理原本看不見的知識,變成儲存庫中可發現的內容,讓新的工作階段不必依賴先前對話也能採取行動。## 觸發信號-- agent 總在追問系統到底怎麼運作。-- 人開始說“這個是 Slack 裡定過的”或“按某某上週說的做”。-- review 裡經常引用儲存庫裡根本沒寫下來的產品、安全或架構規則。-- 新工作階段總在重複那些本該已經穩定下來的發現工作。+- 代理持續追問系統如何運作。+- 有人說「這是在 Slack 決定的」或「照某人上週說的做」。+- 審查意見引用了儲存庫中沒有寫下來的產品或安全規則。+- 新工作階段反覆做本來就該已經釐清的探索工作。## 執行 SOP-1. 先列出所有不可見知識來源:外部文件、聊天、預設團隊規則、口頭決策。-2. 對每條知識判斷:它屬於架構、產品行為、安全策略、可靠性要求、執行脈絡,還是參考材料?-3. 按類別編碼到對應儲存庫工件:+1. 列出所有不可見知識來源,包含外部文件、聊天、預設團隊規則與口頭決策。+2. 逐條判斷它屬於架構、產品行為、安全政策、可靠性要求、計畫脈絡,或參考材料。+3. 依類別編碼到對應的儲存庫工件:- 架構 -> `ARCHITECTURE.md`- 產品行為 -> `docs/product-specs/`- 設計理由 -> `docs/design-docs/`- 執行狀態 -> `docs/exec-plans/`- - 外部參考材料 -> `docs/references/`+ - 重複使用的外部參考 -> `docs/references/`- 品質或可靠性要求 -> `docs/QUALITY_SCORE.md` 或 `docs/RELIABILITY.md`-4. 把模糊表達改寫成執行上真正有用的表達。-5. 刪除或廢棄舊副本,保證儲存庫裡有一個可發現的真相來源。+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 2e397e2..ba270c4 100644--- a/docs/zh-TW/resources/openai-advanced/sops/index.md+++ b/docs/zh-TW/resources/openai-advanced/sops/index.md@@ -1,23 +1,23 @@-# OpenAI 高級 SOP+# OpenAI 進階 SOP-這些 SOP 把文章裡的工作方式翻成可以直接參考、執行、改造的操作手冊。+這些 SOP 把文章中的運作方式整理成可直接參考或調整的操作手冊。## 包含哪些 SOP- [`layered-domain-architecture.md`](./layered-domain-architecture.md):- 搭建顯式分層與跨領域邊界+ 建立明確分層與跨領域邊界- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):- 把聊天、外部文件、腦內知識變成 repo-local 文件+ 把聊天、文件與記憶中的知識移進儲存庫內的文件- [`observability-feedback-loop.md`](./observability-feedback-loop.md):- 給 agent 提供 logs、metrics、traces 與可重複的除錯閉環+ 提供代理 logs、metrics、traces,以及可重複的除錯循環- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):- 用瀏覽器自動化和快照反覆驗證 UI,直到 clean+ 使用瀏覽器自動化與快照反覆驗證 UI 行為,直到流程乾淨-## 怎麼用+## 怎麼使用-1. 先選和你目前瓶頸最相符的 SOP。-2. 按檢查清單補齊缺失工件或工具。-3. 把得到的規則編碼回 `repo-template/` 裡的文件。-4. 把反覆出現的 review 評論升級成檢查、腳本或 guardrail。+1. 選擇最符合你目前瓶頸的 SOP。+2. 依照檢查清單補齊缺少的工件或工具。+3. 把得到的規則編碼回你複製的 `repo-template/` 文件。+4. 把反覆出現的審查意見轉成檢查、腳本或 guardrail。-這些 SOP 的目的是讓 harness 更可讀、更可執行、更可複用,供你直接參考、執行、改造,而非機械照抄。+這些 SOP 不適合機械照抄。它們的用途,是讓執行環境更容易理解、落實與重複使用。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 32b464b..9639e19 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,47 +1,47 @@# SOP:分層領域架構-當 agent 反覆跨層亂連、在不同層重複邏輯、或者幾輪工作階段後程式碼越來越難審時,就用這份 SOP。+當代理持續破壞邊界、在不同層重複邏輯,或幾輪工作階段後產出的程式碼變得難以審查時,就使用這份 SOP。## 目標-把領域邊界寫清楚、立起來、能執行,讓 agent 在高速度下也不至於悄悄把結構做爛。+把領域邊界寫得足夠明確,讓代理能快速推進,同時不會悄悄破壞結構。## 目標模型-在一個業務領域內部,優先使用這條單向流:+在單一業務領域內,優先採用這條單向流程:`Types -> Config -> Repo -> Service -> Runtime -> UI`-跨領域關注點透過明確的 provider 或 adapter 進入。共享 utils 保持在領域之外,不能慢慢長成業務邏輯垃圾場。+橫切關注點應透過明確的 provider 或 adapter 進入。共用 utils 應留在領域之外,不要累積領域邏輯。-## 建設檢查清單+## 建置檢查清單-- 在 `ARCHITECTURE.md` 裡列清目前 domains。-- 在 `ARCHITECTURE.md` 裡寫清允許的依賴方向。-- 記錄 auth、telemetry、外部 API 等 cross-cutting interface。-- 為目前最難處理的邊界違規寫一條短說明。-- 決定哪些規則應該升級成 lint、test 或 script。+- 在 `ARCHITECTURE.md` 中定義目前的領域。+- 在 `ARCHITECTURE.md` 中寫出允許的相依方向。+- 記錄 auth、telemetry、外部 API 等橫切介面。+- 針對目前最難處理的邊界違規,補上一則簡短說明。+- 決定哪些規則要用 lint、測試或腳本做機械化約束。## 執行 SOP-1. 先給程式碼庫畫 domain map,再談實現風格。-2. 對每個 domain,明確允許的 layer sequence。-3. 找出所有橫切關注點,並把它們改走 provider 或 adapter。-4. 把含糊的 shared logic 重新放回所屬 domain,或抽成真正通用的 utils。+1. 在調整實作風格前,先把程式碼庫畫分成各個領域。+2. 針對每個領域,定義允許的層級順序。+3. 找出所有橫切關注點,並把它們導向 provider 或 adapter。+4. 把界線不明的共用邏輯移回負責的領域,或改成真正通用的 utils。5. 把規則寫進 `ARCHITECTURE.md`。-6. 先為代價最高的一類違規補一個可執行 guardrail。-7. 改完後更新品質評分。+6. 針對代價最高的違規類型,加入一條可執行的護欄。+7. 完成後更新品質評分。## 完成定義-- 一個全新的 agent 能判斷某個改動應該落在哪一層。-- UI 不再直接連 repo 或外部副作用。-- 橫切能力都有明確入口。-- 至少一條重要邊界已經被機械執行。+- 新接手的代理能判斷一個變更屬於哪一層。+- `UI` 程式碼不再直接觸及 repo 或外部副作用。+- 橫切關注點都有具名入口。+- 至少有一條重要邊界已透過機械方式強制執行。-## 需要同步更新的儲存庫工件+## 需要更新的儲存庫工件- `ARCHITECTURE.md`- `docs/QUALITY_SCORE.md`-- 如果設計理由變了,更新 `docs/design-docs/`-- `docs/PLANS.md` 或目前 active execution plan+- 設計理由改變時更新 `docs/design-docs/`+- `docs/PLANS.md` 或目前啟用中的執行計畫diff --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 b363c74..c57c48b 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,42 +1,41 @@-# SOP:可觀測性回饋閉環+# SOP:可觀測性回饋迴圈-當除錯太慢、agent 總在沒證據的情況下宣佈成功、或者執行時期行為比程式碼本身還難看懂時,就用這份 SOP。+當除錯速度太慢、代理在沒有證據時反覆宣稱成功,或執行期行為比程式碼本身更難觀察時,就使用這份 SOP。## 目標-給 agent 一套本地閉環,讓它可以基於 logs、metrics、traces 和可重複 workload 來判斷系統,而不是隻靠看程式碼猜。+給代理一個涵蓋 logs、metrics、traces 與可重跑 workload 的本地回饋迴圈,讓它根據執行結果推理,而不是只靠閱讀程式碼。-## 最小可用堆疊+## 最低配置-- 應用輸出結構化日誌-- 條件允許時輸出 metrics 和 traces-- 本地採集或 fan-out 層-- 可查詢 logs / metrics / traces 的接口-- 每次改動後都能重跑的 workload 或 user journey+- 應用程式會輸出結構化 logs+- 可行時輸出 metrics 與 traces+- 本地 fan-out 或採集層+- 可查詢 logs、metrics 與 traces 的介面+- 每次變更後都能重跑的 workload 或使用者旅程## 執行 SOP-1. 先定義最重要的黃金執行旅程。-2. 給啟動流程和關鍵路徑補結構化日誌。-3. 在合適位置補 latency、failure count、queue depth 之類的 metrics。-4. 為慢路徑或多階段流程補 traces 或 timing 標記。-5. 讓這些信號能從本地開發環境查詢到。-6. 給 agent 一條可以反覆重跑的 workload 或場景。-7. 強制執行這條閉環:query -> correlate -> reason -> implement -> restart- -> rerun -> verify。+1. 定義最重要的黃金執行期旅程。+2. 在啟動流程與關鍵路徑加入結構化 logs。+3. 在合適位置加入 latency、失敗次數或佇列深度等 metrics。+4. 為緩慢或多步驟流程加入 traces 或計時標記。+5. 讓這些訊號能從本地開發環境查詢。+6. 給代理一個可重複執行的 workload 或情境。+7. 要求採用這個迴圈,`query -> correlate -> reason -> implement -> restart -> rerun -> verify`。## 除錯工作階段檢查清單-- 到底哪裡失敗了?-- 哪條信號能證明它失敗?-- 失敗歸屬哪一層?-- 修復後哪條信號發生了變化?-- App 是否能乾淨重啟?-- 同一 workload 重跑後是否通過?+- 哪裡失敗了?+- 哪個訊號能證明失敗?+- 哪一層負責這個失敗?+- 修復後哪些訊號改變了?+- 應用程式是否已乾淨重啟?+- 同一個 workload 在重跑後是否通過?## 完成定義-- agent 能用執行證據解釋失敗模式。-- 每次改動後都能重跑同一 workload。-- restart 與 rerun 已經成為正常任務循環的一部分。-- 可靠性信號已經記錄到 `docs/RELIABILITY.md`。+- 代理能根據執行期證據說明失敗模式。+- 每次變更後都能重跑同一個 workload。+- 重啟與重跑已成為正常工作流程的一部分。+- 可靠性訊號已記錄在 `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 4683b50..7b1f01d 100644--- a/docs/zh-TW/resources/reference/coding-agent-startup-flow.md+++ b/docs/zh-TW/resources/reference/coding-agent-startup-flow.md@@ -1,33 +1,33 @@-# 編碼代理開工流程+# 編碼代理啟動流程-初始化完成後,每輪編碼工作階段都按這個流程開始。+初始化完成後,每一輪工作階段開始時都使用這個流程。-## 固定開工範本+## 固定啟動範本-1. 執行 `pwd`,確認儲存庫根目錄-2. 讀取 `claude-progress.md`-3. 讀取 `feature_list.json`-4. 用 `git log --oneline -5` 查看最近提交-5. 執行 `./init.sh`-6. 跑一條基礎 smoke test 或端到端路徑-7. 如果基礎狀態已壞,先修這個-8. 選擇最高優先級的未完成功能-9. 只圍繞這個功能工作,直到它被驗證或明確 blocked+1. 執行 `pwd`,確認儲存庫根目錄。+2. 讀取 `claude-progress.md`。+3. 讀取 `feature_list.json`。+4. 用 `git log --oneline -5` 檢查最近的提交。+5. 執行 `./init.sh`。+6. 執行基礎 smoke 測試或端對端路徑。+7. 如果基礎狀態已損壞,先修復它。+8. 選擇優先級最高且尚未完成的功能。+9. 只處理這個功能,直到它完成驗證或被明確標記為 blocked。-## 為什麼順序不能亂+## 為什麼這個順序重要-- `pwd` 能防止在錯誤目錄裡幹活-- progress 和 feature 檔案先恢復持久狀態-- 最近提交能解釋剛剛發生了什麼-- `init.sh` 讓啟動過程標準化,而不是靠記憶-- 基礎驗證先跑,可以避免在壞狀態上繼續疊改動+- `pwd` 能避免在錯誤目錄中工作。+- 進度檔案與功能檔案會在新編輯開始前恢復持久狀態。+- 最近的提交能說明最近改了什麼。+- `init.sh` 讓啟動流程標準化,不必依賴記憶。+- 基礎驗證能在新工作掩蓋問題前,先找出損壞的起始狀態。-## 對應的收尾流程+## 工作階段結束時的對應流程-同一輪工作階段結束時,也應該鏡像地做這些事:+同一個工作階段在結束時,也應該完成下列事項:-1. 記錄進度-2. 更新功能狀態-3. 必要時寫交接摘要-4. 提交安全狀態的程式碼-5. 留下可直接重啟的乾淨環境+1. 記錄進度。+2. 更新功能狀態。+3. 需要時撰寫交接內容。+4. 提交處於安全狀態的工作。+5. 留下可直接重啟的乾淨路徑。diff --git a/docs/zh-TW/resources/reference/index.md b/docs/zh-TW/resources/reference/index.mdindex 8d01efe..7407c94 100644--- a/docs/zh-TW/resources/reference/index.md+++ b/docs/zh-TW/resources/reference/index.md@@ -1,61 +1,61 @@-# 中文參考+# 參考資料-這一部分解釋這些範本該怎麼配合使用,而不是把它們當成一堆孤立檔案。+這些說明用來解釋如何把範本組成一套可運作的執行環境,而不是把它們當成零散檔案。-## 內部參考材料+## 內部參考說明-- [`method-map.md`](./method-map.md):把常見長時任務翻車點映射到對應方法和工件-- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md):初始化代理在第一輪應該產出什麼-- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md):後續編碼代理每次開工的固定流程-- [`prompt-calibration.md`](./prompt-calibration.md):根指令應該寫到什麼程度才合適+- [`method-map.md`](./method-map.md):把常見的長時編碼代理失敗模式,對應到最先該補的工件或操作規則+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md):初始化代理在功能開發開始前,應留下哪些內容+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md):後續編碼工作固定的工作階段啟動流程+- [`prompt-calibration.md`](./prompt-calibration.md):如何讓根指令保持明確,同時避免膨脹與僵化-## 重點參考文章+## 核心文章-這裡的篩選標準很窄:只保留能直接解釋 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):代理優先的儲存庫、儲存庫在地脈絡、自訂 lint 與結構護欄。+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)(2025-11-26):初始化代理、編碼代理、功能清單、進度日誌,以及跨上下文視窗的交接。+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)(2026-03-24):planner / generator / evaluator 角色、上下文重設、執行環境簡化與過時假設。-額外只加入幾篇高相關、高價值的 2026 文章:+另外只加入少數高度相關的 2026 文章:-- [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。-- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)(2026-04-30):把 harness 當成持續迭代的產品系統,用離線評估、線上指標、工具錯誤分類、模型定製和 mid-chat model switching 改善 agent 行為。+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)(2026-01-23):Codex 執行期執行環境、工具呼叫、脈絡增長與迴圈終止。+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)(2026-01-09):把模型與執行環境一起評估,並區分 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 與自我驗證,讓編碼代理在 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):把編碼代理使用者的執行環境拆成 feedforward guides 與 feedback sensors,並區分 deterministic controls 與 inferential controls。+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)(2026-04-30):把執行環境視為持續改進的產品系統,透過離線評估、線上 metrics、工具錯誤分類、模型調校與 mid-chat model switching 改善行為。-## 2026 擴展參考+## 2026 延伸參考-這些文章不作為課程主軸,但在設計特定 harness 模組時很有借鑑價值。只保留文章正文直接涉及 agent loop、工具執行、脈絡管理、驗證、沙箱、控制層、迴歸治理等機制的材料;純 agent 產品、平臺發佈、團隊實踐或 benchmark 不放進這裡。+這些不是課程核心來源,但在設計特定執行環境模組時仍有價值。這一節只保留正文直接討論代理迴圈、工具執行、脈絡管理、驗證、沙箱、控制層或迴歸治理的來源。純產品介紹、平臺公告、團隊案例與 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 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 控制平面。-- [Anthropic: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler)(2026-02-05):並行 agent 團隊、任務鎖、git 同步、容器隔離和自主循環。-- [Anthropic: Scaling Managed Agents: Decoupling the brain from the hands](https://www.anthropic.com/engineering/managed-agents)(2026-04-08):meta-harness 視角,把 session、harness、sandbox 拆成可替換接口。-- [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem)(2026-04-23):reasoning effort、context pruning、system prompt 都屬於 harness 變更,且需要回歸治理。-- [LangChain: Context Management for Deep Agents](https://www.langchain.com/blog/context-management-for-deepagents)(2026-01-28):filesystem offloading、tool-call truncation、summarization 和 targeted evals 組成的 context-management harness。-- [LangChain: Tuning Deep Agents to Work Well with Different Models](https://www.langchain.com/blog/tuning-deep-agents-different-models)(2026-04-29):用 model-specific harness profiles 調整 prompt、tool names、middleware 和 subagent 配置。-- [LangChain: Continual learning for AI agents](https://www.langchain.com/blog/continual-learning-for-ai-agents)(2026-04-05):把 agent 改進拆成 model、harness、context 三層,並把 traces 作為改進信號。-- [Microsoft: Agent Harness in Agent Framework](https://devblogs.microsoft.com/agent-framework/agent-harness-in-agent-framework/)(2026-03-12):shell/filesystem harness、approval flow、hosted shell、context compaction。-- [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 回饋循環。-- [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 更新):用輕量分類器在關鍵決策點注入短指令,而不是把所有規則塞進系統提示詞。-- [Vercel: How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent)(2026-01-07):動態系統提示、streaming rewrite layer 和 deterministic/model-driven autofixers。-- [Vercel: Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base)(2026-05-04):面向安全掃描的 coding-agent harness,包含 scan、investigate、revalidate、enrich、export、plugin 和 refusal-checker。-- [Sourcegraph: CodeScaleBench](https://sourcegraph.com/blog/codescalebench-testing-coding-agents-on-large-codebases-and-multi-repo-software-engineering-tasks)(2026-03-03):偏 eval/tooling harness,包含 MCP tool adoption、tool-use transcripts、benchmark QA、verifier/reproducibility gates 和 prompt/preamble 迭代。+- [OpenAI: Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/)(2026-02-04):把執行環境抽象成可重用的 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):長時任務中的持久專案記憶、里程碑驗證與 done-when 範例。+- [OpenAI: The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/)(2026-04-15):模型原生的執行環境、沙箱執行與檔案/命令執行能力。+- [OpenAI: An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/)(2026-04-27):把 issue tracker 或 Linear 看板轉成多代理控制平面。+- [Anthropic: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler)(2026-02-05):平行代理團隊、任務鎖、git 同步、容器隔離與自主迴圈。+- [Anthropic: Scaling Managed Agents: Decoupling the brain from the hands](https://www.anthropic.com/engineering/managed-agents)(2026-04-08):從 meta-harness 角度,把工作階段、執行環境與沙箱拆成可替換介面。+- [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem)(2026-04-23):reasoning effort、脈絡裁剪與 system prompt 都屬於執行環境變更,且需要迴歸治理。+- [LangChain: Context Management for Deep Agents](https://www.langchain.com/blog/context-management-for-deepagents)(2026-01-28):以 filesystem offloading、tool-call truncation、summarization 與 targeted evals 建構脈絡管理執行環境。+- [LangChain: Tuning Deep Agents to Work Well with Different Models](https://www.langchain.com/blog/tuning-deep-agents-different-models)(2026-04-29):針對不同模型,以提示詞、工具名稱、middleware 與子代理設定建立專屬執行環境設定檔。+- [LangChain: Continual learning for AI agents](https://www.langchain.com/blog/continual-learning-for-ai-agents)(2026-04-05):把代理改進拆成模型、執行環境與脈絡三層,並以 traces 作為改進訊號。+- [Microsoft: Agent Harness in Agent Framework](https://devblogs.microsoft.com/agent-framework/agent-harness-in-agent-framework/)(2026-03-12):shell/filesystem 執行環境、核准流程、託管 shell 執行與脈絡壓縮。+- [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):plugins、event compaction、HITL、session/memory services 與 A2A,可作為可重用的執行環境原語。+- [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 當成代理式工作流程執行器,涵蓋 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。+- [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 隔離、自訂代理執行環境、blueprint 狀態機、規則檔案、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):雲端代理執行期的 VM 隔離、工作階段快照/恢復、協調、治理、稽核日誌與整合。+- [Cognition: Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working)(2026-04-22):generator-verifier 迴圈、乾淨脈絡 reviewer、smart-friend routing、manager-child coordination 與跨代理通訊邊界。+- [Replit: Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance)(2026-01-20,2026-01-23 更新):在決策點以輕量分類器注入短指令,而不是把所有規則塞進系統提示詞。+- [Vercel: How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent)(2026-01-07):動態系統提示詞、串流重寫層與 deterministic/model-driven 自動修復器。+- [Vercel: Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base)(2026-05-04):面向安全掃描的編碼代理執行環境,包含 scan、investigate、revalidate、enrich、export、plugin 與 refusal-checker 步驟。+- [Sourcegraph: CodeScaleBench](https://sourcegraph.com/blog/codescalebench-testing-coding-agents-on-large-codebases-and-multi-repo-software-engineering-tasks)(2026-03-03):可作為 eval/tooling 執行環境參考,涵蓋 MCP tool 採用、tool-use transcripts、benchmark QA、verifier/reproducibility gates 與 prompt/preamble 迭代。-嚴格按時間篩選時,2025-only 的泛參考不進入主列表。原始三篇中的 Anthropic 2025 文章保留,是因為它是本課程方法的基礎來源。+嚴格來說,只屬於 2025 的一般參考資料不會進入核心清單。原始的 Anthropic 2025 文章仍保留,因為它是本課程的方法基礎。-## 推薦閱讀順序+## 建議閱讀順序1. `method-map.md`2. `initializer-agent-playbook.md`diff --git a/docs/zh-TW/resources/reference/initializer-agent-playbook.md b/docs/zh-TW/resources/reference/initializer-agent-playbook.mdindex 17eae06..ad1d61a 100644--- a/docs/zh-TW/resources/reference/initializer-agent-playbook.md+++ b/docs/zh-TW/resources/reference/initializer-agent-playbook.md@@ -1,35 +1,35 @@# 初始化代理操作手冊-這個手冊用於儲存庫裡的第一輪重要工作階段,也就是正式開始增量開發之前的初始化階段。+在儲存庫中的第一個重要工作階段使用這份手冊,也就是增量功能開發開始前的階段。## 目標-先搭出穩定的工作面,讓後續工作階段不必重新推導啟動命令、目前狀態和任務邊界。+建立穩定的操作面,讓後續工作階段可以直接實作行為,不必重新推導啟動命令、目前狀態或任務邊界。-## 必需產出+## 必要產出-初始化階段至少應該留下這些工件:+初始化代理至少應留下這些工件:-- 一個根指令檔案,例如 `AGENTS.md` 或 `CLAUDE.md`-- 一個機器可讀的功能面,例如 `feature_list.json`-- 一個持久進度工件,例如 `claude-progress.md`-- 一個標準啟動輔助腳本,例如 `init.sh`-- 一個記錄基礎腳手架狀態的初始安全提交+- 根指令檔,例如 `AGENTS.md` 或 `CLAUDE.md`+- 機器可讀的功能面,例如 `feature_list.json`+- 持久的進度工件,例如 `claude-progress.md`+- 標準的啟動輔助工具,例如 `init.sh`+- 記錄基礎腳手架狀態的初始安全提交## 檢查清單-1. 定義標準啟動路徑-2. 定義標準驗證路徑-3. 建立進度日誌並寫下初始狀態-4. 把工作拆成功能,並給出狀態字段-5. 建立第一個乾淨的 baseline commit+1. 定義標準啟動路徑。+2. 定義標準驗證路徑。+3. 建立進度日誌並記錄起始狀態。+4. 把工作拆成具名功能並標註狀態。+5. 建立第一個乾淨的基準提交。-## 成功標準+## 成功測試-一個完全沒有前文聊天脈絡的新工作階段,應該能回答:+一個沒有任何先前聊天脈絡的新工作階段,應該能回答:-- 這個儲存庫是做什麼的-- 怎麼啟動-- 怎麼驗證-- 還有什麼沒做完-- 下一步最佳動作是什麼+- 這個儲存庫的用途+- 如何啟動它+- 如何驗證它+- 哪些工作尚未完成+- 下一個最佳步驟是什麼diff --git a/docs/zh-TW/resources/reference/method-map.md b/docs/zh-TW/resources/reference/method-map.mdindex 8204bdc..8ec21bd 100644--- a/docs/zh-TW/resources/reference/method-map.md+++ b/docs/zh-TW/resources/reference/method-map.md@@ -1,16 +1,16 @@# 方法對照表-這個表把最常見的長時 coding-agent 失敗模式,對應到最先該補的工件或規則。+這個表把最常見的長時編碼代理失敗模式,對應到通常最先能修正它的工件或操作規則。-| 失敗模式 | 實際表現 | 首要修復 | 主要工件 |+| 失敗模式 | 實際表現 | 首要修復 | 輔助工件 || --- | --- | --- | --- |-| 冷啟動混亂 | 新工作階段花大量時間重新摸索狀態和啟動方式 | 讓儲存庫成為唯一事實來源 | `claude-progress.md` |-| 範圍蔓延 | 一次啟動多個功能,最後沒有一個完整收尾 | 限制目前活躍範圍 | `feature_list.json` |-| 提前宣佈完成 | 程式碼改了就說“完成了”,但沒有可執行證據 | 把完成綁定到驗證證據 | `clean-state-checklist.md` |-| 啟動脆弱 | 每輪工作階段都要重新學怎麼啟動專案 | 統一啟動與驗證路徑 | `init.sh` |-| 交接薄弱 | 下一輪看不出哪裡可用、哪裡壞了、接下來做什麼 | 明確寫交接摘要 | `session-handoff.md` |-| 評審主觀 | 品質判斷依賴個人記憶和感覺 | 用固定維度做評分 | `evaluator-rubric.md` |+| 冷啟動混亂 | 新工作階段把大部分時間花在重新摸索設定與狀態 | 讓儲存庫成為事實來源 | `claude-progress.md` |+| 範圍擴散 | 代理同時啟動多個功能,最後沒有一個完整完成 | 限制目前的活躍範圍 | `feature_list.json` |+| 過早宣稱完成 | 代理改完程式碼就宣稱完成,但沒有可執行證據 | 把完成條件綁到證據 | `clean-state-checklist.md` |+| 啟動脆弱 | 每個工作階段都要重新學一次如何啟動專案 | 標準化設定與驗證 | `init.sh` |+| 交接薄弱 | 下一個工作階段無法判斷哪些內容已驗證、已損壞或接下來該做什麼 | 以明確交接結束 | `session-handoff.md` |+| 評審主觀 | 評審品質取決於個人口味或記憶 | 用固定類別評分輸出 | `evaluator-rubric.md` |-## 使用原則+## 操作原則-優先補最能直接消除目前失敗模式的那個工件,不要一出問題就把更多規則堆進一個超長 instruction 檔案裡。+先加入能直接處理目前失敗模式的最小工件。不要把每一個可靠性問題都丟進同一份全域指令檔案。diff --git a/docs/zh-TW/resources/reference/prompt-calibration.md b/docs/zh-TW/resources/reference/prompt-calibration.mdindex d966fdf..0a84c5e 100644--- a/docs/zh-TW/resources/reference/prompt-calibration.md+++ b/docs/zh-TW/resources/reference/prompt-calibration.md@@ -1,23 +1,23 @@-# Prompt 校準+# 提示詞校準-根指令檔案應該定義工作框架,而不是把所有動作寫死。+根指令應該定義操作框架,不應把每一個可能動作都寫死。-## 應該留在根檔案裡的內容+## 應保留在根檔案的內容-- 儲存庫用途和範圍+- 儲存庫用途與範圍- 啟動路徑- 驗證路徑-- 不可違反的約束-- 必需的狀態工件+- 不可協商的約束+- 必要的狀態工件- 工作階段結束規則-## 應該移出根檔案的內容+## 應移出根檔案的內容-- 過長的歷史邊角案例-- 只屬於某個子系統的細節實現說明-- 更適合貼在程式碼附近的局部架構筆記-- 只對單一模組成立的示例+- 冗長的歷史邊角案例+- 特定主題的實作細節+- 更適合放在程式碼附近的局部架構筆記+- 只適用於單一子系統的範例-## 工作原則+## 工作規則-根檔案的職責是讓新工作階段快速建立方向感。如果它開始變成“過去每次失敗都往裡加一句”的堆疊場,就應該把細節拆到更小、更明確的文件裡,再從根檔案跳轉過去。+根檔案應幫助新的工作階段快速定位方向。如果它開始變成蒐集過去所有失敗案例的地方,就把細節拆到更小的文件,再從根檔案連過去。diff --git a/docs/zh-TW/resources/templates/AGENTS.md b/docs/zh-TW/resources/templates/AGENTS.mdindex 402d602..6c6feff 100644--- a/docs/zh-TW/resources/templates/AGENTS.md+++ b/docs/zh-TW/resources/templates/AGENTS.md@@ -1,50 +1,48 @@# AGENTS.md-這個儲存庫面向長時執行的 coding agent 工作流。目標是讓每一輪工作階段結束後,下一個工作階段仍然能無猜測地繼續工作,而不是儘可能快地產出程式碼。+這個儲存庫是為長時編碼代理工作設計的。重點是讓下一個工作階段能在不靠猜測的情況下繼續推進,而非單純追求程式碼產量。-## 開工流程+## 啟動流程-寫程式碼前先做這些事:+在開始寫程式碼前:-1. 用 `pwd` 確認目前目錄。-2. 讀取 `claude-progress.md`,瞭解最新已驗證狀態和下一步。+1. 用 `pwd` 確認目前工作目錄。+2. 讀取 `claude-progress.md`,取得最新的已驗證狀態與下一步。3. 讀取 `feature_list.json`,選擇優先級最高的未完成功能。-4. 用 `git log --oneline -5` 看最近提交。+4. 用 `git log --oneline -5` 檢查最近的提交。5. 執行 `./init.sh`。-6. 在開始新功能前,先跑必需的 smoke test 或端到端驗證。+6. 在開始新工作前,先執行必要的 smoke 測試或端對端驗證。-如果基礎驗證一開始就失敗,先修基礎狀態,不要在壞的起點上繼續疊新功能。+如果基準驗證一開始就失敗,先修復它。不要在損壞的起始狀態上繼續疊加新功能。## 工作規則-- 一次只做一個功能。-- 不要因為“程式碼已經寫了”就把功能標記為完成。-- 除非為了消除目前 blocker 的窄範圍修復,否則不要擴大到其他功能。-- 實現過程中不要悄悄改弱驗證規則。-- 優先依賴儲存庫裡的持久化檔案,而不是聊天記錄。+- 一次只處理一個功能。+- 不要因為已經寫了程式碼,就把功能標記為完成。+- 除非 blocker 迫使你做一個小範圍的支援性修補,否則不要超出選定功能的範圍。+- 實作期間不要悄悄變更驗證規則。+- 優先依賴儲存庫中的持久工件,而不是聊天摘要。-## 必需檔案+## 必要工件-- `feature_list.json`:功能狀態的唯一事實來源-- `claude-progress.md`:工作階段進度和目前已驗證狀態-- `init.sh`:統一的啟動與驗證入口-- `session-handoff.md`:較長工作階段可選的交接摘要+- `feature_list.json`:功能狀態的事實來源+- `claude-progress.md`:工作階段日誌與目前已驗證狀態+- `init.sh`:標準啟動與驗證路徑+- `session-handoff.md`:較長工作階段可使用的精簡交接## 完成定義-一個功能只有在以下條件都滿足時才算完成:+一個功能只有在下列條件全部成立時,才算完成:-- 目標行為已經實現-- 要求的驗證真的跑過-- 證據記錄在 `feature_list.json` 或 `claude-progress.md`-- 儲存庫仍然能按標準啟動路徑重新開始工作+- 目標行為已完成實作+- 要求的驗證已實際執行+- 證據已記錄在 `feature_list.json` 或 `claude-progress.md`+- 儲存庫仍可沿用標準啟動路徑重新開始工作-## 收尾+## 工作階段結束前-結束工作階段前:--1. 更新 `claude-progress.md`-2. 更新 `feature_list.json`-3. 記錄仍未解決的風險或 blocker-4. 在工作處於安全狀態後,用明確的提交資訊提交-5. 保證下一輪工作階段可以直接執行 `./init.sh`+1. 更新 `claude-progress.md`。+2. 更新 `feature_list.json`。+3. 記錄任何尚未解決的風險或 blocker。+4. 在工作處於安全狀態後,以具描述性的訊息提交。+5. 讓下一個工作階段能立刻執行 `./init.sh`。diff --git a/docs/zh-TW/resources/templates/CLAUDE.md b/docs/zh-TW/resources/templates/CLAUDE.mdindex 41f0212..829efa0 100644--- a/docs/zh-TW/resources/templates/CLAUDE.md+++ b/docs/zh-TW/resources/templates/CLAUDE.md@@ -1,43 +1,43 @@# CLAUDE.md-你正在一個為長時實現工作設計的儲存庫中工作。優先保證可靠完成、跨工作階段連續性和顯式驗證,而不是表面上的速度。+你正在一個為長時實作工作設計的儲存庫中工作。請把可靠完成、跨工作階段連續性與明確驗證放在速度之前。-## 固定工作循環+## 操作迴圈-每輪工作階段開始時:+每個工作階段開始時:-1. 執行 `pwd`,確認目前在正確的儲存庫根目錄-2. 讀取 `claude-progress.md`-3. 讀取 `feature_list.json`-4. 用 `git log --oneline -5` 查看最近提交-5. 執行 `./init.sh`-6. 檢查基礎 smoke test 或端到端路徑是否已經損壞+1. 執行 `pwd`,確認你位於預期的儲存庫根目錄。+2. 讀取 `claude-progress.md`。+3. 讀取 `feature_list.json`。+4. 用 `git log --oneline -5` 檢查最近的提交。+5. 執行 `./init.sh`。+6. 檢查基準 smoke 測試或端對端路徑是否已經損壞。-然後只選擇一個未完成功能,圍繞它工作,直到它被驗證通過,或者被明確記錄為 blocked。+接著只選一個尚未完成的功能,並且只處理這個功能,直到你完成驗證,或記錄它為什麼被 blocked。## 規則-- 同一時間只能有一個 active feature-- 沒有可執行證據時,不要聲稱完成-- 不要透過重寫功能清單來隱藏未完成工作-- 不要為了“看起來完成”而刪除或削弱測試-- 以儲存庫內檔案作為唯一事實來源+- 同一時間只能有一個活躍功能。+- 沒有可執行證據時,不要宣稱完成。+- 不要藉由重寫功能清單來掩蓋未完成的工作。+- 不要為了讓任務看起來完成,就移除或削弱測試。+- 以儲存庫工件作為事實來源。-## 必需檔案+## 必要檔案- `feature_list.json`- `claude-progress.md`- `init.sh`-- 需要簡短交接時使用 `session-handoff.md`+- `session-handoff.md`,當你需要精簡交接時使用## 完成門檻-只有在要求的驗證成功且結果被記錄後,功能狀態才可以切換到 `passing`。+功能在要求的驗證成功,且結果已被記錄後,才可切換到 `passing`。-## 結束前+## 停止前-1. 更新進度日誌-2. 更新功能狀態-3. 記錄仍然損壞或未驗證的內容-4. 在儲存庫可安全恢復後提交-5. 給下一輪工作階段留下乾淨的重啟路徑+1. 更新進度日誌。+2. 更新功能狀態。+3. 記錄仍然損壞或尚未驗證的內容。+4. 在儲存庫可安全恢復後提交。+5. 留下供下一個工作階段使用的乾淨重啟路徑。diff --git a/docs/zh-TW/resources/templates/claude-progress.md b/docs/zh-TW/resources/templates/claude-progress.mdindex c927744..81797fc 100644--- a/docs/zh-TW/resources/templates/claude-progress.md+++ b/docs/zh-TW/resources/templates/claude-progress.md@@ -8,28 +8,28 @@- 目前最高優先級未完成功能:- 目前 blocker:-## 工作階段記錄+## 工作階段日誌-### Session 001+### 工作階段 001- 日期:- 本輪目標:- 已完成:- 執行過的驗證:-- 已記錄證據:+- 已擷取證據:- 提交記錄:-- 更新過的檔案或工件:+- 已更新的檔案或工件:- 已知風險或未解決問題:- 下一步最佳動作:-### Session 002+### 工作階段 002- 日期:- 本輪目標:- 已完成:- 執行過的驗證:-- 已記錄證據:+- 已擷取證據:- 提交記錄:-- 更新過的檔案或工件:+- 已更新的檔案或工件:- 已知風險或未解決問題:- 下一步最佳動作:diff --git a/docs/zh-TW/resources/templates/clean-state-checklist.md b/docs/zh-TW/resources/templates/clean-state-checklist.mdindex 566129a..c30f3b6 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 3018538..b2f83ca 100644--- a/docs/zh-TW/resources/templates/evaluator-rubric.md+++ b/docs/zh-TW/resources/templates/evaluator-rubric.md@@ -1,24 +1,24 @@# 評審評分表-在實現完成後、正式驗收前,用這張表做一次評審。+在實作完成後、正式接受前,使用這張評分表進行評審。-| 維度 | 問題 | 分數 (0-2) | 備註 |+| 維度 | 問題 | 分數(0-2) | 備註 || --- | --- | --- | --- |-| 正確性 | 實現出來的行為是否符合目標功能? | | |-| 驗證 | 要求的檢查是否真的跑過,並留下證據? | | |-| 範圍紀律 | 這一輪是否基本保持在選定功能範圍內? | | |-| 可靠性 | 結果是否能在重啟或重跑後繼續工作? | | |-| 可維護性 | 程式碼和文件是否清楚到足以交給下一輪工作階段? | | |-| 交接準備度 | 新工作階段是否能只靠儲存庫內工件繼續推進? | | |+| 正確性 | 實作出的行為是否符合要求的功能? | | |+| 驗證 | 要求的檢查是否真的執行,且附有證據? | | |+| 範圍紀律 | 這個工作階段是否留在選定功能的範圍內? | | |+| 可靠性 | 結果在重啟或重跑後,是否仍能運作而不需修復? | | |+| 可維護性 | 程式碼與文件是否足以讓下一個工作階段接手? | | |+| 交接準備度 | 新的工作階段是否能只依靠儲存庫工件繼續工作? | | |-## 結論+## 判定- Accept- Revise- Block-## 後續動作+## 必要後續動作-- 缺失的證據:-- 必須補的修復:-- 下次複審觸發條件:+- 缺少的證據:+- 必須補上的修復:+- 下次複審的觸發條件:diff --git a/docs/zh-TW/resources/templates/index.md b/docs/zh-TW/resources/templates/index.mdindex 9b9454f..85e9b44 100644--- a/docs/zh-TW/resources/templates/index.md+++ b/docs/zh-TW/resources/templates/index.md@@ -1,226 +1,226 @@-# 範本使用指南+# 範本指南-這些範本可以直接複製到你的專案裡用。每個檔案在 agent 的工作流程中各有分工。複製過去後,把裡面的命令、路徑、功能名稱和驗證步驟換成你自己專案的。+這些範本可以直接複製到你的專案中。每份文件在代理工作流程中都有明確用途。請把內容改成符合你的專案命令、路徑、功能名稱與驗證步驟。-## 怎麼開始+## 如何開始-先把這四個檔案複製到專案根目錄:+先把這四份文件複製到專案根目錄:1. `AGENTS.md` 或 `CLAUDE.md`2. `init.sh`3. `claude-progress.md`4. `feature_list.json`-等專案變複雜了,再補其餘的檔案。+隨著專案變大,再加入其餘文件。---## AGENTS.md-根指令檔案。agent 每次開工會先讀這個檔案。它定義了工作規則:寫程式碼前要做什麼、工作過程中怎麼守規矩、收尾時要檢查什麼。+這是根指令檔。代理在開始工作階段時會先讀這份文件。它定義操作規則,包括寫程式碼前要做什麼、工作期間怎麼執行,以及如何收尾。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 把開工流程裡的步驟換成你自己專案的路徑和命令-- 工作規則按你們團隊的約定調整-- 完成定義那一段別改,那是整個 harness 最關鍵的部分+- 把啟動流程的步驟換成你的實際路徑與命令+- 依照團隊慣例調整工作規則+- 保留完成定義那一節,這是整個執行環境中最重要的部分-**它幫 agent 做什麼:**+**它對代理的作用:**-- 讓它在開始工作前先讀進度和功能狀態-- 逼它一次只做一個功能-- 要求它拿出證據才能標記完成-- 定義了什麼叫「乾淨收尾」+- 要求代理在開始前先讀進度與功能狀態+- 要求代理一次只處理一個功能+- 要求代理在標記完成前提出證據+- 定義乾淨的工作階段結束狀態-用 `AGENTS.md` 給 Codex 或其他 agent。用 `CLAUDE.md` 給 Claude Code——內容一樣,格式按 Claude 的指令風格來的。+給 Codex 或其他代理使用 `AGENTS.md`。如果你使用 Claude Code,就改用 `CLAUDE.md`,結構相同,只是格式更貼近 Claude 的指令風格。## init.sh-啟動腳本。一條命令完成依賴安裝、驗證和列印啟動命令。+這是啟動腳本。它會一次完成相依安裝、驗證,並印出啟動命令。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 改頂部這三個變數:- - `INSTALL_CMD` — 你的依賴安裝命令(比如 `npm install`、`pip install -r requirements.txt`)- - `VERIFY_CMD` — 你的基礎驗證命令(比如 `npm test`、`pytest`)- - `START_CMD` — 你的開發服務器啟動命令(比如 `npm run dev`)-- 加執行權限:`chmod +x init.sh`+- 修改頂端這三個變數:+ - `INSTALL_CMD` — 你的相依安裝命令,例如 `npm install`、`pip install -r requirements.txt`+ - `VERIFY_CMD` — 你的基礎驗證命令,例如 `npm test`、`pytest`+ - `START_CMD` — 你的開發伺服器啟動命令,例如 `npm run dev`+- 加上可執行權限,`chmod +x init.sh`-**它做什麼:**+**它會做什麼:**-1. 列印目前目錄(確認跑在正確的地方)-2. 安裝依賴-3. 跑驗證命令-4. 列印啟動命令(如果設了 `RUN_START_COMMAND=1` 就直接啟動)+1. 印出目前目錄,讓你確認它在正確位置執行+2. 安裝相依套件+3. 執行驗證命令+4. 印出啟動命令;如果設定 `RUN_START_COMMAND=1`,就直接啟動-如果驗證失敗了,agent 應該停下來先修基礎狀態,不要在壞的基礎上繼續疊新功能。+如果驗證失敗,代理應先修復基準狀態,再進行其他工作。## claude-progress.md-進度日誌。每輪工作階段往裡寫,每輪新工作階段先讀它。+這是進度日誌。每個工作階段都要寫入它,每個新的工作階段也都應先讀它。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 把「目前已驗證狀態」那段填上你的專案資訊-- 每輪工作階段結束後更新工作階段記錄--**每個字段的意思:**--- **目前已驗證狀態** — 專案目前進展的唯一真相- - `儲存庫根目录` — 專案在哪- - `標準啟動路徑` — 把專案跑起來的命令- - `標準驗證路徑` — 跑測試的命令- - `当前最高優先級未完成功能` — 下一輪該做什麼- - `当前 blocker` — 哪裡卡住了-- **工作階段記錄** — 每輪一條- - `本輪目標` — 打算做什麼- - `已完成` — 實際做了什麼- - `執行過的驗證` — 跑了什麼測試- - `已記錄證據` — 留下了什麼證明- - `提交記錄` — 提了什麼 commit- - `已知风险或未解决問題` — 哪裡可能有問題- - `下一步最佳動作` — 下一輪從哪開始+- 把「目前已驗證狀態」區段填入你的專案資訊+- 每個工作階段結束後更新工作階段記錄++**各欄位代表什麼:**++- **目前已驗證狀態** — 專案目前狀態的單一事實來源+ - `儲存庫根目錄` — 專案所在位置+ - `標準啟動路徑` — 啟動專案的命令+ - `標準驗證路徑` — 執行測試的命令+ - `目前最高優先級未完成功能` — 下一個工作階段應處理的項目+ - `目前 blocker` — 目前卡住的事項+- **工作階段記錄** — 每個工作階段一筆+ - `本輪目標` — 原本打算完成的事項+ - `已完成` — 實際完成的事項+ - `執行過的驗證` — 實際執行的測試或檢查+ - `已記錄證據` — 留下的驗證證明+ - `提交記錄` — 已提交的內容+ - `已知風險或未解決問題` — 仍可能出錯的地方+ - `下一步最佳動作` — 下一個工作階段應從哪裡開始## feature_list.json-功能清單。機器可讀的功能列表,每個功能有狀態、驗證步驟和證據。+這是功能追蹤檔。它以機器可讀格式列出代理需要實作的每個功能,以及其狀態、驗證步驟與證據。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 把示例功能換成你自己的-- 每個功能需要填:- - `id` — 短的唯一標識- - `priority` — 整數,越小越優先- - `area` — 屬於應用的哪塊(比如 「chat」、「import」、「search」)+- 把示例功能換成你自己的功能+- 每個功能需要這些欄位:+ - `id` — 短而唯一的識別碼+ - `priority` — 整數,數字越小優先級越高+ - `area` — 應用程式中的區域,例如「chat」、「import」、「search」- `title` — 簡短描述- - `user_visible_behavior` — 功能正常時使用者能看到什麼- - `status` — 四種狀態之一:`not_started`、`in_progress`、`blocked`、`passing`- - `verification` — 逐步驗證步驟- - `evidence` — 驗證通過的記錄(agent 填)- - `notes` — 額外說明+ - `user_visible_behavior` — 功能正常時,使用者會看到的行為+ - `status` — `not_started`、`in_progress`、`blocked`、`passing` 其中之一+ - `verification` — 逐步確認功能是否運作的步驟+ - `evidence` — 驗證通過後記錄的證據,由代理填寫+ - `notes` — 額外脈絡**狀態規則:**-- `not_started` — 還沒碰-- `in_progress` — 目前正在做的那個(同一時間只能有一個)-- `blocked` — 有記錄的阻塞問題,推不動-- `passing` — 驗證通過,證據已記錄+- `not_started` — 尚未開始處理+- `in_progress` — 目前正在處理的唯一功能+- `blocked` — 因已記錄的問題而無法繼續+- `passing` — 驗證已通過,且證據已記錄-agent 任何時候只能有一個功能處於 `in_progress`。+代理在任何時間都只應有一個功能處於 `in_progress`。## session-handoff.md-工作階段交接摘要。一輪工作階段結束時寫,下一輪開始時讀。讓接手的人(或 agent)快速瞭解現狀。+這是一份精簡的工作階段交接。當一個工作階段結束,而你希望下一個工作階段快速接手時,就使用它。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 每輪工作階段結束時填寫(也可以讓 agent 自己填)+- 在每個工作階段結束時填寫,或由代理代填-**每段寫什麼:**+**各區段涵蓋內容:**-- **目前已驗證** — 哪些是確認能用的,跑過什麼驗證-- **本輪改動** — 改了什麼程式碼或基礎設施-- **仍損壞或未驗證** — 已知問題和風險區-- **下一步最佳動作** — 下一輪該做什麼,哪些東西不要動-- **命令** — 啟動、驗證、除錯命令,方便快速參考+- **目前已驗證** — 目前哪些內容可用,以及實際跑了哪些驗證+- **本輪改動** — 這一輪新增或修改了哪些程式碼與基礎設施+- **仍損壞或未驗證** — 已知問題與高風險區域+- **下一步最佳動作** — 下一個工作階段應做什麼,以及哪些內容不要動+- **命令** — 啟動、驗證與除錯命令,方便快速查閱-短工作階段可以不寫這個檔案。工作階段長了或者專案有多個並行區域時,它就很關鍵了。+這份文件對短工作階段是可選的。當工作階段變長,或專案同時有多個活躍區域時,它會變得重要。## clean-state-checklist.md-收尾檢查清單。每次工作階段結束前過一遍,讓儲存庫在下一輪可以直接開工。+這是一份收尾檢查清單。每個工作階段結束前都跑一遍,讓儲存庫維持在下一個工作階段可以直接接手的狀態。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 關掉工作階段前逐項檢查-- agent 的收尾流程裡也應該包含這些檢查+- 在結束工作階段前逐項檢查+- 代理的收尾流程也應包含這些項目-**檢查什麼:**+**它會檢查什麼:**-- 標準啟動路徑還能用-- 標準驗證還能跑+- 標準啟動路徑仍可使用+- 標準驗證路徑仍可執行- 進度日誌已更新-- 功能清單真實反映了 passing 和未驗證的邊界(沒有假 passing)-- 沒有半成品處於未記錄狀態-- 下一輪工作階段不需要人工修復就能繼續+- 功能清單反映真實狀態,沒有假的 `passing` 項目+- 沒有半完成的工作處於未記錄狀態+- 下一個工作階段不需要人工修復就能繼續## evaluator-rubric.md-評審評分表。工作階段結束後或到裡程碑時,用它評估 agent 做的東西夠不夠格。+這是一張用來評估代理輸出品質的評分表。你可以在工作階段結束後,或在專案里程碑時用它檢查成果是否達標。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 一輪(或幾輪)工作階段後,按六個維度打分-- 每個維度 0-2 分+- 在一個工作階段或一組工作階段後,依六個面向評分+- 每個面向採 0-2 分-**六個維度:**+**六個面向:**-1. **正確性** — 實現出來的行為是否符合目標功能-2. **驗證** — 要求的檢查是否真的跑過,並留下證據-3. **範圍紀律** — 是否基本保持在選定功能範圍內-4. **可靠性** — 結果是否能在重啟或重跑後繼續工作-5. **可維護性** — 程式碼和文件是否清楚到足以交給下一輪工作階段-6. **交接準備度** — 新工作階段是否能只靠儲存庫內檔案繼續推進+1. **正確性** — 實作是否符合目標功能+2. **驗證** — 要求的檢查是否真的執行,且有證據+3. **範圍紀律** — 代理是否留在選定功能的範圍內+4. **可靠性** — 結果在重啟或重跑後是否仍可運作+5. **可維護性** — 程式碼與文件是否足以讓下一個工作階段接手+6. **交接準備度** — 新工作階段是否能只依靠儲存庫工件繼續工作**結論選項:**-- Accept — 達標-- Revise — 需要修補才能接受-- Block — 有根本性問題,需要先解決+- Accept — 達到標準+- Revise — 需要修補後再接受+- Block — 有根本問題,必須先解決-**Evaluator 需要校準。** 開箱即用的 agent 做評審很弱——它會發現問題,然後把自己說服到通過。你需要反覆校準:+**重要,evaluator 需要調整。** 代理在預設狀態下不擅長替自己評分,它們常會先找出問題,再把自己說服成可以通過。你需要反覆調整:-1. 用 evaluator 給一個已完成的 sprint 打分。-2. 把它的分數和你自己的人工判斷對比。-3. 有分歧的地方,把 rubric 裡的通過/失敗標準寫得更具體。-4. 對同一個輸出重新跑 evaluator,看對齊了沒有。-5. 重複直到 evaluator 的判斷和人工評審基本一致。+1. 用 evaluator 評一個已完成的 sprint。+2. 把分數和你的人工判斷相比。+3. 針對分歧之處,把 rubric 的通過與失敗標準寫得更具體。+4. 重新執行,檢查是否對齊。+5. 重複直到 evaluator 的判斷穩定貼近人工評審。-預計需要 3-5 輪校準。每輪記錄改了什麼、為什麼改。+預期需要 3-5 輪調整。請記錄每一次修改,方便追蹤哪些改動讓對齊變好。## quality-document.md-品質快照。給專案的每個產品領域和架構層打分,跟蹤程式碼庫隨時間是變強了還是變弱了。+這是一份品質快照文件,用來評估專案中的每個產品領域與架構層。它追蹤的是程式碼庫長期健康度,而不是單一工作階段的輸出。-**怎麼用:**+**如何使用:**- 複製到專案根目錄-- 開始工作階段前:讀它,瞭解程式碼庫哪裡最弱-- 工作階段結束後:更新評級-- 長期:對比不同時間點的快照,看哪些 harness 改動真正改善了程式碼庫健康度+- 在工作階段開始前讀它,了解程式碼庫最弱的區域+- 在工作階段結束後依變更更新評級+- 長期比較不同時間點的快照,確認哪些執行環境改動真的改善了程式碼庫健康度-**評什麼:**+**它評估什麼:**-- **產品領域**(如文件導入、問答流程、索引):每個領域按驗證狀態、Agent 可讀性、測試穩定性、關鍵缺口打分-- **架構層**(如 Main Process、Preload、Renderer、Services):每層按邊界執行和 Agent 可讀性打分+- **產品領域**,例如文件匯入、問答流程、索引,每個領域都會依驗證狀態、代理可讀性、測試穩定性與主要缺口評級+- **架構層**,例如主程序、預載入、渲染層與服務層,每一層都會依邊界約束與代理可讀性評級-**為什麼需要它:**+**為什麼重要:**-Evaluator rubric 評的是單次 agent 輸出的品質。Quality document 評的是程式碼庫本身的品質。它們回答的是不同的問題:+evaluator rubric 評分的是單次代理輸出,quality document 評分的是程式碼庫本身。兩者回答的是不同問題:-- Evaluator rubric:「這輪 agent 做得好不好?」-- Quality document:「這個專案是在變強還是變弱?」+- Evaluator rubric:「這一輪代理做得好嗎?」+- Quality document:「這個專案長期來看是在變強,還是變弱?」-**什麼時候更新:**+**何時更新:**-- 每輪重要工作階段之後-- 做基準對比之前-- 做清理或簡化之後-- 換新 agent 或新模型時+- 每次重要工作階段之後+- 進行 benchmark 比較之前+- 完成清理或簡化後+- 專案導入新的代理或模型時-**和 harness 簡化的關係:**+**與執行環境簡化的關係:**-Quality document 也可以用來驗證 harness 是否可以簡化。Harness 裡的每個元件都編碼了一個假設,也就是「模型做不到這件事」。模型變強後,這些假設就過時了。檢查某個元件是否還有必要:+quality document 也能支援執行環境簡化。每個執行環境元件都代表一個模型做不到某件事的假設。模型能力提升後,這些假設可能失效。若要檢查某個元件是否還需要:-1. 拍一份 quality document 快照。-2. 移除一個 harness 元件。-3. 跑基準測試。-4. 再拍一份快照。-5. 對比後,評級沒降,說明那個元件是多餘的。降了,就恢復。+1. 先建立一份 quality document 快照。+2. 移除一個執行環境元件。+3. 執行 benchmark 工作集。+4. 再建立一份快照。+5. 比較結果;如果評級沒有下降,這個元件就是額外負擔。如果評級下降,就把它恢復。diff --git a/docs/zh-TW/resources/templates/quality-document.md b/docs/zh-TW/resources/templates/quality-document.mdindex ef99ba4..4a6134e 100644--- a/docs/zh-TW/resources/templates/quality-document.md+++ b/docs/zh-TW/resources/templates/quality-document.md@@ -1,43 +1,43 @@# 品質文件-每個產品領域和架構層的品質快照。agent 和人都能透過這份文件快速瞭解專案哪裡強、哪裡弱。+這份文件記錄各產品領域與架構層的品質快照。代理與人都能用它快速判斷程式碼庫的強項與弱點。-**更新時機:** 每輪重要工作階段結束後,或開始新一階段工作前。+**更新節奏:** 每次重要工作階段之後,或在開始新的工作階段前更新。**評級標準:**-- **A**:驗證全部通過,架構乾淨,agent 能讀懂,測試穩定-- **B**:驗證通過,基本乾淨,可讀性或測試覆蓋有少量缺口-- **C**:部分可用,有已知缺口,部分程式碼 agent 不容易理解-- **D**:不可用,或存在重大結構問題+- **A**:所有驗證都通過、架構乾淨、代理容易理解、測試穩定+- **B**:驗證通過,整體大致乾淨,但可讀性或測試覆蓋仍有小缺口+- **C**:部分可用,已有已知缺口,部分程式碼區域不利於代理理解+- **D**:無法運作,或存在重大結構問題---## 產品領域-| 領域 | 評級 | 驗證狀態 | Agent 可讀性 | 測試穩定性 | 關鍵缺口 | 上次更新 |-|------|------|---------|-------------|-----------|---------|---------|-| 文件導入 | - | - | - | - | - | - |+| 領域 | 評級 | 驗證狀態 | 代理可讀性 | 測試穩定性 | 主要缺口 | 上次更新 |+| --- | --- | --- | --- | --- | --- | --- |+| 文件匯入 | - | - | - | - | - | - || 文件管理 | - | - | - | - | - | - || 文件索引 | - | - | - | - | - | - || 問答流程 | - | - | - | - | - | - |-| 引用式回答 | - | - | - | - | - | - |+| 具依據的回答 | - | - | - | - | - | - |## 架構層-| 層級 | 評級 | 邊界執行 | Agent 可讀性 | 關鍵缺口 | 上次更新 |-|------|------|---------|-------------|---------|---------|-| Main Process | - | - | - | - | - |-| Preload | - | - | - | - | - |-| Renderer | - | - | - | - | - |-| Services | - | - | - | - | - |+| 層級 | 評級 | 邊界約束 | 代理可讀性 | 主要缺口 | 上次更新 |+| --- | --- | --- | --- | --- | --- |+| 主程序 | - | - | - | - | - |+| 預載入 | - | - | - | - | - |+| 渲染層 | - | - | - | - | - |+| 服務層 | - | - | - | - | - |## 變更歷史### YYYY-MM-DD-- 變更內容:-- 提升:-- 下降:-- 新發現的缺口:+- 變更:+- 提升的領域:+- 下降的領域:+- 新識別的缺口:- 已關閉的缺口:diff --git a/docs/zh-TW/resources/templates/session-handoff.md b/docs/zh-TW/resources/templates/session-handoff.mdindex 90a8bd4..2d99814 100644--- a/docs/zh-TW/resources/templates/session-handoff.md+++ b/docs/zh-TW/resources/templates/session-handoff.md@@ -2,29 +2,29 @@## 目前已驗證-- 現在明確可用的部分:-- 這輪實際跑過的驗證:+- 目前可正常運作的內容:+- 實際執行過的驗證:## 本輪改動-- 新增了哪些程式碼或行為:-- 基礎設施或 harness 發生了哪些變化:+- 新增或修改的程式碼與行為:+- 基礎設施或執行環境變更:## 仍損壞或未驗證- 已知缺陷:-- 未驗證路徑:-- 下一輪工作階段需要注意的風險:+- 尚未驗證的路徑:+- 下一個工作階段需要注意的風險:## 下一步最佳動作- 最高優先級未完成功能:-- 為什麼它是下一步:-- 什麼結果才算 passing:-- 這一步中哪些東西不要動:+- 為什麼它應該先做:+- 什麼結果算是 `passing`:+- 這一步不應變動的內容:## 命令-- 啟動命令:-- 驗證命令:-- 定向除錯命令:+- 啟動:+- 驗證:+- 聚焦除錯命令:diff --git a/docs/zh-TW/skills/index.md b/docs/zh-TW/skills/index.mdindex 20c0e0f..f7ef752 100644--- a/docs/zh-TW/skills/index.md+++ b/docs/zh-TW/skills/index.md@@ -31,11 +31,11 @@ npx skills add walkinglabs/learn-harness-engineering --skill harness-creator|------|----------|| 記憶持久化 | 代理在工作階段間遺忘專案知識 || Skill Runtime | 將可重用 workflow 打包成技能 |-| 脈絡工程 | 脈絡預算管理、按需載入、委託隔離 |-| 工具註冊 | 工具安全、併發控制、權限管道 |-| 多智慧體協調 | 平行化、專業化、研究員→實作者工作流 |+| 脈絡工程 | 脈絡預算管理、按需載入 |+| 工具註冊 | 工具安全、併發控制 |+| 多智慧體協調 | 平行化、專業化工作流 || 生命週期與引導 | 鉤子、背景任務、初始化序列 |-| 常見陷阱 | 15 個常見失敗模式及修復方案 |+| 常見陷阱 | 15 個非顯然的失敗模式及修復方案 |### 範本