Claude Code AGENTS.md 사용법: CLAUDE.md 차이, 4가지 로딩 모드, Codex·OpenCode와 공유

Name

Soren Atelier

업데이트 2026. 9. 21.

요약: Claude Code v2.1.277(2026년 9월 18일)부터, AGENTS.md가 있고 경로상 어디에도 CLAUDE.md가 없는 저장소는 AGENTS.md에서 지시사항을 자동으로 읽습니다. 설치할 것도, import 한 줄도, 심볼릭 링크도 필요 없습니다. 작업 디렉터리나 상위 디렉터리에 CLAUDE.md 또는 CLAUDE.local.md가 있으면 Claude Code는 계속 그 파일을 읽고 AGENTS.md는 무시합니다. /config의 Project instructions 설정을 바꾸지 않는 한 그렇습니다.

10초면 확인할 수 있습니다. AGENTS.md만 있는 저장소에서 새 세션을 시작하고, 대화 상단 근처에서 이 줄을 찾으세요:

no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md

이 줄이 보이지 않는다면 다음 네 가지 중 하나이며, 네 가지 모두 아래에서 다룹니다. 구버전을 쓰고 있거나, 상위 디렉터리 어딘가에 CLAUDE.md나 CLAUDE.local.md가 숨어 있거나, 업그레이드 후 첫 세션이거나, 세션 유형이 AGENTS.md를 아예 로드할 수 없는 경우(Bedrock, Vertex, Foundry, 텔레메트리 비활성화)입니다.

아래에서 테스트됨이라고 표시한 내용은 모두 2026년 9월 21일 macOS의 Claude Code 2.1.278에서, 새로 만든 임시 저장소에 claude -p로 실행해 확인했습니다. 나머지는 공식 memory 문서 (opens in a new tab)와 changelog (opens in a new tab)에서 가져왔습니다.

정확히 무엇이 바뀌었나

2.1.277의 changelog 항목은 한 문장입니다:

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가 없는 프로젝트에서는 Claude Code가 대신 AGENTS.md를 읽고, /config의 "Project instructions"에서 이 동작을 바꿀 수 있으며, Bedrock, Vertex, Foundry에서는 아직 지원되지 않습니다.

이 릴리스 이전에는 Codex, OpenCode, Cursor 등을 위해 AGENTS.md (opens in a new tab)로 표준화한 팀도 CLAUDE.md를 옆에 두어야 했습니다. 내용을 복제하거나, @AGENTS.md import 한 줄을 넣거나, 심볼릭 링크를 거는 식이었습니다. 이 릴리스에 대한 Hacker News 스레드 (opens in a new tab)(725포인트, 댓글 273개)는 대부분 각자 어떤 우회책을 유지해 왔는지 이야기하는 내용입니다.

이 릴리스가 AGENTS.md를 CLAUDE.md와 동등하게 만드는 것은 아닙니다. 스위치가 달린 폴백(fallback)을 추가한 것입니다. 이 가이드의 나머지 부분은 그 폴백이 어디서 멈추고 스위치가 언제 중요해지는지에 관한 내용입니다.

어떤 파일이 우선하나: 결정 표

기본 동작인 claude-md-or-agents-md 모드 기준입니다. "CLAUDE.md가 존재한다"는 검사는 작업 디렉터리와 그 위의 모든 디렉터리에 있는 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md를 대상으로 합니다. 개인용 ~/.claude/CLAUDE.md, 조직의 managed CLAUDE.md, .claude/rules/ 파일은 여기에 포함되지 않으며 AGENTS.md와 함께 계속 로드됩니다.

세 번째 행이 대부분의 사람이 가장 먼저 걸리는 함정입니다. CLAUDE.local.md는 커밋하지 않는 개인 지시사항을 두는 곳으로 문서화된 위치입니다. AGENTS.md에 의존하는 프로젝트에 이 파일을 하나 추가하면, Claude는 아무 말 없이 다시 AGENTS.md를 무시하는 상태로 돌아갑니다. 해결책은 설정 하나이며, 바로 다음에 다룹니다.

테스트 방법

임시 저장소의 각 AGENTS.md 또는 CLAUDE.md에는 지시사항 하나만 넣었습니다. 모든 응답을 [AGENTS_MD_LOADED] 같은 고정 마커로 시작하라는 것입니다. 그다음:

mkdir agentsmd-test && cd agentsmd-test && git init -q
printf '# AGENTS.md\n\nAlways begin your reply with the exact token [AGENTS_MD_LOADED].\n' > AGENTS.md
claude -p "What is 2+2? Answer in five words or fewer." < /dev/null

[AGENTS_MD_LOADED]로 시작하는 응답이 오면 파일이 로드된 것입니다. 그냥 4.가 오면 로드되지 않은 것입니다. /context보다 투박하지만, /context와 /memory는 직접 로드된 AGENTS.md를 목록에 표시하지 않기 때문에(아래 차이점 표 참고) 두 파일 모두에 통하는 방법은 마커 방식입니다.

Project instructions의 4가지 모드

세션에서 /config를 열고 Project instructions를 설정하거나, ~/.claude/settings.json의 내장 agents-md 플러그인 항목에 같은 값을 넣습니다. Claude Code는 프로젝트 수준 설정 파일과 로컬 설정 파일에서는 이 키를 무시하므로 저장소에 커밋할 수 없습니다. 사용자별 또는 managed 설정입니다.

설정 파일 형식:

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

테스트됨: 두 파일이 모두 있는 저장소에서 이 JSON을 --settings both.json으로 전달하자 [CLAUDE_MD_LOADED] [AGENTS_MD_LOADED] 순서로 시작하는 응답이 나왔습니다. AGENTS.md만 있는 저장소에서 "instructionFiles": "claude-md"를 전달하자 그냥 4.가 나왔으므로, 문서대로 파일이 무시되었습니다.

업그레이드 후 첫 세션에서 동작하지 않는 이유

이 문제로 테스트 두 번을 날렸습니다. 문서에는 "설치 또는 업그레이드 후 첫 세션"에서는 지원되지 않고, "다음 세션부터" Claude가 AGENTS.md를 읽는다고 되어 있습니다.

테스트됨: 갓 설치한 2.1.278과 AGENTS.md만 있는 저장소에서, 첫 번째 claude -p 실행은 파일을 무시했습니다. 두 번째도 마찬가지였습니다. 세 번째 실행에서 로드되었습니다. 비대화형 -p 실행은 짧기 때문에, AGENTS.md 지원을 제어하는 feature flag가 두 번째 실행이 시작될 때까지 가져와지지 않았을 수 있습니다. 실용적인 규칙: 업그레이드 후 일회용 세션을 하나 열었다 닫고, 그다음에 AGENTS.md가 읽히는지 판단하세요.

문서 기준으로 AGENTS.md를 아예 로드할 수 없는 세션:

• Amazon Bedrock, Google Vertex AI, Microsoft Foundry
• 텔레메트리 비활성화(feature flag를 가져올 수 없기 때문)
• disableAllHooks 또는 allowManagedHooksOnly가 설정되어 있거나, /plugin에서 내장 agents-md 플러그인이 비활성화된 경우
• 위에서 설명한 설치 또는 업그레이드 후 첫 세션

이 모든 경우에 /config에 Project instructions가 아예 표시되지 않으므로, 이것이 가장 빠른 판별법입니다. 이런 세션의 대안은 다음 절에서 설명하는 import입니다.

직접 로드된 AGENTS.md가 CLAUDE.md와 다른 점

설정을 통해 읽힌 AGENTS.md는 CLAUDE.md를 그대로 대체하지 않습니다. 문서에 나온, 눈에 보이는 차이 세 가지:

하위 디렉터리의 AGENTS.md 파일은 Claude가 Read 도구로 그 디렉터리의 파일을 열 때, 그리고 그 디렉터리에 자체 CLAUDE.md가 없을 때 필요에 따라 로드됩니다. AGENTS.md 안의 @path import는 확장되며, claudeMdExcludes 패턴도 적용됩니다.

마이그레이션: 기존 우회책은 어떻게 할까

2.1.277 이전에 AGENTS.md를 읽도록 설정해 두었다면, 설정별 문서 지침과 언제 조치해야 하는지에 대한 제 해석은 다음과 같습니다.

• @AGENTS.md만 들어 있는 CLAUDE.md: 사용하는 모든 세션이 새 동작을 지원한다면 삭제해도 됩니다. 팀에 Bedrock, Vertex, Foundry로 작업하는 사람이 있다면 유지하세요. 그 환경은 여전히 import가 필요합니다. 유지해도 두 번 읽히는 일은 없습니다.
• "AGENTS.md를 읽어라"라고 산문으로 적힌 CLAUDE.md: 그 문장을 @AGENTS.md로 바꾸거나 파일을 삭제하세요. 산문은 Claude가 파일을 열기로 결정할 때만 통하지만, import는 결정적으로 동작합니다.
• AGENTS.md로 심볼릭 링크한 CLAUDE.md: 어느 쪽이든 동작하지만, Edit와 Write 도구는 심볼릭 링크를 통한 쓰기를 거부하고 대상 파일로 리다이렉트합니다. Windows에서는 core.symlinks가 켜져 있지 않으면 커밋된 심볼릭 링크가 한 줄짜리 텍스트 파일로 체크아웃되므로, 그 환경에서는 import를 권합니다.
• AGENTS.md를 출력하는 SessionStart 훅: 제거하세요. Claude가 AGENTS.md를 직접 읽게 되면 훅이 컨텍스트에 두 번째 사본을 주입합니다.
• 내용이 다른 두 파일: Claude 전용 부분이 별도 파일을 둘 만한 가치가 있는지 결정하세요. 그렇다면 공용 규칙은 AGENTS.md에, Claude 전용 규칙은 짧은 CLAUDE.md에 두고, 둘 다 로드되도록 claude-md-and-agents-md를 설정하세요. 아니라면 AGENTS.md로 합치고 CLAUDE.md를 삭제하세요.

문서는 CLAUDE.md를 유지해야 하는 저장소를 위한 공유 패턴도 제안합니다:

@AGENTS.md
 
# Claude-specific
- Use the `Bash` tool for git; do not call the GitHub MCP for pushes.

Claude는 import를 먼저 읽고, 그다음 Claude 전용 줄을 읽습니다.

다른 도구는 무엇을 읽나

AGENTS.md로 표준화하는 이유는 파일 하나로 모든 에이전트를 지원하기 위해서입니다. 각 도구의 현재 문서 기준으로 실제 동작은 다음과 같습니다.

공유 파일에 대한 두 가지 결과:

1. Codex는 CLAUDE.md를 전혀 읽지 않습니다. 그 파일에만 있는 내용은 Codex에게 보이지 않습니다. 같은 저장소에서 Codex와 Claude Code를 두 파일로 함께 쓰고 있었다면, 둘 다 보는 파일은 AGENTS.md뿐입니다.
2. OpenCode는 AGENTS.md가 없을 때만 CLAUDE.md를 읽습니다. Claude Code 기본 동작과 정반대입니다. 두 파일이 모두 있는 저장소에서 Claude Code는 CLAUDE.md를, OpenCode는 AGENTS.md를 읽습니다. 두 파일 내용이 다르면 두 에이전트가 서로 다른 규칙을 따르는데, 어느 쪽도 그 사실을 알려주지 않습니다.

따라서 여러 도구를 쓰는 저장소의 안전한 최종 상태는 이렇습니다. 공용 규칙을 담은 AGENTS.md 하나, Claude 전용 규칙이 없다면 CLAUDE.md는 두지 않기, 있다면 @AGENTS.md로 시작하는 CLAUDE.md.

상황별 권장 설정

문제 해결: AGENTS.md가 로드되지 않을 때

순서대로 확인하세요. 각 항목은 위에서 재현했거나 문서에 명시된 원인입니다.

1. claude --version을 실행하세요. 2.1.277 이상이 필요합니다. 버전이 낮으면 claude update로 업데이트하세요.
2. 모든 상위 디렉터리에서 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md를 찾으세요:

d="$PWD"; while [ "$d" != "/" ]; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do [ -f "$d/$f" ] && echo "blocks AGENTS.md: $d/$f"; done; d=$(dirname "$d"); done

~/.claude/CLAUDE.md 이외의 결과가 하나라도 나오면, claude-md-and-agents-md로 바꾸지 않는 한 Claude는 그 파일을 대신 읽습니다.

3. 방금 업그레이드했다면 두 번째 세션을 시작하세요. 제 테스트에서는 세 번째 실행에서 처음으로 파일이 로드되었습니다.
4. /config를 열어 Project instructions가 claude-md나 managed-only가 아닌지 확인하세요. 설정 자체가 없다면 세션 유형이 AGENTS.md를 로드할 수 없는 경우이므로 @AGENTS.md import를 사용하세요.
5. /memory나 /context로 확인하려 하지 마세요. 직접 로드된 AGENTS.md는 거기에 표시되지 않습니다. AGENTS.md loaded 줄을 찾거나, Claude에게 프로젝트 지시사항을 인용해 달라고 요청하세요.

FAQ

Claude Code는 기본적으로 AGENTS.md를 읽나요?

예, v2.1.277부터 읽습니다. 다만 작업 디렉터리와 모든 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때만 그렇습니다. 하나라도 있으면 Claude Code는 그 파일을 읽고, Project instructions를 claude-md-and-agents-md로 설정하지 않는 한 AGENTS.md는 무시합니다.

CLAUDE.md와 AGENTS.md를 둘 다 읽게 할 수 있나요?

예. /config에서 Project instructions를 claude-md-and-agents-md로 설정하거나, ~/.claude/settings.json의 pluginConfigs → agents-md@builtin → options.instructionFiles에 설정하세요. 각 디렉터리의 CLAUDE.md가 먼저 로드되고, 그다음 AGENTS.md가 로드됩니다. CLAUDE.md에서 이미 import한 파일은 두 번 읽지 않습니다.

Claude Code를 업데이트한 직후에 AGENTS.md가 로드되지 않는 이유는 무엇인가요?

설치 또는 업그레이드 후 첫 세션은 AGENTS.md를 읽을 수 없습니다. 지원은 이후 세션부터 시작됩니다. claude -p 테스트에서는 세 번째 실행에서 처음 로드되었습니다. 일회용 세션을 열었다 닫은 뒤 다시 확인하세요.

이미 AGENTS.md가 있으면 CLAUDE.md를 삭제해야 하나요?

CLAUDE.md에 @AGENTS.md만 들어 있고 팀에 Bedrock, Vertex, Foundry 사용자가 없다면 삭제해도 됩니다. Claude 전용 규칙이 들어 있다면 유지하고, 어디서나 둘 다 로드되도록 첫 줄에 @AGENTS.md를 넣으세요.

Codex는 CLAUDE.md를 읽나요?

아니요. Codex는 저장소 루트에서 작업 디렉터리까지 디렉터리별로 AGENTS.override.md 또는 AGENTS.md를 읽고, 여기에 ~/.codex/AGENTS.md를 더하며, config.toml에서 폴백 파일명을 설정할 수 있습니다. CLAUDE.md에만 있는 내용은 Codex에게 보이지 않습니다.

관련 가이드

• Codex 사용법 가이드
• Oh My OpenCode와 OpenCode: 설치, 설정, 문제 해결
• Claude Code Bypass Permissions: 데스크톱 토글, CLI 플래그, 오류 해결
• Claude Code 루틴 사용법
• DeepSeek Harness 사용법