AGENTS.md 標準起手式：一份能讓任何 AI agent 看懂的最小範本

AGENTS.md 該寫什麼、最少要有哪幾段？看官方標準專案自己的版本最準。它短到不行卻很完整：一條主規則 + 依賴管理 + 程式碼慣例 + 一張指令表。新手照抄就能上手。

[ Log in to see the full prompt ]

## 這是什麼／解決什麼痛點 AGENTS.md 是一個開放標準——一份放在專案根目錄、給 AI coding agent 讀的純 Markdown 指引檔，作用相當於「寫給機器的 README」。痛點是：人類看 README，但 AI agent 需要更直接的操作指令（用哪個指令啟動、怎麼測、哪些事別做）。把這些散落在腦袋裡或 Slack 裡的約定集中到一個檔案，agent 就不用猜、也不會每次都問。 ## 為什麼這個來源值得用 這篇策展的是 **agents.md 標準專案倉庫本身的 AGENTS.md**。它的特別之處在於「自帶示範性」——一個推廣標準的專案，自己的 AGENTS.md 自然是「最小但完整」的示範樣板。它不像大型專案那份那麼龐雜，反而非常適合新手當起手式：看一眼就懂一份基本的 AGENTS.md 該有哪幾段。AGENTS.md 作為跨工具的開放格式，Codex、Claude Code 等多家 agent 都會主動讀取，寫一份到處通用。 ## 原檔涵蓋的重點 - **一條核心主規則**：開發時「永遠用 dev server（`npm run dev`）」，不要在 agent session 裡跑 production build——因為 build 會關掉 hot reload、拖慢迭代。這條濃縮成一句金句：「不確定時，重啟 dev server，而不是跑正式打包。」 - **依賴管理**：加/更新套件後，同步 lockfile 並重啟 dev server 讓框架認得新變動。 - **程式碼慣例**：新元件用 TypeScript、樣式盡量與元件放在一起。 - **一張指令表**：`dev`／`lint`／`test`／`build` 各自對應的指令——讓 agent 知道每個目的該打哪個指令。 ## 怎麼用 1. 在 repo 根目錄建 `AGENTS.md`。 2. 套用右側範本，把 `{{DEV_CMD}}`、`{{LINT_CMD}}`、`{{TEST_CMD}}`、`{{BUILD_CMD}}` 換成你專案真實的指令。 3. 把「哪件事 agent 平常該做、哪件事絕對別做」講清楚（這份範本的範例是：用 dev server、別 build）。 4. 之後 Codex／Claude Code 等 agent 進到專案會自動讀它。 ## 何時用 任何新專案的「第一份 agent 文件」。先放這份最小版，等專案長大、慣例變多，再往裡面加測試紀律、模組大小上限、API 命名等規則（可參考另一篇 openai/codex 官方 AGENTS.md 的進階版）。 📎 來源：agentsmd/agents.md 倉庫的 AGENTS.md（版權 © 2025 OpenAI，MIT 授權）— 本篇為繁中改寫整理，原始內容見上方連結。