Skip to content

Harness engineering beginner tutorial, from 0 to 1

fix: zh-TW translation residue in Lecture 04 (#72)

Alec Chen0aa032d24bf8
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.md
index 94591c2..4dcec63 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
@@ -23,7 +23,7 @@
**維護衰減。** 大檔案天生難維護。指令過時了沒人刪,因為刪除的後果不確定(「也許別的地方依賴這條規則?」),但加新指令是無成本的。結果檔案只增不減,信噪比持續下降。這和軟體裡的技術債務積累一模一樣。
-**矛盾累積。** 不同時期加的指令之間開始出現矛盾,一條說「用 TypeScript 嚴格模式」,另一條說「某些遺留檔案允許用 any」。Agent 每次隨機選一條遵循。Agent 每次碰到矛盾指令只能隨機選一條遵循。
+**矛盾累積。** 不同時期加的指令之間開始出現矛盾,一條說「用 TypeScript 嚴格模式」,另一條說「某些遺留檔案允許用 any」。Agent 每次隨機選一條遵循。
## 核心概念
@@ -49,17 +49,17 @@ flowchart LR
flowchart TB
File["600 行指令檔案"] --> Top["頂部<br/>快速開始 + 硬約束"]
File --> Mid["中部<br/>第 300 行的安全規則"]
- File --> Bot["底部<br/>明确的結束檢查清單"]
- Top --> Seen["高概率被记住"]
+ File --> Bot["底部<br/>明確的結束檢查清單"]
+ Top --> Seen["高機率被記住"]
Bot --> Seen
- Mid --> Missed["高概率被稀释或忽略"]
+ Mid --> Missed["高機率被稀釋或忽略"]
```
## 拆分思路
核心原則,常用資訊放手邊,偶爾用的收起來,用不上的別帶。
-入口檔案 `AGENTS.md` 控制在 50-200 行,只放最常用的東西,專案概覽(一兩句話說清楚這是什麼)、首次執行命令(`make setup && make test`)、全域硬約束(不超過 15 條不可違反的規則)、指向專題文件的連結(一行描述 + 適用條件)。
+入口檔案 `AGENTS.md` 控制在 50-200 行,只放最常用的東西,專案概覽(一兩句話說清楚這是什麼)、首次執行命令(`make setup && make test`)、全域硬約束(不超過 15 條不可違反的規則)、指向主題文件的連結(一行描述 + 適用條件)。
```markdown
# AGENTS.md
@@ -77,19 +77,19 @@ Python 3.11 FastAPI 後端,PostgreSQL 15 資料庫。
- 所有資料庫查詢必須用 SQLAlchemy 2.0 語法
- 所有 PR 必須通過 pytest + mypy --strict + ruff check
-## 專題文件
+## 主題文件
- API 設計規範 (`docs/api-patterns.md`) — 添加新端點時必讀
- 資料庫操作約束 (`docs/database-rules.md`) — 涉及資料庫修改時必讀
-- 測試標準 (`docs/testing-standards.md`) — 编寫測試時参考
+- 測試標準 (`docs/testing-standards.md`) — 編寫測試時參考
```
-每個專題文件 50-150 行,按主題放在 `docs/` 目錄下或對應模組目錄旁。Agent 只在需要時才去讀。找東西不用翻整份文件。
+每個主題文件 50-150 行,按主題放在 `docs/` 目錄下或對應模組目錄旁。Agent 只在需要時才去讀。找東西不用翻整份文件。
還有些資訊直接放在程式碼裡更合適,類型定義、介面註釋、配置檔案裡的說明。Agent 讀程式碼的時候自然能看到,不用再在指令裡重複一遍。
每條指令都應該標明來源(「為什麼加這條規則?」)、適用條件(「這條規則在什麼時候需要?」)、過期條件(「什麼情況下可以刪掉這條規則?」)。定期審計,刪掉過時的、冗餘的、矛盾的條目。像管理程式碼依賴一樣管理你的指令,用不上的依賴就該刪掉,不然它們只會拖慢系統。
-如果某條指令必須在入口檔案裡,放頂部或底部,不要放中間。「中間迷失」效應告訴我們,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。但更好的做法是把指令放到專題文件裡,讓 agent 按需加載。
+如果某條指令必須在入口檔案裡,放頂部或底部,不要放中間。「中間迷失」效應告訴我們,LLM 對長文字中間部分的資訊利用效率顯著低於兩端。但更好的做法是把指令放到主題文件裡,讓 agent 按需加載。
OpenAI 和 Anthropic 都隱性支援拆分的做法。OpenAI 說入口檔案應「短小且以路由為導向」,Anthropic 說長執行 agent 的控制資訊應「簡潔且高優先級」。兩家都在說同一件事,別把什麼都塞進一個檔案裡。
@@ -101,17 +101,17 @@ Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量脈
團隊執行了文件重組:
1. `AGENTS.md` 裁剪到 80 行:只保留專案概覽、執行命令、15 條全域硬約束
-2. 建立專題文件:`docs/api-patterns.md`(120 行)、`docs/database-rules.md`(60 行)、`docs/testing-standards.md`(80 行)
-3. 路由檔案添加指向專題文件的連結
-4. 歷史筆記要麼轉成測試用例,要麼刪除
+2. 建立主題文件:`docs/api-patterns.md`(120 行)、`docs/database-rules.md`(60 行)、`docs/testing-standards.md`(80 行)
+3. 路由檔案添加指向主題文件的連結
+4. 歷史筆記要嘛轉成測試用例,要嘛刪除
重構後:同一任務集的成功率從 45% 提升到 72%。安全約束遵循率從 60% 提升到 95%,因為從檔案中間移到了路由檔案頂部,不再被「中間迷失」了。
## 關鍵要點
-- 「加條規則」是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放專題文件是不是更合適?,別把所有規則都堆進入口文件。
+- 「加條規則」是短期的止痛藥,長期的毒藥。每次加規則前想想:這條規則放主題文件是不是更合適。
- 入口檔案是路由器,不是百科全書。50-200 行,只放概覽、硬約束、和連結。
-- 利用「中間迷失」效應:重要資訊放檔案頂部或底部,不重要的移到專題文件。
+- 利用「中間迷失」效應:重要資訊放檔案頂部或底部,不重要的移到主題文件。
- 像管理技術債一樣管理指令膨脹。定期審計,每條指令要有來源、適用條件、和過期條件。
- 拆分之後信噪比提升,agent 把更多脈絡預算花在實際任務上,而不是處理無關指令。
@@ -125,8 +125,8 @@ Agent 表現開始明顯下降:簡單 bug 修復任務中 agent 花大量脈
## 練習
-1. **信噪比審計**:拿你目前的入口指令檔案,列出所有指令條目。選 5 個不同的常見任務類型,標註每條指令是否跟該任務相關。計算每個任務類型的 SNR。那些對大多數任務都是噪聲的指令,移到專題文件裡。
+1. **信噪比審計**:拿你目前的入口指令檔案,列出所有指令條目。選 5 個不同的常見任務類型,標註每條指令是否跟該任務相關。計算每個任務類型的 SNR。那些對大多數任務都是噪聲的指令,移到主題文件裡。
-2. **漸進式披露重構**:如果你有一個超過 300 行的指令檔案,把它拆成:(a) 不超過 100 行的路由檔案,(b) 3-5 個專題文件。重構前後各跑同一組任務(至少 5 個),對比成功率。
+2. **漸進式披露重構**:如果你有一個超過 300 行的指令檔案,把它拆成:(a) 不超過 100 行的路由檔案,(b) 3-5 個主題文件。重構前後各跑同一組任務(至少 5 個),對比成功率。
3. **中間迷失驗證**:在一個長指令檔案裡,把一條關鍵約束分別放在頂部、中間、底部各跑一組任務(每組至少 5 次),看遵循率有沒有差別。你可能會驚訝於位置效應有多大。