Claude Code가 AGENTS.md를 읽는다, 단 CLAUDE.md를 지운 저장소만

코딩 에이전트에게 "이 저장소에서는 pnpm만 써라" 같은 규칙을 미리 적어두는 파일이 있습니다. Codex, Cursor, GitHub Copilot, Gemini CLI, Devin은 모두 AGENTS.md라는 같은 이름을 씁니다. Claude Code만 CLAUDE.md를 읽었습니다. 그래서 두 도구를 같이 쓰는 팀은 같은 내용을 파일 두 개로 유지하거나, CLAUDE.md를 AGENTS.md를 가리키는 심볼릭 링크로 만들거나, @AGENTS.md 한 줄만 적힌 CLAUDE.md를 커밋해 왔습니다.

그 우회가 2026년 9월 18일 배포된 v2.1.277부터 필요 없어졌습니다. 릴리스 노트는 한 줄입니다.

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry)

이 한 줄에 조건이 겹쳐 있습니다. CLAUDE.md가 없어야 읽습니다. 동작은 설정으로 바꿀 수 있고, Bedrock과 Vertex, Foundry에서는 아직 안 됩니다. 공식 문서에는 조건이 더 있습니다.

CLAUDE.md가 위쪽에 하나라도 있으면 AGENTS.md는 읽지 않습니다

기본 동작은 합치기가 아니라 둘 중 하나 고르기입니다. 두 파일이 함께 있으면 CLAUDE.md만 읽고 AGENTS.md는 통째로 건너뜁니다. Claude Code 문서의 판정표가 이렇습니다.

"위쪽"의 범위가 넓습니다. 작업 디렉터리뿐 아니라 그 위 모든 상위 디렉터리의 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 AGENTS.md를 막습니다. 반대로 개인 설정인 ~/.claude/CLAUDE.md, 조직 관리형 CLAUDE.md, .claude/rules/ 파일은 막지 않고 AGENTS.md와 함께 로드됩니다.

가장 놓치기 쉬운 것이 CLAUDE.local.md입니다. 팀 저장소는 AGENTS.md로 통일했는데 본인만 커밋하지 않을 메모를 CLAUDE.local.md에 적어 뒀다면, 그 파일 때문에 나만 AGENTS.md를 못 읽는 상태가 됩니다. 둘 다 읽히게 하려면 /config의 Project instructions 값을 바꿔야 합니다.

설정 파일로 고정하려면 ~/.claude/settings.json에 씁니다. 저장소가 대신 정해줄 수는 없습니다. 프로젝트와 로컬 settings 파일에 적으면 무시됩니다.

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

기존 우회를 정리할 때 하나만 주의하면 됩니다. @AGENTS.md import가 든 CLAUDE.md와 심볼릭 링크는 그냥 둬도 내용이 두 번 들어가지 않습니다. 반면 AGENTS.md를 출력하던 SessionStart 훅은 지워야 합니다. 안 지우면 같은 지시문이 컨텍스트에 두 벌 쌓입니다.

로컬 파일을 읽는 기능인데 서버가 켜줘야 합니다

Claude Code는 이 기능을 하드코딩하지 않고 agents-md라는 내장 플러그인으로 넣었습니다. 이 플러그인은 Anthropic 서버에서 받아오는 기능 플래그로 켜집니다. 그래서 네트워크가 필요 없는 로컬 마크다운 읽기인데도 플래그를 못 받는 세션에서는 아예 동작하지 않습니다. 문서는 안 되는 경우를 따로 적어 뒀습니다.

데이터 소재지 규정 때문에 Bedrock이나 Vertex로 Claude Code를 돌리는 팀에는 이번 변경이 적용되지 않습니다. 이 세션들에서는 /config 패널에 Project instructions 항목 자체가 나타나지 않습니다. 텔레메트리를 끈 경우도 같습니다. 이슈 #6235 댓글에서 한 사용자는 settings.json에서 "env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"을 지우고 나서야 설정 항목이 보였다고 보고했습니다.

내 세션에서 실제로 읽혔는지 확인하는 방법이 평소와 다릅니다. 직접 읽은 AGENTS.md는 /memory에도, /context의 Memory files 목록에도 표시되지 않습니다. 대신 세션 시작 직후 대화창에 이런 줄이 뜹니다.

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

InstructionsLoaded 훅도 이 경로에서는 발화하지 않습니다. 훅으로 지시문 로딩을 계측하던 팀은 아무 기록도 남지 않은 채 지나갑니다. import나 심볼릭 링크를 거친 AGENTS.md는 평소대로 발화합니다.

5,178표가 달린 요청은 기능보다 한 달 먼저 닫혔습니다

AGENTS.md는 OpenAI가 2025년 8월에 공개한 규약입니다. 지금은 Linux Foundation 산하 Agentic AI Foundation으로 MCP, goose와 함께 넘어가 있고, 오픈소스 6만 개 이상이 채택했습니다. devlery도 MCP와 A2A가 한 재단에 모인 과정을 다룬 적이 있습니다.

Claude Code 저장소의 요청 이슈 #6235는 2025년 8월 21일에 열렸습니다. 👍 5,178개, 댓글 405개가 달린 채로 2026년 8월 17일에 닫혔습니다. 기능이 나온 것은 그로부터 한 달 뒤인 9월 18일입니다.

그사이 9월 초에 Shopify CEO Tobi Lütke가 X에 이렇게 적었습니다.

Claude Code가 마음을 바꿔 AGENTS.md와 .agents/skills 같은 것을 읽기 전까지는, Shopify에서 Claude Code를 금지할까 생각 중입니다. CLAUDE.md만 고집하면 팀원마다 다른 도구를 쓸 때 서로 다른 지시문을 보는 문제가 생깁니다. 불필요한 일입니다.

Anthropic의 Thariq는 릴리스 당일 X에 "오늘 나온 2.1.277부터, 폴더에 CLAUDE.md가 없으면 Claude가 AGENTS.md를 찾아 사용합니다"라고 알렸습니다.

.agents/skills/는 그대로입니다

Lütke는 두 가지를 요구했는데 Anthropic은 하나만 들어줬습니다. 문서는 무엇을 읽지 않는지 못박아 뒀습니다. AGENTS.local.md, AGENTS.override.md, 그리고 .agents/ 디렉터리 아래 전부입니다. 스킬 파일의 공식 위치는 여전히 .claude/skills/{skill-name}/SKILL.md입니다.

"AGENTS.md와 .agents/skills/ 지원" 이슈 #31005는 릴리스 당일 닫혔고, 곧바로 재오픈 요청이 붙었습니다. 한 참여자는 "v2.1.277은 이 이슈의 AGENTS.md 절반만 해결했다"고 적었습니다.

로딩이 매번 되는지도 아직 확실하지 않습니다. 9월 19일 올라온 버그 리포트 #95589는 v2.1.278에서 같은 디렉터리, 같은 파일, 같은 설정으로 45분 안에 연 세션 8개 중 5개만 AGENTS.md를 로드했다고 기록했습니다. 나머지 3개는 오류도 경고도 없이 지시문 없는 세션으로 돌았습니다. 제보자는 기능 플래그 캐시가 true인 상태에서도 실패했다고 적었습니다. 아직 단일 제보이고 Anthropic 확인 전입니다.

AGENTS.md를 쓰는 저장소를 Claude Code로 열고 있다면, claude --version으로 v2.1.277 이상인지 확인하고 세션 시작 줄에 AGENTS.md loaded가 뜨는지 한 번 보면 됩니다. 안 뜨면 원인은 대개 위쪽 어딘가의 CLAUDE.md나 본인의 CLAUDE.local.md입니다. Bedrock이나 Vertex를 거치는 팀은 이 기능을 기다리지 말고 @AGENTS.md import가 든 CLAUDE.md를 그대로 두는 편이 낫습니다. 플랫폼 지원 여부는 Claude Code 릴리스 노트에 올라옵니다.