中級：從對話管理升級成 repo 管理
當四個習慣不夠用，你需要把規則從腦袋裡搬回 repo，讓 agent 不靠外部口頭上下文也能繼續工作。
情境：第 47 次跟同事解釋 AI 不能改 migration
你的團隊終於開始認真用 Claude Code / Cursor / Codex 做事。但你發現自己每天都在 Slack 打同一段話：
「記得叫它不要改 migrations/ 下面的檔案。也不能改 API response schema。測試一定要跑過才能交。」
這句話你已經講 47 次了。新人進來還是不知道。AI 每次開新 session 也是從零開始。
這就是中級最常見的訊號：你手上有規則，但規則從來沒進入 agent 的工作環境。中級的解法只有一個 — 把規則寫回 repo。
OpenAI 在 2026 的實戰裡最值得注意的一點：他們把 plan、進度、decision log、technical debt 都視為一級工件，版本化後放回 repo，讓 agent 不依賴外部口頭上下文也能繼續工作。
一、中級要建立三種關鍵能力
| 能力 | 核心問題 | 代表產物 |
|---|---|---|
| 規則檔 | 怎麼把人腦裡的規則變成 agent 可讀的上下文 | AGENTS.md / CLAUDE.md / .cursorrules |
| Tool boundary | 怎麼讓 agent 知道自己能碰哪裡 | 權限分級表、approval 清單 |
| Verification loop | 怎麼固定迴圈、不靠臨場發揮 | 修改 → 測試 → 讀錯 → 修正 → 重跑 |
這三件事加起來，就是「從聊天對象變成可持續工作的 agent」的門票。
二、規則檔：把經驗寫進 repo
最典型的幾個檔名你一定會聽到：
AGENTS.mdCLAUDE.md.cursorrulestasks/、plans/、decision-log/
這些不是文件管理工具，它們是把「本來靠人腦記的事」轉成 agent 可讀的固定上下文。
一份最小可用的 AGENTS.md 長這樣：
# AGENTS.md
## Repo map
- app/: FastAPI app
- tests/: pytest tests
- scripts/: local automation
## Commands
- dev: uvicorn app.main:app --reload
- lint: ruff check .
- format: ruff format .
- test: pytest -q
## Rules
- Do not edit migrations/ unless task explicitly asks.
- Do not change API schema without tests and docs.
- Always run lint + test before done.
- Summarize root cause before final response.
## Approval required
- delete files
- edit infra config
- change production secrets references
注意四個重點：
- Repo map — 讓 agent 知道這個 repo 有什麼。
- Commands — 讓 agent 用你統一指定的命令，而不是自己猜。
- Rules — 寫成祈使句，不要寫精神標語。
- Approval required — 明確列出哪些事必須先問人。
這份檔放進 repo 之後，agent 每次開新 session 都會看到，你就不用再在 Slack 重複第 48 次了。
三、Tool boundary：能力邊界即安全邊界
中級最起碼要做到這樣的權限分類：
| 類型 | 例子 | 風險 |
|---|---|---|
| Read-only | 搜檔、看 log、讀 DB schema | 低 |
| Write-safe | 修改 app/、tests/、docs/ | 中 |
| Destructive | 刪檔、改 migration、drop data | 高 |
| External side-effect | deploy、發 Slack、叫 API | 高 |
這個分類在 2026 的 agent harness 實戰文章中反覆出現，因為很多真實事故都不是「模型太笨」，而是工具暴露太多、沒有權限分級。
實作上，你至少要回答這三個問題：
- 哪些工具是常駐可用的（read-only、write-safe）？
- 哪些工具需要明確 approval（destructive、external side-effect）？
- 哪些工具根本不該讓 agent 碰（production secrets、金流、刪資料）？
四、Verification loop：固定迴圈，不靠臨場發揮
中級最實用的 loop 長這樣：
1. 理解任務
2. 列計畫
3. 執行修改
4. 執行測試 / lint / type check
5. 收集錯誤
6. 分析 root cause
7. 修正後重跑
8. 超過 N 次失敗則升級給人
第 8 步是最容易被忽略、但最重要的一步。沒有 escalation 條件，agent 就會無限打轉 — 有時候連跑 20 次重試還卡在同一個錯誤，token 燒掉你半天的預算。
實務上 escalation 條件可以是：
- 失敗次數上限：連續 3 次同類型錯誤就升級。
- 時間上限：超過 30 分鐘沒完成就升級。
- 成本上限：token 用量超過 X 就升級。
- 信心度不足：agent 自己表達「我不確定該怎麼做」就升級。
五、一份最小可行的中級 Harness 範例
假設你在維護一個 FastAPI 的電商訂單服務，你的中級 harness 可以長這樣：
1. AGENTS.md（前面已經給過範例，這裡是專案實際版）
# AGENTS.md — orders-service
## Repo map
- app/: FastAPI app
- app/routers/: API endpoints（含 /orders、/products、/checkout）
- app/models/: Pydantic models
- tests/: pytest tests
- migrations/: Alembic migrations（agent 不可改）
## Commands
- dev: uvicorn app.main:app --reload
- lint: ruff check .
- test: pytest -q
- test-one: pytest -q -k
## Rules
- 只能改 app/ 與 tests/。
- 不可改 API response schema（會影響前端合約）。
- 任何修改都必須有對應 regression test。
- 完成前必須執行 lint + test，兩者都綠才算 done。
- 完成後必須說明 root cause。
## Approval required
- 改 migrations/
- 改 .env / docker-compose.yml
- 任何涉及 payment provider 的改動
2. 任務模板
Goal: 修復 /orders API 空購物車時回 500 的錯誤
Constraints:
- 只能修改 app/ 與 tests/
- 不可修改 API response schema
- 必須新增一個針對空購物車情境的 regression test
Definition of done:
- pytest 全綠
- ruff check 全綠
- 說明 root cause
- 列出改動過的檔案清單
3. Verification loop（寫進 agent 的 system prompt 或 skill）
每次任務：
1. 先讀 AGENTS.md 與相關檔案。
2. 列計畫給人看，等確認。
3. 執行修改。
4. 跑 lint + test。
5. 如果失敗：分析 root cause、修正、重跑（最多 3 次）。
6. 3 次仍失敗：停下、整理目前狀況、請人介入。
這三樣加起來，已經不是單純的 prompt，而是一個最小可行的 project harness。
六、中級常見誤區
- 規則散在 Slack / Notion，不寫回 repo — agent 每次都會重新失憶。
- 工具放太多 — Vercel 與社群案例都顯示：工具變少反而更穩。
- 規則只寫原則，不寫命令 — agent 要的是「可執行的資訊」，不是「精神標語」。
- 沒有 escalation 條件 — 失敗次數、成本、時間上限不定義，agent 就會無限打轉。
特別提醒一下第 2 點：你的直覺通常會想給 agent 更多工具，讓它更強大。但實戰經驗一再證明，工具越少反而越穩定。多的工具 = 多的誤用機會 = 多的 token 浪費。
AI 協作：學了這個，跟 AI 怎麼配合？
中級的關鍵是讓 agent 有一個「共同的工作環境」，而不是每次都從零開始。你花在寫 AGENTS.md 的 30 分鐘，會在接下來三個月幫你省下幾十小時的重複溝通。
你的人類優勢：
- 只有你知道這個 repo 的歷史包袱、哪些檔案「看起來可以改但其實動不得」。
- 只有你知道團隊的 approval 流程與真正在意的風險點。
可以這樣跟 AI 說：
我要為一個 [專案類型] 的 repo 寫第一版 AGENTS.md。請基於以下資訊產出草稿：[貼上 repo 結構、常用命令、已知禁區]。寫完後請列出 5 個你會想問我但我沒告訴你的問題（例如 approval 門檻、escalation 條件），而不是自己猜。
練習題
本堂重點回顧
- 規則必須寫回 repo：
AGENTS.md/CLAUDE.md不是文件，是 agent 的工作環境。 - Tool boundary：能力邊界即安全邊界，預設走嚴格比較安全。
- Verification loop：固定流程 + escalation 條件 — 沒有 escalation，agent 就會燒錢打轉。
- 工具越少越穩定：你的直覺會想加工具，實戰會叫你刪工具。
下堂課：進階 — 當 agent 真的開始跑，你會需要 middleware、state、observability 這三樣東西，讓系統從「會跑」變成「可追、可修、可優化」。
挑戰任務
挑一個你現在正在維護（或維護過）的專案，寫一份最小可行的 AGENTS.md。至少包含 Repo map、Commands、Rules、Approval required 四個區塊。Rules 至少 5 條，Approval required 至少 3 條。
為你的 agent 設計一份 tool boundary 表，至少涵蓋 read-only、write-safe、destructive、external side-effect 四類。每類至少列 2 個具體工具或操作，並標註「預設可用 / 需 approval / 禁止」。
為你的 agent 定義至少 3 條 escalation 條件。每一條寫清楚：(1) 觸發情境、(2) 觸發時 agent 要做什麼、(3) 你期待人介入時看到什麼資訊。