Imported from skogai/harness (.docs/harness-engineering/docs/zh-TW/resources/openai-advanced/repo-template/AGENTS.md). Install upstream with npx skills add skogai/harness --skill repo-template. Copyright stays with the author.

AGENTS.md

這個儲存庫針對長時間執行的程式設計代理工作做了最佳化。保持這個檔案簡短。把它當成通往系統記錄文件的路由層，不要把所有指令都堆在這裡。

開工流程

改動程式碼前，先做這些事：

1. 用 pwd 確認儲存庫根目錄。
2. 讀取 ARCHITECTURE.md，了解目前的系統地圖與硬性相依規則。
3. 讀取 docs/QUALITY_SCORE.md，確認目前最弱的領域或分層。
4. 讀取 docs/PLANS.md，再打開你目前依循的進行中計畫。
5. 讀取 docs/product-specs/ 內相關的產品規格。
6. 執行這個儲存庫的標準啟動與驗證流程。
7. 如果基線驗證失敗，先修復基線，再新增範圍。

路由地圖

• ARCHITECTURE.md：領域地圖、分層模型、相依規則
• docs/design-docs/index.md：設計決策與核心信念
• docs/product-specs/index.md：目前產品行為與驗收目標
• docs/PLANS.md：計畫生命週期與執行計畫政策
• docs/QUALITY_SCORE.md：產品領域與分層健康度
• docs/RELIABILITY.md：執行訊號、基準與重新啟動要求
• docs/SECURITY.md：密鑰、沙箱、資料與外部動作規則
• docs/FRONTEND.md：UI 約束、設計系統規則與無障礙檢查

工作約定

• 一次只處理一個有邊界的計畫或功能切片。
• 不要只靠閱讀程式碼就判定完成，必須有可執行的證據。
• 如果你改動了行為，就在同一個工作階段更新對應的產品、計畫或可靠性文件。
• 如果某類 review feedback 反覆出現，就把它升級成機械規則、檢查或 linter，不要在聊天裡重複解釋。
• 把產生物放在 docs/generated/，把來源參考資料放在 docs/references/。
• 優先新增小而且保持最新的文件，不要持續擴大這個檔案。

完成定義

只有在下列條件都成立時，改動才算完成：

• 目標行為已經實作
• 要求的驗證已實際執行
• 證據已連結到相關計畫或品質文件
• 受影響的文件仍是最新狀態
• 儲存庫可依標準啟動路徑乾淨重啟

工作階段結束前

1. 更新目前的進行中執行計畫。
2. 如果任何領域或分層有明顯變化，更新 docs/QUALITY_SCORE.md。
3. 如果你延後處理新的技術債，記錄到 docs/exec-plans/tech-debt-tracker.md。
4. 在適合的時候，把已完成的計畫移到 docs/exec-plans/completed/。
5. 讓儲存庫維持可重新啟動狀態，並留下明確的下一步。