AGENTS.md 是什麼？給 agent 讀的 README

2026 年 2 月，OpenAI 發了一篇工程文章，講一個內部實驗：3 名工程師從 2025 年 8 月底的空 repo 開始，5 個月沒有親手寫過一行程式碼，全部交給 Codex。結果是大約 1,500 個合併的 PR、上百萬行 production 程式碼。

管理這群 agent 的核心工具之一，是 repo 根目錄一個約 100 行的 Markdown 檔。

它叫 AGENTS.md。

AGENTS.md 是放在 repo 根目錄、給編碼代理（coding agent）讀的專案指引檔：建置指令、測試方式、程式風格、repo 慣例、禁區。官方定位是「給 agent 的 README」——README 寫給人看，AGENTS.md 寫給 agent 看。它是純 Markdown、沒有固定 schema，由 OpenAI 等多家在 2025 年 8 月推成開放慣例，2025 年 12 月捐入 Linux Foundation。

為什麼需要這個檔案？因為 coding agent 有個根本限制：每個 session 都失憶。今天教它「測試要用 pnpm test、不要跑整包」，明天開新 session 它全忘光。AGENTS.md 就像貼在失憶同事桌上的便條——每天上工前必讀，把最重要的規矩固定下來。

起源：CLAUDE.md 先跑，AGENTS.md 統一戰場

先行者是 Anthropic。2025 年 2 月 24 日，Claude Code 隨 Claude 3.7 Sonnet 以研究預覽（research preview）形式上線，內建 CLAUDE.md 機制：這個檔案在每個 session 開始時自動載入，官方文件明講它該裝「bash 指令、程式風格、工作流程規則」——agent 光讀 code 推不出來的那些。

接下來半年，每家工具各立山頭。Cursor 有 .cursorrules，GitHub Copilot 有 .github/copilot-instructions.md，Gemini 有 GEMINI.md。同一個專案想支援三個工具，就要維護三份幾乎一樣的檔案——跟 MCP 出現前「N 個工具 × M 個應用」的整合地獄同一個劇本。

2025 年 8 月，OpenAI 聯合 Amp、Google Jules、Cursor、Factory 等團隊推出 AGENTS.md，定位是中立的開放慣例：一個檔名、純 Markdown、任何 agent 都能讀。InfoQ 報導當時已有超過 2 萬個 GitHub repo 採用；到 2025 年 12 月 9 日，Linux Foundation 宣布成立 Agentic AI Foundation（AAIF），OpenAI 把 AGENTS.md 捐入，同批還有 Anthropic 的模型上下文協定（MCP）與 Block 的 goose——採用數已破 6 萬個開源專案。AWS、Anthropic、Google、Microsoft 都是白金會員。

支援名單現在很長：Codex、Amp、Cursor、Devin、Gemini CLI、GitHub Copilot、Jules、VS Code、Zed、Aider、goose 都讀 AGENTS.md。

有個小諷刺：最早發明這套玩法的 Claude Code，截至 2026 年年中仍只原生讀 CLAUDE.md。要求支援 AGENTS.md 的 GitHub issue #6235 從 2025 年 8 月開到現在，累積了大量 upvote。社群通行解法一行搞定：

ln -s AGENTS.md CLAUDE.md

內容寫一份，兩個檔名都指向它。

一份好的 AGENTS.md 該有什麼

原則只有一條：寫 agent 猜不到的，不寫 agent 讀 code 就知道的。Claude Code 官方文件給 CLAUDE.md 的建議，對 AGENTS.md 同樣適用：

✅ 該寫	❌ 不該寫
建置、測試指令（含「怎麼只跑單一測試」）	agent 讀 code 就能推斷的東西
跟語言預設不同的風格規則	標準語言慣例（agent 本來就會）
branch 命名、PR 慣例	詳細 API 文件（放連結就好）
環境變數等開發環境地雷	常變動的資訊（很快過期）
禁區——不准動 migrations/、不准 commit .env	「寫乾淨的 code」這種廢話

可以直接抄的起手式，五個段落：

1. 專案一句話——這個 repo 是什麼、跑在哪。
2. 指令——install、build、test、lint 各一行，含最快的驗證方式。
3. 風格——只列跟預設不同的（例如「用 ES modules 不用 CommonJS」）。
4. 禁區——負面規則跟正面規則一樣重要。沒寫「不准」，agent 會選它最熟的通用做法，未必是你的做法。
5. 驗證——改完 code 要跑什麼才算完成。給 agent 一個能自己跑的檢查，它才能自己收斂，你才不用當人肉 QA。

不知道從哪開始？讓 agent 自己寫第一版。Claude Code 有 /init 指令會掃專案生出草稿；OpenAI 那個百萬行實驗裡，最初的 AGENTS.md 也是 Codex 自己寫的。

跟 README、system prompt 的邊界

三個東西常被混在一起，並排看最清楚：

	給誰讀	誰維護	管什麼
README.md	人	專案維護者	專案介紹、quick start、貢獻指南
AGENTS.md	coding agent	專案維護者，進 git	這個 repo 的建置、風格、禁區
系統提示（system prompt）	模型	工具廠商	產品層行為——工具怎麼用、輸出格式

README 和 AGENTS.md 是互補的。官方說法：README 給人看 quick start 和專案描述，AGENTS.md 裝那些「會把 README 弄亂、人類貢獻者也不關心」的細節——建置步驟、測試流程、慣例。

跟 system prompt 的分工是層次問題：system prompt 是廠商出廠設定，管所有專案的通用行為；AGENTS.md 是專案自己的規則，跟著 repo 走、進版本控制、全隊共用。monorepo 還能放多份——子目錄的 AGENTS.md 蓋過根目錄的，就近原則。

另外它沒有 schema。官方網站原話：「AGENTS.md 就是標準 Markdown，標題隨你用，agent 就是讀你給的文字。」它的約定只有檔名和位置，內容完全自由。

常見錯誤：寫成行銷文、塞成百科全書

看過幾十個 repo 的 AGENTS.md 之後，爛法主要兩種。

寫成行銷文。「本專案採用業界領先的模組化架構，致力於卓越的開發者體驗」——agent 讀完等於沒讀。它需要的是 pnpm test -- --filter=api 這種可以直接執行的事實，形容詞一個都用不上。

塞成百科全書。 這個更常見，也更隱蔽。Claude Code 官方文件警告得很直白：檔案太肥，agent 會忽略你真正重要的指令——關鍵規則淹沒在雜訊裡。判斷標準是逐行問：「刪掉這行，agent 會犯錯嗎？」不會就刪。

OpenAI 那個實驗給了規模化的解法：AGENTS.md 當目錄頁用，不當百科全書。全檔約 100 行，只放最高頻的規則和指標，深水區的設計決策、規格、參考資料放進 docs/，讓 agent 需要時自己翻。上下文視窗（context window）是稀缺資源，開場白越短越好。

還有一種爛法是過期。指令改了、目錄搬了，AGENTS.md 沒跟上，agent 照舊檔操作直接撞牆。把它當 code 對待：出錯時檢討、定期修剪、改完觀察 agent 行為有沒有真的變。

Harness engineering 的最小單位

AGENTS.md 真正的價值在一個迴路。OpenAI 在 harness engineering（替 agent 打造工作環境的工程）那篇文章裡，把它描述成「活的約束系統」而非靜態文件：

agent 犯錯 → 把教訓寫進 AGENTS.md → 同樣的錯永不再犯。

這跟帶人類新人完全一樣——差別是人類新人會忘，agent 的便條每個 session 都重新生效。你每修一次檔案，就是把一次性口頭糾正變成永久性制度。用三個月後回頭看 AGENTS.md 的禁區清單，那就是你的 agent 犯過的錯的化石紀錄。

這也是「harness engineering 最小單位」的意思：不用先搞持續整合（CI）、評測、sandbox，一個 Markdown 檔就能開始累積。今天就能做的三步：

1. 在 repo 根目錄開 AGENTS.md（用 Claude Code 就跑 /init，或直接叫 agent 掃專案寫第一版，再加上 symlink）。
2. 只寫五段：專案一句話、指令、風格差異、禁區、驗證方式。100 行封頂。
3. 之後每次 agent 犯錯，回來補一條。每季逐行問一次「刪掉會出事嗎」，不會就刪。

一個沒有 schema 的 Markdown 檔，18 個月內從單一工具的功能變成 Linux Foundation 標準、6 萬多個專案採用——因為它剛好卡在一個真實的痛點上：agent 能力再強，也需要有人告訴它「在我們家，規矩是這樣」。

資料來源：AGENTS.md 官方網站、Linux Foundation 新聞稿、Claude Code 官方文件、OpenAI Harness engineering 工程文章、Anthropic Claude 3.7 Sonnet 發布文、InfoQ、GitHub anthropics/claude-code issue #6235

矽基前沿 · 大百科線（編輯：廖玄同），《AGENTS.md 是什麼？給 agent 讀的 README》，矽基前沿 [Si]gnals，2026-07-05。https://signals.tw/articles/what-is-agents-md/