AGENTS.md와 CLAUDE.md를 둘 다 만들면 끝일까? Claude가 하나를 건너뛰는 조건

결론부터 말하면, Claude Code는 기본 설정에서 AGENTS.md와 CLAUDE.md를 자동으로 합쳐 읽지 않습니다. 작업 폴더나 상위 경로에 CLAUDE.md 또는 CLAUDE.local.md가 하나라도 있으면, 공통 지침으로 만든 AGENTS.md를 건너뛸 수 있습니다.

이 글은 Codex와 Claude Code를 같은 저장소에서 쓰는 초급·중급 사용자를 위한 선택 가이드입니다. 2026년 10월 9일 기준 Codex 공식 문서와 Claude Code v2.1.277 이후 공식 동작을 확인했으며, 실제 프로젝트 파일을 만들거나 설정을 변경하지 않고 문서 기준으로 정리했습니다.

AGENTS.md와 CLAUDE.md가 기본 설정에서 자동 병합되지 않는다는 개념도

먼저 내 상황에 맞는 답부터 고르세요

상황	권장 구조	이유
Codex·Cursor·Claude Code 등 여러 도구가 같은 규칙을 써야 함	AGENTS.md를 공통 원본으로 두고 CLAUDE.md에서 @AGENTS.md 가져오기	중복 복사와 규칙 불일치를 줄임
Claude Code만 사용함	CLAUDE.md 중심	Claude 전용 범위·규칙·가져오기 기능을 그대로 활용
공통 규칙과 Claude 전용 규칙을 따로 유지함	Project instructions를 claude-md-and-agents-md로 설정하거나 CLAUDE.md에서 @AGENTS.md 가져오기	기본값에서는 두 파일이 자동 병합되지 않음
도구별 규칙을 완전히 분리해야 함	두 파일을 따로 유지하되 같은 내용을 중복 작성하지 않음	각 도구가 읽는 파일과 우선순위가 다름

OpenAI의 Codex 공식 문서는 Codex가 작업 전 AGENTS.md를 읽고, 프로젝트 루트부터 현재 작업 폴더까지 지침을 이어 붙인다고 설명합니다. 반면 Anthropic의 Claude Code 메모리 문서는 두 파일이 함께 있을 때의 기본 동작을 별도로 정의합니다.

AGENTS.md와 CLAUDE.md는 무엇이 다른가

AGENTS.md는 여러 코딩 에이전트가 공유할 수 있는 일반 마크다운 지침 파일입니다. AGENTS.md 공식 사이트는 이를 “에이전트를 위한 README”로 설명하며, 필수 필드나 고정 스키마는 두지 않습니다. 빌드·테스트 명령, 프로젝트 구조, 수정 금지 영역, 검증 기준처럼 새 팀원에게도 필요한 내용을 적는 방식입니다.

CLAUDE.md는 Claude Code용 지속 지침 파일입니다. 프로젝트의 ./CLAUDE.md나 ./.claude/CLAUDE.md, 개인 프로젝트용 CLAUDE.local.md, 사용자 전역과 조직 관리 범위를 나눌 수 있습니다. Claude 전용 규칙, 경로별 규칙, 다른 파일 가져오기가 필요할 때 더 세밀합니다.

중요한 공통점도 있습니다. 두 파일은 방화벽이나 권한 정책처럼 행동을 강제로 막는 설정이 아니라 모델에게 주는 컨텍스트입니다. 파일 삭제·배포·외부 전송을 확실히 차단해야 한다면 지침 문장만 믿지 말고 권한 설정과 훅, 샌드박스 같은 별도 통제를 사용해야 합니다.

Codex의 계층형 지침 탐색과 Claude Code의 fallback 선택 차이

Claude Code가 AGENTS.md를 건너뛰는 조건

Claude Code v2.1.277부터 AGENTS.md를 직접 읽을 수 있습니다. 다만 기본값은 “합치기”가 아니라 “둘 중 하나”입니다. v2.1.281 이전의 일부 Bedrock·텔레메트리 비활성화 세션이나 업데이트 직후 첫 세션에서는 지원되지 않을 수 있으므로, 오래된 버전이라면 @AGENTS.md 가져오기를 사용하세요.

• 작업 폴더와 그 위 경로에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없으면 AGENTS.md를 읽습니다.
• 셋 중 하나라도 있으면 기본 설정에서는 Claude 계열 파일만 읽습니다.
• 사용자 전역 ~/.claude/CLAUDE.md, 조직 관리형 파일, .claude/rules/는 이 fallback 판정과 별개입니다.
• AGENTS.override.md는 Codex에서는 우선 파일이지만 Claude Code의 직접 AGENTS 지원 대상은 아닙니다.

특히 개인 설정을 넣으려고 CLAUDE.local.md를 추가한 순간, 팀의 AGENTS.md가 기본값에서 빠질 수 있습니다. “팀원들은 규칙이 적용되는데 내 Claude Code만 다르게 움직인다”면 이 조합을 먼저 확인하세요.

Codex의 탐색 순서는 어떻게 다른가

Codex는 전역과 프로젝트 지침을 층으로 쌓습니다. 전역 범위에서는 ~/.codex/AGENTS.override.md가 있으면 그것을, 없으면 ~/.codex/AGENTS.md를 읽습니다. 프로젝트에서는 Git 루트부터 현재 작업 폴더까지 내려오며 각 디렉터리에서 AGENTS.override.md, AGENTS.md, 설정한 대체 파일명 순으로 하나를 고릅니다.

루트 지침 뒤에 가까운 하위 폴더 지침이 붙기 때문에, 결제 모듈처럼 예외가 필요한 곳은 해당 폴더 가까이에 별도 파일을 둘 수 있습니다. 기본 합산 크기는 32KiB이며 빈 파일은 건너뜁니다. 작업 폴더를 잘못 열면 예상한 지침 체인도 달라지므로, Claude Code와 편집기가 같은 작업 폴더를 보는지 확인하는 순서도 함께 점검하는 편이 안전합니다.

여러 도구가 같은 저장소를 쓸 때 가장 단순한 구조

공통 규칙은 AGENTS.md 하나에 두고, Claude 전용 내용이 필요할 때만 얇은 CLAUDE.md를 추가하는 방식이 관리하기 쉽습니다.

# CLAUDE.md
@AGENTS.md

## Claude Code 전용
- src/billing/ 변경은 먼저 계획을 보여 주세요.
- 실제 배포 명령은 승인 없이 실행하지 마세요.

Anthropic 공식 문서에 따르면 @AGENTS.md 가져오기는 공통 파일을 먼저 읽고 그 아래 Claude 전용 규칙을 이어서 적용합니다. Windows 팀원이 있다면 심볼릭 링크보다 이 가져오기 방식을 권합니다. Windows에서는 링크 생성 권한과 Git의 core.symlinks 설정 때문에 한 줄짜리 일반 파일로 풀릴 수 있기 때문입니다.

Claude Code에서 두 파일을 직접 함께 읽게 하려면 /config의 Project instructions를 claude-md-and-agents-md로 바꿀 수 있습니다. 하지만 팀 전체가 같은 설정을 쓴다는 보장이 없다면, 저장소 안의 명시적 @AGENTS.md 연결이 더 쉽게 검토됩니다.

공통 AGENTS.md를 원본으로 두고 Claude 전용 규칙만 얇게 연결하는 구조

처음 작성할 때 넣을 것과 뺄 것

넣을 것	빼거나 다른 도구로 옮길 것
실제 설치·실행·테스트 명령	코드에서 바로 알 수 있는 긴 폴더 목록
반드시 지켜야 할 수정 범위와 금지 영역	린터와 포매터가 자동 검사하는 세부 스타일 전부
완료 판정에 필요한 테스트와 결과물	특정 한 번의 작업에만 필요한 긴 절차
비밀정보·배포·데이터 처리 주의	서로 충돌하는 예외 규칙과 오래된 명령

지침 파일이 길수록 좋은 것은 아닙니다. 모든 세션에 필요한 규칙만 남기고, 특정 기능의 긴 절차는 별도 문서나 경로별 규칙으로 나누세요. 같은 문장을 두 파일에 복사하면 한쪽만 수정돼 규칙이 어긋나기 쉽습니다.

정말 읽혔는지 확인하는 방법

1. 저장소 루트와 현재 작업 폴더를 확인합니다.
2. Codex에서는 새 세션에서 codex --ask-for-approval never "Summarize the current instructions."처럼 로드된 지침 요약을 요청합니다.
3. Claude Code에서는 새 세션을 열고 /memory의 Memory files에 어떤 파일이 잡혔는지 확인합니다.
4. 임시로 “테스트 후 완료 보고”처럼 위험하지 않은 한 줄을 추가해 실제 행동과 대조한 뒤, 확인이 끝나면 불필요한 테스트 문구를 지웁니다.
5. 파일 삭제나 외부 전송처럼 되돌리기 어려운 행동은 지침 준수 여부와 별개로 권한 정책을 확인합니다.

핵심은 파일 이름을 두 개 만드는 것이 아니라 어느 도구가 어떤 경로에서 무엇을 읽는지를 확인하는 것입니다. 여러 에이전트를 함께 쓴다면 공통 규칙은 AGENTS.md에 한 번만 두고, Claude 전용 차이만 CLAUDE.md에 얇게 연결하는 구조부터 시작하세요.

---

출처 및 확인일

• OpenAI, 「Custom instructions with AGENTS.md」, 게시일 미표기, https://developers.openai.com/codex/guides/agents-md, 확인 2026-10-09
• Anthropic, 「How Claude remembers your project」, 게시일 미표기, https://code.claude.com/docs/en/memory, 확인 2026-10-09
• Agentic AI Foundation, 「AGENTS.md」, 게시일 미표기, https://agents.md/, 확인 2026-10-09
• OpenAI, 「openai/codex AGENTS.md」, 지속 갱신, https://github.com/openai/codex/blob/main/AGENTS.md, 확인 2026-10-09