왜 지금 확인해야 하나

9월 18일 이전에는 Codex·Cursor용으로 AGENTS.md를 쓰는 팀도 Claude Code를 위해 CLAUDE.md를 옆에 두어야 했다. 내용을 복제하거나, @AGENTS.md import 한 줄을 넣거나, 심볼릭 링크를 거는 식이었다. 이 발표 관련 해커뉴스 스레드는 739포인트·286댓글에 달했고, 토론의 대부분은 “각자 어떤 우회책을 써 왔는가”였다.

문제는 검색해서 나오는 한국어 가이드 상당수가 아직 우회책 시대 정보라는 점이다. 8월 30일자 글은 “Claude Code는 CLAUDE.md만 읽고 AGENTS.md는 읽지 않는다(공식 문서)”라고 안내한다 — 9월 18일에 뒤집힌 내용이다. 2025년 11월자 글은 이제 불필요해진 Gemini CLI·Codex 설정 파일 세팅을 여전히 권고한다. 이 글은 실행 당일 기준으로 공식 문서를 다시 읽고 정리했다.

5개 도구가 실제로 읽는 파일 — 공식 문서 기준

각 도구의 공식 문서를 2026년 9월 23일에 다시 확인했다. 표의 내용은 모두 1차 자료(공식 문서·공식 changelog) 기반이다.

여기서 눈여겨볼 두 가지.

Codex는 CLAUDE.md를 전혀 읽지 않는다. CLAUDE.md에만 있는 규칙은 Codex에게 보이지 않는다. 같은 저장소에서 Codex와 Claude Code를 함께 썼다면 두 도구가 공통으로 보는 파일은 AGENTS.md뿐이었다. 이번 지원 added로 드디어 Claude Code도 그 파일을 기본으로 읽게 된 것이다.

OpenCode는 Claude Code와 정반대다. OpenCode는 AGENTS.md를 먼저 읽고, AGENTS.md가 없을 때만 CLAUDE.md를 폴백으로 읽는다. 두 파일이 모두 있는 저장소에서 Claude Code는 CLAUDE.md를, OpenCode는 AGENTS.md를 읽는다. 내용이 다르면 두 에이전트가 서로 다른 규칙을 따르는데 어느 쪽도 그 사실을 알려주지 않는다.

Claude Code의 우선순위 규칙 — 어떤 파일이 ‘존재한다’로 세는가

Claude Code 공식 memory 문서가 정의하는 판정 규칙이다.

CLAUDE.md가 존재한다고 세는 파일 (이 중 하나라도 있으면 AGENTS.md를 읽지 않는다):

• 작업 디렉터리와 모든 상위 디렉터리의 CLAUDE.md
• 같은 위치의 .claude/CLAUDE.md
• 같은 위치의 CLAUDE.local.md

세지 않는 파일 (AGENTS.md와 함께 계속 로드된다):

• 개인용 ~/.claude/CLAUDE.md
• 조직의 managed CLAUDE.md
• .claude/rules/ 파일

이 구분이 중요한 이유는 “개인 전역 설정을 쓰고 있으면 AGENTS.md가 안 읽히는 것 아닌가” 하는 오해 때문이다. 그렇지 않다. ~/.claude/CLAUDE.md는 프로젝트 판정에 영향을 주지 않는다. 프로젝트 경로 안의 파일만 판정에 개입한다.

AGENTS.md가 읽혔는지 확인하는 가장 빠른 방법은 대화 상단의 안내 줄이다. agents-md: no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md 형태로 뜬다. 직접 로드된 AGENTS.md는 /memory나 /context의 Memory files 목록에 표시되지 않으므로, 이 줄이 없으면 읽히지 않은 것이다.

4가지 Project instructions 모드

/config의 Project instructions 설정으로 동작을 바꿀 수 있다. 프로젝트·로컬 설정 파일에서는 이 키가 무시되고 사용자(~/.claude/settings.json)·managed 설정에서만 적용된다는 점에 주의한다.

설정 파일 형태는 다음과 같다.

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

Claude 전용 규칙이 정말 필요한 게 아니라면 claude-md-and-agents-md를 쓰기보다 기본값 그대로 두고 CLAUDE.md를 정리하는 쪽이 깔끔하다. 파일이 둘이면 언젠가 내용이 갈라진다.

직접 로드된 AGENTS.md가 CLAUDE.md와 다른 점

설정으로 읽힌 AGENTS.md는 CLAUDE.md를 완전히 대체하지 않는다. 공식 문서가 밝히는 차이는 세 가지다.

• InstructionsLoaded 훅: CLAUDE.md에서는 발생, 설정으로 직접 읽은 AGENTS.md에서는 발생하지 않는다. CLAUDE.md가 import한 AGENTS.md에 대해서는 발생한다.
• --add-dir 추가 디렉터리: CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 환경 변수와 함께 쓰면 추가 디렉터리의 CLAUDE.md는 로드되고 AGENTS.md는 로드되지 않는다.
• 외부 @path import: CLAUDE.md는 저장소 밖 파일 import 시 승인을 요청하지만, AGENTS.md는 이미 승인된 경우에만 로드하고 프롬프트하지 않는다.

훅을 쓰는 자동화가 있다면 이 차이가 실질적으로 영향을 준다. 해당 없으면 체감 차이는 없다.

마이그레이션 판정 — CLAUDE.md를 삭제할지 import로 남길지

기존 상태별로 공식 문서가 권하는 처리 방법이 다르다. 3분기 매트릭스로 정리했다.

과거 우회책을 쓰고 있었다면 이렇게 정리한다. CLAUDE.md에 @AGENTS.md import가 들어 있으면 그대로 둬도 된다 — 어떤 모드에서든 파일을 두 번 읽지 않는다. “AGENTS.md를 읽으라”는 문장만 있는 CLAUDE.md는 삭제하거나 import 구문으로 바꾼다. AGENTS.md를 심볼릭 링크한 CLAUDE.md는 링크를 삭제해도 내용은 한 번만 읽힌다. SessionStart 훅으로 AGENTS.md를 출력하고 있었다면 훅을 제거한다 — 직접 로드가 되면 컨텍스트에 사본이 하나 더 생긴다.

권장 최종 구성

# AGENTS.md (저장소 루트)

## 공통 규칙
- 커밋 메시지는 Conventional Commits 형식
- PR 전에 npm test 실행

## Claude Code 전용 (필요할 때만 CLAUDE.md로 분리)

Claude 전용 규칙이 필요할 때만 CLAUDE.md를 이렇게 만든다.

@AGENTS.md

## Claude Code
- src/billing/ 변경은 plan mode 사용

import 아래에 Claude 전용 내용을 적으면 import된 파일이 먼저, 나머지가 그 뒤에 로드된다.

Gemini CLI — AGENTS.md를 읽게 하는 설정 한 줄

Gemini CLI는 소스 코드 수준에서 기본 컨텍스트 파일명이 GEMINI.md로 정의되어 있다. AGENTS.md를 읽게 하려면 .gemini/settings.json에 컨텍스트 파일명 배열을 지정한다.

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

배열로 지정하면 두 파일을 모두 로드하고, 파일명 우선순위대로 찾는다. 전역 ~/.gemini/GEMINI.md는 그대로 살아 있으니 개인 기본값을 유지하면서 프로젝트 단위로 AGENTS.md를 붙일 수 있다. Gemini CLI는 @file.md import도 지원하므로, GEMINI.md 하나만 쓰고 싶다면 @AGENTS.md import로 공용 규칙을 가져오는 방법도 있다.

Codex — 전역과 32KiB 제한

Codex의 지침 체인은 두 층이다. 전역은 ~/.codex/AGENTS.override.md가 있으면 그것만, 없으면 ~/.codex/AGENTS.md를 읽는다. 프로젝트에서는 저장소 루트부터 작업 디렉터리까지 내려가며 디렉터리당 최대 한 파일(AGENTS.override.md → AGENTS.md → fallback 파일명 순)을 읽고, 루트부터 순서대로 이어 붙인다. 나중에 오는 파일(작업 디렉터리에 가까운 파일)이 앞선 지침을 덮어쓴다.

합산 크기 제한이 project_doc_max_bytes로 32KiB 기본값이다. 모노레포에서 지침이 길어지면 잘리므로, 제한을 올리거나 중첩 디렉터리로 분할한다.

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536

지침을 어디서 로드했는지 감사하려면 codex -c log_dir=./.codex-log으로 TUI 로그를 남기거나 세션 로그의 jsonl 파일을 확인한다.

AGENTS.md가 읽히지 않을 때 — 순서대로 확인하는 체크리스트

1. 버전: claude --version으로 2.1.277 이상인지 확인한다. 낮으면 claude update다.
2. 상위 디렉터리 스캔: 작업 디렉터리 위 어딘가에 CLAUDE.md 계열 파일이 숨어 있으면 그것이 이긴다. 다음으로 찾는다.
3. 업그레이드 직후라면: 두 번째 세션부터 판단한다. 첫 세션은 feature flag가 내려오지 않았을 수 있다.
4. 세션 유형: /config에 Project instructions 항목 자체가 없으면 그 세션은 AGENTS.md를 로드할 수 없는 유형이다(Bedrock, 텔레메트리 비활성화 등). @AGENTS.md import로 우회한다.
5. 읽히지 않는 파일명: AGENTS.local.md, AGENTS.override.md, .agents/ 디렉터리 안의 파일은 Claude Code가 읽지 않는다. AGENTS.override.md는 Codex 전용 규칙이다.
6. /memory로 확인하지 말 것: 직접 로드된 AGENTS.md는 거기 표시되지 않는다. 대화 상단의 AGENTS.md loaded 줄이나 에이전트에 대한 지침 인용 질문으로 확인한다.

AGENTS.md에 무엇을 쓸 것인가

공식 문서의 기준은 “매번 다시 설명하게 되는 것”이다.

• 같은 실수를 두 번째 저질렀을 때
• 코드 리뷰에서 Claude가 알았어야 할 것이 걸렸을 때
• 지난 세션에 쳤던 교정을 또 치고 있을 때
• 새 팀원이 생산성을 내려면 같은 맥락이 필요할 때

빌드 명령, 컨벤션, 프로젝트 구조, “항상 X를 하라”류 규칙 같은 매 세션 필요한 사실만 담는다. 다단계 절차나 코드베이스 일부에서만 중요한 내용은 스킬이나 경로 스코프트 규칙으로 옮긴다. 지침은 구체적이고 간결할수록 일관되게 따른다.

FAQ

AGENTS.md와 CLAUDE.md를 둘 다 두면 어떻게 되나?

기본값에서는 CLAUDE.md만 읽히고 AGENTS.md는 무시된다. 둘 다 읽게 하려면 Project instructions를 claude-md-and-agents-md로 바꾼다.

Claude Code만 쓰는데 바꿔야 하나?

아니다. CLAUDE.md를 그대로 쓰면 된다. 바꿀 이유가 없다. 다른 도구를 같이 쓰게 되는 순간부터 AGENTS.md가 의미를 갖는다.

하위 폴더의 AGENTS.md도 읽나?

Claude가 그 폴더의 파일을 Read 도구로 열 때 읽는다. 단, 그 하위 폴더에 CLAUDE.md 계열 파일이 없을 때만이다. Cursor는 하위 폴더 작업 전반에 적용되고, Codex는 작업 디렉터리까지의 경로 전체를 미리 읽는다 — 도구마다 시점이 다르다.

Codex는 CLAUDE.md를 읽나?

아니요, 전혀 읽지 않는다. Codex와 Claude Code가 같은 규칙을 보게 하는 유일한 방법은 AGENTS.md 한 곳에 규칙을 두는 것이다.

/init을 돌리면 어떻게 되나?

Claude Code의 /init은 기본적으로 CLAUDE.md를 생성한다. CLAUDE_CODE_NEW_INIT=1을 켜면 기존 AGENTS.md를 CLAUDE.md에 합치고 이후 CLAUDE.md가 우선한다. AGENTS.md를 단일 소스로 유지하려면 /init을 건너뛰거나 생성된 파일을 삭제한다. Codex와 OpenCode의 /init은 AGENTS.md를 생성·갱신하므로 충돌하지 않는다.

마이그레이션 후 검증은 어떻게 하나?

Claude Code는 다음 세션에서 /context를 실행해 CLAUDE.md가 Memory files에 나타나는지 확인한다(import 방식의 경우). AGENTS.md 직접 로드는 대화 상단 줄로 확인한다. Codex는 codex --ask-for-approval never "Summarize the current instructions."를 저장소 루트에서 실행해 전역→프로젝트 순서로 인용되는지 확인한다.

참고자료

• Claude Code 공식 문서 — Memory (CLAUDE.md / AGENTS.md): https://code.claude.com/docs/en/memory
• Claude Code Changelog v2.1.277: https://code.claude.com/docs/en/changelog
• OpenAI Codex — Custom instructions with AGENTS.md: https://learn.chatgpt.com/docs/agent-configuration/agents-md
• Gemini CLI — Provide context with GEMINI.md files: https://raw.githubusercontent.com/google-gemini/gemini-cli/main/docs/cli/gemini-md.md
• Cursor Docs — Rules: https://cursor.com/docs/rules
• GitHub Docs — Repository custom instructions for Copilot: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
• OpenCode Docs — Rules: https://opencode.ai/docs/rules/
• AGENTS.md 공식 사이트: https://agents.md/
• 해커뉴스 토론 (2026-09-19, 739pts): https://news.ycombinator.com/item?id=49760187

The post CLAUDE.md와 AGENTS.md, 이제 하나로 쓴다 — 5개 도구 우선순위와 통합 마이그레이션 판정 appeared first on .