Claude Code AGENTS.md 설정: 안 읽히는 파일과 하위 폴더 규칙

Codex CLI용으로 꾸려 둔 저장소를 Claude Code로 열면 지시 파일이 어디까지 따라올지 궁금했습니다. 그래서 AGENTS가 이름에 들어간 파일 여섯 개에 서로 다른 코드워드를 하나씩 적고, Claude에게 처음 받은 지시에 들어 있는 코드워드를 전부 말해 달라고 했어요.

돌아온 건 두 개뿐이었습니다. 루트의 AGENTS.md와 .claude/AGENTS.md요. 나머지는 이렇게 됐습니다.

• AGENTS.override.md, AGENTS.local.md: 경고 없이 빠짐
• .agents/AGENTS.md: 빠짐
• sub/AGENTS.md: 그 폴더의 파일을 어떤 방법으로 여느냐에 따라 붙기도 하고 안 붙기도 함

AGENTS.md만 있는 저장소라면 Claude Code에서 따로 할 일은 없습니다. 다만 Codex 전용 파일에 적은 지시는 Claude에게 닿지 않으니 공통 지시는 AGENTS.md로 옮기고, 개인 메모를 두고 싶으면 Project instructions 설정을 사용자 설정에서 먼저 바꾸세요.

2026년 10월 26일 Ubuntu 24.04 테스트 환경에서 Claude Code 2.1.310으로 직접 확인했고, 공식 문서도 같은 날 확인했습니다.

여섯 개 중 두 개만 읽혔다

Claude Code는 시작할 때 작업 폴더와 그 위 모든 폴더에서 AGENTS.md와 .claude/AGENTS.md를 찾습니다. 두 파일이 다 있으면 둘 다 읽어요.

반대로 이름이 비슷한 다음 파일들은 읽지 않도록 정해져 있습니다.

• AGENTS.override.md와 AGENTS.local.md
• .agents/ 폴더 아래의 모든 파일

Codex CLI는 폴더마다 AGENTS.override.md를 먼저 찾기 때문에, Codex에서 쓰던 덮어쓰기 지시가 Claude Code에서는 그냥 사라지는 셈이에요.

Codex용 덮어쓰기 파일에만 적어 둔 규칙은 Claude Code가 모르는 규칙입니다. 두 도구가 같이 지켜야 하면 AGENTS.md로 옮기세요.

읽혔는지 확인하는 건 간단합니다. 세션에서 /context를 치면 Memory files 표에 읽힌 파일이 나와요. 위 저장소에서는 이렇게 두 줄이었습니다.

| Type | Path | Tokens |
|------|------|--------|
| Project | <프로젝트 경로>/AGENTS.md | 19 |
| Project | <프로젝트 경로>/.claude/AGENTS.md | 19 |

/memory를 열어 목록에서 경로를 찾아도 됩니다. 대화형 세션에서는 대화 안에 no CLAUDE.md found; AGENTS.md loaded: 같은 줄도 보입니다.

하위 폴더 AGENTS.md는 Read 도구로 열어야 붙는다

모노레포에서는 패키지마다 AGENTS.md를 두기도 합니다. 이 파일은 시작할 때가 아니라 Claude가 그 폴더 일을 할 때 붙는데, 붙는 조건이 CLAUDE.md보다 좁더라고요.

저장소 루트에서 시작해 sub/notes.txt를 열게 한 뒤 코드워드를 다시 물었습니다.

그 폴더 파일을 연 방법	sub/AGENTS.md	sub/CLAUDE.md(비교용)
Read 도구로 읽기	붙음	—
Bash로 cat sub/notes.txt	안 붙음(두 번 모두)	붙음

하위 폴더 CLAUDE.md는 Claude가 그 폴더 파일을 읽거나 쓰거나 고칠 때 붙습니다. 파일 하나를 Bash로 출력하는 것(cat, head)도 읽기로 쳐요.

반면 하위 폴더 AGENTS.md는 Claude가 Read 도구로 그 폴더 파일을 열 때 붙고, Bash로 본 것은 치지 않습니다. 그 폴더에 CLAUDE 파일 세 종류 중 하나라도 따로 있으면 Read 도구로 열어도 붙지 않고요.

Claude가 그 폴더를 Bash의 cat이나 grep으로만 들여다보면, 패키지 규칙이 있는데도 모르는 채 일할 수 있다는 뜻입니다. 그래서 한 패키지만 만질 때는 그 패키지 폴더에서 claude를 띄우는 걸 권합니다. sub에서 시작하니 sub/AGENTS.md가 처음부터 지시에 들어와 있었거든요.

하위 폴더 파일을 @로 멘션했을 때 그 폴더의 AGENTS.md가 붙지 않던 문제도 2.1.290에서 고쳐졌습니다. 그보다 오래된 버전을 쓰고 있다면 업데이트부터 하세요.

개인 메모를 두려면 Project instructions를 먼저 바꾼다

기본값에서는 작업 폴더나 그 위에 CLAUDE 파일이 하나라도 있으면 AGENTS.md를 통째로 건너뜁니다. 여기서 CLAUDE 파일은 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 세 가지예요. 개인 메모용 CLAUDE.local.md 하나가 팀 지시를 끄는 장면은 CLAUDE.md 작성법 글의 AGENTS.md 절에서 Windows로 확인해 뒀어요.

다음 파일은 이 판단에 들어가지 않고 AGENTS.md와 나란히 읽힙니다.

• 사용자 파일 ~/.claude/CLAUDE.md
• 조직이 배포한 managed CLAUDE.md
• .claude/rules/ 아래 규칙 파일

이 동작은 /config의 Project instructions로 바꿉니다. 값은 넷입니다.

값	읽는 것
claude-md-or-agents-md	기본값. CLAUDE 파일이 없을 때만 AGENTS.md
claude-md-and-agents-md	둘 다. 폴더마다 CLAUDE.md가 먼저
claude-md	CLAUDE.md 계열만
managed-only	시작 때는 managed CLAUDE.md와 자동 메모리만

둘 다 읽게 해도 import나 심볼릭 링크로 이미 들어온 AGENTS.md는 두 번 읽히지 않습니다. managed-only여도 하위 폴더의 CLAUDE.md와 .claude/rules/, 경로 조건 규칙은 필요할 때 따로 붙고요.

설정 파일에 적을 때는 저장소가 아니라 사용자 설정에

/config 대신 설정 파일에 적을 수도 있습니다. 내장 플러그인 설정 아래 instructionFiles로 적어요.

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

팀 전체에 적용하려고 이걸 저장소의 .claude/settings.json에 넣어 봤습니다. AGENTS.md와 CLAUDE.local.md를 함께 둔 저장소였는데, 여전히 CLAUDE.local.md만 읽히더라고요.

같은 내용을 ~/.claude/settings.json으로 옮기자 두 파일이 모두 들어왔습니다. 이 키는 사용자 설정, --settings로 넘긴 파일, managed 설정에서만 읽히고 프로젝트·로컬 설정 파일에서는 무시되는 키입니다.

그래서 이 값을 커밋해 팀원 모두에게 강제할 방법은 없습니다. 각자 /config에서 바꾸거나, 조직이라면 managed 설정으로 배포해야 해요.

플러그인 ID는 2.1.285에서 agents-md@builtin에서 cc-plugin-agents-md@builtin으로 바뀌었습니다. 2.1.285 이상은 두 ID를 다 읽지만, 그 전 버전은 새 ID를 무시합니다. 같은 설정 파일을 오래된 버전도 읽는다면 옛 ID로 적으세요.

바꾼 값은 다음에 보내는 메시지부터, 그리고 새 세션마다 적용됩니다. 어느 설정 파일이 이기는지가 헷갈리면 settings.json 네 곳의 우선순위를 같이 보세요.

AGENTS.md로 읽힌 파일이 CLAUDE.md와 다르게 구는 곳

설정을 통해 직접 읽힌 AGENTS.md는 내용은 같아도 몇 군데에서 CLAUDE.md와 다르게 다뤄집니다. 훅이나 --add-dir를 쓰고 있다면 걸릴 수 있어요.

상황	CLAUDE.md	직접 읽힌 AGENTS.md
InstructionsLoaded 훅	발동	발동 안 함
--add-dir로 더한 폴더	그 폴더 파일 읽음	읽지 않음
작업 폴더 밖을 @로 import	승인을 물음	이미 승인한 경우만, 묻지 않음

두 번째 줄은 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD를 켜 둔 경우의 이야기입니다. CLAUDE.md가 import하거나 심볼릭 링크로 가리켜 들어온 AGENTS.md라면 첫 줄의 훅은 평소처럼 발동해요.

같은 점도 있습니다. AGENTS.md 안의 @path import는 펼쳐지고, claudeMdExcludes 패턴도 적용됩니다. 프로젝트 지시 없이 시작하는 서브에이전트는 AGENTS.md도 없이 시작하고요.

그래도 안 읽힐 때

/memory 목록에 AGENTS.md 경로가 없으면 먼저 작업 폴더와 그 위에 CLAUDE 파일 세 종류가 있는지 찾아보세요. 대개는 여기서 원인이 나옵니다.

그다음 /config를 열어 Project instructions 항목이 있는지 봅니다. 항목 자체가 없다면 AGENTS.md를 직접 읽을 수 없는 세션입니다.

• 2.1.277 전 버전
• /plugin에서 AGENTS.md를 읽는 내장 플러그인을 끈 경우
• 2.1.276 이하에서 올린 직후의 첫 세션(일부 경우만. 다음 세션부터 읽음)

2.1.281 전에는 Amazon Bedrock이나 텔레메트리를 끈 세션 같은 일부 세션도 CLAUDE.md만 읽었습니다. 이 경우는 업데이트로 풀려요. 업데이트할 수 없는 세션이라면 CLAUDE.md에 @AGENTS.md 한 줄을 넣는 방법이 여전히 통합니다.

2.1.280 전에는 직접 읽힌 AGENTS.md가 /memory와 /context 목록에 나오지 않았습니다. 그 버전에서는 목록이 비어 있어도 읽혔을 수 있으니, Claude에게 프로젝트 지시 내용을 물어 확인하세요.

예전에 걸어 둔 우회는 정리하기

Claude Code가 AGENTS.md를 직접 읽기 전에 만들어 둔 우회가 있다면 하나씩 정리하는 게 좋습니다.

• SessionStart 훅으로 AGENTS.md를 출력하던 것: 지우세요. 직접 읽기와 겹쳐 같은 내용이 두 번 들어갑니다.
• CLAUDE.md에 “AGENTS.md를 읽어라”라고 문장으로 적어 둔 것: Claude가 그 파일을 열기로 해야만 보입니다. CLAUDE.md를 지우거나 @AGENTS.md import로 바꾸세요.
• @AGENTS.md import나 심볼릭 링크: 그대로 둬도 두 번 읽히지 않습니다. 다른 내용이 없다면 지워도 되지만, 직접 읽지 못하는 세션을 쓰는 사람이 있다면 import는 남겨 두세요.

Codex용 저장소를 그대로 열 때

이번에 해 보고 남은 건, 이름이 AGENTS로 시작한다고 다 같은 파일이 아니라는 점입니다. Claude Code가 챙기는 건 AGENTS.md와 .claude/AGENTS.md뿐이고, 하위 폴더 파일은 Claude가 그 폴더를 어떻게 들여다보느냐에 따라 빠질 수 있어요.

그래서 저는 여러 도구가 같이 지켜야 할 규칙은 루트 AGENTS.md에 모으고, 패키지 규칙이 중요한 작업은 그 패키지 폴더에서 시작하길 권합니다. 개인 메모가 필요하면 CLAUDE.local.md를 만들기 전에 Project instructions부터 claude-md-and-agents-md로 바꿔 두세요.

Codex CLI·Gemini CLI가 각자 어떤 파일을 어느 범위에서 찾는지는 CLAUDE.md·AGENTS.md·GEMINI.md를 하나로 합치는 법에 나란히 정리해 뒀습니다.