Claude Code 2.1.277 為開放格式 AGENTS.md 加入原生支援:在專案內沒有 CLAUDE.md 時,Claude Code 可改讀 AGENTS.md 作為專案指令。對於已經用同一份說明檔服務多個 AI 編碼工具的團隊,這代表不必先額外建立 Claude 專用檔案,也能讓 Claude Code 取得儲存庫規範。
1
最重要的規則:這是備援,不是預設合併
官方變更紀錄描述的預設邏輯很直接:
- **沒有
CLAUDE.md 的專案:**Claude Code 會使用 AGENTS.md 作為專案指令。
1
- 已有
CLAUDE.md 的專案:CLAUDE.md 仍是既有的專案指令檔;官方針對預設備援行為,並未說明會自動把兩份檔案合併載入。
1
可在 Claude Code 輸入 /config,進入 Project instructions 調整此行為。這項功能目前尚未支援 Amazon Bedrock、Google Vertex AI 與 Azure AI Foundry 上的 Claude Code 部署。
1
AGENTS.md 是什麼?
AGENTS.md 是給 AI 編碼代理使用的開放 Markdown 格式,可把它理解為「寫給代理看的 README」。它適合放置代理在特定儲存庫工作時需要的固定背景,例如:專案架構、環境設定步驟、建置與測試指令、程式碼慣例,以及貢獻規則。
19
32
此格式源自 OpenAI Codex、Amp、Google Jules、Cursor 與 Factory 等團隊的協作,現由 Linux Foundation 旗下的 Agentic AI Foundation 維護。專案方表示,目前已有超過 6 萬個開源儲存庫採用。
19
21
AGENTS.md 官網列出的生態系工具包括 OpenAI Codex、Google Jules、Cursor、GitHub Copilot coding agent、Gemini CLI、Aider、Zed、Warp、VS Code、Devin、JetBrains Junie、Factory、Goose 與 OpenCode 等。
19 不過,各工具對檔案搜尋範圍、目錄層級規則與衝突處理方式仍可能不同;有檔案不代表在所有工具中的載入結果完全一致。
對團隊有何實際影響?
在原生支援以前,若團隊以 AGENTS.md 作為共用規範,想讓 Claude Code 讀取同一份內容,通常得採取額外做法:
- 維護另一份
CLAUDE.md;
- 將
CLAUDE.md 建立為指向 AGENTS.md 的符號連結;或
- 建立內容只有
@AGENTS.md 匯入指令的精簡 CLAUDE.md。
這些都是 Claude Code 尚未原生讀取 AGENTS.md 時的替代方案。
10
現在,若儲存庫不需要 Claude 專屬指令,一份共用的 AGENTS.md 就能同時成為 Claude Code 與其他相容工具的基本工作說明,減少重複維護與內容不同步的機會。
但這不代表所有指令機制都已統一。團隊仍應實際確認每一種代理如何尋找檔案、是否讀取子目錄規則,以及遇到多份指令時採取何種優先順序。
AGENTS.md 與 SKILL.md:用途不同,彼此互補
這次更新也容易和 Anthropic 推動的 Agent Skills 混為一談;兩者並不是替代關係。
AGENTS.md:儲存庫層級的長期工作指引,也就是在某個程式碼庫中應遵守的背景與規則。
19
32
SKILL.md:Agent Skill 的核心檔案。Skill 是可重複使用的檔案系統套件,可含指令、中繼資料與其他支援資源;Claude 會在任務相關時使用它來取得特定工作流程或領域知識。
33
37
Claude Code 表示其 Skills 遵循跨工具的 Agent Skills 標準。其文件所示的專案 Skill 結構,是將 SKILL.md 放入各自目錄,例如 .claude/skills/<名稱>/SKILL.md。
37
39
簡單說,AGENTS.md 是「這個專案平常怎麼做事」,SKILL.md 則是「遇到特定任務時可取用的專業工具包」。
仍存在的限制
此次更新解決的是專案指令檔的備援問題,並不表示 Claude Code 已完整支援所有代理工具慣例。
首先,Claude Code 文件列出的專案 Skill 位置仍是 .claude/skills/<名稱>/SKILL.md。2.1.277 的更新公告只談到 AGENTS.md 專案指令,並未宣布支援探索 .agents/skills/ 目錄。
1
37
其次,不應把預設備援視為 CLAUDE.md 與 AGENTS.md 的自動合併規則。若專案同時需要可攜的跨工具規範與 Claude Code 專屬做法,應明確定義兩者關係,而不是單靠備援機制。
已有 CLAUDE.md 的專案,建議怎麼安排?
對既有 Claude Code 專案而言,一個務實的做法是:
- 將通用、跨工具的儲存庫規範放進
AGENTS.md。
- 將 Claude Code 專屬的工作流程與指令保留在
CLAUDE.md。
- 視需要由
CLAUDE.md 明確參照或匯入共用規範,不要假設兩份檔案必然會同時載入。
這樣既能保留跨工具可攜性,也能把 Claude 專屬設定清楚分開。Claude Code 2.1.277 的意義正在於此:它讓「以 AGENTS.md 為主」的儲存庫在缺少 CLAUDE.md 時也能直接使用 Claude Code,但並未宣稱各家工具的指令檔與 Skill 搜尋規則已完全一致。