Canonical: https://seo.whoops.com.tw/what-is-agents-md/
Author: Sliven 褚崇名
Source robots: follow, index, max-snippet:-1, max-video-preview:-1, max-image-preview:large
Content modified (WordPress): 2026-11-15T04:13:41+00:00
Representation modified (content/template/converter): 2026-11-15T04:13:41+00:00

# 最佳 AGENTS.md 完整教學：寫法範本與工具支援比較

 

圖片：AGENTS.md 說明檔連接專案目錄、載入設定與測試驗收的流程概念圖（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-guide-featured.webp）

 

撰文作者 

[Sliven 褚崇名](<https://seo.whoops.com.tw/about/#founder-title>)

 

Whoops SEO 創辦人

 

SEO 與 AI SEO 專家，專長涵蓋技術 SEO、內容策略與 GEO 優化。從搜尋排名到 AI 答案中的品牌呈現，協助企業找出優化機會、排定執行順序，並追蹤實際成效。

 

圖片：Sliven 褚崇名肖像（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/sliven-portrait-navy.webp）

 

[作者背景與專業領域](<https://seo.whoops.com.tw/about/#founder-title>) 更新 2026-11-15 約 29 分鐘閱讀

 

本篇內容

 

### 本篇內容

 

## 先看重點

摘自本文

- monorepo 與多套件專案靠巢狀支援：官方的建議是每個 package 再放一份自己的 AGENTS.md，官網的一般約定是較近的局部指示優先；是否自動發現、何時載入與如何處理衝突，仍依工具實作而定。

[agent 怎麼讀 AGENTS.md：根目錄、巢狀與優先順序](<https://seo.whoops.com.tw/what-is-agents-md/#agent-%E6%80%8E%E9%BA%BC%E8%AE%80-AGENTS.md%EF%BC%9A%E6%A0%B9%E7%9B%AE%E9%8C%84%E3%80%81%E5%B7%A2%E7%8B%80%E8%88%87%E5%84%AA%E5%85%88%E9%A0%86%E5%BA%8F>)
- AGENTS.md 官網建議衝突時以離正在編輯的檔案最近的指示為準，使用者在對話裡的明確要求優先於專案文件。

[agent 怎麼讀 AGENTS.md：根目錄、巢狀與優先順序](<https://seo.whoops.com.tw/what-is-agents-md/#agent-%E6%80%8E%E9%BA%BC%E8%AE%80-AGENTS.md%EF%BC%9A%E6%A0%B9%E7%9B%AE%E9%8C%84%E3%80%81%E5%B7%A2%E7%8B%80%E8%88%87%E5%84%AA%E5%85%88%E9%A0%86%E5%BA%8F>)
- 「支援 AGENTS.md」五個字背後至少有三種程度：原生預設就讀、有條件讀、要設定才讀。

[各工具怎麼支援：Codex、Claude Code、Gemini CLI、opencode、Cursor、Copilot 的實際行為](<https://seo.whoops.com.tw/what-is-agents-md/#%E5%90%84%E5%B7%A5%E5%85%B7%E6%80%8E%E9%BA%BC%E6%94%AF%E6%8F%B4%EF%BC%9ACodex%E3%80%81Claude-Code%E3%80%81Gemini-CLI%E3%80%81opencode%E3%80%81Cursor%E3%80%81Copilot-%E7%9A%84%E5%AF%A6%E9%9A%9B%E8%A1%8C%E7%82%BA>)

 

### 檢查網站的 SEO 基礎

從網站網址開始，檢視可讀性與頁面基礎訊號。

- 檢查標題與搜尋摘要標記
- 核對 canonical 與索引指令
- 整理公開 HTML 的待改善項目

[免費檢查網站](<https://seo.whoops.com.tw/free-seo-audit/>)

 

[將 Whoops 設為 Google 偏好來源（另開 Google 設定頁）](<https://www.google.com/preferences/source?q=seo.whoops.com.tw>)

 

AGENTS.md 是寫給 coding agent 的專案說明檔，用 Markdown 記錄建置與測試指令、程式碼慣例和操作禁區。把它放在儲存庫根目錄，支援的工具便可依各自的載入規則使用；Claude Code 有條件直接讀取，Gemini CLI 則需要設定檔名。它沒有必填欄位，也不能取代權限設定與 CI。

 

## 影片：5 分鐘理解 AGENTS.md

 

先用影片掌握專案規則的寫法、Codex 載入順序，以及 Claude Code 與 Gemini CLI 的支援差異。[在 YouTube 觀看完整解析](<https://www.youtube.com/watch?v=peWdjQ6eQ64>)。

 

5 分鐘看懂 AGENTS.md 的用途、寫法、載入差異與權限界線。

[以影片頁觀賞：AGENTS.md 是什麼？Codex 載入規則、Claude Code 與 Gemini CLI 差異｜5 分鐘看懂](<https://seo.whoops.com.tw/videos/youtube-pewdjq6eq64-dedb806651/>)

  

### 影片素材授權與改作紀錄

 

以下四項素材已剪輯、裁切，原聲未採用；適用片段另作超分與色彩修正。

 

1. Computer work at home
 作者：Sounds of Changes / Erik Pålsson；錄音：Helena Törnqvist。
 [原始素材與作者紀錄](<https://commons.wikimedia.org/wiki/File:Soundscape,_computer_work_at_home,_the_computer_is_Lenovo_Think_pad.webm>) · [CC BY 3.0](<https://creativecommons.org/licenses/by/3.0/>) 
2. Speed typing with dvorak
 作者：Enteryourname0000。
 [原始素材與作者紀錄](<https://commons.wikimedia.org/wiki/File:Speed_typing_with_dvorak.webm>) · [CC0](<http://creativecommons.org/publicdomain/zero/1.0/deed.en>) 
3. Coding da Vinci 2014
 攝影與剪輯：Zum Grauen Bären — Christian Fussenegger、Yvonne App；設計：FUK Graphic Design。原片音樂：Josh Woodward（本集未採用）。
 [原始素材與作者紀錄](<https://commons.wikimedia.org/wiki/File:Coding_da_Vinci_2014.webm>) · [CC BY 4.0](<https://creativecommons.org/licenses/by/4.0/>) 
4. Debugging JavaScript – Chrome DevTools 101
 作者：Google Chrome Developers。
 [原始素材與作者紀錄](<https://commons.wikimedia.org/wiki/File:Debugging_JavaScript_Chrome_DevTools_101.webm>) · [CC BY 3.0](<https://creativecommons.org/licenses/by/3.0/>)

 

官方影片片段的來源另見片內標示；此區未將其列為 CC 授權素材。

  

同一個儲存庫，白天用 Codex 在雲端跑背景任務，下班前用 Claude Code 收尾，同事偏好 Cursor，demo 當天開 opencode。每個工具都很聰明，但沒有一個天生知道你們的測試要下哪個指令、哪個資料夾絕對不能動、commit 訊息有沒有固定格式。這些事在對話裡重講一遍不難，講到第十次就會開始想：有沒有一個地方寫一次，所有工具自己去看？AGENTS.md 就是為這個需求長出來的檔案。

 

它是一份放在儲存庫裡的 Markdown 檔，內容寫給 coding agent 讀：專案怎麼建置、怎麼測試、程式碼有什麼慣例、地雷在哪。它不綁任何一家廠商，OpenAI 的 Codex、Google 的 Gemini CLI、JetBrains 的 Junie、GitHub 的 Copilot cloud agent 都認得它，Cursor 與 opencode 也讀。下方整理檔案位置、六種工具的支援差異、可直接修改的範本，以及規則沒有生效時的排查方式。工具載入行為依 2026 年 10 月 6 日的官方文件整理。

 

> AGENTS.md 是放在儲存庫裡的純 Markdown 說明檔，定位是「給 agent 的 README」。沒有必填欄位、沒有 schema，寫你想讓 agent 知道的事就夠。規格由 OpenAI、Google、Cursor 等團隊協作發起，現在交由 Linux Foundation 之下的 Agentic AI Foundation 治理。
> 
>  
> 
> 常見做法是以根目錄保存通用規則，子目錄補充局部指示；實際搜尋路徑、合併順序與重讀時機由工具決定。對話中的明確要求可以覆寫專案文件指示，仍受工具權限與更高優先序規則限制。
> 
>  
> 
> 支援程度是一條光譜：Codex、opencode、Cursor、Copilot cloud agent 原生就讀；Claude Code 從 2.1.277 版起，在專案裡沒有 CLAUDE.md 時會直接讀，也能設成兩者都讀；Gemini CLI 預設讀 GEMINI.md，要用設定把 AGENTS.md 加進檔名清單。
> 
>  
> 
> 它是建議，不是強制。必須阻擋的操作應交給適用的 hooks、權限規則與 CI；AGENTS.md 負責讓 agent「知道」，不負責讓 agent「服從」。

 

## AGENTS.md 是什麼：把「給 agent 的 README」變成跨工具標準

 

[AGENTS.md 官方網站](<https://agents.md/>)給它的定義很直白：一個簡單、開放的格式，用來引導 coding agent。講白了就是「agent 版的 README」，一個固定、可預期的位置，存放專案 context 與指示，讓 AI coding agent 在你的專案上工作得更順。人類看 README.md 認識專案，agent 讀 AGENTS.md 取得同一份認知，這個類比就是整個標準的核心。

 

圖片：AGENTS.md 官網首屏將這份檔案定義為給 agent 的 README，右側呈現安裝、開發、測試與程式碼風格範例（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-official-definition.webp）

AGENTS.md 官網用純 Markdown 範例呈現專案指令與程式碼慣例。

 

格式上它寬鬆到幾乎不設限：就是標準 Markdown。官方 FAQ 明講，AGENTS.md 只是普通的 Markdown，標題隨你用，agent 解析的就是你寫出來的文字本身。你可以用 H2 分節、用條列、貼指令，也可以只寫十行。標準規範的是「檔名叫什麼、放在哪裡、怎麼被找到」，不管內容長什麼樣，這也是它能同時被二十幾個工具接受的前提：門檻夠低，誰都進得來。

 

這個格式不是 OpenAI 單方面拍板。官方說法是它由 AI 軟體開發生態系的協作長出來，最早的參與者包括 OpenAI Codex、Amp、Google 的 Jules、Cursor 與 Factory，現在規格交由 Linux Foundation 之下的 Agentic AI Foundation 管理。規格本體放在[GitHub 上以 MIT 授權公開的儲存庫](<https://github.com/agentsmd/agents.md>)，官網宣稱有超過六萬個開源專案採用，這是網站公布的採用數量。採用清單上有 20 多個名字，除了前面提過的，還包括 VS Code、Windsurf、Devin、Zed、Warp、Aider、goose、RooCode、Kilo Code、Junie、Semgrep 與 Augment Code，橫跨終端工具、編輯器、雲端代理與資安掃描。哪個工具今天還在清單上，以官網當下內容為準，這個生態仍在變動。

 

> [https://t.co/gbLgHDtImj](<https://t.co/gbLgHDtImj>) is quickly becoming a popular way to share instructions with coding agents in your repo. 
> 
> Now supported in Cursor, Amp, Jules, Factory, RooCode, and Codex. [https://t.co/KAdwdvwRKl](<https://t.co/KAdwdvwRKl>)
> 
> — OpenAI Developers (@OpenAIDevs) [August 19, 2025](<https://x.com/OpenAIDevs/status/1957925682048336354?ref_src=twsrc%5Etfw>)

 

圖片：README.md 提供給人的專案介紹，AGENTS.md 提供給 coding agent 的建置、測試、慣例與禁區說明（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-project-guide.webp）

README.md 幫助人了解專案；AGENTS.md 整理 agent 動工前需要知道的規則，並須確認工具的載入設定。

 

一個常見的混淆先拆掉：AGENTS.md 跟 llms.txt 名字裡都有 AI 味，層級卻完全不同。AGENTS.md 在你的儲存庫裡，讀者是「你授權進來工作的 agent」，性質是工作指示；llms.txt 通常放在網站根目錄，提案目的是給使用網站資訊的模型一份站內內容選單，性質接近對外宣告，而且它的實際效果在實務上仍有爭議，站上對[llms.txt 實際效果的檢驗](<https://seo.whoops.com.tw/llms-txt/>)另有完整拆解。把兩者分開，才不會把專案規則寫進網站行銷檔，也不會誤以為放了一個 txt 檔，agent 就會自動懂你的程式碼。

 

### 檔名少一個 s：agent.md 是同一件事嗎

 

標準檔名是複數的 AGENTS.md，全部大寫。只放 agent.md 的專案，對多數工具來說等於沒放，工具找的就是那個精確檔名。有些早期採用者用的是單數的 AGENT.md，官方 FAQ 對這些專案給了兩行搬家指令：先把檔案改名成複數，再建一個反向的符號連結，讓寫死舊檔名的腳本與文件不會斷。

 

````
mv AGENT.md AGENTS.md
ln -s AGENTS.md AGENT.md
````

 

多數 agent 讀到連結時，讀到的就是同一份內容，等於一分維護、兩個檔名都通。新專案不需要這層相容，直接從 AGENTS.md 開始；你在搜尋或文件裡看到有人寫 agent.md 怎麼寫，談的通常也是同一套標準，只是檔名少了一個 s。

 

## agent 怎麼讀 AGENTS.md：根目錄、巢狀與優先順序

 

基本盤很簡單：先在儲存庫根目錄放一份，再確認使用工具的載入條件；部分工具預設讀取，部分需要設定。讀取時機多半是「動工之前」，例如 Codex 官方文件明講，它會在做任何工作之前先讀 AGENTS.md，而且每個 run 只讀一次，在 TUI 裡大約等於每個 session 一次。這代表你中途改檔案，同一個 session 不一定會重讀，改完規則後重開 session 或重跑指令，是最保險的驗證方式。

 

各工具的讀取時點其實有譜系，跨工具工作時值得記住：Codex 是每個 run 重建一次指示鏈，等於每次啟動都重讀；Claude Code 在符合檔案選擇設定時，於 session 開始載入沿途的 AGENTS.md，子目錄的檔案則在讀到該目錄檔案時按需載入；Gemini CLI 更積極，把串接好的內容隨每個 prompt 送出，改完檔案可以用 /memory refresh 重掃。同一份規則改下去，三個工具的生效時間點不同，排查「為什麼新規則沒生效」時，先確認該工具的重讀時機，而不是懷疑檔案內容。

 

monorepo 與多套件專案靠巢狀支援：官方的建議是每個 package 再放一份自己的 AGENTS.md，官網的一般約定是較近的局部指示優先；是否自動發現、何時載入與如何處理衝突，仍依工具實作而定。規模可以長到什麼程度？官網以 OpenAI 自己的主要儲存庫為例，說裡面有 88 份 AGENTS.md：根目錄那份寫全域慣例，各服務目錄那份寫自己的測試指令與禁區，由各工具依自己的搜尋與載入機制取得適用規則。這不是炫技，是把「全域規範」與「在地規範」分層管理的自然結果。

 

AGENTS.md 官網建議衝突時以離正在編輯的檔案最近的指示為準，使用者在對話裡的明確要求優先於專案文件。不同工具的實際搜尋範圍仍要分開確認：例如 Codex 啟動時建立的是從專案根目錄到當前工作目錄的指示鏈。反過來利用它：看到 agent 行為跟檔案不一致時，先想想這個 session 裡是不是有人（包括你自己）下過更具體的指示。

 

還有一個實用的用途：讓工具知道該執行哪些驗收指令。官網說明，如果你在檔案裡列了測試指令，agent 會在結束任務前嘗試執行相關的程式化檢查，並修復失敗再收工。這讓 AGENTS.md 不只是風格建議，而是把驗收標準寫進去的地方：建置、測試、lint 指令寫得越明確，agent 自我檢查的閉環就越完整。想更系統化地設計「讓 agent 自己跑、自己驗、知道何時停」的流程，可以往[迴圈工程](<https://seo.whoops.com.tw/loop-engineering/>)的方向延伸，兩者是同一個問題的兩個層次。

 

心態上把它當活文件。官方鼓勵 AGENTS.md 像其他文件一樣隨時更新，不必一次寫到完美。實務上比較健康的節奏是事故驅動：agent 每踩一次坑、每次 code review 抓到一個「它本來該知道」的問題，就回去補一條規則。檔案隨專案一起演化，價值才會累積。

 

圖片：Codex 由全域與專案根目錄往目前工作子目錄合併指示，同目錄的 AGENTS.override.md 優先（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/codex-agents-md-loading-hierarchy.webp）

此圖以 Codex 為例：全域與專案指示由上往下合併，當前子目錄補充局部規則；其他工具的搜尋範圍須另行核對。

 

## 各工具怎麼支援：Codex、Claude Code、Gemini CLI、opencode、Cursor、Copilot 的實際行為

 

標準要成立，得看工具怎麼實作。「支援 AGENTS.md」五個字背後至少有三種程度：原生預設就讀、有條件讀、要設定才讀。跨工具團隊至少要弄清楚自己用的那幾個落在哪一格，單一檔案策略才知道能不能成立。先看總表，再逐個工具展開。

 

| 工具 | 預設行為 | 讀取位置與階層 | 與其他記憶檔的關係 |
| --- | --- | --- | --- |
| OpenAI Codex | 預設就讀 | 全域 ~/.codex/AGENTS.md，加上專案根到當前目錄逐層收錄 | 同目錄有 AGENTS.override.md 時優先；config.toml 可加替代檔名與 32 KiB 上限 |
| Claude Code | 沒有 CLAUDE.md 時直接讀 | 工作目錄與上層的 AGENTS.md 與 .claude/AGENTS.md，子目錄按需載入 | 預設有 CLAUDE.md 就只讀 CLAUDE.md；可設成兩者都讀；AGENTS.local.md 不讀 |
| Gemini CLI | 預設讀 GEMINI.md，需設定才讀 AGENTS.md | 全域 ~/.gemini/、工作區與父目錄；工具存取檔案時沿目錄往 trusted root 載入 JIT context | context.fileName 接受清單，可讓 GEMINI.md 與 AGENTS.md 並存 |
| opencode | 預設就讀，主要規則檔 | V1：全域與往上找規則檔；V2：先載入全域與工作區上層檔案，存取子目錄時再按需載入 | V1 有 CLAUDE.md fallback；V2 只識別 AGENTS.md |
| Cursor | 預設就讀 | 專案根與子目錄，巢狀與父層合併 | 定位為 .cursor/rules 的純 Markdown 替代，無 frontmatter |
| Copilot cloud agent | 預設就讀 | \*\*/AGENTS.md，任意目錄 | 同時支援 copilot-instructions.md、CLAUDE.md、GEMINI.md 等五種檔案 |

六個主流工具對 AGENTS.md 的支援行為，依 2026 年 10 月 6 日的各官方文件整理。

 

圖片：Codex、Cursor、opencode 與 Copilot cloud agent 預設讀取，Claude Code 有條件讀取，Gemini CLI 需要設定檔名（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-tool-support-comparison.webp）

支援 AGENTS.md 的工具仍有不同預設、作用範圍與優先序。Claude Code 和 Gemini CLI 的條件與設定尤其需要確認。

 

### OpenAI Codex：把 AGENTS.md 當主要記憶機制的原始推手

 

Codex 對 AGENTS.md 的搜尋與合併有明確定義，也是標準最早的推手之一。根據[Codex 官方文件的 AGENTS.md 頁](<https://learn.chatgpt.com/docs/agent-configuration/agents-md>)，它讀兩層：全域層是 ~/.codex/AGENTS.md，也可放 AGENTS.override.md 蓋掉前者，內容放你跨專案的個人工作約定；專案層從儲存庫根目錄一路走到當前目錄，每個目錄至多取一份，同目錄的優先序是 AGENTS.override.md、AGENTS.md，再來才是你在 config.toml 用 project\_doc\_fallback\_filenames 自訂的替代檔名。若找不到專案根，就只檢查當前目錄。

 

合併行為有明確規則：找到的檔案由根目錄往下串接，越靠近當前目錄的排在越後面，因此在合併後的提示裡覆寫先前的指引；空檔案直接略過，合併總量超過 project\_doc\_max\_bytes 就停止收錄，預設值是 32 KiB。32 KiB 聽起來很大，但巢狀多層的 monorepo 是真的會撞到，官方提供兩種調整方式：提高 project\_doc\_max\_bytes，或將局部規則拆進適用的子目錄檔案；每次載入的規則仍應保持精簡。

 

圖片：Codex 官方 AGENTS.md 文件列出 Global scope、Project scope、Merge order 三項載入規則，以及預設 32 KiB 合併限制（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/codex-agents-md-official-discovery.webp）

Codex 由專案根目錄往目前工作目錄合併指示；同目錄優先讀 AGENTS.override.md，合併上限預設為 32 KiB。

 

官方文件給的巢狀範例可以直接借用：根目錄的 AGENTS.md 規定「送 PR 前跑 npm run lint，公開工具函式要寫進 docs/」，而 services/payments/ 目錄放一份 AGENTS.override.md，內容改為「這個服務用 make test-payments 測試，不要在未通知資安頻道前輪替 API key」。Codex 走到該目錄工作時，override 生效、同目錄的 AGENTS.md 被忽略，其他目錄完全不受影響。code review 的規則也可以這樣分層：整個 repo 的檢查放根目錄，特定服務的檢查放進該服務的目錄，官方的說法是把規則放在離它管理的程式碼最近的地方。

 

想確認規則真的被吃到，官方建議直接問它：跑一次 Codex 並下「總結目前的指示」這類 prompt，看它複述的內容對不對；更硬的稽核是在啟動時指定 log 目錄，再翻 session 紀錄找實際載入的檔案清單。行為異常時的排查順序也是官方給的：先看是不是上層目錄殘留 AGENTS.override.md，再確認 CODEX\_HOME 有沒有被指去別的地方。Codex 本身的安裝、方案與操作，[OpenAI Codex 的完整介紹](<https://seo.whoops.com.tw/openai-codex/>)另有專文，此處不重複。

 

### Claude Code：有 CLAUDE.md 時的條件式讀取

 

Claude Code 從 2.1.277 版起原生支援讀 AGENTS.md。[官方記憶文件](<https://code.claude.com/docs/en/memory>)給的預設規則很明確：工作目錄與其上層目錄都沒有 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 時，Claude 直接讀 AGENTS.md；一旦其中任何一份存在，預設就只讀 CLAUDE.md。注意這個檢查不含你家目錄的 ~/.claude/CLAUDE.md 與組織管理層檔案，那兩者照常載入，與 AGENTS.md 並存不衝突。

 

這個預設藏著一個實務陷阱：專案用 AGENTS.md 當單一真相，某天你為了放個人偏好而加了 CLAUDE.local.md，Claude 就默默不讀 AGENTS.md 了。官方文件特別點名這件事，解法是在 session 裡執行 /config，把 Project instructions 設成 claude-md-and-agents-md，兩者都讀；同一個設定也有 claude-md（只讀 CLAUDE.md）與 managed-only（只讀組織管理層）等值，還能寫進 settings.json 的 pluginConfigs 區塊，從下一則訊息起生效，之後的新 session 也會沿用；手動寫檔可放在 ~/.claude/settings.json，也支援 –settings 指定檔案或 managed settings。2.1.285 起使用 cc-plugin-agents-md@builtin，較早版本的 plugin ID 為 agents-md@builtin，專案層或 local settings 不會套用這個選項。

 

載入範圍的細節：session 開始時，Claude 會載入工作目錄與上層的每份 AGENTS.md 與 .claude/AGENTS.md，互動模式會顯示一行「AGENTS.md loaded」訊息讓你確認；子目錄的 AGENTS.md 則是在 Claude 讀到該目錄的檔案時按需載入，前提是那個子目錄沒有自己的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。檔案內的 @path 匯入語法照常展開；AGENTS.local.md、AGENTS.override.md 與 .agents/ 目錄下的東西則明確不讀。v2.1.280 起可在 session 裡跑 /memory 或 /context，確認載入清單；v2.1.277 至 v2.1.279 不會列出直接讀取的 AGENTS.md，應改問 Claude 目前的專案指示。

 

還有三個細微差異，重度使用者會踩到：經由這套設定載入的 AGENTS.md，不會觸發 InstructionsLoaded hooks，靠 hooks 做注入的既有流程要改走 CLAUDE.md 匯入；用 –add-dir 額外掛進來的目錄，需設定 CLAUDE\_CODE\_ADDITIONAL\_DIRECTORIES\_CLAUDE\_MD 才會載入其中的 CLAUDE.md；其中的 AGENTS.md 不會透過這條路徑載入；AGENTS.md 裡 @ 匯入工作目錄以外的檔案時，不會跳核准提示，只在這個專案早就核准過外部匯入時才載入。版本方面也要留意：從 2.1.276 或更早升級後的第一個 session 可能還讀不到，下一個 session 才生效，官方對這些邊界都有明說。

 

若你的專案兩種檔案都需要，官方給的並存配方很乾淨：建一份 CLAUDE.md，內容只有 @AGENTS.md 這行匯入，Claude 專屬指示寫在匯入下方。symlink 也行，ln -s AGENTS.md CLAUDE.md 一行搞定，但有兩個但書：透過連結寫入會被工具拒絕，得回頭改本體；Windows 上建符號連結需要管理員權限或 Developer Mode；Git 在 core.symlinks 未啟用時，會把連結 checkout 成純文字檔，跨平台團隊官方建議用匯入、不要用連結。CLAUDE.md 本身的四層記憶結構與寫法紀律，[CLAUDE.md 的記憶檔與載入規則](<https://seo.whoops.com.tw/what-is-claude-md/>)談得更細；工具本身的安裝與操作見[Claude Code 完整教學](<https://seo.whoops.com.tw/claude-code/>)。

 

開發者 Simon Willison 在 2025 年分享過 CLAUDE.md 匯入 AGENTS.md 的做法；目前 Claude Code 已另有條件式原生支援，這則貼文可作為匯入方式的歷史例子。

 

> Looks like the official recommendation from Anthropic is to use an @-AGENTS.md reference in your CLAUDE .md to have Claude read that file instead [https://t.co/Qsbp3UtZdi](<https://t.co/Qsbp3UtZdi>) [pic.twitter.com/XEHlzZ0irg](<https://t.co/XEHlzZ0irg>)
> 
> — Simon Willison (@simonw) [October 25, 2025](<https://x.com/simonw/status/1981945527114875384?ref_src=twsrc%5Etfw>)

 

### Gemini CLI：預設檔名不同，一行設定解決

 

Gemini CLI 的記憶檔預設叫 GEMINI.md，不會自動去讀 AGENTS.md，這是搜尋「AGENTS.md vs GEMINI.md」的人最常撞到的牆。根據[Gemini CLI 官方說明文件](<https://geminicli.com/docs/cli/gemini-md/>)，它的階層制很完整：全域的 ~/.gemini/GEMINI.md 套用所有專案，載入工作區與父目錄的 context；工具存取檔案或目錄時，再沿該目錄與祖先目錄到 trusted root 找 JIT context。已載入的內容會串接後隨每個 prompt 一起送出。

 

要讓它吃 AGENTS.md，官方做法是在 settings.json 的 context.fileName 指定檔名，而且這個欄位接受清單，例如同時列 AGENTS.md、CONTEXT.md、GEMINI.md，三者並讀。這對多工具專案是關鍵設計：你不必在兩個檔名之間二選一，讓 GEMINI.md 保留給 Gemini 專屬調校、AGENTS.md 當跨工具主檔，一行設定就並存。驗證用 /memory 指令，show 顯示目前載入的完整內容，refresh 重新載入，list 列出載入路徑。

 

例如在專案的 .gemini/settings.json 設定以下檔名清單，便能同時保留通用規則與 Gemini 專屬內容：

 

````
{
  "context": {
    "fileName": [
      "AGENTS.md",
      "GEMINI.md"
    ]
  }
}
````

 

### opencode：把 AGENTS.md 當第一公民的開源工具

 

opencode 以 AGENTS.md 為主要規則檔，但 V1 與 V2 的搜尋方式不同。下列 CLAUDE.md 相容行為出自 V1 文件。依[opencode 的規則文件](<https://opencode.ai/docs/rules/>)，它啟動時從當前目錄往上找規則檔，同時認得 AGENTS.md 與 CLAUDE.md，同層兩者並存時 AGENTS.md 勝出，每類第一個命中的檔案才算數。全域層的 ~/.config/opencode/AGENTS.md 套用到所有 session，官方建議放個人規則、不進版控；它甚至會 fallback 去讀 ~/.claude/CLAUDE.md，讓 Claude Code 的使用者近乎無痛搬家，不想被讀也有環境變數可以整組關掉。

 

V1 的 opencode.json 可透過 instructions 指定額外文件，接受本地路徑、glob 與遠端 URL，例如 packages/\*/AGENTS.md。V1 文件也說明不會自動解析指示檔內的文件參照，需要用設定加入，或教 agent 按需讀取。執行 /init 可以掃描專案生成或改善現有檔案，官方明確說既有檔案會被就地改善、不會整份覆蓋。

 

另需核對 [opencode V2 的 instructions 文件](<https://opencode.ai/v2/docs/instructions>)：V2 在 read 或 list 存取工作區下的路徑時，會自動載入沿途的 AGENTS.md；巢狀檔案按由近到遠的順序載入並去重，但 OpenCode 不會自動解決規則衝突；V2 只識別 AGENTS.md，沒有 V1 的 CLAUDE.md fallback。目前 V2 雖接受 instructions 陣列，文件仍註明尚未實際載入其中的檔案、glob 與 URL，因此不能把 V1 的設定直接當成 V2 的生效方式。

 

### Cursor：想要純文字規則就用它，.cursor/rules 之外的簡單選項

 

[Cursor 官方規則文件](<https://cursor.com/docs/rules>)對 AGENTS.md 的定位一句話講完：純 Markdown 的 agent 指示，是 .cursor/rules 的簡單替代品，支援放在專案根目錄與子目錄。沒有 frontmatter、沒有 globs、沒有套用條件，文件甚至明講，如果你偏好純 Markdown，就改用 AGENTS.md。巢狀檔案與父層合併，越具體的指示越優先，行為與標準精神一致。

 

取捨在於控制粒度：.cursor/rules 有路徑比對、條件套用這類精細機制，AGENTS.md 沒有；但 AGENTS.md 讓通用規則可以沿用到其他支援的工具；換工具時仍要確認檔名設定與載入條件。實務上不少團隊兩層並用：通用規範放 AGENTS.md 給所有工具讀，Cursor 特有的路徑規則留在 .cursor/rules，各取所長。要注意的是，純 .md 檔直接丟進 .cursor/rules 是不會生效的，規則系統需要 frontmatter，這是文件明說的行為。

 

### GitHub Copilot cloud agent：一份清單讀五種指示檔

 

GitHub 的 cloud agent，也就是先前的 coding agent，走大包容路線。依[官方最佳實踐文件](<https://docs.github.com/en/copilot/tutorials/cloud-agent/get-the-best-results>)，它讀的指示檔清單包括 .github/copilot-instructions.md、.github/instructions/ 底下可依路徑套用的 .instructions.md 檔案、\*\*/AGENTS.md、/CLAUDE.md 與 /GEMINI.md，等於把幾家主流工具的慣例檔全部收進來。優先序上，文件明說 repository 層的指示優先於 organization 層。

 

用 copilot-instructions.md 的人有一件事要記得：它的影響範圍不只是 agent。官方明說這份檔案同時套用到 Copilot Chat 與 code review，寫得太針對 agent 的指示，會連你在編輯器裡的聊天與 PR 審查一起影響。AGENTS.md 任意目錄都讀的特性，加上它是跨工具標準，讓它很適合當主檔；copilot-instructions.md 保留給「只想影響 GitHub 生態」的那類規則。第一次指派任務時，Copilot 也會在 PR 留言給出自動生成指示的連結，可以當草稿起點，再人工整理進 AGENTS.md。

 

### 放同一份檔案，六種讀法的實際後果

 

把六個工具的行為放在一起看，幾個後果會浮出來。第一，Gemini CLI 沒設定前完全不讀 AGENTS.md，這是最常見的「我放了卻沒生效」：以為全團隊規則已上線，其實只有部分工具吃到。第二，Claude Code 的條件式讀取讓 CLAUDE.local.md 這類個人檔案有靜默停讀的副作用，多人協作時很難互相發現。第三，巢狀不是人人自動：Codex 逐目錄收錄，Cursor 子目錄支援，opencode 還要區分 V1 的 instructions 設定與 V2 的按需載入，同一份 monorepo 佈局在不同工具和版本上的實際覆蓋範圍不同。

 

可以先請團隊用每個工具各跑一次「總結你目前遵循的專案規則」，把輸出攤開做初步對照。再查工具提供的載入路徑或記憶清單，並到需要局部規則的目錄執行一項可驗證任務。模型的摘要不能單獨證明所有檔案都已載入；上線新的說明檔策略前與每次大改後，都應重新確認。

 

## AGENTS.md 怎麼寫：建議章節、可直接複製的範本與被遵守的原則

 

### 官方建議的章節，與一個好用的判斷標準

 

官網給了一份建議章節清單：專案概述、建置與測試指令、程式碼風格、測試說明、資安考量，再往外延伸到 commit 與 PR 慣例、部署步驟、大型資料集位置這類「你會告訴新隊友的事」。這份清單是起筆的好架構，但它只是建議，真實專案多半會長出自己的分節方式，標準本來就不強制任何結構。

 

比章節清單更實用的是判斷標準：把這份檔案當 onboarding 文件寫。想像你錄取了一位很強、但完全沒看過這個專案的工程師，入職第一小時你會口頭交代什麼？那些內容就是 AGENTS.md 該放的。反過來說，他不會問的（框架的基本語法）、翻程式碼就知道的（函式長相）、經常變動的（這週衝刺目標），都不必寫進去。這個標準能擋掉大半不知道該不該寫的猶豫。

 

### 可直接複製的 AGENTS.md 範本

 

下面這份範本以一個用 TypeScript 與 pnpm 的網站專案為例，把官方建議的章節填成具體內容。複製到儲存庫根目錄後，把指令與路徑換成你專案的實際值，很快就有一份能上線的版本。

 

````
# AGENTS.md

## 專案概述
- 本專案是電商後台，TypeScript + React，套件管理用 pnpm
- 應用程式原始碼在 src/，共享套件在 packages/

## 環境與常用指令
- 安裝相依套件：pnpm install
- 本機啟動：pnpm dev
- 建置：pnpm build
- 只針對單一套件操作：pnpm --filter <package-name> build

## 測試
- 跑全部測試：pnpm test
- 只跑單一檔案：pnpm vitest run src/utils/date.test.ts
- 只跑名稱符合的測試：pnpm vitest run -t 邊界
- 修改行為時，同步補上或更新對應測試
- 送出前執行 pnpm lint 與 pnpm test，失敗先修再交

## 程式碼風格
- TypeScript strict 模式，不為了過編譯放寬既有型別
- 縮排 2 格，字串用單引號，行尾不加分號
- 新的 API 處理函式放在 src/api/handlers/ 底下
- 註解與 commit 訊息用繁體中文

## 提交與 PR
- commit 格式：type(scope): 中文描述，如 fix(auth): 修正 token 更新邏輯
- PR 標題前面加套件名，如 [payments] 新增退款欄位
- 動到資料庫 schema 時，在 PR 說明列出 migration 順序

## 資安與禁區
- 絕對不 commit .env 與任何金鑰
- migrations/ 底下既有檔案只加不改
- src/legacy/ 是待重寫區，除非任務明確要求，不要動

## 工具專屬備註
- Codex：沙盒連不到內網資源，需要時先停下來問
- Claude Code：涉及 src/billing/ 的變更，先進 plan mode 討論
````

 

圖片：AGENTS.md 範本以專案概述、環境與指令、程式碼慣例、測試與驗收、資安與禁區五個部分組成。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-template-structure.webp）

依專案需要保留這五類資訊；指令、路徑與限制應以儲存庫的實際狀態為準。

 

範本裡每一段都有存在理由。「環境與常用指令」是最有價值的一段，因為 agent 拿到可執行指令就能自我驗證；「測試」段的送出前檢查，配合 agent 會主動執行測試指令的行為，等於把驗收閉環寫進檔案。「資安與禁區」放絕對不能碰的東西，語氣可以直白，這不是客氣的地方。「工具專屬備註」是給多工具團隊的緩衝區：某個工具特有的行為約定放這裡，工具專屬段落要明寫適用工具，並檢查是否與通用規則衝突。

 

[OpenAI 官方的 Codex 入門影片](<https://www.youtube.com/watch?v=px7XlbYgk7I&t=492s>)從 08:12 示範 AGENTS.md 的寫法與使用模式，可對照上方範本。

 

OpenAI 官方教學從 08:12 說明 AGENTS.md 的寫法與使用模式。

[以影片頁觀賞：Getting started with Codex](<https://seo.whoops.com.tw/videos/youtube-px7xlbygk7i-d2b6c68a8a/>)

 

想看更多真實範例，官方建議直接上 GitHub 程式碼搜尋，用 path:AGENTS.md 過濾掉 fork 與封存專案，能翻到數萬份現成檔案；官網也點名 openai/codex、apache/airflow、temporalio/sdk-java 這些大型專案的 AGENTS.md 當參考。看別人怎麼寫很快，但抄襲前記得回到自己的專案脈絡：他們的測試指令與禁區，跟你的專案沒有關係。

 

### 寫得會被遵守：具體、可驗證、短

 

同一個意圖的兩種寫法，遵循效果差很多。原則是具體到可驗證：agent 要能拿你的規則當自我檢查的標準，你事後也要有基準看它有沒有做到。

 

| 模糊的寫法 | 具體的寫法 |
| --- | --- |
| 把程式碼整理乾淨 | 縮排 2 格，送出前跑 pnpm lint |
| 記得測試 | 送出前執行 pnpm test，失敗先修再交 |
| 檔案放整齊 | 新的 API handler 放 src/api/handlers/ 底下 |

左邊每次解讀都可能不同，右邊每一條都事後可驗證。

 

### 一條規則的長成過程：從模糊到可驗證

 

拿一條真實會出現的規則看它怎麼演化。第一版通常長這樣：「程式碼要保持整潔」。立意良善，但 agent 沒有檢查標準，整潔的定義每次都重新猜。第二版補上可執行的指令：「送出前跑 pnpm lint 與 pnpm test」。到這裡已經可驗證，跑了沒過就是沒做到，agent 也會自己發現失敗回頭修。第三版再補上結構約定：「新增的 API handler 放 src/api/handlers/，命名用動詞開頭，並補一個 404 案例的測試」。

 

每一版多出來的東西，都不是修辭，是檢查點：第二版給了機器可執行的驗收，第三版給了事後可核對的位置與命名。反過來看，如果一條規則寫完之後，你說不出「違反它會看到什麼」，那它對 agent 大概也不構成約束，值得改寫或刪掉。這個標準比任何範本都可靠，因為它直接對應模型使用規則的方式。

 

長度要有紀律。AGENTS.md 本身沒有官方行數上限，但兩個現實約束擺在眼前：Codex 的合併上限預設 32 KiB，超過就停止收錄；而 context 是每次 session 都要付的固定成本，檔案裡每多一行，留給程式碼與對話的空間就少一行，規則一多，每一條分到的注意力也變薄。修剪時對每一行問同一個問題：刪掉這行，agent 會開始出錯嗎？不會就刪。

 

兩條規則打架時，模型可能任意挑一條遵循，Claude 官方文件對這一點寫得最直白。定期把整份檔案重讀一遍，特別是巢狀多份的 monorepo：根目錄說測試跑 vitest，子目錄又說跑 jest，兩者都「對」的時候就是都錯。維護節奏前面提過，事故驅動最省力：agent 踩坑一次補一條，比憑空想一份完美文件實際。

 

一條硬規則怎麼樣都要放在心上：任何金鑰、帳密、token 都不進 AGENTS.md。這份檔案會進版控、會被團隊每個人看到、會進入模型的 context，它不是放機密的地方，跟 .env 不進 repo 是同一條紀律。

 

圖片：AGENTS.md 規則由「保持整潔」逐步改成 pnpm lint、pnpm test，以及 src/api/handlers/ 路徑和 404 測試的可驗收寫法。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-verifiable-rules.webp）

把規則寫成可執行的指令、明確的檔案位置與測試案例，才有事後可驗收的標準。

 

### 從零開始：用 /init 生成草稿再手工補

 

不想從空白檔案開始，opencode 的 /init 前面提過，會掃描專案生成或就地改善 AGENTS.md；Claude Code 的 /init 生成的是 CLAUDE.md，草稿內容照樣可以整段搬進 AGENTS.md，再用一行匯入接回去。生成的永遠是起點：模型猜得到的東西它寫得出來，但「上層目錄那份 override 是歷史共業」「某個指令要加特定環境變數」這類在地知識，只有你知道。草稿生成後把這些補進去，檔案才真正開始有價值。

 

## 多工具並存：AGENTS.md 與 CLAUDE.md、GEMINI.md、copilot-instructions.md、skills 的取捨

 

真實專案的痛點很少是「選哪個檔案」，而是四種檔案已經同時存在：早期就採用 Claude Code 的團隊有 CLAUDE.md，Gemini 的使用者有 GEMINI.md，GitHub 的重度使用者有 copilot-instructions.md，後來又聽說 AGENTS.md 是標準。全部保留，規則會在四個地方漂移；全部搬家，又怕某個工具讀不到。這一節把取捨講清楚。

 

### AGENTS.md vs CLAUDE.md：專屬記憶系統與跨工具標準

 

本質差異一句話：CLAUDE.md 是 Claude Code 的一環，屬於它自己的四層記憶系統，有匯入語法、auto memory 這些配套；AGENTS.md 是獨立於任何工具的開放標準，一份內容所有支援的工具都能讀。單工具團隊用哪個都行，CLAUDE.md 的分層與路徑規則甚至更細；團隊裡只要有人用第二個工具，AGENTS.md 的優勢就出現了，規則不必維護兩份。

 

Claude Code 對兩者的處理前面講過：有 CLAUDE.md 就只讀 CLAUDE.md，都沒有才讀 AGENTS.md。所以既有 CLAUDE.md 的專案不必刪檔案，官方配方是在 CLAUDE.md 加一行 @AGENTS.md 匯入，通用規則放 AGENTS.md、Claude 專屬指示寫在匯入下方，一份內容兩邊都吃得到。要不要反過來把 CLAUDE.md 收掉併入 AGENTS.md，取決於你們還有多少 Claude 專屬的規則，多就留著，少就收掉。

 

### AGENTS.md vs GEMINI.md：改個設定就並存

 

Gemini CLI 預設只認 GEMINI.md，但 context.fileName 接受清單，把 AGENTS.md 加進去之後，兩份會串接載入。實務上最乾淨的分工是：通用規則全放 AGENTS.md，GEMINI.md 只留 Gemini 特有的偏好，甚至清空。這比維護兩份內容重複的檔案安全得多，規則漂移通常就是從「兩邊都改了、只改了一邊」開始。

 

### AGENTS.md vs copilot-instructions.md：影響範圍不同

 

這兩份的差異主要在相容工具與套用機制。copilot-instructions.md 放 .github/ 目錄，是 GitHub Copilot 的儲存庫指示檔；AGENTS.md 是跨工具格式，在 Copilot cloud agent、部分 Chat 與 code review 環境也有支援，細節以[GitHub 官方支援表](<https://docs.github.com/en/copilot/reference/custom-instructions-support>)為準。建議的分工：通用專案規範放 AGENTS.md，Copilot 專屬規則放 copilot-instructions.md，再確認團隊使用環境是否支援。兩者可以在同一個儲存庫並存，Copilot 會依支援的指示機制讀取；重複或相反的規則仍要整理。

 

### AGENTS.md vs skills.md 與 SKILL.md：名稱撞車的兩種東西

 

搜尋「AGENTS.md vs skills.md」的人，很可能把兩個不相干的東西當成了同類。先講 SKILL.md：它是 Agent Skills 開放標準的檔案，[Claude Code 的 skills 說明頁](<https://code.claude.com/docs/en/skills>)明說這套 skills 實作遵循該跨工具標準，每個技能一個資料夾、一份帶 YAML frontmatter 的 SKILL.md，用途是打包可重複使用的流程。流程的封裝與載入也可參考[Agent Skills 的載入與自製方式](<https://seo.whoops.com.tw/kimi-ai-seo/>)。它與 AGENTS.md 的分工很清楚：AGENTS.md 保存專案指示，依工具的啟動或目錄存取規則載入；skill 是隨需載入的能力包，可以由使用者指定，也能由模型判斷與任務相關後載入。專案如何工作寫前者，發佈流程怎麼跑寫後者，兩者是互補不是競爭。

 

網頁開發就是一個具體例子：[Modern Web Guidance 的網頁平台技能](<https://seo.whoops.com.tw/modern-web-guidance/>)補充原生 HTML、CSS 與瀏覽器相容性知識，測試指令、專案禁區與交付條件則仍寫進 AGENTS.md，兩者各自維護。若任務是讓代理在 App 裡生成互動介面，則可對照[A2UI 1.0 的元件目錄與 SDK](<https://seo.whoops.com.tw/a2ui-1-0/>)，把可用元件、資料綁定與驗證規則另行定義。

 

再講 skills.md 這個網域：[skills.md 網站](<https://skills.md/>)是 Hasna 這家公司經營的託管技能服務，讓 agent 透過 MCP 呼叫雲端執行的技能，有免費額度與按次計費。它是產品，不是規格，跟 AGENTS.md 沒有標準層級的競爭關係。把它跟 AGENTS.md 放在一起比較，就像比較 npm 與 README：一個是取得能力的市集，一個是你專案裡的說明文件。

 

圖片：AGENTS.md 保存專案工作規則，SKILL.md 打包可重複使用的流程，llms.txt 提供網站內容與文件連結（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-skills-llms-txt-comparison.webp）

專案規則、技能流程與網站內容入口解決不同問題。llms.txt 是內容入口提案，不能當作搜尋排名或 AI 引用的保證。

 

### 單一真相檔：三種做法與一個建議

 

整理成一份權威檔案，常見做法有三種，各有適用場景。做法一是匯入：CLAUDE.md 只寫 @AGENTS.md 一行，Claude 專屬內容寫下方，這是 Claude Code 官方給的配方，跨平台最穩。做法二是符號連結，ln -s AGENTS.md CLAUDE.md，檔案系統層級等價，但 Windows 團隊會踩到權限與 checkout 問題，官方不建議跨平台專案用。做法三是設定檔名，Gemini CLI 的 context.fileName 與 Codex 的 project\_doc\_fallback\_filenames 都能讓工具直接認其他檔名，適合不想多建任何檔案的團隊。

 

| 你已經有的檔案 | 建議處置 |
| --- | --- |
| 只有 CLAUDE.md | 通用規則搬到 AGENTS.md，CLAUDE.md 留一行 @AGENTS.md 匯入加 Claude 專屬指示 |
| 只有 GEMINI.md | 通用規則搬到 AGENTS.md，context.fileName 列入兩個檔名 |
| 只有 copilot-instructions.md | 通用規則搬到 AGENTS.md，原本檔案縮減為 GitHub 專屬規則 |
| 三種都有 | AGENTS.md 當唯一權威，其餘檔案退化為匯入或專屬設定，逐一清掉重複內容 |

搬遷原則：通用規則只存在一份，專屬規則明確標示歸屬。

 

搬遷可以分步進行：先備份既有指示檔，再把通用內容整理到 AGENTS.md；CLAUDE.md 加上 @AGENTS.md 匯入，Gemini CLI 設定 context.fileName，各工具另保留必要的專屬規則。確認載入路徑與實際任務行為後，才清掉舊檔的重複內容。只寫「最新規則見 AGENTS.md」不等於設定匯入；保留備份，發現問題時才有明確的回退點。

 

會在同樣幾個工具之間長期搖擺的團隊，決策可以更乾脆：工具怎麼選是另一個問題，[Codex 與 Claude Code 的深度比較](<https://seo.whoops.com.tw/codex-vs-claude-code/>)專文談過各自適合的任務型態；但檔案策略不必跟著工具選擇一起搖擺。AGENTS.md 當主檔、專屬檔當薄薄的轉接頭，是今天各家文件都支撐得住的中間路線，未來換工具或加工具，搬的只是轉接頭，不是規則本體。

 

圖片：AGENTS.md 作為通用規則主檔，CLAUDE.md 使用 @AGENTS.md 匯入，Gemini CLI 透過 context.fileName 設定檔名，另保留少量工具專屬規則。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-single-source-of-truth.webp）

通用規則集中維護；匯入語法與檔名設定要逐一配置，各工具的專屬限制留在自己的檔案。

 

## 界線與維護：AGENTS.md 解決不了的事

 

把期待放對位置。AGENTS.md 是被當成 context 的建議，不是強制設定，這一點各家文件的口徑一致：官方規格明講使用者的即時指示覆寫檔案內容，工具文件也提醒遵循率隨指令品質浮動。它擅長的是把「需要重複交代的事」變成常識，讓 agent 大多數時候做對；它不擅長的是保證。絕對不能發生的事，交給對的層：[Claude Code 的權限與安全設定](<https://seo.whoops.com.tw/claude-code-permissions-plan-mode/>)、hooks，以及 Codex 的核准與沙盒設定、CI 的強制檢查，這些才是硬邊界。說明檔負責教，強制層負責擋，兩層都要有。

 

維護面把它當程式碼對待：進版控、進 code review、變更有意義地寫進 commit。誰都能改，改壞了看得到歷史。評估它的效果也用工程方法：agent 行為跑掉時，先確認檔案有沒有被載入（Codex 問它總結指示、Claude Code 看 /memory 或 /context、Gemini CLI 看 /memory show），再檢查規則是否互相矛盾或太長被截斷，而不是急著加重語氣。語氣從來不是問題，具體與一致才是。

 

圖片：AGENTS.md 規則未生效時，依序確認載入、檢查作用目錄、檢查衝突與長度，最後以測試驗收。（來源：https://seo.whoops.com.tw/wp-content/uploads/2026/10/agents-md-troubleshooting-checklist.webp）

先確認工具讀到正確檔案，再排查作用範圍與指令衝突；需要強制執行的限制仍由權限、hooks 或 CI 驗證。

 

[OpenAI 的提示詞與技能整理建議](<https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra>)也提醒使用者重新檢查 AGENTS.md、skills 和既有長指令。先刪掉過時或互相衝突的規則，再評估需要保留哪些常駐內容。

 

入門不必有儀式感。今天就可以在儲存庫根目錄放一份十行的 AGENTS.md：怎麼裝、怎麼跑測試、一條禁區。下一次 agent 動工前它就在場，之後每次踩坑補一條，一個月後你會有一份比任何範本都貼合專案的規則檔，之後換工具時，先確認載入條件，通用規則仍可維持同一份。

 

## 常見問題

 

### AGENTS.md 是什麼？

 

AGENTS.md 是一份放在儲存庫裡的 Markdown 說明檔，內容寫給 coding agent 讀，定位是「給 agent 的 README」。它記錄專案的建置與測試指令、程式碼慣例、地雷與禁區，讓 agent 在動工前先取得這些 context。格式就是標準 Markdown，沒有必填欄位，規格由 Linux Foundation 之下的 Agentic AI Foundation 治理。

 

### AGENTS.md 要放在哪裡？

 

基本位置是儲存庫根目錄，檔名精確是全部大寫的 AGENTS.md。monorepo 可以在各套件目錄再放巢狀的 AGENTS.md，常見約定是較近的局部規則優先，但是否自動發現及何時載入，仍須看各工具與版本。部分工具還支援全域位置，例如 Codex 的 ~/.codex/AGENTS.md 與 opencode 的 ~/.config/opencode/AGENTS.md，放跨專案的個人規則。

 

### AGENTS.md 怎麼寫？有規定格式嗎？

 

沒有規定格式，就是標準 Markdown，標題隨你用。官方建議的章節包括專案概述、建置與測試指令、程式碼風格、測試說明與資安考量，判斷標準是「你會告訴新隊友的事」。寫作原則是具體、可驗證、簡短：與其寫「記得測試」，不如寫「送出前執行 pnpm test，失敗先修再交」。

 

### agent.md 少一個 s 也有效嗎？

 

標準檔名是複數的 AGENTS.md，只放 agent.md 對多數工具來說等於沒放。還在用單數 AGENT.md 的專案，官方給的搬家方式是改名成 AGENTS.md 之後，再建一個指向它的符號連結維持舊路徑相容，寫死舊檔名的腳本就不會斷。新專案直接用 AGENTS.md 命名即可。

 

### 哪些工具支援 AGENTS.md？

 

依 AGENTS.md 官網採用清單，支援工具包含 OpenAI Codex、Gemini CLI、Cursor、opencode、GitHub Copilot coding agent、VS Code、Windsurf、Junie、Zed、Warp、Devin、Aider、goose、Jules 等 20 多個，Claude Code 也從 2.1.277 版起原生支援。支援程度不同：多數原生就讀，Claude Code 在沒有 CLAUDE.md 時直接讀，Gemini CLI 需要把 context.fileName 指到 AGENTS.md。

 

### AGENTS.md 和 CLAUDE.md 有什麼不同？

 

CLAUDE.md 是 Claude Code 專屬的記憶檔，有自己的四層結構與匯入語法；AGENTS.md 是跨工具標準，一份檔案給所有支援的工具讀。兩者在 Claude Code 的優先序是：工作目錄與上層有任何 CLAUDE.md 或 CLAUDE.local.md 時，預設只讀 CLAUDE.md；都沒有時直接讀 AGENTS.md。想兩者並讀，要在設定裡把 Project instructions 調成 claude-md-and-agents-md。

 

### Claude Code 會直接讀 AGENTS.md 嗎？

 

會，但有條件。Claude Code 從 2.1.277 版起原生支援：工作目錄與其上層都沒有 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 時，session 開始會自動載入沿途的 AGENTS.md，子目錄的 AGENTS.md 則在讀到該目錄檔案時按需載入。既有的 CLAUDE.md 可以用 @AGENTS.md 匯入同一份內容，這是官方給的並存配方。

 

### AGENTS.md 和 skills.md 是同一種東西嗎？

 

不是。常被拿來一起討論的 skills.md 有兩種意思：一是 Claude Code 的 SKILL.md，放在 .claude/skills/ 底下、帶 YAML frontmatter、隨需載入，與 AGENTS.md 的常駐專案說明互補而非競爭；二是網域 skills.md 上的託管技能服務，與 AGENTS.md 規格無關。AGENTS.md 放「這個專案如何工作」，SKILL.md 放「某個流程怎麼執行」。

 

### AGENTS.md 和 copilot-instructions.md 有什麼差別？

 

copilot-instructions.md 是 GitHub Copilot 的儲存庫指示檔，放在 .github/ 目錄；AGENTS.md 是跨工具格式。兩者在 Copilot 的支援範圍依 Chat、cloud agent、code review 與使用環境而異，AGENTS.md 並非只供 cloud agent 使用。用 AGENTS.md 當主檔、copilot-instructions.md 放 GitHub 生態專用的規則，兩者在同一個 repo 可以並存。

 

### AGENTS.md 可以用中文寫嗎？

 

可以。AGENTS.md 的內容就是給模型讀的文字，中文、英文或混合都行，模型對中文的理解足以支撐全中文的規則檔。指令名稱、檔案路徑與程式語法保留原文，模型對原文術語的辨識最穩定；用詞維持一致、指令動詞明確，遵循效果就會好。

 

### 寫在 AGENTS.md 裡的規則 agent 一定會遵守嗎？

 

不一定。AGENTS.md 是被當成 context 的建議，不是強制設定，官方也明講使用者在對話裡的明確指示會覆寫檔案內容。遵循率會隨檔案膨脹與指令模糊而下降，規則互相矛盾時模型可能任意挑一條。必須阻擋的操作，要另外設定適用的 hooks、工具權限與 CI 檢查。

 

### 已經有 CLAUDE.md 和 GEMINI.md 的專案怎麼導入 AGENTS.md？

 

把跨工具通用的內容整理進根目錄的 AGENTS.md，既有檔案用三種方式銜接：在 CLAUDE.md 裡加 @AGENTS.md 匯入、把 Gemini CLI 的 context.fileName 加上 AGENTS.md，或直接把通用規則搬家後縮小既有檔案。工具選擇與檔案策略沒有綁定，先讓通用規則有一份權威版本，再讓各工具的專屬檔案退居輔助。

 

[Agent Skills](<https://seo.whoops.com.tw/tag/agent-skills/>)[AGENTS.md](<https://seo.whoops.com.tw/tag/agents-md/>)[AI Agent](<https://seo.whoops.com.tw/tag/ai-agents/>)[AI 寫程式](<https://seo.whoops.com.tw/tag/ai-coding/>)[Claude Code](<https://seo.whoops.com.tw/tag/claude-code/>)[CLAUDE.md](<https://seo.whoops.com.tw/tag/claude-md/>)[OpenAI](<https://seo.whoops.com.tw/tag/openai/>)[OpenAI Codex](<https://seo.whoops.com.tw/tag/openai-codex/>)

 

喜歡這篇內容？讓下次搜尋，更容易遇見 Whoops。

[將 Whoops 設為 Google 偏好來源（另開 Google 設定頁）](<https://www.google.com/preferences/source?q=seo.whoops.com.tw>)前往 Google 選取並確認，即可完成設定。

 

[## Sliven 褚崇名](<https://seo.whoops.com.tw/about/#founder-title>)

Sliven 褚崇名是 Whoops SEO 創辦人，負責技術 SEO、內容與關鍵字策略、WordPress 網站重建，以及 AI SEO、AEO、GEO 的量測與內容優化。作者頁可查閱由他署名的〈SEO 是什麼〉與〈AI SEO 是什麼〉等教學；內容中的自有量測、模型觀測與第三方來源應分開判讀，並以各頁標示的方法與限制為準。是否適合特定專案，仍需依網站現況、目標、執行範圍與可驗證成果判斷。

[查看作者文章 →](<https://seo.whoops.com.tw/about/#founder-title>)

 

## 討論與提問

 

### 發佈留言

 

WHOOPS / JOURNAL

## 更多值得一讀的文章

[探索知識庫 ↗](<https://seo.whoops.com.tw/blog/>)

[AI 工具與應用約 37 分鐘閱讀

### 最佳 Claude Desktop 完整教學：安裝、MCP 設定與比較

Claude Desktop 是 Anthropic 官方的 macOS 與 Windows 桌面應用程式。本文整理下載安裝、MCP／Connectors、Cowork、Code 模式與 ChatGPT 比較，並加入 2026 年 7 月實機截圖及 Grok Build Gateway＋Grok 4.5 環境說明。

閱讀文章](<https://seo.whoops.com.tw/claude-desktop/>) [AI 工具與應用約 45 分鐘閱讀

### 最佳 WorkBuddy 完整教學：台灣使用方式、費用與安全

WorkBuddy 是騰訊的 AI 辦公工作台。本篇保留實際操作畫面，從模型、工作空間與檔案設定，示範會議紀要、資料分析與十頁 PPT；另整理台灣使用方式、Free／Pro／Team 費用、credits 規則、聯結器、定時任務與資料安全。

閱讀文章](<https://seo.whoops.com.tw/workbuddy/>) [AI 工具與應用約 23 分鐘閱讀

### 最佳 Claude Code 安全設定完整教學：權限與 Plan Mode

Claude Code 安全嗎？本篇從實戰設定角度深掘 Plan Mode、四種權限模式、settings.json allow/deny 規則與 PreToolUse hook 範本（擋 .env/憑證/lock）、Team vs Pro 資料政策與公司導入 8 項檢查表。附真實生產 settings.json 範例與 7 題 FAQ。

閱讀文章](<https://seo.whoops.com.tw/claude-code-permissions-plan-mode/>)
