範本指南

這些範本可以直接複製到你的專案中。每份文件在代理工作流程中都有明確用途。請把內容改成符合你的專案命令、路徑、功能名稱與驗證步驟。

如何開始

先把這四份文件複製到專案根目錄：

1. AGENTS.md 或 CLAUDE.md
2. init.sh
3. claude-progress.md
4. feature_list.json

隨著專案變大，再加入其餘文件。

---

AGENTS.md

這是根指令檔。代理在開始工作階段時會先讀這份文件。它定義操作規則，包括寫程式碼前要做什麼、工作期間怎麼執行，以及如何收尾。

如何使用：

• 複製到專案根目錄
• 把啟動流程的步驟換成你的實際路徑與命令
• 依照團隊慣例調整工作規則
• 保留完成定義那一節，這是整個執行環境中最重要的部分

它對代理的作用：

• 要求代理在開始前先讀進度與功能狀態
• 要求代理一次只處理一個功能
• 要求代理在標記完成前提出證據
• 定義乾淨的工作階段結束狀態

給 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

它會做什麼：

1. 印出目前目錄，讓你確認它在正確位置執行
2. 安裝相依套件
3. 執行驗證命令
4. 印出啟動命令；如果設定 RUN_START_COMMAND=1，就直接啟動

如果驗證失敗，代理應先修復基準狀態，再進行其他工作。

claude-progress.md

這是進度日誌。每個工作階段都要寫入它，每個新的工作階段也都應先讀它。

如何使用：

• 複製到專案根目錄
• 把「目前已驗證狀態」區段填入你的專案資訊
• 每個工作階段結束後更新工作階段記錄

各欄位代表什麼：

• 目前已驗證狀態 — 專案目前狀態的單一事實來源
  • 儲存庫根目錄 — 專案所在位置
  • 標準啟動路徑 — 啟動專案的命令
  • 標準驗證路徑 — 執行測試的命令
  • 目前最高優先級未完成功能 — 下一個工作階段應處理的項目
  • 目前 blocker — 目前卡住的事項
• 工作階段記錄 — 每個工作階段一筆
  • 本輪目標 — 原本打算完成的事項
  • 已完成 — 實際完成的事項
  • 執行過的驗證 — 實際執行的測試或檢查
  • 已記錄證據 — 留下的驗證證明
  • 提交記錄 — 已提交的內容
  • 已知風險或未解決問題 — 仍可能出錯的地方
  • 下一步最佳動作 — 下一個工作階段應從哪裡開始

feature_list.json

這是功能追蹤檔。它以機器可讀格式列出代理需要實作的每個功能，以及其狀態、驗證步驟與證據。

如何使用：

• 複製到專案根目錄
• 把示例功能換成你自己的功能
• 每個功能需要這些欄位：
  • id — 短而唯一的識別碼
  • priority — 整數，數字越小優先級越高
  • area — 應用程式中的區域，例如「chat」、「import」、「search」
  • title — 簡短描述
  • user_visible_behavior — 功能正常時，使用者會看到的行為
  • status — not_started、in_progress、blocked、passing 其中之一
  • verification — 逐步確認功能是否運作的步驟
  • evidence — 驗證通過後記錄的證據，由代理填寫
  • notes — 額外脈絡

狀態規則：

• not_started — 尚未開始處理
• in_progress — 目前正在處理的唯一功能
• blocked — 因已記錄的問題而無法繼續
• passing — 驗證已通過，且證據已記錄

代理在任何時間都只應有一個功能處於 in_progress。

session-handoff.md

這是一份精簡的工作階段交接。當一個工作階段結束，而你希望下一個工作階段快速接手時，就使用它。

如何使用：

• 複製到專案根目錄
• 在每個工作階段結束時填寫，或由代理代填

各區段涵蓋內容：

• 目前已驗證 — 目前哪些內容可用，以及實際跑了哪些驗證
• 本輪改動 — 這一輪新增或修改了哪些程式碼與基礎設施
• 仍損壞或未驗證 — 已知問題與高風險區域
• 下一步最佳動作 — 下一個工作階段應做什麼，以及哪些內容不要動
• 命令 — 啟動、驗證與除錯命令，方便快速查閱

這份文件對短工作階段是可選的。當工作階段變長，或專案同時有多個活躍區域時，它會變得重要。

clean-state-checklist.md

這是一份收尾檢查清單。每個工作階段結束前都跑一遍，讓儲存庫維持在下一個工作階段可以直接接手的狀態。

如何使用：

• 複製到專案根目錄
• 在結束工作階段前逐項檢查
• 代理的收尾流程也應包含這些項目

它會檢查什麼：

• 標準啟動路徑仍可使用
• 標準驗證路徑仍可執行
• 進度日誌已更新
• 功能清單反映真實狀態，沒有假的 passing 項目
• 沒有半完成的工作處於未記錄狀態
• 下一個工作階段不需要人工修復就能繼續

evaluator-rubric.md

這是一張用來評估代理輸出品質的評分表。你可以在工作階段結束後，或在專案里程碑時用它檢查成果是否達標。

如何使用：

• 複製到專案根目錄
• 在一個工作階段或一組工作階段後，依六個面向評分
• 每個面向採 0-2 分

六個面向：

1. 正確性 — 實作是否符合目標功能
2. 驗證 — 要求的檢查是否真的執行，且有證據
3. 範圍紀律 — 代理是否留在選定功能的範圍內
4. 可靠性 — 結果在重啟或重跑後是否仍可運作
5. 可維護性 — 程式碼與文件是否足以讓下一個工作階段接手
6. 交接準備度 — 新工作階段是否能只依靠儲存庫工件繼續工作

結論選項：

• Accept — 達到標準
• Revise — 需要修補後再接受
• Block — 有根本問題，必須先解決

重要，evaluator 需要調整。 代理在預設狀態下不擅長替自己評分，它們常會先找出問題，再把自己說服成可以通過。你需要反覆調整：

1. 用 evaluator 評一個已完成的 sprint。
2. 把分數和你的人工判斷相比。
3. 針對分歧之處，把 rubric 的通過與失敗標準寫得更具體。
4. 重新執行，檢查是否對齊。
5. 重複直到 evaluator 的判斷穩定貼近人工評審。

預期需要 3-5 輪調整。請記錄每一次修改，方便追蹤哪些改動讓對齊變好。

quality-document.md

這是一份品質快照文件，用來評估專案中的每個產品領域與架構層。它追蹤的是程式碼庫長期健康度，而不是單一工作階段的輸出。

如何使用：

• 複製到專案根目錄
• 在工作階段開始前讀它，了解程式碼庫最弱的區域
• 在工作階段結束後依變更更新評級
• 長期比較不同時間點的快照，確認哪些執行環境改動真的改善了程式碼庫健康度

它評估什麼：

• 產品領域，例如文件匯入、問答流程、索引，每個領域都會依驗證狀態、代理可讀性、測試穩定性與主要缺口評級
• 架構層，例如主程序、預載入、渲染層與服務層，每一層都會依邊界約束與代理可讀性評級

為什麼重要：

evaluator rubric 評分的是單次代理輸出，quality document 評分的是程式碼庫本身。兩者回答的是不同問題：

• Evaluator rubric：「這一輪代理做得好嗎？」
• Quality document：「這個專案長期來看是在變強，還是變弱？」

何時更新：

• 每次重要工作階段之後
• 進行 benchmark 比較之前
• 完成清理或簡化後
• 專案導入新的代理或模型時

與執行環境簡化的關係：

quality document 也能支援執行環境簡化。每個執行環境元件都代表一個模型做不到某件事的假設。模型能力提升後，這些假設可能失效。若要檢查某個元件是否還需要：

1. 先建立一份 quality document 快照。
2. 移除一個執行環境元件。
3. 執行 benchmark 工作集。
4. 再建立一份快照。
5. 比較結果；如果評級沒有下降，這個元件就是額外負擔。如果評級下降，就把它恢復。