AGENTS.md

AGENTS.md 是什麼，為什麼會有這個檔案？

AGENTS.md 是一套跨工具的專案指示檔規格，目的是讓同一份專案說明文件能被多種 AI 編碼工具共用，不用每套工具各自維護一份格式不同、內容卻幾乎重複的設定檔。The Register 的報導指出，這套規格原本是 OpenAI 陣營主要在推動的，Anthropic 在 2026 年 9 月 18 日發布的 v2.1.277 決定讓 Claude Code 也支援它，等於承認了團隊 repo 裡堆了 CLAUDE.md、AGENTS.md、.cursorrules 等好幾份幾乎相同指示檔的真實維護負擔。

在 v2.1.277 之前，Claude Code 只認 CLAUDE.md，完全不讀 AGENTS.md，匯入或 symlink 是當時唯一能讓內容生效的變通方法；之後，官方文件已經寫明「資料夾裡沒有 CLAUDE.md 時，Claude 會改讀 AGENTS.md」，不再需要任何變通手法。

如果 repo 裡 CLAUDE.md 跟 AGENTS.md 同時存在，到底讀哪一份？

官方預設行為是 claude-md-or-agents-md 模式：只要在目前目錄或任何上層目錄找到 CLAUDE.md、.claude/CLAUDE.md，或 CLAUDE.local.md 三者之一，Claude Code 就只載入這些，完全跳過 AGENTS.md；只有整個目錄樹都找不到任何 CLAUDE.md 變體時，才會把 AGENTS.md 當成備案讀取。這個行為可以透過設定調整：claude-md-and-agents-md 會讓兩份檔案同時載入（CLAUDE.md 優先、並做去重），claude-md 完全不理會 AGENTS.md，managed-only 限定只讀組織層級管理的 CLAUDE.md。

這裡最容易被忽略的細節是：CLAUDE.local.md（開發者個人用、不進版控的設定檔）在「是否存在 CLAUDE.md」這個判斷上，跟團隊共用的 CLAUDE.md 地位完全相同。這代表如果團隊 repo 本來只用 AGENTS.md，某個開發者為了寫自己的私人設定建立了 CLAUDE.local.md，在預設模式下，這個開發者的 Claude Code 就會悄悄停止讀取團隊共用的 AGENTS.md，其他沒建這份檔案的同事則完全不受影響。

如果團隊已經維護一份 AGENTS.md，想讓 Claude Code 吃到裡面的內容，又不想維護兩份重複檔案，怎麼做最省事？

社群整理的操作指南列出了兩種從舊版本沿用至今仍然有效的做法：在 CLAUDE.md 檔案最上方加一行 @AGENTS.md 匯入指令，Claude Code 會在 session 啟動時載入被匯入的內容，再接著讀取 CLAUDE.md 裡 Claude 專屬的補充指示；或者直接建立 CLAUDE.md 指向 AGENTS.md 的 symlink。在 Windows 上，建立 symlink 需要系統管理員權限或開發者模式，所以 @AGENTS.md 匯入法在跨平台團隊裡更實用。

另外，在已經有 AGENTS.md 的 repo 裡執行 /init，Claude Code 會讀取其內容並併入自動產生的 CLAUDE.md，提供一次性整合的選項，不需要手動寫匯入指令。

設定好了卻發現 Claude Code 沒有讀到 AGENTS.md，該從哪裡開始排查？

先確認版本是否在 v2.1.277（2026/9/18）之後——這個功能有明確的時間分界線，網路上流通的教學文章新舊混雜，很容易查到過時版本的說明。接著確認目前使用的平台：這個功能目前還沒有擴展到 Bedrock、Vertex 或 Foundry 等平台。另外，沒有 feature-flag 權限、或關閉了 telemetry 的 session 也讀不到 AGENTS.md；全新安裝的 Claude Code 在第一次 session 完成之前，這個能力也還沒生效。

如果以上都確認過沒問題，再檢查目錄樹裡是否意外存在一份 CLAUDE.local.md——這是最常被忽略的原因，它會讓 Claude Code 判定「已經有 CLAUDE.md」，直接跳過 AGENTS.md，而這份檔案通常不會出現在版控紀錄裡，排查時容易被忽略。