ROOST 專案的 Agent 指示實務
第一部分：AGENTS.md 標準
AGENTS.md 是引導 AI 程式開發 agent 的開放格式，由 Linux Foundation 旗下的 Agentic AI Foundation 治理。GitHub Copilot、OpenAI Codex、Cursor、Gemini/Jules、Claude Code 等工具皆支援此格式。
README.md 給人讀，AGENTS.md 則供機器讀取。
檔案設定
- 在 repository 根目錄中，與
README.md並列放置AGENTS.md。 - 為使用個別檔名的工具建立符號連結，包括
ln -s AGENTS.md CLAUDE.md與ln -s AGENTS.md .github/copilot-instructions.md。 - 若是 monorepo，可在子目錄中放置額外的
AGENTS.md。Agent 會讀取目錄樹中最近的檔案，距離最近者優先。這些檔案也應建立對應的符號連結。
建議內容
此標準沒有固定 schema，使用一般 Markdown 與自訂標題即可。社群共識建議涵蓋下列內容。
- 設定與建置指令
- 測試指示
- 程式碼風格指引
- 專案結構
- 安全注意事項
- PR 與 commit 指引
標準所採原則
- 指令優先於說明。
- 將
AGENTS.md視為持續更新的文件，專案慣例改變時同步更新。 - 距離編輯檔案最近的
AGENTS.md優先，使用者的明確提示則具有最高優先順序。
相關標準：Agent Skills
.agents/skills/ 目錄是相鄰的開放標準，可將專門的 agent 能力，包括指令碼、範本與參考文件，包裝成可重複使用的 SKILL.md 檔案。ROOST 未來可能在專門工作流程中採用 skills，目前不在本文件範圍內。
第二部分：ROOST 特定要求
ROOST repository 必須包含涵蓋完整開發生命週期的 AGENTS.md，使貢獻者使用的 agent 從第一次嘗試起，便能產出符合專案標準的成果。
各 SDLC 領域的最低內容
| 領域 | 應包含內容 | 優先順序 |
|---|---|---|
| 架構 | 關鍵目錄、模組邊界，以及新增程式碼應放置的位置。指向參考檔案，並標示應避免使用的舊檔案。 | P0 |
| 設計 | API 慣例與資料模型慣例。 | P1 |
| 建置與執行 | 安裝相依套件、建置及啟動專案的確切指令。 | P0 |
| 測試 | 單元測試、整合測試、lint 與型別檢查的指令，包括單一檔案與完整測試套件。 | P0 |
| CI | PR 會執行哪些 CI 檢查，以及推送前如何在本機執行。 | P0 |
| 安全 | 不在程式碼中放入 secrets、不停用 lint 規則、檢查新套件是否有 CVE。若有 SECURITY.md，應附上連結。 | P0 |
| 程式碼審查 | PR 要求，包括小型差異、描述清楚的標題、測試涵蓋率，以及適用時的 changelog 項目。 | P0 |
| 程式碼風格 | 程式語言版本與框架版本，並指向 linter／formatter 設定。 | P1 |
| CD | 發行流程、語意化版本標籤慣例與環境。說明 agent 不得修改的項目，例如正式環境部署指令碼與發行簽署。 | P1 |
| 相依套件 | 新增相依套件的規則，包括授權與審查流程，以及哪些動作需要人工核准。 | P1 |
ROOST 指導原則
| 項目 | 說明／備註 |
|---|---|
| 指令優先於敘述 | Agent 會依指令行動。相較於描述性段落，應優先提供 npm run test -- path/to/file。 |
| 相同審查標準 | 使用 agent 協助撰寫的 PR，與其他 PR 適用相同標準。 |
| 限制須附替代方式 | 說明限制時，一律提供可行的替代路徑。 |
| 持續迭代 | 從最低限度開始。同一項指示向 agent 說明第二次時，就把它加入檔案。 |
| 貢獻者更新 AGENTS.md | 貢獻者發現缺漏時，建議在 PR 中一併更新 AGENTS.md。 |
需要人工核准的動作
執行下列動作前，agent 必須停止並取得人工明確核准。
- 變更授權標頭、著作權聲明或任何法律文字
- 修改發行、簽署或部署工作流程，包括 CI/CD pipeline 檔案與 Makefile 等
- 新增、移除或升級任何函式庫或套件，包括間接相依套件，並確認授權相容