如果專案根目錄同時有 CLAUDE.md 和 AGENTS.md，子目錄只有 AGENTS.md，會怎麼合併？
不會合併，這是逐層獨立判斷的。根目錄因為有 CLAUDE.md，就只讀根目錄的 CLAUDE.md；子目錄因為沒有 CLAUDE.md，才會讀子目錄的 AGENTS.md。兩層讀到的檔案來源可能不一樣，這是正常行為，不是 bug——但如果你沒意識到這點，很容易誤以為子目錄的規則跟根目錄用的是「同一份邏輯」在合併。
實務上比較安全的做法是在同一個專案裡統一選定的檔名策略，避免不同目錄層混用兩種檔案造成心智負擔。
managed-only 模式一般個人開發者會用到嗎？
幾乎不會。這個模式的設計對象是需要集中治理的企業組織——例如公司希望所有開發者的 Claude Code 都遵循同一份由 IT 或平台團隊統一派發、員工本機無法覆蓋的規則，藉此避免每個人各自寫的 CLAUDE.md 或 AGENTS.md 造成規範不一致。個人專案或小團隊通常不需要這種鎖定層級，用 claude-md-or-agents-md 或 claude-md-and-agents-md 就足夠。
如果你在公司帳號底下發現 instructionFiles 被設成 managed-only 而你自己的 CLAUDE.md 完全不生效，這通常是平台團隊刻意設定的結果，而不是設定錯誤。
如果團隊決定改用 claude-md-and-agents-md，兩份檔案內容衝突時誰贏？
公開文件目前並未明確定義「衝突時」的裁決順序，實務上比較安全的假設是兩份內容都會被當作指令輸入給模型，如果兩邊直接矛盾（例如一份說用 tabs、另一份說用 spaces），結果會取決於模型自己怎麼權衡兩段同時存在的指示，而不是有一個明確的「誰蓋過誰」規則。
因此用這個模式的團隊，應該把 AGENTS.md 定位成「跨工具通用、範圍較廣」的規範，CLAUDE.md 定位成「Claude Code 專屬、範圍較窄」的補充，盡量避免兩份檔案就同一件事給出互相矛盾的指示。
升級到支援 AGENTS.md 的版本後，我需要手動修改任何現有設定才能生效嗎？
預設模式 claude-md-or-agents-md 已經是升級後的預設值，如果你的專案裡本來就沒有 AGENTS.md，行為完全不會改變——Claude Code 一樣只讀 CLAUDE.md。只有在你的專案（或其中某個子目錄）本來就存在 AGENTS.md、但沒有對應的 CLAUDE.md 時，這個更新才會讓 Claude Code 開始讀取到過去被忽略的內容，這時候務必先檢查那份 AGENTS.md 裡的規則是否適用於 Claude Code（例如某些針對其他工具語法的指令可能不適用）。
最保險的做法是升級後先跑一次 /status 確認目前生效的 instructionFiles 模式與實際讀取到的檔案路徑，再決定要不要調整。
如果你的團隊同時用 Claude Code 和其他 AI 編碼工具（例如 Cursor、Aider、或任何遵循開放 Claude Code 生態外的 AGENTS.md 規範的工具），過去最麻煩的事情之一，就是要為每個工具各寫一份幾乎一樣的指令檔——CLAUDE.md 給 Claude Code，AGENTS.md 給其他工具，兩份內容一改就要同步改兩次，時間一長必然會漂移。Claude Code 近期版本原生支援讀取 AGENTS.md 作為指令檔案，這篇文章把實際的優先權邏輯、四種設定模式、以及一個容易被忽略的 CLAUDE.local.md 交互細節講清楚。
核心規則很簡單但容易被誤解：在每一層目錄裡，Claude Code 會先找 CLAUDE.md，只有在找不到 CLAUDE.md 的情況下，才會退而讀取同目錄下的 AGENTS.md。這不是「兩者都讀、合併內容」的機制——是逐層的 either/or 判斷。也就是說，如果你的專案根目錄同時放了 CLAUDE.md 和 AGENTS.md，Claude Code 只會讀 CLAUDE.md，AGENTS.md 裡寫的東西完全不會生效，即便它可能是給其他工具維護的更新版本。這也代表如果你原本用其他工具、已經累積了一份維護良好的 AGENTS.md，直接讓 Claude Code 沿用它是可行的，不需要重寫；但一旦哪天有人在同一目錄加了一個空的或過時的 CLAUDE.md，AGENTS.md 就會被靜默忽略，而且不會有任何錯誤提示。
這個行為透過 settings.json 裡的 instructionFiles 欄位控制，有四種可設定的值：
CLAUDE.md，完全不讀取 AGENTS.md，即使找不到 CLAUDE.md 也不會退回去找它——這是最保守、最明確的模式，適合不想要任何隱性 fallback 行為的團隊。CLAUDE.md，找不到才用 AGENTS.md 補位，如前段所述的 either/or 邏輯。CLAUDE.md 放 Claude Code 專屬的補充規則（例如某個 slash command 的用法），同時共用 AGENTS.md 裡跨工具通用的專案規範，兩份內容會被同時載入而不是互斥。選擇哪個模式取決於你的協作情境：純 Claude Code 團隊建議用 claude-md 避免任何意外讀檔；混合工具鏈團隊多半該用 claude-md-and-agents-md，讓兩份檔案各司其職而不是互相取代。
另一個實際操作中常被忽略的細節是 CLAUDE.local.md（未提交進版控、只在本機生效的個人化指令檔）跟 AGENTS.md 的交互關係。CLAUDE.local.md 的優先權高於同層的 AGENTS.md——即使你的模式是 claude-md-or-agents-md 且該目錄沒有 CLAUDE.md，只要存在 CLAUDE.local.md，它就會蓋過 AGENTS.md 生效，而不是兩者疊加。這意味著如果你在本機留了一份舊的、用來臨時除錯的 CLAUDE.local.md，之後團隊統一遷移到 AGENTS.md 規範，你本機的 Claude Code 實際上仍然在吃那份被遺忘的本機檔案，行為會跟同事不一致，而且很難第一時間意識到原因是本機殘留的個人指令檔案。
如果你的工程團隊已經、或打算採用多種 AI 編碼工具並存的策略，這個原生支援直接省下了維護重複指令檔的時間成本，也降低了指令漂移導致 AI 輸出品質不一致的風險。但升級前務必先用 /status 或直接檢查 settings.json 確認目前的 instructionFiles 模式，並清點專案裡各層目錄殘留的 CLAUDE.local.md——這比想像中常見，尤其是在做過臨時除錯或個人化配置之後忘記刪除的情況下。