Claude Code v2.1.277부터는 프로젝트 폴더에 CLAUDE.md가 없으면 AGENTS.md를 대체 지침으로 읽습니다(공식 릴리즈 노트 ↗). 기본값인 claude-md-or-agents-md에서는 두 파일을 합쳐 읽지 않습니다. CLAUDE.md가 있는 프로젝트는 CLAUDE.md만 읽고, claude-md-and-agents-md를 선택하면 두 파일을 함께 읽습니다.
이 변경으로 여러 코딩 에이전트가 함께 쓰는 저장소는 AGENTS.md 하나를 공용 지침으로 둘 수 있습니다. 지금까지는 CLAUDE.md, AGENTS.md, 팀 위키에 같은 규칙을 복사해 두다가 어느 파일이 정본인지 알기 어려워지곤 했습니다. 한 도구용 파일만 두면 같은 저장소를 쓰는 다른 에이전트가 팀 규칙을 놓쳤습니다.
2026-09-19 · 갱신 2026-10-07 · 공식 메모리 문서와 v2.1.290 릴리즈 노트 기준입니다. v2.1.277에서의 provider 제한과 현재 동작은 아래에서 구분합니다.
기본값에서는 CLAUDE.md가 있으면 AGENTS.md는 읽지 않습니다
공식 메모리 문서 ↗는 기본값에서 프로젝트의 CLAUDE.md 지침이 없을 때 AGENTS.md를 읽는다고 설명합니다. 작업 디렉터리와 그 상위 경로의 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 이 판단에 포함됩니다. 개인 ~/.claude/CLAUDE.md, 조직의 managed 지침, .claude/rules/는 이 fallback을 막지 않습니다.
flowchart TD
A[기본값으로 프로젝트 시작] --> B{프로젝트 CLAUDE 지침이 있는가?}
B -->|예| C[CLAUDE.md를 프로젝트 지침으로 사용]
B -->|아니오| D{AGENTS.md가 있는가?}
D -->|예| E[AGENTS.md를 대체 지침으로 사용]
D -->|아니오| F[이 두 파일의 프로젝트 지침 없음]
CLAUDE.md를 이미 쓰고 있다면 업그레이드 뒤 파일을 옮길 이유가 없습니다. Codex 같은 다른 코딩 에이전트와 같은 저장소를 쓰면서 AGENTS.md를 공용 지침으로 두고 있다면, 이제 Claude Code도 그 파일을 읽습니다.
두 파일을 함께 읽으려면
Claude Code에서 /config를 열고 **Project instructions → claude-md-and-agents-md**를 선택합니다. 기존 CLAUDE.md를 바꾸지 않고 공용 AGENTS.md를 함께 읽을 수 있습니다. 설정은 다음 메시지부터 적용됩니다.
공식 메모리 문서 ↗와 built-in agents-md plugin ↗은 네 가지 모드를 설명합니다.
| 모드 | 읽는 지침 |
|---|---|
claude-md-or-agents-md (기본값) | 프로젝트의 CLAUDE.md 지침이 있으면 그것을 읽고, 없으면 AGENTS.md를 읽습니다. |
claude-md-and-agents-md | CLAUDE.md와 AGENTS.md를 함께 읽습니다. 이미 import하거나 symlink로 읽은 같은 파일은 중복 로드하지 않습니다. |
claude-md | CLAUDE.md 지침만 읽습니다. |
managed-only | 시작 시 조직의 managed CLAUDE.md와 auto memory만 남깁니다. 하위 디렉터리의 CLAUDE.md·rule은 작업 중 여전히 로드될 수 있습니다. |
CLAUDE.local.md를 유지하면서 공용 AGENTS.md도 읽으려면 함께 읽는 모드를 선택합니다. 두 파일에 충돌하는 규칙을 넣지 않고, 공용 규칙과 Claude 전용 지침을 나눕니다. 팀 정책이나 기존 자동화가 특정 파일명을 전제한다면 설정과 실제로 읽힌 파일을 먼저 확인합니다.
직접 로드가 지원되지 않는 세션
공식 문서의 지원 예외 ↗에 따르면 v2.1.277 이전 버전이나 built-in plugin을 비활성화한 세션에서는 CLAUDE.md만 읽습니다. v2.1.276 이하에서 업그레이드한 뒤 일부 첫 세션도 해당하며, 다음 세션부터 AGENTS.md를 읽습니다. 이런 세션에는 /config의 Project instructions도 나타나지 않습니다.
v2.1.277 당시 Bedrock·Vertex·Foundry 등 서드파티 provider에서는 fallback이 지원되지 않았습니다. 현재 문서는 Bedrock·telemetry 비활성 등 일부 세션의 제한을 v2.1.281 이전으로 구분하므로, 해당 버전에서는 먼저 업데이트합니다. 직접 로드가 불가능한 세션은 CLAUDE.md에 @AGENTS.md를 import해 공용 지침을 읽을 수 있습니다.
무엇을 한 파일에 두어야 할까
지침 파일에는 놓치면 비용이 큰 결정을 짧게 적습니다. 빌드·테스트 명령, 디렉터리 책임, 수정 금지 영역, PR 검증 기준이 여기에 해당합니다. 모델에게 필요한 모든 정보를 담는 파일로 쓰면 길어지기만 합니다.
# AGENTS.md
## 프로젝트 규칙
- 패키지 설치와 스크립트 실행은 pnpm을 사용합니다.
- 변경 뒤에는 관련 테스트와 린트를 실행합니다.
- 데이터베이스 마이그레이션은 별도 승인 없이 적용하지 않습니다.
## 검증
- 애플리케이션: pnpm test
- 타입 검사: pnpm typecheck공용 지침에는 위 예시처럼 팀원이 그대로 실행할 수 있는 명령과 경계를 적습니다. 개인 API 키 경로, 로컬 프록시 주소, 개인 선호처럼 저장소에 공유하면 안 되는 정보는 다른 곳에 둡니다.
Claude Code Memory에서 다룬 CLAUDE.md 중심의 메모리·규칙 계층은 그대로 동작합니다. 이번 변경으로 달라지는 것은 프로젝트 공용 지침의 파일명을 고를 수 있다는 점뿐입니다.
팀에 이미 CLAUDE.md가 있다면
기존 CLAUDE.md는 그대로 둡니다. CLAUDE.md와 AGENTS.md에 비슷하지만 다른 규칙을 복제하면, 기본값에서 Claude Code는 CLAUDE.md만 읽습니다. 시간이 지나면 팀은 “어느 지침이 맞는가”를 따로 관리해야 합니다.
| 팀 상황 | 권장 선택 | 이유 |
|---|---|---|
| Claude Code만 주로 사용 | 기존 CLAUDE.md 유지 | 동작 변경이 없고, 마이그레이션 비용이 없습니다. |
| 여러 에이전트가 같은 지침을 소비 | AGENTS.md를 공용 정본으로 검토 | Claude Code도 fallback으로 읽을 수 있습니다. |
| 두 파일이 이미 존재 | 정본 하나를 정하고 다른 파일의 중복 제거 | 도구별로 다른 규칙이 적용되는 위험을 줄입니다. |
공용 정본을 AGENTS.md로 옮기기로 했다면, 개인 설정까지 한 번에 옮기지 마세요. 먼저 팀 규칙만 담은 AGENTS.md를 만듭니다. 기존 CLAUDE.md의 개인·도구 전용 지침은 별도 규칙이나 로컬 설정으로 나눕니다. 이렇게 나누면 변경을 리뷰하고 되돌리기 쉽습니다.
Skill과 지침 파일은 역할이 다릅니다
프로젝트 지침에는 “항상 적용되는 제약”을, Skill에는 “특정 작업에서만 필요한 절차”를 둡니다. 모든 작업 절차를 AGENTS.md에 길게 넣을 필요는 없습니다.
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 세션에서 /context의 Memory files를 확인하고, 작은 읽기 전용 작업으로 지침이 적용되는지 확인합니다. 예를 들어 “이 저장소의 테스트 명령만 알려줘”처럼 지침 파일에 적은 정보를 물어봅니다.
v2.1.290 릴리즈 노트 ↗는 작업 디렉터리 밖을 가리키는 프로젝트 CLAUDE.md·rule·AGENTS.md symlink의 읽기 제한 문제를 수정했습니다. permissions.blockReadsOutsideWorkingDirectories나 Read deny 규칙으로 차단한 외부 파일이 로드되던 문제입니다. 외부 공용 지침을 symlink로 연결했다면 대상 경로의 읽기 권한도 확인합니다.
예상과 다른 규칙이 적용되면 어떤 파일이 읽혔는지부터 확인합니다. 도구가 느려지거나 원인이 여전히 불분명하면 Claude Code --safe-mode로 프로젝트 지침·Skill·plugin·hook을 하나씩 분리해 봅니다.
참고 자료
- Claude Code v2.1.277 릴리즈 노트 ↗ — AGENTS.md fallback과 지원 환경
- Claude Code 메모리 문서 ↗ — 기본값, 함께 읽는 모드와 버전별 지원 예외
- built-in agents-md plugin ↗ — 네 가지 instructionFiles 모드
- Claude Code v2.1.290 릴리즈 노트 ↗ — 외부 symlink 지침의 읽기 제한 수정
- Claude Code CHANGELOG ↗ — v2.1.277 변경 내역
- Thariq Shihipar의 발표 ↗ — 기능 공개 맥락
2026년 10월 7일 수정: 공식 메모리 문서와 v2.1.290 릴리즈 노트로 설정 모드·지원 예외·symlink 읽기 제한을 보강했습니다.