claude.md agents.md 차이 · claude code agents.md: 공통 규칙은 AGENTS.md 에 두고 CLAUDE.md 는 불러오기 한 줄과 Claude 전용만

작업 폴더나 그 위에 CLAUDE.md 가 있으면 Claude Code는 기본값에서 AGENTS.md 를 읽지 않는다. 두 파일의 차이는 결국 누가 읽느냐에서 갈린다. CLAUDE.md 는 Claude Code가 읽는 지시 파일, AGENTS.md 는 Codex를 비롯한 여러 코딩 에이전트가 같이 읽는 공개 형식의 지시 파일. 그래서 둘 다 쓴다면 공통 규칙은 AGENTS.md 한 곳에 적고, CLAUDE.md 에는 @AGENTS.md 한 줄과 Claude Code에만 필요한 지시를 둔다. 기준은 2026년 10월 16일에 읽은 Claude Code · Codex 공식 문서와 agents.md 사이트다.

claude.md 와 agents.md 차이 한눈에 (2026-10-16 공식 문서 기준)

세 곳에 적힌 내용을 표 하나로 모았다.

	CLAUDE.md	AGENTS.md
누가 읽나	Claude Code	Codex, Cursor, Jules 등 agents.md 사이트가 꼽은 여러 코딩 에이전트. Claude Code도 v2.1.277 이상에서 조건에 따라 읽음
어디에 두나	저장소 맨 위 ./CLAUDE.md(또는 ./.claude/CLAUDE.md), 내 전역 ~/.claude/CLAUDE.md, 나만 쓸 CLAUDE.local.md, 하위 폴더	저장소 맨 위와 하위 폴더(Codex는 실행한 폴더까지). Codex는 전역 ~/.codex/AGENTS.md 도 읽음
문법	마크다운. @경로 로 다른 파일을 불러옴(네 단계까지)	그냥 마크다운. 정해진 필드 없음
불러오는 때	세션을 시작할 때 실행 폴더와 그 위 폴더의 파일을 이어 붙임. 하위 폴더 파일은 그 폴더 파일을 다룰 때	Codex는 시작할 때 한 번(실행마다). 저장소 루트에서 현재 폴더까지 폴더마다 한 파일, 합쳐서 기본 32KiB 까지
지시가 겹치면	파일끼리 덮어쓰지 않고 이어 붙음. 지시가 어긋나면 Claude가 아무 쪽이나 고를 수 있음	편집하는 파일에 가장 가까운 AGENTS.md 가 이기고, 채팅에서 직접 한 지시는 그보다 위(agents.md 사이트). Codex는 실행한 폴더에 가까운 파일이 뒤에 붙어 앞 지시를 덮고, 실행한 폴더 아래의 파일은 읽지 않음

출처는 Claude Code 메모리 문서, Codex 「Custom instructions with AGENTS.md」, agents.md, 모두 2026-10-16 조회. Claude Code가 AGENTS.md 를 직접 읽을 때는 그 안의 @경로 불러오기도 펼친다.

Claude Code가 AGENTS.md 를 읽는 경우, 안 읽는 경우 (v2.1.277 이상)

공식 문서의 기본값 표를 옮기면 이렇다.

저장소에 있는 것	Claude Code가 읽는 것(기본값)
AGENTS.md 만 있고, 작업 폴더나 그 위에 CLAUDE.md · CLAUDE.local.md 가 없음	AGENTS.md
AGENTS.md 와 함께, 작업 폴더나 그 위에 CLAUDE.md 또는 CLAUDE.local.md	CLAUDE.md 쪽만
AGENTS.md 를 불러오는 CLAUDE.md	CLAUDE.md, 불러온 AGENTS.md 포함

여기서 「있다」로 치는 건 작업 폴더나 그 위 폴더의 CLAUDE.md · .claude/CLAUDE.md · CLAUDE.local.md 셋. 내 전역 ~/.claude/CLAUDE.md, 회사 관리 정책 CLAUDE.md, .claude/rules/ 파일은 치지 않고 AGENTS.md 와 같이 실린다. 그래서 생기는 함정 하나. AGENTS.md 만 쓰던 저장소에 나만 쓸 메모를 두려고 CLAUDE.local.md 를 만들면, 그때부터 Claude Code가 AGENTS.md 를 읽지 않는다. 그 파일을 두면서 AGENTS.md 도 읽히게 하려면 Project instructions 를 claude-md-and-agents-md 로 바꾸라는 게 문서의 방법.

하위 폴더의 AGENTS.md 는 Claude가 그 폴더의 파일을 Read 도구로 열 때 실린다. 작업 폴더와 그 위에 치는 파일이 없고, 그 폴더에도 CLAUDE.md 계열 파일이 하나도 없을 때만.

AGENTS.md 를 직접 읽는 건 v2.1.277 이상부터다. 그보다 낮은 버전, /plugin 으로 AGENTS.md 를 읽는 내장 플러그인을 끈 경우, v2.1.276 이하에서 올린 직후의 첫 세션 일부는 예외. 이런 세션은 CLAUDE.md 만 읽고, /config 에 Project instructions 항목도 나오지 않는다. v2.1.281 전에는 Amazon Bedrock 세션이나 텔레메트리를 끈 세션 일부도 CLAUDE.md 만 읽었다. Claude Code가 아예 읽지 않는 이름도 있다. AGENTS.local.md, AGENTS.override.md, 그리고 .agents/ 폴더 아래 파일.

읽혔는지는 /memory 목록에 AGENTS.md 경로가 있는지로 본다. 대화형 세션이라면 no CLAUDE.md found; AGENTS.md loaded: 로 시작하는 줄도 찍힌다.

Codex는 AGENTS.md 를 이렇게 읽는다

Codex 쪽은 어떨까? 문서에는 「Codex reads AGENTS.md files before doing any work.」라고 적혀 있다. 지시 묶음은 시작할 때 한 번 만든다(실행마다, TUI 라면 보통 띄운 세션마다). 그러니 고친 내용은 다음 실행부터.

1. 전역 — Codex 홈(기본 ~/.codex, CODEX_HOME 으로 바꿀 수 있음)에 AGENTS.override.md 가 있으면 그것, 없으면 AGENTS.md. 비어 있지 않은 첫 파일 하나만 쓴다.
2. 프로젝트 — 프로젝트 루트(보통 Git 루트)에서 현재 작업 폴더까지 내려가며, 폴더마다 AGENTS.override.md → AGENTS.md → 설정 project_doc_fallback_filenames 에 적은 이름 순으로 보고 한 파일만 넣는다.
3. 합치기 — 루트 쪽부터 빈 줄을 끼워 이어 붙인다. 현재 폴더에 가까운 파일이 뒤에 오므로 앞의 지시를 덮는다. 빈 파일은 건너뛴다.
4. 크기 — 합친 크기가 project_doc_max_bytes(기본 32KiB)에 닿으면 더 붙이지 않는다. 한도를 올리거나 하위 폴더로 나누라고 문서는 권한다.

CLAUDE.md 는 이 목록에 없다. 대체 이름에 넣어 봐야, 같은 폴더에 AGENTS.md 가 있으면 한 폴더 한 파일이라 그쪽이 먼저 잡히는 구조. 실린 지시는 저장소 맨 위에서 아래처럼 요약해 달라고 물어 확인한다.

codex --ask-for-approval never "Summarize the current instructions."

둘 다 쓸 때 나누는 법: 공통은 AGENTS.md, Claude 전용은 CLAUDE.md

한 저장소에 두 파일을 같이 둔다면 이 순서로 나눈다.

1. 공통 규칙은 AGENTS.md 에. 빌드 · 테스트 명령, 코드 관례처럼 어느 에이전트든 지켜야 할 것을 적는다. agents.md 사이트는 README 를 사람용(빠른 시작, 프로젝트 소개, 기여 안내)으로 두고, 에이전트에게 필요한 빌드 단계 · 테스트 · 관례 같은 세부를 AGENTS.md 에 두라고 설명한다.
2. CLAUDE.md 는 맨 위에 @AGENTS.md, 그 아래 Claude 전용. Claude는 불러온 파일을 먼저 읽고 그다음 나머지를 읽는다. 공식 문서의 예시 그대로 옮기면 이렇다.

   @AGENTS.md
   
   ## Claude Code
   
   Use plan mode for changes under `src/billing/`.

3. 같은 규칙을 두 파일에 나눠 쓰지 않는다. 지시가 겹칠 때의 처리가 도구마다 다르다. Claude Code는 파일을 이어 붙여 읽고 어긋나면 아무 쪽이나 고를 수 있고, agents.md 사이트 기준으로는 편집하는 파일에 가장 가까운 AGENTS.md 가 이긴다. 한 규칙은 한 파일에만 두는 편이 안전하다.
4. 「AGENTS.md 를 읽어라」 문장으로만 가리키지 않는다. 그렇게 적힌 CLAUDE.md 라면 Claude는 AGENTS.md 를 열기로 했을 때만 본다. 문서는 그 문장을 @AGENTS.md 불러오기로 바꾸거나, CLAUDE.md 를 지워 AGENTS.md 를 직접 읽게 하라고 적었다. 지우는 쪽은 그 파일에 다른 내용이 없을 때 얘기.
5. Claude 전용 내용이 없다면 CLAUDE.md 없이, 또는 심볼릭 링크로. CLAUDE.md 가 없으면 v2.1.277 이상 Claude Code는 AGENTS.md 를 직접 읽는다. 링크는 ln -s AGENTS.md CLAUDE.md. 이때 Claude의 Edit · Write 도구는 링크를 거쳐 쓰지 않고 대상인 AGENTS.md 를 고치라고 안내한다. Windows 에서 clone 하는 사람이 있으면 링크가 한 줄짜리 CLAUDE.md 로 풀릴 수 있어서, 그때는 불러오기 쪽을 쓰라고 문서에 적혀 있다.
6. 설정으로 둘 다 읽게 하는 길도 있다. /config 에서 Project instructions 를 claude-md-and-agents-md 로 두면 폴더마다 CLAUDE.md 다음에 AGENTS.md 를 읽는다. 이 값을 설정 파일에 적을 때는 ~/.claude/settings.json 같은 내 설정이나 관리 설정에서만 읽히고, 저장소의 프로젝트 · 로컬 설정 파일에 적으면 무시된다. 저장소를 받는 사람 모두에게 같은 결과를 주려면 저장소에 들어가는 불러오기 한 줄 쪽이 맞는 셈. 불러오기를 남겨 둔 채 이 값을 켜도 AGENTS.md 를 두 번 읽지는 않는다.
7. /import 는 한 번 복사다. /import 는 다른 코딩 에이전트 설정을 가져오면서 AGENTS.md 같은 지시 파일을 맞는 CLAUDE.md 뒤에 한 번 복사해 붙인다(v2.1.213 이상). 복사한 뒤로는 두 파일을 따로 고쳐야 하니, 계속 같이 쓸 규칙이면 불러오기가 낫다.
8. 에이전트가 같이 지킬 규칙은 메모리가 아니라 파일에. Claude Code의 auto memory 는 Claude가 스스로 적는 메모다. Codex 문서가 지시 파일로 드는 건 AGENTS.override.md · AGENTS.md 와 설정에 적은 대체 이름이다.

확인은 다음 세션에서 /context 를 쳐 Memory files 에 CLAUDE.md 가 보이는지로.

실제로 겪은 일

우리 저장소도 두 파일을 같이 쓴다. AGENTS.md 는 Codex CLI · Claude Code를 포함한 모든 에이전트용 전체 운영 규칙이고, CLAUDE.md 는 그 요약에 「둘이 다르면 AGENTS.md 를 따른다」를 적어 둔 세션 진입점이다. 10월 12일, 내가 짚고 나서 확인해 보니 여러 세션에 걸쳐 준 프런트엔드 지시가 Claude 메모리에만 있고 저장소 문서에는 한 줄도 없었다. 그날 「이건 에이전트 공통에 심어두고」라고 지시했고, 내가 건네는 링크 · 자료를 출처와 분석까지 남기는 규칙이 AGENTS.md 에 여섯 단계짜리 새 절로 들어갔다. CLAUDE.md 에 붙은 건 요약 한 줄과 그 절 번호인데, 우리 CLAUDE.md 가 아직 @AGENTS.md 로 불러오지 않고 요약을 따로 적는 쪽이라 위 나누는 법 3번 기준으로는 이것도 고칠 거리다.

내 저장소 점검표: claude.md · agents.md 같이 쓸 때

1. 공통 규칙이 AGENTS.md 한 곳에만 있나. CLAUDE.md 에 같은 규칙이 또 적혀 있지 않나.
2. CLAUDE.md 가 @AGENTS.md 로 불러오나. 「읽어라」 문장으로만 가리키고 있지 않나.
3. claude --version 이 v2.1.277 이상인가(Bedrock · 텔레메트리를 끈 세션은 v2.1.281 이상). AGENTS.md 만 쓰는 저장소에 CLAUDE.local.md 를 만들어 두지 않았나.
4. 다음 세션의 /context Memory files 에 CLAUDE.md 가 보이나. AGENTS.md 를 직접 읽게 했다면 /memory 목록에 그 경로가 있나.
5. Codex 쪽에 AGENTS.override.md 가 남아 같은 폴더의 AGENTS.md 를 가리고 있지 않나. 합친 크기가 32KiB 를 넘지 않나.
6. 심볼릭 링크를 쓴다면, Windows 로 clone 하는 사람은 없나.
7. 모든 에이전트가 지킬 규칙이 한 도구의 메모리에만 남아 있지 않나.

같이 읽을 글

• 13편 — claude.md 파일 위치 · 클로드 코드 claude.md 작성법: 저장소 맨 위 CLAUDE.md 에, 200줄 안쪽으로 매번 필요한 것만: CLAUDE.md 를 어디에 두고 무엇을 적는지. 이 글의 앞 편.
• 5편 — Claude Code vs Codex 비교(클로드 코드 vs 코덱스 차이): 둘 다 매일 쓰며 일을 나누는 법: 두 에이전트가 같은 규칙집을 읽으면서 일을 나누는 방식.

다음 글은 claude code skills vs agents. 스킬과 서브에이전트를 언제 나눠 쓰는지 다룬다.

다음에 다뤘으면 하는 질문은 댓글로 남기거나 codenara.contact@gmail.com 으로 보내 주세요. 받은 질문은 다음 글감으로 씁니다.