클로드 코드 AGENTS.md 지원, CLAUDE.md와 함께 쓰는 법
클로드 코드가 2026년 9월 18일(미국 시간 기준) 공개된 v2.1.277부터 AGENTS.md를 직접 읽어요. 다만 기본 동작은 ‘합치기’가 아니라 ‘대체’라서, CLAUDE.md가 없을 때만 AGENTS.md를 읽고 둘 다 있으면 CLAUDE.md만 읽습니다. 개인용 CLAUDE.local.md 하나만 만들어도 AGENTS.md가 밀려나니 아래 표부터 보세요.
이 글은 2026년 9월 19일 기준 공식 문서와 v2.1.277 릴리스 노트를 풀어 쓴 글이에요. 제가 직접 실행해 확인한 화면이 아니라 문서 기준이고, 릴리스 하루 뒤라 문서가 바뀔 수 있어요.
9월 18일에 바뀐 것 — 요청 393일 만의 AGENTS.md 지원
AGENTS.md는 쉽게 말해 AI 코딩 도구용 README예요. 사람이 새 프로젝트를 열면 README부터 읽듯이, AI 에이전트가 작업 전에 읽는 설명서죠. 빌드 명령어나 테스트 방법, 코드 스타일 같은 걸 적어 두는 파일이고, 공식 사이트 agents.md에 따르면 오픈소스 프로젝트 60,000개 이상이 쓰고 있어요.
클로드 코드는 이 파일을 자동으로 읽지 않았어요. 지원 요청 이슈(anthropics/claude-code #6235, ‘Feature Request: Support AGENTS.md.’)가 2025년 8월 21일에 열렸고 지원이 들어온 날이 2026년 9월 18일(미국 시간 기준)이니, 두 날짜에서 계산하면 393일, 약 1년 1개월 만이에요. 이슈는 지금 Closed 상태입니다.
릴리스 노트의 요지는 두 가지예요. CLAUDE.md가 없는 프로젝트에서는 AGENTS.md를 대신 읽고, 이 동작은 /config의 Project instructions에서 바꿀 수 있다는 것. 그리고 아직 Bedrock·Vertex·Foundry는 제외라는 단서가 붙었어요. 업데이트 이전에 쓰인 설명글은 “아직 공식 지원하지 않는다”를 전제로 심볼릭 링크 우회법을 안내하는데요.
그 전제가 9월 18일부로 틀린 정보가 됐습니다.
AGENTS.md와 CLAUDE.md, 뭐가 다른가요
가장 큰 차이는 누가 읽느냐예요. CLAUDE.md는 클로드 코드가 읽는 전용 이름이고, AGENTS.md는 여러 도구가 함께 읽는 공용 이름이에요. 2025년 8월에 공개된 형식으로, 같은 해 12월 리눅스 재단 산하 Agentic AI Foundation에 기증돼 관리되고 있어요. agents.md가 꼽는 지원 도구는 Codex·Cursor·GitHub Copilot·Gemini CLI·Windsurf·Zed 등 20개 이상이고, 하위 폴더에 두면 편집하는 파일과 가장 가까운 AGENTS.md가 우선해요(agents.md 기준 OpenAI 메인 저장소에만 AGENTS.md 파일이 88개). 처리 방식은 도구마다 갈립니다.
| 도구 | AGENTS.md를 읽는 방식(기본 동작) |
|---|---|
| Codex | 루트부터 현재 폴더까지 폴더당 최대 1개씩 이어 붙이고 가까운 파일이 우선. 합산 32 KiB에서 중단 |
| Cursor | 루트 AGENTS.md를 .cursor/rules 대안으로 쓰고, 하위 폴더 파일은 그 폴더 작업 때 자동 적용 |
| GitHub Copilot coding agent | 2025년 8월 28일부터 루트·하위 폴더 지원. .github/copilot-instructions.md와 CLAUDE.md·GEMINI.md도 계속 읽음 |
| 클로드 코드 | 2026년 9월 18일(v2.1.277)부터. CLAUDE.md가 없을 때만 AGENTS.md를 대신 읽는 ‘대체’ 방식 |
저는 이 표에서 클로드 코드 줄이 제일 눈에 걸렸어요. Codex는 폴더를 내려오며 이어 붙이는데 클로드 코드는 기본값이 둘 중 하나만 고르는 방식이거든요. 같은 저장소에서 두 도구를 오가면 “Codex는 아는데 클로드는 모른다”는 일이 생길 수 있는 구조예요. 그래서 두 파일이 한 폴더에 같이 있을 때가 문제예요.
둘 다 있으면 뭘 읽나 — 상황별 4가지와 CLAUDE.local.md 함정
공식 문서 표 기준으로, 기본값에서 클로드는 작업 폴더나 그 위 폴더에 CLAUDE.md가 하나라도 있으면 그쪽만 읽고, 하나도 없을 때만 AGENTS.md로 넘어가요. 여기서 ‘CLAUDE.md가 있다’로 치는 파일은 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md 세 가지입니다. 반대로 ~/.claude/CLAUDE.md(개인 전역), 조직 관리 CLAUDE.md, .claude/rules/ 파일은 ‘있다’로 세지 않고 AGENTS.md와 함께 계속 로드돼요.
| 프로젝트 상황 | 클로드 코드가 읽는 것 | 확인 단서 |
|---|---|---|
| 1. AGENTS.md만 있음 | AGENTS.md | 대화 첫머리에 ‘no CLAUDE.md found; AGENTS.md loaded’ 줄 |
| 2. AGENTS.md + CLAUDE.md | CLAUDE.md만 | /memory·/context 목록에 CLAUDE.md만 뜸 |
| 3. CLAUDE.md가 @AGENTS.md를 import | CLAUDE.md + import된 AGENTS.md | /context의 Memory files에 AGENTS.md도 뜸 |
| 4. AGENTS.md + 개인용 CLAUDE.local.md | CLAUDE.local.md만(AGENTS.md 제외) | AGENTS.md loaded 줄이 안 뜸 |
4번째 줄이 이번 업데이트에서 제일 조심할 곳이에요.
CLAUDE.local.md는 커밋하지 않는 개인용 지침 파일인데, 이것도 CLAUDE.md로 쳐요. AGENTS.md에 기대던 프로젝트에 내 취향 메모용으로 CLAUDE.local.md를 하나 추가하는 순간, 클로드는 팀의 AGENTS.md를 더 이상 읽지 않습니다. 해결은 /config의 Project instructions를 claude-md-and-agents-md로 바꾸는 거예요. 참고로 AGENTS.local.md, AGENTS.override.md, .agents/ 폴더는 이름이 비슷해도 읽지 않아요.
내 프로젝트에 맞춰 설정하기 — 케이스 A·B·C와 설정값 4종
설정은 세 케이스 중 내 프로젝트에 맞는 하나만 고르면 끝나요. 케이스 A는 AGENTS.md만 있고 CLAUDE.md 계열이 하나도 없는 경우인데, 이때는 할 일이 없어요. 터미널에서 claude –version으로 v2.1.277 이상인지만 보면 됩니다.
케이스 B는 클로드에게만 따로 시킬 말이 있는 경우예요. AGENTS.md는 공용으로 두고, CLAUDE.md 첫 줄에서 불러온 뒤 Claude 전용 지침을 아래에 붙여요. 공식 문서 예시를 한국어로 옮기면 빈 줄을 빼고 3줄이면 됩니다. 이 방식은 어느 설정값에서도 같은 파일을 두 번 읽지 않아요.
@AGENTS.md
Claude 전용 지침:
- src/billing/ 아래를 고칠 때는 먼저 plan mode로 계획부터 세워줘.케이스 C는 개인용 CLAUDE.local.md도 쓰고 싶거나 두 파일을 다 읽히고 싶을 때예요. /config를 열어 Project instructions를 바꾸면 값은 다음 메시지부터 적용돼요. 파일로도 지정할 수 있지만(~/.claude/settings.json의 pluginConfigs) 프로젝트·로컬 설정 파일에서는 무시된다고 해요. 제가 읽기엔 저장소로 팀 전체에 강제할 수는 없다는 뜻이라, 팀 동작을 맞추려면 설정값보다 케이스 B 같은 파일 배치가 맞아 보여요.
| Project instructions 값 | 클로드가 읽는 파일 | 이럴 때 고르세요 |
|---|---|---|
| claude-md-or-agents-md(기본값) | CLAUDE.md 계열, 없으면 AGENTS.md | 대부분의 프로젝트. 건드릴 필요 없음 |
| claude-md-and-agents-md | 둘 다. 폴더마다 CLAUDE.md 먼저, AGENTS.md 나중(이미 읽은 파일은 중복 로드 안 함) | CLAUDE.local.md를 쓰면서 AGENTS.md도 읽히고 싶을 때 |
| claude-md | CLAUDE.md 계열만 | AGENTS.md는 다른 도구용으로 두고 클로드에겐 안 보이게 할 때(CLAUDE.md에서 import하지 않았다면) |
| managed-only | 조직 관리 지침·자동 메모리만(프로젝트·개인 CLAUDE.md와 모든 AGENTS.md 제외) | 조직 관리자가 정책으로 묶을 때 |
예전 우회법, 지워도 될까요? 저라면 이 순서로 해요
서두를 필요는 없어요. 공식 문서가 우회법을 항목별로 짚어 주는데, 절반은 그냥 둬도 되거든요. (아 근데 “클로드 코드는 AGENTS.md를 못 읽는다”는 말도 정확한 표현은 아니었어요. 자동으로 안 읽었을 뿐 CLAUDE.md에서 @import로 불러오면 예전에도 읽혔으니까요.)
| 옛 우회법 | 판정 | 이유 |
|---|---|---|
| CLAUDE.md 안의 @AGENTS.md import | 그대로 둠 | 어느 설정값에서도 두 번 읽지 않음. AGENTS.md를 직접 못 읽는 세션이 있다면 유지 |
| CLAUDE.md에 “AGENTS.md를 읽어라”라고 적은 문장 | 그 CLAUDE.md에 이 문장뿐이면 파일째 삭제, 다른 내용이 있으면 문장을 @AGENTS.md로 교체 | 클로드가 파일을 열기로 정해야만 읽힘. 문장만 지우고 파일을 두면 AGENTS.md는 계속 안 읽힘 |
| CLAUDE.md → AGENTS.md 심볼릭 링크(ln -s AGENTS.md CLAUDE.md) | 둬도, 지워도 됨 | 어느 쪽이든 내용은 한 번만 읽힘 |
| AGENTS.md를 출력하는 SessionStart 훅 | 제거 | 직접 읽기와 겹쳐 컨텍스트에 사본이 하나 더 생김 |
링크를 남길 때는 제약이 둘 있어요. Edit·Write 도구는 링크 너머에 쓰기를 거부하고 원본인 AGENTS.md를 고치라고 안내해요. Windows에서는 링크 생성에 관리자 권한이나 개발자 모드가 필요하고 git이 링크를 한 줄짜리 텍스트로 체크아웃할 수 있어서, 문서는 @AGENTS.md import를 권합니다.
진짜 함정은 “지워도 된다”는 판정이 내 버전에서만 참이라는 점이에요. 오픈소스 phabfive는 CLAUDE.md가 AGENTS.md를 가리키는 링크를 쓰다가 2.1.277 이후 링크를 지우자는 이슈(#347)를 열었는데, 바로 지우면 2.1.276 이하 사용자는 경고 없이 프로젝트 지침이 통째로 빠지니 이슈 날짜로부터 3개월 뒤인 2026년 12월 18일까지 기다리자고 제안했어요. 저라면 팀 저장소의 링크·import는 그때까지 두고, 팀원 버전이 다 올라온 걸 확인한 뒤에 걷어낼 거예요. SessionStart 훅도 같은 이유로 버전이 섞여 있으면 미루는 게 안전해 보이는데, 이건 문서가 아니라 제 추론이에요.
AGENTS.md가 안 읽힐 때 점검 순서와 규칙 파일 쓰는 요령
분명 AGENTS.md를 넣었는데 클로드가 모르는 눈치라면 원인은 대개 경로 위 어딘가의 CLAUDE.md예요. 공식 문서 문제 해결 절이 권하는 순서를 옮기면 이래요.
- 작업 폴더와 그 위 폴더에서 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md를 찾기(~/.claude/CLAUDE.md는 제외). 하나라도 있으면 그 파일만 읽힘
- 터미널에서 claude –version을 쳐서 v2.1.277 이상인지 확인
- Bedrock 같은 타사 제공자, 텔레메트리를 끈 세션, 설치·업그레이드 직후 첫 세션인지, disableAllHooks·allowManagedHooksOnly를 켰거나 내장 agents-md 플러그인을 껐는지 확인
- /config에서 Project instructions가 claude-md나 managed-only가 아닌지 확인. 항목 자체가 안 보이면 3번 유형
읽혔는지는 기본값이면 대화 첫머리에 ‘no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md’ 같은 줄이 떠요. 직접 읽힌 AGENTS.md는 /memory 목록이나 /context의 Memory files에 안 뜨니(import·심볼릭으로 읽힌 것만 뜸), 줄이 안 보이면 클로드에게 프로젝트 지침 내용을 물어보면 됩니다. 3번에 걸렸다면 케이스 B의 @AGENTS.md 한 줄이 대안이에요. 4번은 파일이 아니라 값이 원인이라 /config에서 값을 바꾸면 돼요. claude-md라면 CLAUDE.md에 @AGENTS.md를 두는 것도 문서가 안내하는 대안이고, managed-only는 프로젝트 CLAUDE.md까지 빠지니 값을 바꿔야 해요.
이제 파일에 뭘 적을지가 남아요. 공식 문서는 CLAUDE.md를 한 파일당 200줄 이내로 권장해요. 길수록 컨텍스트를 더 쓰고 지시 준수율이 떨어지거든요(4 MiB를 넘는 파일은 건너뜀). Codex는 AGENTS.md 합산 32 KiB에서 파일 추가를 멈춰요. 제 계산으로는 한글이 UTF-8에서 글자당 3바이트라서, 공백·영문 없이 한글만 꽉 채운 줄이 55자씩 200줄이면 약 33,000바이트로 32,768을 넘어요. 공백·영문이 섞이면 더 작아지지만 한글 비중이 높을수록 Claude의 200줄 권장보다 Codex의 32 KiB 상한이 먼저 찰 수 있어요. 서로 다른 도구의 기준을 견준 거라 참고용이에요.
내용은 코드를 읽어서는 알 수 없는 것 위주가 좋아요. 공식 문서 예시대로 ‘npm test를 커밋 전에 실행한다’처럼 검증 가능하게, ‘API 핸들러는 src/api/handlers/에 둔다’처럼 구체적으로 쓰는 식이에요. 두 파일을 다 읽히는 케이스 C라면 같은 규칙을 양쪽에 적지 마세요. 규칙끼리 충돌하면 클로드가 임의로 하나를 고를 수 있다고 문서가 경고하니까요. 지난번 ‘AI 코드 검증 체크리스트’ 글의 커밋 전 5분 루틴 중 명령어로 굳힐 수 있는 항목은 AGENTS.md의 Testing instructions 자리에 한두 줄로 옮겨 두면, AGENTS.md를 읽는 도구라면 세션마다 그 줄을 읽고 시작해요.
자주 묻는 질문
클로드 코드만 쓰는데 AGENTS.md도 만들어야 하나요?
안 만들어도 돼요. 클로드 코드만 쓴다면 CLAUDE.md로 충분하고, 다른 도구를 같이 쓰거나 그런 협업자가 있을 때 AGENTS.md가 값어치를 해요. 그땐 공용 규칙을 AGENTS.md에 적고 CLAUDE.md는 @AGENTS.md 한 줄로 시작하면 규칙 파일을 도구마다 따로 관리하지 않아도 됩니다.
업데이트하면 내가 써 둔 CLAUDE.md 설정이 바뀌나요?
프로젝트에 CLAUDE.md가 있으면 기본값에서 읽는 파일은 그대로예요(위 표의 2번). 지원이 켜졌는지는 /config에 Project instructions 항목이 보이는지로 알 수 있어요. 항목이 아예 없다면 그 세션은 AGENTS.md를 직접 못 읽는 유형입니다.
오늘 할 일은 세 가지예요. 버전을 확인하고, 프로젝트 폴더에서 CLAUDE.md·CLAUDE.local.md가 있는지 찾고, 새 세션 첫머리에 AGENTS.md loaded 줄이 뜨는지 보는 거요. 업그레이드 직후라면 첫 세션은 건너뛰고 두 번째 세션에서 봐야 해요. 저라면 팀 저장소는 케이스 B로 맞춰 두고, 링크와 훅 정리는 팀원 버전이 다 올라온 뒤로 미룰 거예요.
