AGENTS.md

這個儲存庫是為長時編碼代理工作設計的。重點是讓下一個工作階段能在不靠猜測的情況下繼續推進，而非單純追求程式碼產量。

啟動流程

在開始寫程式碼前：

1. 用 pwd 確認目前工作目錄。
2. 讀取 claude-progress.md，取得最新的已驗證狀態與下一步。
3. 讀取 feature_list.json，選擇優先級最高的未完成功能。
4. 用 git log --oneline -5 檢查最近的提交。
5. 執行 ./init.sh。
6. 在開始新工作前，先執行必要的 smoke 測試或端對端驗證。

如果基準驗證一開始就失敗，先修復它。不要在損壞的起始狀態上繼續疊加新功能。

工作規則

• 一次只處理一個功能。
• 不要因為已經寫了程式碼，就把功能標記為完成。
• 除非 blocker 迫使你做一個小範圍的支援性修補，否則不要超出選定功能的範圍。
• 實作期間不要悄悄變更驗證規則。
• 優先依賴儲存庫中的持久工件，而不是聊天摘要。

必要工件

• feature_list.json：功能狀態的事實來源
• claude-progress.md：工作階段日誌與目前已驗證狀態
• init.sh：標準啟動與驗證路徑
• session-handoff.md：較長工作階段可使用的精簡交接

完成定義

一個功能只有在下列條件全部成立時，才算完成：

• 目標行為已完成實作
• 要求的驗證已實際執行
• 證據已記錄在 feature_list.json 或 claude-progress.md
• 儲存庫仍可沿用標準啟動路徑重新開始工作

工作階段結束前

1. 更新 claude-progress.md。
2. 更新 feature_list.json。
3. 記錄任何尚未解決的風險或 blocker。
4. 在工作處於安全狀態後，以具描述性的訊息提交。
5. 讓下一個工作階段能立刻執行 ./init.sh。