CLAUDE.md와 AGENTS.md 차이 코딩 에이전트 지침 우선순위와 실전 작성법

이 글에서 사용하는 주요 용어 정의

용어정의

CLAUDE.md	Claude Code 세션 시작 시 컨텍스트에 주입되는 전용 프로젝트 지침 파일
AGENTS.md	여러 코딩 에이전트가 공통으로 참조할 수 있도록 설계된 벤더 중립적 오픈 표준 지침 파일
컨텍스트 주입	에이전트가 작업을 시작하기 전 지침 문서의 내용을 프롬프트 컨텍스트로 불러오는 과정
폴백(Fallback)	주 지침 파일이 없을 때 지정된 대체 지침 파일을 자동으로 탐색해 로드하는 동작

도입

코딩 에이전트가 프로젝트에 처음 투입될 때 빌드 명령, 패키지 매니저, 테스트 규칙을 모르면 프로젝트 규칙과 맞지 않는 코드를 만들거나 빌드 오류를 일으킬 수 있습니다. 이를 방지하기 위해 저장소 루트에 지침 문서를 배치합니다.

현재 널리 쓰이는 지침 파일 규격은 Claude Code의 CLAUDE.md와 OpenAI Codex 등이 채택한 AGENTS.md입니다. 두 파일의 개념 차이와 로딩 우선순위 규칙을 정리합니다.

배경과 구조: 전용 매뉴얼과 오픈 표준 계약

CLAUDE.md는 Claude Code 전용 정적 온보딩 매뉴얼입니다. 세션 대화를 거치며 동적으로 학습이 누적되는 MEMORY.md와 달리, 팀 전체가 공유하는 정적 제약 조건을 정의합니다.

AGENTS.md는 특정 도구에 종속되지 않는 벤더 중립적 오픈 표준 규격입니다. 특정 독점 CLI에 묶이지 않고 저장소의 기본 엔지니어링 계약을 기술합니다.

핵심 내용: 도구별 로딩 매커니즘과 우선순위

Claude Code에서의 로딩 규칙

Claude Code는 프로젝트 루트의 CLAUDE.md와 로컬 개인 설정인 CLAUDE.local.md를 최우선으로 읽습니다. 계층별 로딩 구조는 Claude Code 공식 문서에 명시되어 있습니다.

Claude Code v2.1.277부터 AGENTS.md 지원이 추가되었습니다. 기본 동작은 폴백(Fallback) 방식으로, CLAUDE.md와 CLAUDE.local.md가 모두 없을 때만 AGENTS.md를 불러옵니다. 둘 다 있으면 CLAUDE.md가 우선 로드되고 AGENTS.md는 무시됩니다. 로드 방식을 변경하려면 /config의 Project instructions 설정을 조정합니다.

전체 스코프 우선순위는 다음과 같습니다.

1. 시스템 및 엔터프라이즈 정책
2. 전역 개인 설정 (~/.claude/CLAUDE.md)
3. 프로젝트 공용 설정 (./CLAUDE.md)
4. 로컬 개인 오버라이드 (./CLAUDE.local.md)

OpenAI Codex에서의 로딩 규칙

OpenAI Codex는 AGENTS.md를 기본 지침 규격으로 다룹니다. 단일 디렉터리 내에서는 AGENTS.override.md가 최우선 적용 파일이며, 해당 파일이 없을 때 AGENTS.md를 읽습니다.

Codex의 특징은 디렉터리 계층 병합(Hierarchical Concatenation)입니다. Git 저장소 루트부터 현재 작업 디렉터리까지 내려가며 지침 파일을 수집해 결합합니다. 프롬프트 뒷부분에 배치되는 하위 폴더의 규칙이 상위 폴더의 규칙을 자연스럽게 오버라이드합니다.

Codex에서 CLAUDE.md를 읽게 하려면 앞선 지침 파일(AGENTS.override.md, AGENTS.md)이 없을 때 대체 파일로 선택되도록 ~/.codex/config.toml에 등록합니다. 세부 설정 옵션은 OpenAI Codex 기술 문서에서 확인할 수 있습니다. 다음은 설정 예제이며 실제 적용 테스트는 수행하지 않은 예시 코드입니다.

project_doc_fallback_filenames = ["CLAUDE.md"]

도구별 지침 로딩 비교

항목Claude CodeOpenAI Codex

기본 지침 파일	CLAUDE.md	AGENTS.md
상대 파일 지원 방식	CLAUDE.md 및 CLAUDE.local.md 부재 시 AGENTS.md 자동 폴백 (v2.1.277+)	config.toml fallback 등록 시 앞선 지침 파일 부재 시 로드
디렉터리 병합	전역/프로젝트/로컬 계층 분리	루트부터 하위 작업 폴더까지 계층적 결합 및 오버라이드
최우선 적용 파일	CLAUDE.local.md (로컬 개인 설정)	AGENTS.override.md (동일 디렉터리 최우선 파일)

실제 적용과 지침 작성 가이드

지침에 반드시 포함해야 할 내용

• 검증된 실행 명령어: 에이전트가 추측하기 어려운 고유한 빌드, 린트, 테스트 명령어와 필수 플래그를 명시합니다.
• 기술 스택과 패키지 관리자: pnpm과 npm 구분, 특정 런타임 버전을 지정합니다.
• 비타협적 아키텍처 규칙: 특정 라이브러리 사용 금지, 강제 타입 단언 금지, 환경 변수 직접 커밋 금지 같은 하드 제약을 기술합니다.

지침에서 제외해야 할 내용

• 모호한 일반론: "클린 코드를 작성하라" 같은 모호한 문장은 컨텍스트만 낭비합니다.
• 수시로 바뀌는 세부 명세: 자주 변경되는 개별 API 엔드포인트 명세나 긴 튜토리얼은 지침 문서에서 제외합니다.

실무 협업 운영 전략

• 벤더 중립 단일화 전략: 저장소 루트에 AGENTS.md만 관리합니다. Codex는 기본 인식하며, Claude Code 역시 CLAUDE.md와 CLAUDE.local.md가 모두 없으면 자동 폴백하므로 파일 중복 관리를 없앱니다.
• 도구별 분리 전략: 공통 규칙은 AGENTS.md에 두고, Claude Code 전용 기능(서브에이전트 지정, 훅 연계)이 필요할 때만 CLAUDE.md를 추가합니다. 단, Claude Code에서 CLAUDE.md가 있으면 기본적으로 AGENTS.md가 무시됩니다.

마무리

지침 문서는 코딩 에이전트의 컨텍스트 낭비와 불필요한 시행착오를 줄이는 핵심 장치입니다. 두 도구를 함께 사용하거나 지침 문서를 처음 도입한다면, 저장소 루트에 AGENTS.md를 먼저 구성해 빌드 명령과 핵심 제약 조건을 정의하는 것부터 시작하는 것을 권장합니다.

출처

• Claude Code 공식 문서: https://code.claude.com/docs/en/overview
• OpenAI Codex 기술 문서: https://developers.openai.com/codex