AGENTS.md와 CLAUDE.md 함께 쓰기

이 페이지의 목차

확인 2026-10-18근거 자료 5건갱신 2026-10-26언급 14곳

이 페이지의 목차

확인 날짜 안내

Claude Code 공식 문서(Claude Code 메모리), Codex 공식 문서(Codex AGENTS.md 가이드), Antigravity CLI 이전 문서(Gemini CLI에서 Antigravity CLI로 이전) 모두 원본 날짜 미상이라 수집일(2026-10-18) 기준이다. Antigravity 공식 Rules 문서(Antigravity 규칙 문서)는 원본 날짜 미상, 수집 2026-10-21 기준이다. 설정 값과 버전 조건은 빨리 바뀔 수 있다.

Codex 같은 다른 코딩 에이전트용 AGENTS.md(용어 사전)가 이미 있는 저장소에서 Claude Code도 같은 지시를 읽게 하는 방법이다. Claude Code는 AGENTS.md를 프로젝트 지시로 읽을 수 있어서, 다른 에이전트용으로 세팅된 저장소는 CLAUDE.md나 import, 설정을 더하지 않아도 동작한다. 직접 읽기는 v2.1.277 이상이다. Claude Code 메모리

두 도구는 지시 파일을 어떻게 찾나 (2026-10-18 기준)#

같은 AGENTS.md라도 두 도구가 찾고 합치는 규칙이 다르다. 칸마다 근거 원본을 따로 달았다. C = Codex AGENTS.md 가이드, M = Claude Code 메모리.

항목	Codex	Claude Code (기본값 `claude-md-or-agents-md`)
디렉터리마다 보는 파일	`AGENTS.override.md` → `AGENTS.md` → `project_doc_fallback_filenames`의 이름 순, 디렉터리당 최대 1개 (C)	`CLAUDE.md`·`.claude/CLAUDE.md`·`CLAUDE.local.md`. 작업 디렉터리나 그 위에 이것들이 하나도 없을 때만 `AGENTS.md`·`.claude/AGENTS.md` (M)
같은 디렉터리의 여러 파일	최대 1개만 넣는다 (C)	`CLAUDE.local.md`가 `CLAUDE.md` 뒤에 붙는다 (M)
개인·전역 층	Codex 홈(기본 `~/.codex`, `CODEX_HOME`)의 `AGENTS.override.md`, 없으면 `AGENTS.md`. 비어 있지 않은 첫 파일 하나만 (C)	`~/.claude/CLAUDE.md`. 조직 managed CLAUDE.md도 있다. 둘 다 AGENTS.md와 함께 계속 로드된다 (M)
위쪽 탐색 범위	프로젝트 루트(보통 Git 루트)에서 현재 디렉터리까지. 루트를 못 찾으면 현재 디렉터리만 (C)	작업 디렉터리와 그 위 모든 디렉터리 (M)
현재 디렉터리 아래	현재 디렉터리에 닿으면 탐색을 멈춘다 (C)	하위 디렉터리 CLAUDE.md는 Claude가 그 디렉터리 파일을 다룰 때 로드된다. 하위 `AGENTS.md`는 Read 도구로 그 디렉터리 파일을 열고 그 디렉터리에 CLAUDE.md 세 종류가 없을 때 로드된다 (M)
합치는 순서	루트에서 아래로 빈 줄을 끼워 이어 붙인다. 가까운 파일이 뒤에 와서 앞선 지시를 override한다 (C)	덮어쓰지 않고 이어 붙인다. 파일 시스템 루트에서 작업 디렉터리 쪽 순이라 가까운 지시가 마지막에 읽힌다. 모순되면 하나를 임의로 고를 수 있다 (M)
`AGENTS.override.md`	읽는다. 같은 디렉터리의 `AGENTS.md`는 무시된다 (C)	읽지 않는다. `AGENTS.local.md`, `.agents/` 아래도 읽지 않는다 (M)
크기	합친 크기가 `project_doc_max_bytes`(기본 32 KiB)에 닿으면 파일을 더 넣지 않는다 (C)	`CLAUDE.md` 파일 하나가 4 MiB까지면 전부 로드하고 넘으면 건너뛴다. `CLAUDE.md`당 200줄 이하를 목표로 권한다. `AGENTS.md`의 크기 한도는 원본에 없다 (M)
읽을 파일을 바꾸는 설정	`~/.codex/config.toml`의 `project_doc_fallback_filenames`, `project_doc_max_bytes` (C)	`/config`의 Project instructions 4값, 또는 `cc-plugin-agents-md@builtin` 설정 (M)
언제 읽나	시작할 때 한 번(실행마다, TUI는 보통 세션마다). 낡아 보이면 다시 시작 (C)	작업 디렉터리와 그 위는 시작할 때, 하위 디렉터리는 필요할 때 (M)
로드 확인	지시를 요약하거나 출처를 나열하게 하는 프롬프트, `codex -c log_dir=./.codex-log` 로그 (C)	`/context`의 Memory files, `/memory` 목록 (M)

크기 칸은 단위가 다르다. Codex는 합친 전체 크기, Claude Code는 CLAUDE.md 파일 하나의 크기를 말한다.

두 도구를 함께 쓸 때 걸릴 만한 곳 (편집자 해석):

override 파일: Codex 문서는 override가 있는 디렉터리의 AGENTS.md를 "Ignored because an override exists"로 표시하고, Claude Code 문서는 AGENTS.override.md를 읽지 않는 파일로 든다. 그래서 AGENTS.override.md와 AGENTS.md가 함께 있는 디렉터리에서는 Codex는 override를, Claude Code는 (작업 디렉터리나 그 위에 CLAUDE.md가 없는 기본 설정이거나 claude-md-and-agents-md일 때) AGENTS.md를 따라 두 도구가 서로 다른 지시로 일할 수 있다고 볼 수 있다. 공유할 지시는 override가 아닌 파일에 두는 편이 안전하다고 볼 수 있다.
크기: Codex는 합친 지시가 기본 32 KiB에 닿으면 파일을 더 넣지 않고, 문제 해결 절에서 "Instructions truncated"를 증상으로 든다. Claude Code 문서는 CLAUDE.md를 4 MiB까지 전부 로드한다고 말하고, AGENTS.md의 크기 한도는 따로 말하지 않는다. 그래서 CLAUDE.md로 import해 공유하는 긴 지시라면 Codex의 32 KiB 합계 한도에 먼저 걸릴 수 있다고 볼 수 있다.

세 번째 도구: Antigravity CLI (2026-10-21 기준, 이전 문서 문장은 2026-10-18)#

Antigravity CLI도 AGENTS.md를 읽는다. 공식 이전 문서는 Gemini CLI와 Antigravity CLI가 같은 워크스페이스 컨텍스트 규칙을 쓰고, 현재 디렉터리의 GEMINI.md와 AGENTS.md, 전역 ~/.gemini/GEMINI.md를 읽는다고 말한다. Gemini CLI에서 옮길 때 기존 규칙 문서는 고칠 필요가 없다. Gemini CLI에서 Antigravity CLI로 이전 → Gemini CLI에서 Antigravity CLI로 옮기기

찾고 합치는 규칙은 Antigravity 공식 Rules 문서가 정한다. 위 비교표와 항목을 맞추지 않고, 이 원본이 말하는 것만 따로 적는다. Antigravity 규칙 문서

항목	Antigravity CLI (Rules 문서)
디렉터리마다 보는 파일	`AGENTS.md`, `GEMINI.md`, `.agents/AGENTS.md`, `.agents/GEMINI.md`, `.agents/rules/.md`(예전 `.agent/rules/.md`)
전역	`~/.gemini/AGENTS.md`, `~/.gemini/GEMINI.md`, `~/.gemini/config/AGENTS.md`, `~/.gemini/config/GEMINI.md`, `~/.gemini/config/rules/.md`. CLI는 `~/.gemini/antigravity-cli/rules/.md`와 플러그인 규칙도 든다
탐색 범위	파일을 읽거나 고칠 때마다 그 파일의 폴더에서 워크스페이스 루트까지 올라가며 각 단계의 규칙을 로드
합치는 방식	대체가 아니라 누적. 전역·워크스페이스·디렉터리 규칙을 모두 프롬프트에 합치고, 충돌하면 더 구체적인 디렉터리 규칙이 앞선다
frontmatter	`AGENTS.md`·`GEMINI.md`는 쓰지 않고 그 디렉터리 범위에서 항상 활성. `rules/*.md`는 `trigger` 필수
파일 참조	`@[label](path)`는 내용을 펼쳐 넣고, `@filename`은 펼치지 않고 절대 워크스페이스 경로로 바꾼다
크기	규칙 파일 하나가 24,000바이트를 넘으면 잘림. 전역·`always_on` 규칙 합계 20,000토큰을 넘으면 큰 파일부터 포인터로 바뀜

원본이 말하지 않는 것: 워크스페이스 루트 위 디렉터리를 읽는지, 같은 디렉터리에 AGENTS.md와 GEMINI.md가 둘 다 있을 때 둘 사이의 순서, AGENTS.override.md 같은 override 파일. Antigravity 규칙 문서

세 도구를 함께 쓸 때 걸릴 만한 곳 (편집자 해석):

.agents/ 폴더: Antigravity CLI는 .agents/AGENTS.md와 .agents/rules/*.md를 규칙으로 읽고, 워크스페이스 스킬은 .agents/skills/, MCP 서버는 .agents/mcp_config.json에 둔다. Antigravity 규칙 문서, Gemini CLI에서 Antigravity CLI로 이전 Claude Code 메모리 문서는 .agents/ 디렉터리 아래를 지시 파일로 읽지 않는다고 말한다. Claude Code 메모리 그래서 .agents/ 안에 둔 지시는 Antigravity CLI만 읽는다고 볼 수 있고, 여러 도구가 함께 읽을 지시는 .agents/ 안이 아니라 저장소의 AGENTS.md 파일에 두는 편이 맞다고 볼 수 있다. Claude Code가 그 AGENTS.md를 읽는 조건(CLAUDE.md가 없을 때, 또는 설정·import)은 아래 절에 있다.
@ 참조: Antigravity Rules 문서에서 @filename은 내용을 펼치지 않고 경로만 바꾸며, 내용을 넣으려면 @[label](path)를 쓴다. Antigravity 규칙 문서 Claude Code 메모리 문서는 @path를 import로 다뤄 가져온 파일을 읽는다(아래 방법 2, "AGENTS.md로 읽을 때 달라지는 점"). Claude Code 메모리 그래서 공유하는 AGENTS.md에 @docs/standards.md처럼 쓰면 Claude Code는 그 파일 내용을 읽고 Antigravity CLI는 경로 참조로만 받는 식으로 두 도구가 받는 내용이 달라질 수 있다고 볼 수 있다. 두 원본 모두 상대 도구의 문법을 말하지 않는다.
크기: 한도의 단위와 대상이 도구마다 다르다. Antigravity는 규칙 파일 하나 24,000바이트(넘으면 잘림)와 합계 20,000토큰(넘으면 포인터로), Codex는 합친 크기 기본 32 KiB, Claude Code는 CLAUDE.md 파일 하나 4 MiB다. 그래서 긴 지시를 한 AGENTS.md에 몰아 두면 도구에 따라 잘리거나 빠지는 부분이 다를 수 있다고 볼 수 있다. Antigravity 규칙 문서, Codex AGENTS.md 가이드, Claude Code 메모리

Claude Code 기본 동작: 무엇을 읽는가#

저장소에 있는 것	Claude가 읽는 것
`AGENTS.md`만 있고 작업 디렉터리나 그 위에 `CLAUDE.md`·`CLAUDE.local.md`가 없음	`AGENTS.md`
`AGENTS.md`와 `CLAUDE.md`(또는 `CLAUDE.local.md`)가 함께 있음	`CLAUDE.md` 파일들만
`AGENTS.md`를 import하는 `CLAUDE.md`	`CLAUDE.md`, import로 `AGENTS.md` 포함

근거: Claude Code 메모리

"CLAUDE.md가 있다"로 치는 것: 작업 디렉터리나 그 위의 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md. Claude Code 메모리
치지 않고 AGENTS.md와 함께 계속 로드되는 것: ~/.claude/CLAUDE.md, 조직 managed CLAUDE.md, .claude/rules/ 파일. Claude Code 메모리
읽지 않는 것: AGENTS.local.md, AGENTS.override.md, .agents/ 디렉터리 아래 전부. Claude Code 메모리
주의: CLAUDE.local.md도 CLAUDE.md로 치므로, AGENTS.md에 기대는 프로젝트에 개인 지시용 CLAUDE.local.md를 더하면 그 사용자에게는 AGENTS.md가 읽히지 않는다. 둘 다 쓰려면 아래 설정을 claude-md-and-agents-md로 둔다. Claude Code 메모리

방법 1: 설정으로 고르기#

세션에서 /config를 열고 Project instructions를 고른다. 바꾼 값은 다음 메시지부터, 그리고 모든 새 세션에 적용된다. Claude Code 메모리

값	읽는 것
`claude-md-or-agents-md` (기본값)	CLAUDE.md, 없으면 AGENTS.md
`claude-md-and-agents-md`	둘 다. 디렉터리마다 CLAUDE.md 다음에 AGENTS.md. 이미 import·심볼릭 링크로 읽은 AGENTS.md는 두 번 읽지 않는다
`claude-md`	CLAUDE.md만
`managed-only`	시작 때 조직 managed CLAUDE.md와 자동 메모리만. 하위 디렉터리 CLAUDE.md·규칙과 경로별 규칙은 필요할 때 여전히 로드된다

근거: Claude Code 메모리

설정 파일로 두려면 pluginConfigs의 내장 플러그인 cc-plugin-agents-md@builtin 아래에 쓴다. ~/.claude/settings.json, --settings 파일, managed settings에서만 읽고 project·local 설정 파일에서는 무시한다. Claude Code 메모리

json

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

v2.1.285 전에는 이 플러그인 ID가 agents-md@builtin이었다. 옛 버전도 같은 설정 파일을 읽는다면 그 ID를 쓴다. v2.1.285 이상은 둘 다 읽는다. Claude Code 메모리

방법 2: CLAUDE.md에서 import하기#

Claude가 AGENTS.md를 직접 읽지 않는 경우(프로젝트에 CLAUDE.md도 있을 때, 설정이 claude-md일 때, AGENTS.md를 못 읽는 세션일 때)에도 AGENTS.md를 모든 도구가 공유하는 한 파일로 유지할 수 있다. 옆에 @AGENTS.md를 import하는 CLAUDE.md를 둔다. Claude 전용 지시는 import 아래에 쓴다. Claude는 가져온 파일을 먼저 읽고 나머지를 읽는다. Claude Code 메모리

markdown

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

방법 3: 심볼릭 링크#

Claude 전용 내용이 필요 없으면 심볼릭 링크도 된다. 성공하면 아무것도 출력하지 않는다. Claude Code 메모리

bash

ln -s AGENTS.md CLAUDE.md

심볼릭 링크를 고르기 전 확인할 제약: Claude Code 메모리

편집: Claude는 링크를 통해 CLAUDE.md를 읽지만 Edit·Write 도구는 링크를 통해 쓰지 않고 대상인 AGENTS.md를 고치라고 안내한다.
Windows: 저장소를 Windows에서 쓰는 사람이 있으면 import를 쓴다. 심볼릭 링크 생성에 관리자 권한이나 개발자 모드가 필요하고, core.symlinks가 꺼져 있으면 Git이 링크를 한 줄짜리 일반 텍스트 파일로 체크아웃한다.

어느 방법이든 다음 세션에서 /context를 실행해 Memory files에 CLAUDE.md가 보이는지 확인한다. Claude Code 메모리

예전 우회 설정 정리하기#

Claude Code가 AGENTS.md를 직접 읽기 전에 해 둔 설정은 이렇게 처리한다. Claude Code 메모리

예전 설정	처리
`@AGENTS.md`를 담은 CLAUDE.md	그대로 둬도 두 번 읽히지 않는다. 다른 내용이 없으면 지워도 되지만, AGENTS.md를 직접 못 읽는 세션이 있으면 남긴다
"AGENTS.md를 읽어라"라고 말로 쓴 CLAUDE.md	Claude가 파일을 열기로 정해야만 본다. CLAUDE.md를 지우거나 문장을 `@AGENTS.md` import로 바꾼다
AGENTS.md를 가리키는 CLAUDE.md 심볼릭 링크	그대로 두거나 지운다. 어느 쪽이든 한 번만 읽힌다
AGENTS.md를 출력하는 `SessionStart` 훅	지운다. 직접 읽게 되면 훅이 컨텍스트에 사본을 하나 더 넣는다

AGENTS.md로 읽을 때 달라지는 점#

설정으로 읽은 AGENTS.md는 CLAUDE.md와 세 군데가 다르다. Claude Code 메모리

InstructionsLoaded 훅이 실행되지 않는다(CLAUDE.md가 import하거나 링크한 AGENTS.md면 평소처럼 실행).
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD를 켜고 --add-dir로 더한 디렉터리의 AGENTS.md는 로드되지 않는다.
작업 디렉터리 밖 파일을 가리키는 @path import는 승인 대화상자 없이, 이 프로젝트에서 외부 import를 이미 승인했을 때만 로드된다.

언제 쓰고 언제 쓰지 않는가#

쓴다: 한 저장소를 Claude Code와 Codex 등 여러 에이전트로 함께 다룰 때, 다른 도구용으로 세팅된 저장소를 Claude Code로 열 때. LLM Wiki도 Claude Code에서는 CLAUDE.md, Codex에서는 AGENTS.md를 스키마 파일로 쓰므로 두 도구를 오가는 위키라면 해당된다. Karpathy LLM Wiki
쓰지 않는다: (편집자 해석) 원본의 AGENTS.md 지원은 다른 코딩 에이전트용으로 세팅된 저장소를 위한 것이므로, Claude Code만 쓰는 저장소라면 CLAUDE.md 하나로 충분하다고 볼 수 있다(→ CLAUDE.md 작성·구성).
문제가 생기면: CLAUDE.md 문제 해결의 "AGENTS.md가 로드되지 않는다"
Codex 쪽에서 지시가 안 읽히거나 엉뚱한 지시가 나오면: Codex의 "문제 해결" 표 Codex AGENTS.md 가이드