不再是備援方案：Claude Code 終於支援 AGENTS.md —— 拆解 2.1.277 版更新

過去一年多，AI 輔助開發領域最惱人的痛點之一，跟模型能力毫無關係。如果你的專案倉庫裡放了一份 AGENTS.md——專案層級 AI 指令的開放標準檔案——Claude Code 會直接無視它。這個工具只讀 CLAUDE.md，而且只讀 CLAUDE.md。想兩者兼顧的開發者，必須維護一堆 symlink、重複檔案或同步腳本，只為了讓 Anthropic 的編碼代理和生態系其他工具看到同一份指令。

這個時代在 2026 年 9 月 18 日劃下句點，Claude Code 更新日誌裡出現了一行字。版本 2.1.277「新增 AGENTS.md 支援：專案中沒有 CLAUDE.md 時，Claude Code 改為讀取 AGENTS.md」。這個行為可以在 /config 的「Project instructions」底下調整。這是個小功能，背後卻有一長段故事——而且伴隨一組注意事項，任何團隊在決定今天要不要刪掉 workaround 之前，都應該先看清楚。

實際上釋出了什麼

機制設計刻意保守。Claude Code 在專案裡啟動工作階段時，會先找自家原生的指令檔 CLAUDE.md。如果不存在——沒有 CLAUDE.md，而且根據社群實測，CLAUDE.local.md 也沒有——工具才會退而求其次，改讀 AGENTS.md。這個設定在 /config 面板的「Project instructions」底下有開關，需要固定行為的企業可以整個關掉回退機制。

有兩個限制必須立刻點出來。第一，這個功能尚未支援 Bedrock、Vertex 與 Foundry——也就是受監管企業使用 Claude Code 最多的那些託管雲端部署。如果你的組織透過 AWS、Google Cloud 或 Azure 的管線跑 Claude Code，目前仍然活在 2.1.277 之前的世界。第二，也是 Hacker News 上早期採用者最痛的一點：這個回退只涵蓋指令檔本身，並不包含 .agents/skills——較完整的 AGENTS.md 生態會用這個目錄層級慣例，把可重用的技能連同指令一起打包。第一批留言者之一寫道：「注意這不包含 .agents/skills。啊。」——算是對這半步最公道的總結。

AGENTS.md 支援是搭著一次大規模維護性版本一起來的。2.1.277 同時新增了閘道與外掛控制——給「唯一對外連線是正向代理」的 Claude apps 閘道用的 CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY 旗標，以及閘道上行的選配 headers: 映射——並修了一長串穩定性問題：無頭模式 claude -p 和 Agent SDK 工作階段在內部錯誤後可能無聲掛死的問題，現在會回報錯誤並以結束碼 1 退出；「text content blocks must be non-empty」的對話失敗修好了；Edit 工具裡一個解析缺陷——跳脫反斜線後面接 uXXXX 序列時可能弄壞編輯內容，對含非 ASCII 字元的程式碼是實際危險——也獲得修正。

為什麼一個檔名之爭這麼重要

要理解為什麼一個設定回退能在 Hacker News 拿到 51 分、引發一波部落格文章，得回頭看 AGENTS.md 的來歷。這個標準由 OpenAI 在 2025 年 8 月提出，作為對「工具專屬規則檔大爆炸」的廠商中立解方：CLAUDE.md 給 Claude Code、.github/copilot-instructions.md 給 GitHub Copilot、.cursorrules 給 Cursor、GEMINI.md 給 Gemini CLI。訴求很簡單——倉庫根目錄放一份 markdown，所有編碼代理都讀它，描述建置指令、程式碼風格、測試慣例與架構護欄，就像 README.md 對人類描述專案一樣。

以開發者工具的標準來說，採用速度很快。Codex、Gemini CLI、Cursor 和一長串較小的代理都接了，到 2025 年底 GitHub 上已有超過 20,000 個倉庫內嵌這個檔案。Claude Code 是最顯眼的釘子戶。其他所有主要代理都讀開放標準，就 Anthropic 的不讀。

這個堅持造成的成本不只是美感問題。以 AGENTS.md 為標準的團隊發現，Claude Code 工作階段靜悄悄地在「沒有任何專案指令」的狀態下執行——工具不會警告你它看到一個認不得的檔案。 圍繞這個缺口長出來的 workaround 文化自成一格：把 CLAUDE.md symlink 到 AGENTS.md、用 CI 檢查兩邊同步，還有 Hacker News 上那句自嘲：「為了 md 檔名搞廠商鎖定，真是瘋了。」

壓力在檯面上持續累積。Shopify 執行長 Tobi Lütke——他的公司經營著數一數二大的 Claude Code 部署——公開推文談這個落差，而競爭格局也在 2026 年 9 月隨著 OpenAI 的 Codex 搭上 GPT-6 Astra 的氣勢而變化。Hacker News 上有留言這樣論斷：「是 Shopify 執行長那則推文，加上 Astra 讓一大票人轉向 Codex，他們才終於讓步。」這個因果故事是否精確見仁見智，但時間點頗耐人尋味：功能上線前幾週，正是一波高能見度的 AGENTS.md 倡議，和一個競爭異常激烈的編碼代理市場。

當老二的策略

有一種說法是，Anthropic 的拖延純粹是工程優先順序問題，而非鎖定策略——更新日誌裡密密麻麻的修復，顯示這個團隊埋首於其他事。但實作的形狀本身就說明了立場。這是回退，不是預設。CLAUDE.md 在解析順序中仍是第一名，AGENTS.md 只在它缺席時才被讀取。Anthropic 一邊可以宣稱相容開放標準，一邊讓自家格式維持特權位置——這正是一年多前 GitHub issue 裡請求的「雙檔案做法：原生格式優先，優雅回退到開放標準」。

對團隊而言，接下來的實際問題是該以哪個檔案為標準。如果你本來就兩份都維護，重複維護的壓力減輕了：一份 AGENTS.md 現在同時餵飽 Claude Code 和其他所有相容代理，代價是失去「刻意讓 Claude 版指令分歧」的空間。如果你只用 CLAUDE.md 而且用得很開心，什麼都不變。尷尬的中間地帶——需要 Claude 專屬覆寫又需要跨工具指令的倉庫——仍然沒有乾淨解，因為優先順序只往一個方向跑。

更大的解讀是關於整併。代理指令格式是 2025 到 26 年產業的格式之戰，而這次釋出實質上就是開放標準勝利的那一刻。當最後一個主要釘子戶採用了某個慣例——哪怕是部分採用、哪怕只是回退——網路效應就翻面了：新專案現在會預設用 AGENTS.md，因為它到處都能動，工具專屬檔案反而變成相容性墊片，而非主要載具。尚未解決的是檔案之上更豐富的那一層：.agents/skills、巢狀指令探索、匯入與優先規則——廠商還能差異化的地方。可以預期下一場標準之戰會打在那裡。

至於現在，幾千位開發者在做一件更簡單的事：執行 claude --version、更新到 2.1.277，然後刪掉一個 symlink。正如一位 Hacker News 留言者所說：「終於。現在可以把所有 symlink 刪一刪了。」

封面圖由 MiniMax 圖像生成產生。來源列於 frontmatter 中，並渲染於下方。