範本使用指南

這些範本可以直接複製到你的項目裡用。每個檔案在 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 的指令風格來的。

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 就直接啟動）

如果驗證失敗了，agent 應該停下來先修基礎狀態，不要在壞的基礎上繼續疊新功能。

claude-progress.md

進度日誌。每輪會話往裡寫，每輪新會話先讀它。

怎麼用：

• 複製到項目根目錄
• 把"當前已驗證狀態"那段填上你的項目信息
• 每輪會話結束後更新會話記錄

每個字段的意思：

• 當前已驗證狀態 — 項目當前進展的唯一真相
  • 倉庫根目录 — 項目在哪
  • 標準啟動路徑 — 把項目跑起來的命令
  • 標準驗證路徑 — 跑測試的命令
  • 当前最高優先級未完成功能 — 下一輪該做什麼
  • 当前 blocker — 哪裡卡住了
• 會話記錄 — 每輪一條
  • 本輪目標 — 打算做什麼
  • 已完成 — 實際做了什麼
  • 執行過的驗證 — 跑了什麼測試
  • 已記錄證據 — 留下了什麼證明
  • 提交記錄 — 提了什麼 commit
  • 已知风险或未解决問題 — 哪裡可能有問題
  • 下一步最佳動作 — 下一輪從哪開始

feature_list.json

功能清單。機器可讀的功能列表，每個功能有狀態、驗證步驟和證據。

怎麼用：

• 複製到項目根目錄
• 把示例功能換成你自己的
• 每個功能需要填：
  • id — 短的唯一標識
  • priority — 整數，越小越優先
  • area — 屬於應用的哪塊（比如 "chat"、"import"、"search"）
  • title — 簡短描述
  • user_visible_behavior — 功能正常時用戶能看到什麼
  • status — 四種狀態之一：not_started、in_progress、blocked、passing
  • verification — 逐步驗證步驟
  • evidence — 驗證通過的記錄（agent 填）
  • notes — 額外說明

狀態規則：

• not_started — 還沒碰
• in_progress — 當前正在做的那個（同一時間只能有一個）
• blocked — 有記錄的阻塞問題，推不動
• passing — 驗證通過，證據已記錄

agent 任何時候只能有一個功能處於 in_progress。

session-handoff.md

會話交接摘要。一輪會話結束時寫，下一輪開始時讀。讓接手的人（或 agent）快速瞭解現狀。

怎麼用：

• 複製到項目根目錄
• 每輪會話結束時填寫（也可以讓 agent 自己填）

每段寫什麼：

• 當前已驗證 — 哪些是確認能用的，跑過什麼驗證
• 本輪改動 — 改了什麼代碼或基礎設施
• 仍損壞或未驗證 — 已知問題和風險區
• 下一步最佳動作 — 下一輪該做什麼，哪些東西不要動
• 命令 — 啟動、驗證、調試命令，方便快速參考

短會話可以不寫這個檔案。會話長了或者項目有多個並行區域時，它就很關鍵了。

clean-state-checklist.md

收尾檢查清單。每次會話結束前過一遍，確保倉庫處於下一輪可以直接開工的狀態。

怎麼用：

• 複製到項目根目錄
• 關掉會話前逐項檢查
• agent 的收尾流程裡也應該包含這些檢查

檢查什麼：

• 標準啟動路徑還能用
• 標準驗證還能跑
• 進度日誌已更新
• 功能清單真實反映了 passing 和未驗證的邊界（沒有假 passing）
• 沒有半成品處於未記錄狀態
• 下一輪會話不需要人工修復就能繼續

evaluator-rubric.md

評審評分表。會話結束後或到裡程碑時，用它評估 agent 做的東西夠不夠格。

怎麼用：

• 複製到項目根目錄
• 一輪（或幾輪）會話後，按六個維度打分
• 每個維度 0-2 分

六個維度：

1. 正確性 — 實現出來的行為是否符合目標功能
2. 驗證 — 要求的檢查是否真的跑過，並留下證據
3. 範圍紀律 — 是否基本保持在選定功能範圍內
4. 可靠性 — 結果是否能在重啟或重跑後繼續工作
5. 可維護性 — 代碼和文檔是否清楚到足以交給下一輪會話
6. 交接準備度 — 新會話是否能只靠倉庫內檔案繼續推進

結論選項：

• Accept — 達標
• Revise — 需要修補才能接受
• Block — 有根本性問題，需要先解決

Evaluator 需要校準。 開箱即用的 agent 做評審很弱——它會發現問題，然後把自己說服到通過。你需要反覆校準：

1. 用 evaluator 給一個已完成的 sprint 打分。
2. 把它的分數和你自己的人工判斷對比。
3. 有分歧的地方，把 rubric 裡的通過/失敗標準寫得更具體。
4. 對同一個輸出重新跑 evaluator，看對齊了沒有。
5. 重複直到 evaluator 的判斷和人工評審基本一致。

預計需要 3-5 輪校準。每輪記錄改了什麼、為什麼改。

quality-document.md

質量快照。給項目的每個產品領域和架構層打分，跟蹤代碼庫隨時間是變強了還是變弱了。

怎麼用：

• 複製到項目根目錄
• 開始會話前：讀它，瞭解代碼庫哪裡最弱
• 會話結束後：更新評級
• 長期：對比不同時間點的快照，看哪些 harness 改動真正改善了代碼庫健康度

評什麼：

• 產品領域（如文檔導入、問答流程、索引）：每個領域按驗證狀態、Agent 可讀性、測試穩定性、關鍵缺口打分
• 架構層（如 Main Process、Preload、Renderer、Services）：每層按邊界執行和 Agent 可讀性打分

為什麼需要它：

Evaluator rubric 評的是單次 agent 輸出的質量。Quality document 評的是代碼庫本身的質量。它們回答的是不同的問題：

• Evaluator rubric："這輪 agent 做得好不好？"
• Quality document："這個項目是在變強還是變弱？"

什麼時候更新：

• 每輪重要會話之後
• 做基準對比之前
• 做清理或簡化之後
• 換新 agent 或新模型時

和 harness 簡化的關係：

Quality document 也可以用來驗證 harness 是否可以簡化。Harness 裡的每個組件都編碼了一個假設——"模型做不到這件事"。模型變強後，這些假設就過時了。檢查某個組件是否還有必要：

1. 拍一份 quality document 快照。
2. 移除一個 harness 組件。
3. 跑基準測試。
4. 再拍一份快照。
5. 對比——評級沒降，說明那個組件是多餘的。降了，就恢復。