프로젝트마다 CLAUDE.md, AGENTS.md, 팀 위키에 같은 규칙을 복사해 두면, 결국 어느 파일이 정본인지 알기 어려워집니다. 반대로 한 도구에만 맞춘 파일을 고집하면, 같은 저장소를 쓰는 다른 코딩 에이전트가 팀의 규칙을 놓칠 수 있습니다.
Claude Code v2.1.277은 이 문제를 작지만 실용적인 방식으로 다룹니다. 공식 릴리즈 노트 ↗에 따르면, 프로젝트 폴더에 CLAUDE.md가 없을 때 Claude Code가 AGENTS.md를 대체 지침으로 읽습니다.
먼저 결론부터 말하면, 이것은 두 파일을 합쳐 읽는 기능이 아닙니다. 기존 CLAUDE.md 프로젝트는 그대로 우선권을 유지하고, 여러 에이전트가 공유하는 저장소에서는 AGENTS.md를 공통 진입점으로 선택할 수 있게 된 변화입니다.
2026-09-19 · Claude Code v2.1.277 릴리즈 노트 기준입니다. 이 fallback은 Bedrock, Vertex, Foundry에서는 아직 지원하지 않습니다.
이 글에서 다루는 내용:
CLAUDE.md와AGENTS.md의 실제 우선순위- 기존 프로젝트를 불필요하게 흔들지 않는 정리 방법
- 공유 지침·개인 설정·Skill을 분리하는 기준
중요한 건 “지원”보다 우선순위입니다
이번 변경을 “Claude Code가 이제 AGENTS.md도 읽는다”라고만 이해하면, 두 파일을 함께 두고 서로 다른 내용을 넣는 실수를 하기 쉽습니다. 공식 CHANGELOG ↗는 조건을 명확히 적습니다. 프로젝트에 CLAUDE.md가 없을 때 AGENTS.md를 읽습니다.
flowchart TD
A[프로젝트 폴더 시작] --> B{CLAUDE.md가 있는가?}
B -->|예| C[CLAUDE.md를 프로젝트 지침으로 사용]
B -->|아니오| D{AGENTS.md가 있는가?}
D -->|예| E[AGENTS.md를 대체 지침으로 사용]
D -->|아니오| F[이 두 파일의 프로젝트 지침 없음]즉, CLAUDE.md를 이미 잘 운영하고 있다면 업그레이드 뒤 파일을 옮길 이유가 없습니다. 반대로 Codex 등 여러 코딩 에이전트에서 같은 저장소를 운영하면서 AGENTS.md를 이미 공용 지침으로 쓰고 있다면, Claude Code가 그 파일을 읽을 수 있는 선택지가 생겼습니다.
이 동작은 /config의 Project instructions에서 켜고 끌 수 있습니다. 팀 정책이나 기존 자동화가 특정 파일명을 전제한다면, 먼저 이 설정과 실제 로딩 결과를 확인하는 편이 안전합니다.
무엇을 한 파일에 두어야 할까
지침 파일의 목적은 모델에게 모든 정보를 전달하는 것이 아니라, 반복해서 놓치면 비용이 큰 결정을 짧게 고정하는 것입니다. 예를 들어 빌드·테스트 명령, 디렉터리 책임, 수정 금지 영역, PR 검증 기준이 여기에 해당합니다.
# AGENTS.md
## 프로젝트 규칙
- 패키지 설치와 스크립트 실행은 pnpm을 사용합니다.
- 변경 뒤에는 관련 테스트와 린트를 실행합니다.
- 데이터베이스 마이그레이션은 별도 승인 없이 적용하지 않습니다.
## 검증
- 애플리케이션: pnpm test
- 타입 검사: pnpm typecheck위 예시처럼 공용 지침에는 팀원이 재현할 수 있는 명령과 경계를 남기는 편이 좋습니다. 개인 API 키 경로, 로컬 프록시 주소, 개인 선호처럼 저장소에 공유하면 안 되는 정보는 분리해야 합니다.
Claude Code Memory에서 다룬 CLAUDE.md 중심의 메모리·규칙 계층은 여전히 유효합니다. 이번 변화는 그 체계를 폐기하는 것이 아니라, 프로젝트 공용 지침의 파일명을 선택할 수 있게 한 것에 가깝습니다.
팀에 이미 CLAUDE.md가 있다면
가장 안전한 기본값은 기존 파일을 유지하는 것입니다. CLAUDE.md와 AGENTS.md에 비슷하지만 다른 규칙을 복제하면, Claude Code에서는 전자만 읽히는 상황이 생길 수 있습니다. 이 상태는 시간이 지날수록 “어느 지침이 맞는가”라는 운영 문제로 바뀝니다.
| 팀 상황 | 권장 선택 | 이유 |
|---|---|---|
| Claude Code만 주로 사용 | 기존 CLAUDE.md 유지 | 동작 변경이 없고, 마이그레이션 비용이 없습니다. |
| 여러 에이전트가 같은 지침을 소비 | AGENTS.md를 공용 정본으로 검토 | Claude Code도 fallback으로 읽을 수 있습니다. |
| 두 파일이 이미 존재 | 정본 하나를 정하고 다른 파일의 중복 제거 | 도구별로 다른 규칙이 적용되는 위험을 줄입니다. |
공용 정본을 AGENTS.md로 옮기기로 했다면, 한 번에 모든 개인 설정까지 옮기지 마세요. 먼저 팀 규칙만 담은 파일을 만들고, 기존 CLAUDE.md의 개인·도구 전용 지침은 별도 규칙이나 로컬 설정으로 분리하는 편이 리뷰와 롤백에 유리합니다.
Skill과 지침 파일은 역할이 다릅니다
AGENTS.md 지원이 추가됐다고 해서 모든 작업 절차를 이 파일에 장문으로 넣을 필요는 없습니다. 프로젝트 지침은 “항상 적용되는 제약”에, Skill은 “특정 작업에서만 필요한 절차”에 어울립니다.
Claude Code Skills 실전 가이드에서 설명한 SKILL.md는 배포, 접근성 감사, 블로그 작성처럼 조건부로 활성화되는 작업 지식을 담기에 좋습니다. 반면 AGENTS.md나 CLAUDE.md에는 모든 작업에서 지켜야 하는 명령·경계·코드베이스의 최소 지도를 남깁니다.
flowchart TD
A[항상 적용되는 팀 규칙] --> B[AGENTS.md 또는 CLAUDE.md]
C[특정 작업의 재사용 절차] --> D[SKILL.md]
E[개인 로컬 환경 정보] --> F[로컬 설정·비공개 파일]이 분리를 하면 지침 파일이 거대한 운영 매뉴얼이 되는 일을 막을 수 있습니다. 에이전트가 지침을 따르지 않는 문제도 “공용 규칙이 잘못됐는지, 특정 Skill이 잘못됐는지”로 더 빠르게 좁힐 수 있습니다.
전환 뒤에는 깨끗한 세션으로 확인하세요
파일을 정리한 뒤에는 새 Claude Code 세션에서 작은 읽기 전용 작업을 요청해 지침이 적용되는지 확인하는 것이 좋습니다. 예를 들어 “이 저장소의 테스트 명령만 알려줘”처럼 지침 파일에 명시한 정보를 물어볼 수 있습니다.
예상과 다른 규칙이 적용되거나 도구가 느려진다면, Claude Code --safe-mode처럼 프로젝트 지침·Skill·plugin·hook을 분리해 보는 진단 방법도 유용합니다. 이 글의 변화는 지침 파일의 선택지를 늘린 것이므로, 문제 발생 시에는 어떤 파일이 선택됐는지부터 확인해야 합니다.
마무리
Claude Code 2.1.277의 AGENTS.md 지원은 화려한 기능은 아니지만, 여러 에이전트를 병행하는 팀에는 꽤 중요한 호환성 변화입니다. 기존 CLAUDE.md는 건드리지 않고 유지할 수 있고, 필요할 때만 AGENTS.md를 공용 지침의 후보로 선택하면 됩니다.
핵심은 파일을 하나 더 만드는 데 있지 않습니다. 중복된 규칙을 늘리지 않고, 팀 공용 규칙·조건부 작업 절차·개인 환경 정보를 각자 맞는 위치에 두는 데 있습니다.
참고 자료
- Claude Code v2.1.277 릴리즈 노트 ↗ — AGENTS.md fallback과 지원 환경
- Claude Code CHANGELOG ↗ — v2.1.277 변경 내역
- Thariq Shihipar의 발표 ↗ — 기능 공개 맥락