AGENTS.md 起手式：minimal 與 advanced 兩種範本（給 Codex／任何 agent）

剛接觸 AGENTS.md，不知道該寫什麼？這裡有兩款現成骨架：五行就能跑的 minimal，和含測試/慣例/安全的 advanced。填空就能用，讓 Codex 一進專案就守規矩。

[ Log in to see the full prompt ]

## 這是什麼／解決什麼痛點 AGENTS.md 是放在專案根目錄、寫給「AI 編碼 agent」看的說明檔——等於專案版的 README，但讀者是 Codex、Claude Code 這類 agent。它告訴 agent：這個專案怎麼裝、怎麼跑測試、用什麼程式風格、有哪些安全紅線。痛點很實際：沒有它，agent 每次進專案都在瞎猜你的慣例，常常裝錯套件管理器、用錯命名風格、或做出破壞性操作。 Ischca 的 awesome-agents-md 是一個策展集合，收錄真實世界的 AGENTS.md 範例、範本、指南與工具，主打「accelerate agent onboarding」——讓 agent 一進專案就上手。 ## 為什麼這來源值得用 它提供兩款定位清楚的範本，正好覆蓋兩種起點： - **Minimal**：「a concise, no-frills starting point」——只有單一區塊的最小檢查清單（指定 runtime、安裝指令、測試指令、格式化、一條網路安全限制），五行就能上路。 - **Advanced**：「a feature-rich template with testing, safety and style rules」——含 Overview / Environment / Testing / Coding Conventions / Safety 五大區塊，外加 Example Tasks 示範典型指派。advanced 範本裡有幾條很值得抄的硬規則，例如「一個 commit 必須讓測試套件保持全綠」「檔名用 kebab-case」「禁止用使用者輸入拼 shell 指令」「未經授權不得 sudo」。 而且整個 repo 是 CC0（公眾領域奉獻）——授權上最寬鬆、可放心改用。 ## 怎麼用（步驟／要點） 本篇 full_prompt 把 minimal 與 advanced 兩款骨架都改寫成「填空版」，直接複製到專案根目錄的 AGENTS.md： 1. **新專案／小專案**：先用範本 A（minimal），把 {{NODE_OR_RUNTIME}}、{{INSTALL_CMD}}、{{TEST_CMD}}、{{FORMAT_CMD}}、{{ALLOWED_ENDPOINT}} 五個空填掉就能跑。 2. **較大／多人專案**：升級到範本 B（advanced），補上環境（Docker/服務）、測試分層、命名與風格慣例、安全邊界，再加兩個 Example Tasks 讓 agent 知道「典型任務長怎樣」。 3. 檔案放 repo 根目錄；OpenAI Codex 等多數 agent 會自動讀取。子目錄也可放各自的 AGENTS.md 做局部覆寫。 ## 何時用 任何要交給 AI agent 協作的 repo 都該有一份。剛開新專案、或想快速讓 Codex/Claude Code 守規矩時，從 minimal 起步；當專案長出測試套件、CI、安全要求後，再換成 advanced。它和 CLAUDE.md / Agent OS 的 standards 文件可以互補——AGENTS.md 是給 agent 的「進場守則」，越精準，agent 越不會亂來。 ## 出處＋授權 📎 來源：Ischca/awesome-agents-md（作者 Ischca，CC0 1.0 公眾領域奉獻）— 本篇為繁中改寫整理，原始內容見上方連結。原始 repo 另收錄多個真實世界 AGENTS.md（含 production-grade 的 Java SDK 範例）、指南與工具；本條目僅取其 minimal / advanced 兩款範本的結構改寫為填空起手式，未逐字搬運其完整範本檔。