Claude Code·Codex·Cursor가 AGENTS.md 하나를 같이 읽는 법

AGENTS.md는 여러 코딩 에이전트가 함께 읽기로 한 지침 파일 이름입니다(agents.md). Codex와 Cursor는 이 파일을 읽었지만 Claude Code는 CLAUDE.md만 읽어서, @AGENTS.md 한 줄짜리 CLAUDE.md를 따로 두는 레포가 많았습니다. 이 블로그 레포의 CLAUDE.md도 그 한 줄입니다.

CLAUDE.md가 없을 때만 읽는 AGENTS.md

v2.1.277부터 Claude Code는 작업 폴더와 그 위 폴더에 CLAUDE.md가 없으면 AGENTS.md를 프로젝트 지침으로 읽습니다.

AGENTS.md를 건너뛰게 만드는 파일은 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md(커밋하지 않는 개인 지침) 셋입니다(공식 문서). 개인 전역 파일 ~/.claude/CLAUDE.md와 .claude/rules/는 여기에 들지 않고 AGENTS.md와 함께 읽힙니다. 하위 폴더의 AGENTS.md는 Claude가 그 폴더의 파일을 열 때 붙습니다.

직접 v2.1.292에서 두 파일에 서로 다른 암호를 적어 두고 Claude에게 물어 확인했습니다.

v2.1.280 전에는 /memory 목록에 직접 읽은 AGENTS.md가 나오지 않았습니다. 그 전 버전에서는 Claude에게 프로젝트 지침 내용을 물어 확인합니다.

세 도구가 한 파일을 쓰게 하는 구성 셋

고르는 기준은 Claude에게만 줄 지침이 있는지, Windows에서 클론하는 사람이 있는지입니다.

2번은 CLAUDE.md 맨 위에 @AGENTS.md(그 파일 내용을 끌어와 함께 읽는 import)를 쓰고 아래에 Claude 전용 줄을 붙입니다. 공식 문서의 예입니다.

1@AGENTS.md
2
3## Claude Code
4Use plan mode for changes under `src/billing/`.

Claude는 AGENTS.md를 먼저, 아래 줄을 뒤에 읽습니다. 3번의 심볼릭 링크(다른 파일을 가리키는 바로가기 파일)는 Windows에서 만들려면 관리자 권한이나 개발자 모드가 필요하고, core.symlinks가 꺼진 클론에서는 경로 한 줄짜리 텍스트 파일로 풀립니다.

예전 우회책 가운데 @AGENTS.md import는 남겨 둬도 두 번 읽지 않습니다. 세션 시작 때 AGENTS.md를 출력하던 SessionStart 훅은 같은 내용을 한 벌 더 넣으니 지웁니다. "AGENTS.md를 읽어라"라고 글로만 적은 CLAUDE.md는 Claude가 파일을 열기로 해야만 내용을 보므로 import로 바꿉니다.

CLAUDE.local.md와 AGENTS.md를 함께 읽히려면

CLAUDE.local.md도 AGENTS.md를 건너뛰게 만듭니다. AGENTS.md로 돌던 레포에 개인 메모용 CLAUDE.local.md를 만들면, 그때부터 내 세션만 AGENTS.md를 읽지 않습니다. /config의 Project instructions를 claude-md-and-agents-md로 바꾸면 폴더마다 CLAUDE.md를 먼저, AGENTS.md를 뒤에 읽습니다(설정 값).

기본값은 claude-md-or-agents-md이고, claude-md와 managed-only(조직 관리형 지침만)는 AGENTS.md를 읽지 않습니다. 설정 파일에 두려면 ~/.claude/settings.json에 씁니다.

1{
2  "pluginConfigs": {
3    "cc-plugin-agents-md@builtin": {
4      "options": { "instructionFiles": "claude-md-and-agents-md" }
5    }
6  }
7}

키 이름은 AGENTS.md 읽기를 맡은 내장 플러그인의 ID이고, v2.1.285 전에는 agents-md@builtin이었습니다. 레포의 .claude/settings.json에 쓴 값은 무시되므로 팀 전체에 맞추려면 관리형 설정(조직이 배포하는 설정)을 씁니다.

Codex·Cursor가 같은 파일을 읽는 방식

루트의 AGENTS.md는 세 도구가 모두 읽지만(Claude Code는 CLAUDE.md가 없을 때만), 하위 폴더 파일과 덮어쓰기 파일을 다루는 방식이 다릅니다.

Codex는 실행할 때 한 번, Git 루트에서 지금 폴더까지 폴더마다 파일 하나를 골라 이어 붙입니다. 같은 폴더에 AGENTS.override.md(Codex의 덮어쓰기 파일)가 있으면 AGENTS.md 대신 그것을 읽고, 합친 크기가 32 KiB를 넘으면 더 붙이지 않습니다. CLAUDE.md는 설정의 project_doc_fallback_filenames에 이름을 더해야 읽습니다. 반대로 AGENTS.override.md에 둔 규칙은 Claude Code에 닿지 않습니다.

Cursor는 .cursor/rules의 .mdc 파일(머리에 적용 조건을 적는 규칙 파일)과 AGENTS.md를 함께 읽습니다. 하위 폴더 AGENTS.md는 그 폴더 파일을 다룰 때 부모 것과 합쳐지고, 더 구체적인 쪽이 이깁니다. 루트의 CLAUDE.md도 AGENTS.md처럼 자동으로 읽으므로(Cursor 도움말), 2번 구성의 Claude 전용 줄도 Cursor에 들어갑니다.

Bedrock에서 안 읽히던 문제와 남은 차이

릴리스 원문은 Bedrock·Vertex·Foundry에서는 아직 안 된다고 적었지만, v2.1.281부터 이 환경과 텔레메트리를 끈 세션에서도 읽습니다. /plugin에서 내장 플러그인을 끄거나 v2.1.276 이하에서 올린 직후 첫 세션 일부에서는 CLAUDE.md만 읽고, /config에 Project instructions 항목도 보이지 않습니다.

설정으로 읽은 AGENTS.md에는 지침 파일을 읽을 때 도는 InstructionsLoaded 훅이 돌지 않고, --add-dir로 더한 폴더의 AGENTS.md도 읽지 않습니다. 이 동작에 기대고 있다면 import 구성이 안전합니다.

세 도구가 같은 지침을 보게 하는 일은 이제 루트에 AGENTS.md를 두는 것으로 끝납니다. 걸리는 곳은 개인용 CLAUDE.local.md와 Codex의 AGENTS.override.md 둘입니다. CLAUDE.local.md를 쓰고 있다면 /memory 목록에 AGENTS.md가 보이는지부터 확인합니다.