지침 로딩: 두 도구가 AGENTS.md를 읽는 조건

내용 검토: 2026. 09. 23.

결론부터

CLAUDE.md 없이 AGENTS.md 하나만 두고, 파일이 있다는 것과 실제로 읽혔다는 것을 구분해 확인한다

이 페이지는 두 도구가 AGENTS.md를 언제 어디까지 읽는가, CLAUDE.md는 언제만 필요한가에 답한다. AGENTS.md에 무엇을 적을지는 AGENTS.md 작성법에서 정했다.

이 장에서 처음 나오는 말2개

작업 디렉터리Current Working Directory: 에이전트를 시작한 위치. 어느 지침 파일이 자동으로 발견되는지가 여기에 달려 있다.
Project instructions: Claude Code /config의 설정 항목. CLAUDE.md와 AGENTS.md 중 무엇을 읽을지 고른다. 기본값은 CLAUDE.md가 없을 때만 AGENTS.md를 읽는 claude-md-or-agents-md다.

CLAUDE.md 없이 AGENTS.md만 둔다

같은 규칙을 AGENTS.md와 CLAUDE.md에 따로 적으면 한쪽만 고치는 날이 온다. 그 뒤로는 어느 도구로 시작했느냐에 따라 다른 검사를 돌린다. 예전에는 Claude Code가 AGENTS.md를 읽지 않아 CLAUDE.md에 @AGENTS.md 한 줄을 두는 어댑터가 필요했다.

Claude Code v2.1.277(2026-09-18)부터는 작업 디렉터리와 그 상위에 CLAUDE.md가 없으면 AGENTS.md를 직접 읽는다(changelog). 그래서 기본 구성은 레포 루트의 AGENTS.md 하나다. 기본 설정에서 Claude Code가 읽는 파일은 다음과 같다(공식 표).

레포 구성	Claude Code가 읽는 것
AGENTS.md만 있고 작업 디렉터리와 상위에 CLAUDE.md·CLAUDE.local.md가 없음	AGENTS.md
AGENTS.md와 CLAUDE.md(또는 CLAUDE.local.md)가 함께 있음	CLAUDE.md만. AGENTS.md는 무시
CLAUDE.md가 `@AGENTS.md`를 import함	CLAUDE.md. AGENTS.md는 import로 포함

Claude Code는 AGENTS.local.md·AGENTS.override.md·.agents/ 아래 파일은 읽지 않는다. Codex 전용 AGENTS.override.md를 공유 정본처럼 쓰면 Claude Code는 그 내용을 모른다. 공유 규칙은 일반 AGENTS.md에만 둔다.

두 도구는 어디까지 자동으로 읽는가

2026-09-23에 공식 문서로 확인한 차이다.

항목	Codex	Claude Code
시작 때 읽는 파일	프로젝트 루트부터 작업 디렉터리까지의 `AGENTS.md`	작업 디렉터리와 그 상위의 `AGENTS.md`·`.claude/AGENTS.md`
작업 디렉터리 아래의 지침	시작 때 읽지 않음	그 폴더의 파일을 읽을 때 로드. 그 폴더에 CLAUDE.md가 있으면 그것만
여러 파일의 결합	루트부터 이어 붙이고, 가까운 파일이 뒤에 와서 우선	발견한 파일을 모두 결합. 상충 규칙은 임의로 하나를 고를 수 있음
크기 제한	합쳐서 기본 32 KiB	파일당 200줄 아래 권장

Codex는 폴더마다 AGENTS.override.md → AGENTS.md 순서로 하나만 고른다 (Codex AGENTS.md 문서). Claude Code의 탐색 순서는 AGENTS.md 로딩 문서에 있다.

두 도구 모두 작업 디렉터리 아래의 지침은 시작 때 읽지 않는다. 루트에서 시작해 apps/web을 고친다면 apps/web/AGENTS.md는 자동으로 들어온 것이 아니다. 그래서 AGENTS.md에 “수정 대상 경로에 아직 읽지 않은 하위 AGENTS.md가 있으면 수정 전에 읽는다”는 규칙을 둔다.

직접 읽기가 안 되는 세션에만 CLAUDE.md 어댑터를 둔다

다음 세션에서는 Claude Code가 AGENTS.md를 직접 읽지 않고, /config에 Project instructions 항목도 나타나지 않는다(지원되지 않는 경우).

v2.1.277 이전 버전, 또는 설치·업그레이드 직후 첫 세션
Amazon Bedrock·Vertex AI·Foundry 같은 제3자 제공자, telemetry를 끈 세션
disableAllHooks·allowManagedHooksOnly를 켰거나 내장 agents-md plugin을 끈 설정

팀에 이런 세션이 있으면 AGENTS.md 옆에 CLAUDE.md를 두고 import 한 줄만 적는다. 직접 읽기가 되는 세션에서도 같은 AGENTS.md를 두 번 읽지는 않는다.

@AGENTS.md

Claude Code 전용 지시가 정말 필요하면 이 줄 아래에 적는다. 그 경우에도 검사 명령이나 제약처럼 두 도구에 공통인 내용은 AGENTS.md에 남긴다. 어댑터가 필요한 세션이 없어지면 CLAUDE.md를 지운다. AGENTS.md를 출력하던 SessionStart hook도 함께 지운다. 직접 읽기와 겹쳐 같은 내용이 두 번 들어간다(옛 우회 방법 정리).

import는 복사가 아니다

@AGENTS.md는 CLAUDE.md 기준 상대 경로이고, 매 세션 원본을 다시 읽어 CLAUDE.md와 함께 컨텍스트에 넣는다. 파일이 한 줄이라고 컨텍스트가 줄지는 않는다 (import 문법).

한 번 복사해 만든 CLAUDE.md는 이후 AGENTS.md 변경을 따라오지 않는다. “AGENTS.md를 읽어라”라고 글로 적은 CLAUDE.md도 Claude가 그 파일을 열기로 결정해야만 읽히므로 import와 다르다. 이런 CLAUDE.md는 지우거나 @AGENTS.md 한 줄로 바꾼다.

실제로 읽혔는지 확인한다

파일이 있다는 것, 자동으로 발견됐다는 것, 실제로 따른다는 것은 각각 다른 관찰이다.

도구	확인 방법
Claude Code, AGENTS.md 직접 읽기	세션 시작 때 `agents-md: no CLAUDE.md found; AGENTS.md loaded: <경로>` 줄을 본다. `/context`·`/memory` 목록에는 안 나온다
Claude Code, CLAUDE.md 어댑터	`/context`의 Memory files 목록에 `CLAUDE.md`가 있는지 본다
Codex	활성 지침의 출처와 적용 규칙을 요약하도록 요청하고 파일 내용과 대조한다

AGENTS.md가 안 읽힌 것 같으면 작업 디렉터리와 상위 폴더의 CLAUDE.md·CLAUDE.local.md부터 찾는다. 그다음 위의 지원되지 않는 세션인지, Project instructions가 claude-md로 바뀌어 있지 않은지 본다 (문제 해결).

하위 지침이나 필수 문서가 빠진 것 같을 때 쓰는 진단 요청이다.

이번 수정에 적용한 지침의 출처를 알려 줘.
세션 시작 때 자동으로 들어온 지침과 작업 중 직접 읽은 문서를 구분해 줘.
수정 대상 경로의 하위 AGENTS.md나 필수 참조 문서를 아직 읽지 않았다면 지금 읽고,
빠져 있던 규칙이 있는지 알려 줘.

읽은 파일 경로와 적용 규칙이 나오면 정상이다. 없는 파일을 읽었다고 하거나 관계없는 문서를 필수로 읽었다면 AGENTS.md의 읽기 조건부터 손본다.

이해 확인

루트에서 Codex를 시작해 apps/web을 고친다. 그 폴더에 AGENTS.md가 있으면 자동 적용됐다고 말할 수 있을까? 없다. 시작 때 읽는 범위는 루트부터 작업 디렉터리까지다. 그 파일을 직접 읽게 하거나 apps/web에서 시작한다.

레포에는 AGENTS.md만 있는데 Claude Code가 그 내용을 모른다. 어디부터 볼까? 레포 상위 폴더에 남은 CLAUDE.md나 개인용 CLAUDE.local.md다. 하나라도 있으면 그것만 읽고 AGENTS.md는 무시한다. 없으면 버전이 v2.1.277 이전이거나 직접 읽기가 안 되는 세션이므로 어댑터를 둔다.

CLAUDE.md에 검사 명령을 적어 두었다. 문제일까? 그 순간 AGENTS.md는 읽히지 않으므로 Codex와 다른 지침으로 일하게 된다. 명령은 AGENTS.md로 옮기고 CLAUDE.md는 지운다. 어댑터가 필요한 세션이 있다면 @AGENTS.md 한 줄만 남긴다.

스펙 문서무엇을 왜 만들고 완료를 어떻게 판정하는지를 기능 단위로 한 곳에 둔다.