- Claude Code는 실행된 폴더와 그 위의 모든 계층에 있는
CLAUDE.md 및 / CLAUDE.local.md 파일을 시작 시 로드합니다 (공식 문서 'How CLAUDE.md files load').
- Claude Code는
CLAUDE.md가 하나도 없을 때만, 실행 폴더와 상위 계층의 AGENTS.md를 읽습니다 (공식 문서 'When Claude Code reads AGENTS.md', v2.1.277 이상).
- Codex는 프로젝트 루트(보통 Git의 루트)부터 시작 폴더까지 내려가면서
AGENTS.md를 읽습니다. 루트를 찾지 못하면 실행 폴더만 확인합니다 (공식 문서 'AGENTS.md' 가이드).
- 저는 실행하기 전에 어떤 지시 파일이 읽힐 수 있는지 목록화하는 작은 셸 스크립트를 만들고, 손쉽게 사용할 임시 환경에서 작동 여부를 확인해 보았습니다.
Downloads 폴더에서 AI 코딩 에이전트를 실행하면, 그곳에 놓인 AGENTS.md나 CLAUDE.md를 지시사항으로 읽어버린다는 점이 X(구 트위터)에서 화제가 되었습니다.
지시 파일은 '실행된 폴더의 것만'이라고 생각하기 쉽지만, 공식 문서를 읽어보면 툴에 따라 상위 계층까지 읽는 것을 알 수 있습니다. 그래서 어디까지 읽는지 공식 설명을 바탕으로 정리하고, 실행 전에 점검하는 방법을 모았습니다.
공식 문서(Memory의 'How CLAUDE.md files load')에는 다음과 같이 쓰여 있습니다.
Claude Code loads CLAUDE.md and CLAUDE.local.md from your current working directory and every directory above it.
~/Downloads/tool-x/src에서 실행하면, ~/Downloads/tool-x/src, ~/Downloads/tool-x, ~/Downloads, ~, / 등 각 계층에 있는 CLAUDE.md와 CLAUDE.local.md가 대상이 됩니다. 읽어온 내용은 덮어쓰기가 아니라 이어 붙여서 사용됩니다 (
사전 설정된 32 KiB에 도달하면 더 이상 추가하지 않습니다.
즉, 공식 설명대로라면 Git 루트보다 위쪽의 AGENTS.md는 Codex의 대상에서 제외됩니다. 반면, Git으로 관리되지 않은 폴더에서 실행할 경우, 해당 실행 폴더의 AGENTS.md만 읽습니다.
필자의 보충 설명 (추측 포함): Claude Code와 Codex가 파일을 읽는 범위가 다르기 때문에, 'Codex에서는 괜찮았던 폴더'가 Claude Code에서도 괜찮다고 할 수는 없습니다. 두 가지를 모두 사용하는 분이라면, Claude Code의 범위(상위 계층 전체)에 맞춰 점검하는 것이 누락을 줄이는 데 도움이 될 것이라고 생각합니다.
이 스크립트는 실행 폴더부터 /까지 각 계층과 홈 설정 위치를 확인하여 지시 파일이 있으면 크기와 경로만 출력할 뿐입니다. 파일을 수정하거나 삭제하지는 않습니다.
#!/usr/bin/env bash
# 실행 폴더부터 / 까지의 각 계층 및 홈 설정 위치에 있는 지시 파일을 목록화합니다 (읽기 전용)
d=$PWD
...
임시 홈 디렉터리 (HOME=/tmp/demo-home)를 사용하여 다음 파일들을 배치하고 테스트했습니다.
~/Downloads/AGENTS.md와 ~/Downloads/CLAUDE.md (Downloads에 위치했다고 가정)
~/work/app/AGENTS.md (~/work/app은 git init이 되어 있음)
~/Downloads/tool-x/src (Git 관리 없음)에서 실행한 출력입니다.
2B /tmp/demo-home/Downloads/CLAUDE.md
16B /tmp/demo-home/Downloads/AGENTS.md
git root: 없음
두 계층 위의 Downloads에 있는 파일도 목록에 나타났습니다. 상위 공식 설명에 대입해 보면, 여기서 Claude Code를 실행하면 ~/Downloads/CLAUDE.md가 읽히는 대상이 됩니다 (CLAUDE.md가 있으므로 AGENTS.md는 읽히지 않습니다). Codex는 Git 루트가 없기 때문에 실행 폴더만 보고, Downloads의 AGENTS.md는 대상에서 제외됩니다. 둘 다 공식 설명에 대입한 것이며, 실제 도구 실행은 이번에는 시도하지 않았습니다.
~/work/app에서 실행한 출력입니다.
6B /tmp/demo-home/work/app/AGENTS.md
git root: /tmp/demo-home/work/app
검증 환경: Linux 6.12, GNU bash 5.2.37, git 2.47.3.
- Claude Code: 세션 내에서
/context를 실행하여 Memory files 목록을 확인합니다 (공식 Memory). CLAUDE.md가 없고 AGENTS.md를 읽었을 때는, 'no CLAUDE.md found; AGENTS.md loaded: ...'와 같은 줄이 대화에 나타납니다 (동일 페이지).
- Codex: 공식 가이드 예시에서는
codex --ask-for-approval never "List the instruction sources you loaded."처럼 읽어 들인 지시의 출처를 Codex 자체에게 답변하게 합니다.
Claude Code에서는 settings의 claudeMdExcludes에 경로 또는 glob을 작성하면, 해당 CLAUDE.md를 읽기 대상에서 제외할 수 있습니다. 패턴은 절대 경로와 대조됩니다. 자신의 환경에만 적용하려면 .claude/settings.local.json에 작성합니다 (공식 Memory "Exclude specific CLAUDE.md files"). 다만 조직이 배포하는 관리형(managed) CLAUDE.md는 제외할 수 없습니다.
{
"claudeMdExcludes": [
"**/Downloads/CLAUDE.md"
...
}
필자의 보충 설명 (추측 포함): 가장 확실한 방법은 Downloads처럼 타인의 파일이 들어가기 쉬운 곳에서 실행하지 않는 것이라고 생각합니다. 제외 설정은 실행 위치를 바꿀 수 없을 때의 보조 수단으로 사용하는 것이 좋을 것 같습니다.
- Claude Code는 실행 폴더와 상위 모든 계층의
CLAUDE.md
/CLAUDE.local.md를 읽는다.
AGENTS.md는 CLAUDE.md가 없을 때만 (공식).
- Codex는 Git의 루트부터 시작 폴더까지의
AGENTS.md를 읽고, 루트가 없으면 시작 폴더만 (공식).
- 시작 전에
agent-instr-check.sh로 목록화하고, 시작 후에는 /context (Claude Code)에서 확인한다.
※ 사양은 2026-10-28 시점의 공식 문서에 근거합니다. 스크립트는 Linux 임시 환경에서만 테스트했습니다.
업데이트 정보나 간단한 팁은 X (@supportapp3_lab)에서 발신하고 있습니다.
