지난 7월에 CLAUDE.md를 AGENTS.md로 바꾸면 느려질까요?라는 글을 쓰면서 Claude Code가 AGENTS.md를 직접 읽지 못하니 @AGENTS.md import 한 줄을 남기거나 심볼릭 링크(symbolic link)를 거는 우회 방법을 쓸 수밖에 없다는 이야기를 했었습니다. 그 우회 방법 때문에 세션마다 비용이 더 드는지가 걱정이어서 210회를 측정했고 결과는 손해가 없다는 쪽이었습니다.
그런데 2026년 9월에 Claude Code 2.1.277이 나오면서 AGENTS.md를 직접 읽는 기능이 추가되었습니다. 그러면 이제 우회 방법을 지워야 하는 걸까요? 결론부터 말씀드리면 대부분의 경우 그대로 두어도 되고 오히려 남겨 두는 편이 안전한 상황도 있습니다. 다만 반드시 지워야 하는 구성이 1개 있고 기본값이 이름만 보고 짐작한 것과 다르게 동작해서 “분명히 켰는데 안 읽힌다"고 느끼기 쉬운 자리도 있습니다. 이 글에서는 그 부분들을 정리해 보겠습니다.
무엇이 바뀌었나
Claude Code 2.1.277부터 AGENTS.md를 읽는 일은 agents-md라는 내장 플러그인이 담당하고 세션에서 /config를 열어 Project instructions 값을 바꾸면 어느 파일을 읽을지 고를 수 있습니다. 고를 수 있는 값을 표로 정리하면 다음과 같습니다.
| 값 | Claude Code가 읽는 파일 |
|---|---|
claude-md-or-agents-md | 기본값. 작업 디렉터리나 그 위에 CLAUDE.md나 CLAUDE.local.md가 있으면 그쪽을 읽고 없을 때만 AGENTS.md를 읽습니다 |
claude-md-and-agents-md | 둘 다 읽습니다. 디렉터리마다 CLAUDE.md를 먼저 읽고 AGENTS.md를 뒤에 읽습니다 |
claude-md | CLAUDE.md만 읽습니다 |
managed-only | 세션을 시작할 때는 조직이 관리하는 CLAUDE.md와 자동 메모리만 읽습니다. 다만 Claude가 하위 디렉터리의 파일을 열면 그 디렉터리의 CLAUDE.md와 .claude/rules/는 그때 읽힙니다 |
/config 화면이 아니라 설정 파일로 지정하고 싶다면 ~/.claude/settings.json의 pluginConfigs 아래에 내장 플러그인 ID를 적어 주면 됩니다. 프로젝트 설정과 로컬 설정 파일에서는 이 값이 무시되므로 사용자 설정, --settings로 넘기는 설정 파일 그리고 관리 설정 중 한 곳에 두어야 합니다.
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
기본값은 어느 파일을 읽나
우선 가장 헷갈리기 쉬운 부분부터 살펴보겠습니다. 기본값인 claude-md-or-agents-md는 이름 그대로 둘 중 하나만 읽습니다. 작업 디렉터리와 그 위쪽 어디에도 CLAUDE.md가 없을 때에만 AGENTS.md를 읽습니다. 그러니까 지금 저장소에 CLAUDE.md가 있는 상태라면 직접 읽는 기능이 추가되었어도 AGENTS.md는 여전히 읽히지 않습니다.
여기서 어떤 파일이 있어야 “CLAUDE.md가 있다"고 보는지가 중요한데 공식 문서는 이를 명확하게 나누어 설명하고 있습니다. 작업 디렉터리나 그 위쪽에 있는 CLAUDE.md, .claude/CLAUDE.md 그리고 CLAUDE.local.md가 여기에 해당합니다. 반면 사용자 전역 파일인 ~/.claude/CLAUDE.md, 조직 관리 파일 그리고 .claude/rules/ 아래의 파일들은 여기에서 빠지기 때문에 AGENTS.md와 함께 읽힙니다.
이 구분이 매우 중요한 이유는 CLAUDE.local.md 때문입니다. AGENTS.md를 정본으로 쓰는 프로젝트에서 커밋하지 않을 개인용 지시를 CLAUDE.local.md에 따로 적어 두는 경우가 많은데, 이 파일이 여기에 해당하기 때문에 그 파일을 만든 사람에게만 AGENTS.md가 읽히지 않게 됩니다. 같은 저장소를 쓰는 동료는 멀쩡히 읽는데 자기 세션만 다르게 동작하니 원인을 찾기가 쉽지 않습니다. 개인용 파일을 유지하면서 AGENTS.md도 읽게 하려면 Project instructions를 claude-md-and-agents-md로 바꾸면 됩니다.
읽는 범위도 알아 두면 좋습니다. 세션을 시작할 때 작업 디렉터리와 그 위쪽의 AGENTS.md와 .claude/AGENTS.md를 전부 읽고 하위 디렉터리는 Claude가 그 안의 파일을 Read 도구로 열 때 그 디렉터리에 세 가지 CLAUDE.md가 하나도 없으면 그쪽 AGENTS.md를 읽습니다.
읽히지 않는 파일도 정해져 있습니다. AGENTS.local.md, AGENTS.override.md 그리고 .agents/ 디렉터리 아래의 내용은 읽지 않습니다. 반대로 AGENTS.md 안에 적은 @경로 import는 그대로 펼쳐지고 claudeMdExcludes 설정도 동일하게 적용되며 프로젝트 지시를 건너뛰도록 만든 서브에이전트는 AGENTS.md도 건너뜁니다.
기능이 지원되지 않는 세션
하지만 이 기능이 추가되었다고 해서 모든 세션에서 바로 쓸 수 있는 것은 아닙니다. 공식 문서가 밝힌 조건은 다음 4가지로 나누어 볼 수 있습니다.
- 2.1.277보다 낮은 버전을 쓰는 경우. 이 글을 쓰는 시점에 stable 채널은 아직 그보다 낮은 2.1.267이라 채널에 따라 업데이트해도 항목이 보이지 않을 수 있습니다
- 세션에 앤트로픽(Anthropic)의 기능 플래그가 전달되지 않는 경우. 여러 모델을 API로 쓸 수 있게 해 주는 AWS의 관리형 서비스인 Amazon Bedrock, 그리고 Vertex 나 Foundry 같은 서드파티 제공자를 거치거나 텔레메트리(telemetry)를 꺼 두었을 때가 대표적입니다
- 설치하거나 업그레이드한 직후의 첫 세션인 경우. 그다음 세션부터 읽습니다
disableAllHooks나allowManagedHooksOnly를 켜 두었거나/plugin에서 내장agents-md플러그인을 꺼 둔 경우
이 조건에 해당하면 /config 화면에 Project instructions 항목 자체가 나타나지 않고 CLAUDE.md만 읽습니다. 사내에서 Amazon Bedrock을 경유해 모델을 쓰는 환경이라면 이 항목이 특히 걸릴 수 있으니, 팀 전체가 AGENTS.md로 옮기기 전에 /config에 항목이 보이는지부터 확인해 보시는 편이 좋겠습니다.
남겨 둘 것과 고칠 것
그렇다면 7월에 이야기한 우회 방법들은 이제 어떻게 해야 할까요? 공식 문서가 구성별로 안내하고 있는데, 이를 표로 정리해 볼 수 있습니다.
| 기존 구성 | 권고 |
|---|---|
CLAUDE.md에 @AGENTS.md import 한 줄 | 그대로 두어도 됩니다. 어느 설정값이든 AGENTS.md를 두 번 읽지 않습니다. 그 파일에 import 한 줄뿐이면 지워도 되고 직접 읽지 못하는 세션이 섞여 있으면 남깁니다 |
CLAUDE.md가 AGENTS.md를 가리키는 심볼릭 링크 | 그대로 두거나 지우거나 상관없습니다. 어느 쪽이든 내용을 한 번만 읽습니다 |
CLAUDE.md에 “AGENTS.md를 읽어라"라고 문장으로 적어 둔 경우 | 고쳐야 합니다. 모델이 그 문장을 보고 파일을 여는 동작을 해야만 읽히기 때문입니다. CLAUDE.md를 지워 직접 읽게 하거나 그 문장을 @AGENTS.md import로 바꿉니다 |
AGENTS.md를 출력하는 SessionStart 훅(hook) | 지워야 합니다. 그대로 두면 같은 내용을 두 번 읽게 됩니다 |
앞의 두 가지는 지울 이유가 딱히 없습니다. 오히려 앞에서 말씀드린 대로 지원되지 않는 세션을 함께 쓰는 팀이라면 import를 남겨 두는 쪽이 안전합니다. 직접 읽는 방식, 곧 네이티브(native)로 읽는 세션과 우회 방법으로 읽는 세션이 같은 저장소에 섞여도 결과가 같아지기 때문입니다.
다만 심볼릭 링크를 그대로 둘 때 한 가지는 알아 두셔야 합니다. 윈도우에서 저장소를 클론하는 사람이 섞여 있다면 공식 문서는 심볼릭 링크 대신 import를 권합니다. 링크를 만드는 데 관리자 권한이나 개발자 모드가 필요하고 core.symlinks가 꺼진 클론에서는 git이 링크를 평문 파일로 받아 그 클론의 CLAUDE.md가 한 줄짜리 텍스트가 되기 때문입니다.
반면 마지막 항목은 반드시 고쳐야 합니다. Claude Code가 AGENTS.md를 직접 읽는 상태에서 세션 시작 훅이 같은 파일을 또 출력하면 같은 내용을 두 번 읽게 되고 이건 그대로 토큰 비용이 됩니다. 7월 측정에서 우회 방법 자체는 비용을 늘리지 않는다고 확인했지만 그건 파일을 한 번만 읽었을 때의 이야기이고 같은 내용을 두 번 넣으면 그만큼 더 듭니다.
네이티브로 읽으면 더 빨라질까
그러면 어차피 이제 직접 읽을 수 있게 되었으니 우회 방법보다 네이티브 쪽이 더 빠르거나 저렴하지는 않을까요?
이 질문은 7월 연구를 확장하면서 이미 측정해 두었습니다. 당시에 Claude Code는 AGENTS.md를 네이티브로 읽지 못했기 때문에, 대신 AGENTS.md를 기본으로 읽고 그 파일이 없을 때만 CLAUDE.md를 읽는 OpenCode를 가져와 같은 비교를 했습니다. 에이전트가 파일을 읽어 들이는 단계 자체가 달라지는 것이라 import 한 줄을 넣고 빼는 것보다 비교 조건이 더 분명합니다.
이때 비교한 조건은 2개이고 두 조건에 넣은 문서는 본문이 바이트까지 같습니다. 한쪽은 작업 디렉터리에 CLAUDE.md만 두었고 다른 쪽은 AGENTS.md만 두었습니다. 올라마(Ollama)로 로컬 모델 2종을 돌려 같은 시나리오 4개를 5회씩 반복해 80회를 측정했습니다.
여기서도 차이가 없었습니다. 회차별로 두 조건을 짝지어 두 값의 차이를 구해 보면, AGENTS.md만 둔 쪽이 더 느리게 나온 회차가 한 모델은 20쌍 중 7쌍이고 다른 모델은 20쌍 중 12쌍이어서 어느 쪽이 느린지부터 모델마다 나누어집니다. 짝을 지어 구한 차이의 평균은 그 차이들의 표준편차와 비교하면 한 모델은 3%, 다른 모델은 7%에 지나지 않고 같은 조건 안에서 회차끼리 벌어지는 폭이 그보다 훨씬 큽니다. 과제를 해결한 건수도 마찬가지여서 한 모델은 CLAUDE.md 쪽 13건에 AGENTS.md 쪽 15건, 다른 모델은 15건에 18건으로 같은 조건 안의 회차 편차를 넘지 않습니다. 보다 상세한 수치와 채점 규칙은 저장소의 확장 측정 문서에 정리해 두었으니 참고하시기 바랍니다.
따라서 속도나 비용을 이유로 우회 방법을 급하게 정리할 필요는 없습니다. 파일을 한 번 읽는 비용은 어느 경로로 읽든 비슷하고 비용이 달라지는 자리는 위에서 이야기한 것처럼 같은 내용을 두 번 읽게 되는 구성입니다.
운영하면서 알아 두면 좋은 차이
다만 설정으로 읽힌 AGENTS.md는 CLAUDE.md와 4가지가 다르게 동작하는데, 이 부분은 문제가 생겼을 때 원인을 찾는 데 필요하니 미리 알아 두시는 편이 좋습니다.
첫 번째는 확인 방법입니다. CLAUDE.md는 /memory와 /context의 Memory files 목록에 나오지만 설정으로 읽힌 AGENTS.md는 그 목록에서 빠져 있습니다. 그래서 목록만 보고 “안 읽혔구나"라고 판단하기 쉽습니다. 실제로 읽혔는지는 기본값을 쓸 때 대화 시작 부분에 나오는 no CLAUDE.md found; AGENTS.md loaded: ... 줄로 확인합니다. 기본값이 아닌 설정에서는 그 줄이 뜨지 않으므로 Claude에게 프로젝트 지시에 무엇이 적혀 있는지 직접 물어보면 됩니다.
두 번째는 훅입니다. InstructionsLoaded 훅은 CLAUDE.md에서는 실행되지만 설정으로 읽힌 AGENTS.md에서는 실행되지 않습니다. 다만 CLAUDE.md가 import하거나 심볼릭 링크로 가리키는 AGENTS.md에서는 평소대로 동작하니, 이 훅에 의존하는 자동화가 있다면 우회 방법을 그대로 유지하시기 바랍니다.
세 번째는 추가한 디렉터리입니다. --add-dir로 디렉터리를 함께 열면서 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD를 설정해 두었다면 그쪽의 CLAUDE.md는 읽히는데 AGENTS.md는 그렇지 않습니다. 이 환경변수를 설정하지 않았다면 둘 다 읽히지 않으므로 두 파일이 나누어지는 것은 변수를 켜 둔 경우뿐입니다.
네 번째는 작업 디렉터리 밖의 파일을 @경로로 불러올 때입니다. CLAUDE.md에서 그렇게 쓰면 Claude Code가 외부 import를 승인할지 물어봅니다. 설정으로 읽힌 AGENTS.md에서는 그 프로젝트에 외부 import를 이미 승인해 둔 경우에만 물어보지 않고 불러오며 승인한 적이 없으면 물어보지도 않고 불러오지도 않습니다. 승인 절차가 한 번 끝난 프로젝트라면 사람이 다시 확인할 기회 없이 외부 파일이 들어온다는 뜻입니다.
그래서 무엇을 하면 될까
지금까지 이야기한 것을 점검 목록으로 정리해 보겠습니다.
/config를 열어 Project instructions 항목이 보이는지 확인합니다. 안 보이면 위의 “지원되지 않는 세션” 조건에 해당하니 우회 방법을 그대로 유지합니다.AGENTS.md를 정본으로 쓸 생각이라면 저장소에CLAUDE.md가 남아 있는지 확인합니다. 남아 있으면 기본값에서는AGENTS.md가 읽히지 않습니다.- 개인용
CLAUDE.local.md를 쓰고 있다면 Project instructions를claude-md-and-agents-md로 바꿉니다. AGENTS.md를 출력하는 SessionStart 훅이 있으면 지웁니다. 이 훅을 그대로 두면 파일을 두 번 읽게 됩니다.@AGENTS.mdimport나 심볼릭 링크는 그대로 두어도 됩니다. 팀에 지원되지 않는 세션이 있다면 오히려 그대로 두는 것을 권해 드립니다.- 바꾼 뒤에는 새 세션에서 확인합니다. 기본값을 그대로 쓴다면
AGENTS.md loaded:줄이 뜨고claude-md-and-agents-md로 바꿨다면 그 줄이 뜨지 않으므로 Claude에게 프로젝트 지시에 무엇이 적혀 있는지 직접 물어봅니다. 설정으로 직접 읽힌AGENTS.md는/context목록에 나오지 않지만 import나 심볼릭 링크로 읽히는 경우에는 나옵니다.
마치며
7월에는 우회 방법을 써도 손해가 없는지가 궁금했고 이번에는 그 우회 방법을 지워야 하는지가 궁금했습니다. 두 번 모두 답은 전달 방식 자체에 드는 비용이 거의 없다는 쪽이었습니다. 그러니 읽는 경로는 편한 쪽을 고르시고 같은 내용을 두 번 읽게 되는 구성만 확인하시면 됩니다.
덧붙여 AGENTS.md는 에이전틱 AI 재단(AAIF, Agentic AI Foundation)이 관리하는 개방형 형식이고 6만 개가 넘는 오픈소스 프로젝트가 쓰고 있습니다. 같은 요청이 이슈 #34235에 반응 130여 개로 모여 있고 그 이슈는 이 글을 쓰는 시점에도 열려 있습니다. 도구마다 파일을 따로 두는 대신 파일 1개로 정리할 수 있게 되었습니다.
그리고 측정 하네스, 클러스터 구성 그리고 집계 스크립트는 GitHub 저장소에 있으니, 자기 프로젝트의 컨텍스트 파일로 같은 비교를 돌려 보실 수 있습니다.