apps/web/AGENTS.md는 Vitest를 사용하고 생성된 API 클라이언트는 무시하도록 지시합니다. 레포지토리 루트에서 Codex를 시작하여 React 컴포넌트 수정을 요청하면, 그래도 src/generated/client.ts 파일을 편집합니다.
이 파일은 프롬프트에 도달한 적이 없습니다. Codex는 실행당 한 번, 프로젝트 루트부터 시작 디렉터리까지의 명령어 체인을 구축하며, 그 아래 폴더의 규칙 파일은 제외됩니다. 반면, Claude Code는 다른 방식으로 작동합니다: 해당 파일에 접근할 때 나중에 서브폴더의 CLAUDE.md를 로드합니다.
따라서 각 패키지에 사용할 규칙서를 제공하고, 두 에이전트가 모두 사용할 수 있도록 한 다음, 각각 무엇을 실제로 로드했는지 확인해 보세요.
1단계: 하나의 루트 파일, 패키지별 하나의 파일
React 프론트엔드와 Go 백엔드를 가진 모노레포를 가정해 봅시다:
acme/
AGENTS.md # 전체 레포에 대한 규칙서
CLAUDE.md # @AGENTS.md
...
AGENTS.md는 agents.md가 많은 도구, 그중 Codex를 위해 설명하는 공유 형식입니다. 여기에 실제 규칙이 담깁니다. 각 CLAUDE.md는 3단계에서 설명할 한 줄의 임포트(import)에 해당합니다. 루트 파일은 모든 곳에서 참인 것을 다룹니다:
Rulebook: root
- 커밋 제목은 패키지 이름으로 시작해야 합니다: `web: fix nav`.
...
프론트엔드 파일은 프론트엔드에만 해당되는 내용을 다룹니다:
Rulebook: web
- 테스트: `npx vitest run`. Jest는 절대 사용하지 마세요.
...
그리고 백엔드 파일은 백엔드에만 해당되는 내용을 다룹니다:
규칙서(Rulebook): api
- 테스트:
services/api에서 go test ./... 실행.
...
첫 줄의 Rulebook:은 여러분을 위한 것입니다. 이는 4단계에서 검색할 고유한 문자열을 제공합니다. 각 파일은 간결하게 유지하세요. Anthropic의 문서에 따르면 CLAUDE.md는 200줄 미만이 적절하며, Codex는 결합된 크기가 project_doc_max_bytes(기본값 32 KiB)에 도달하면 파일 추가를 중단합니다.
2단계: Codex가 파일을 선택하는 방법
Codex AGENTS.md 문서에 따르면, 다음 순서로 진행됩니다:
- 먼저,
~/.codex (또는 $CODEX_HOME)의 전역 파일: 존재하고 비어있지 않으면 AGENTS.override.md, 그렇지 않으면 AGENTS.md입니다.
- 다음으로 프로젝트 루트(일반적으로 git root)부터 현재 디렉터리까지 모든 디렉터리를 순차적으로 확인합니다. 각 디렉터리에서
AGENTS.override.md를 확인하고, 다음으로 AGENTS.md, 그리고 project_doc_fallback_filenames에 나열된 이름들을 확인하며, 디렉터리당 최대 하나의 파일만 가져옵니다.
- 파일들은 루트부터 순서대로 결합됩니다. 현재 디렉터리에 가까운 파일들이 프롬프트의 후반부에 오기 때문에, 규칙이 겹치는 부분에서는 해당 파일들이 우선권을 가집니다.
따라서 Codex를 시작하는 위치에 따라 어떤 패키지 규칙을 받게 되는지가 결정됩니다. 프론트엔드 작업을 할 경우, 다음과 같이 프론트엔드에서 시작하세요:
이 체인은 루트 AGENTS.md가 먼저 오고, 그 다음 apps/web/AGENTS.md가 옵니다. 백엔드 파일은 절대 읽히지 않습니다. 루트에서 시작하면 전역 및 루트 파일만 얻게 됩니다. 이 체인은 실행당 한 번 구축되므로, AGENTS.md를 편집해도 현재 세션이 아닌 다음 세션의 Codex에 반영됩니다.
AGENTS.override.md는 같은 폴더의 AGENTS.md를 추가하는 대신 대체합니다. 백엔드의 릴리스 동결(release freeze)과 같이 임시적인 변경에 사용하고, 여전히 필요한 기본 규칙은 복사해 두세요. 왜냐하면 오버라이드가 존재하는 동안에는 일반 파일이 무시되기 때문입니다. 오버라이드를 삭제하면 일반 파일이 다시 작동합니다.
3단계: Claude Code가 파일을 선택하는 방법
Claude Code의 메모리 문서(Claude Code's memory docs)는 두 가지 순간을 설명합니다:
- 시작 시, 작업 디렉토리와 그 위의 모든 디렉토리에서
CLAUDE.md와 CLAUDE.local.md를 로드합니다.
- 나중에는 Claude가 해당 서브디렉토리의 파일을 읽거나, 쓰거나, 편집할 때만 서브디렉토리의
CLAUDE.md를 로드합니다.
Codex와 달리, 여기서 루트에서 시작해도 괜찮습니다. 프론트엔드 규칙은 Claude가 프론트엔드 파일을 열 때 도착하기 때문입니다. apps/web에서 Claude를 시작하면, 루트 파일과 프론트엔드 파일 모두 시작 시 로드되며, 이는 Anthropic의 모노레포 가이드가 작업이 하나의 패키지 내에 머무를 경우 권장하는 방식입니다.
Claude Code는 v2.1.277부터 AGENTS.md도 읽을 수 있습니다. 기본적으로 이는 작업 디렉토리 또는 그 위의 위치에 CLAUDE.md, .claude/CLAUDE.md, 또는 CLAUDE.local.md가 없을 때만 수행됩니다. 해당 경로 어디든 CLAUDE.md 하나만 추가하면, Claude는 사용자의 AGENTS.md 대신 CLAUDE.md 파일을 읽게 됩니다.
이것이 바로 위의 모든 폴더에 한 줄을 담은 CLAUDE.md가 있는 이유입니다:
@ 임포트는 자신이 위치한 파일 기준으로 상대 경로를 해석하므로, apps/web/CLAUDE.md는 apps/web/AGENTS.md를 가져옵니다. 문서에 따르면 이 임포트는 /config의 Project instructions 설정이 무엇이든 간에 Claude가 파일을 두 번 읽게 만들지 않습니다. 또한 AGENTS.md를 직접 읽을 수 없는 세션에서도 계속 작동합니다.
이제 마커를 찾으세요. Codex의 경우, codex debug prompt-input은 모델이 실제로 보는 정확한 프롬프트 입력을 JSON 형식으로 렌더링하며, 명령어 참조는 지침 발견 디버깅을 위해 이를 제안합니다. 관심 있는 폴더에서 실행하여 마커를 검색하세요. 플래그는 버전별로 다를 수 있으므로 먼저 --help를 확인하세요:
cd apps/web
codex debug prompt-input | grep -o 'Rulebook: [a-z]*'
원하는 것은 Rulebook: root와 Rulebook: web이 순서대로 나타나고, api는 없는 것입니다. Codex 문서는 프롬프트를 읽는 대신 모델에게 질문하는 빠른 확인 방법도 제공합니다:
codex --cd apps/web --ask-for-approval never \
"List the instruction sources you loaded."
Claude Code의 경우, 세션에서 /context를 실행하고 Memory files 아래 목록을 읽으세요. 이 목록은 시작 시 로드된 내용을 보여줍니다. 서브폴더 CLAUDE.md는 아직 여기에 없습니다. 왜냐하면 필요할 때(on demand) 로드되기 때문입니다. 실제로 로드되면 터미널에 경로와 함께 Loaded 줄이 나타납니다. 문서는 테스트를 제안합니다: Claude에게 작성하도록 요청하는 대신 자체 셸에서 파일을 생성한 다음, Claude에게 해당 폴더의 파일을 읽도록 요청하세요.
기록으로 보관할 수 있도록 InstructionsLoaded 훅을 추가하세요. 이 훅은 CLAUDE.md 또는 규칙 파일이 컨텍스트에 진입할 때마다 발동되며, stdin에서 JSON 형식으로 세부 정보를 받습니다. 이 스크립트는 jq를 사용하여 로드될 때마다 한 줄을 추가합니다:
#!/bin/sh
# .claude/hooks/loads.sh (chmod +x it)
jq -c '{load_reason, file_path,
...
이를 리포지토리 루트의 .claude/settings.json에 등록하세요:
{
"hooks": {
"InstructionsLoaded": [{...
이 테스트를 위해 레포지토리 루트에서 Claude를 시작하고, apps/web의 파일을 읽게 한 다음, .gitignore에 loads.log를 추가하도록 요청합니다. 훅스(hooks) 참조에 따르면, 로드 시점에 로드된 파일은 load_reason이 session_start이며, 온디맨드로 로드되는 하위 폴더인 CLAUDE.md는 nested_traversal입니다. 이때 trigger_file_path가 Claude가 건드린 파일을 명명합니다. @ 임포트(import)로 가져온 파일은 include로 표시되며, parent_file_path가 이를 임포트한 파일을 명명합니다. 프론트엔드 파일을 읽는 경우, apps/web/CLAUDE.md를 nested_traversal로, 그리고 apps/web/AGENTS.md를 include로 기록해야 합니다. 이 훅은 Claude가 설정(setting)을 통해 직접 읽는 AGENTS.md에 대해서는 작동하지 않으므로, 임포트 기능을 사용하는 것이 또 하나의 이유입니다.
Step 5: Hermes IDE에서의 동일한 규칙서
저는 Hermes IDE를 구축했으니 이 섹션을 염두에 두고 읽어주세요. 이것은 macOS, Windows 및 Linux용 무료의 소스 공개(BSL 1.1) 데스크톱 앱이며, Nous Research, Anthropic 또는 OpenAI와는 제휴하지 않습니다. 이 IDE는 Claude Code, Codex 및 기타 에이전트들을 나란히 실행하며, 각각 실제 터미널에서 자체 인터페이스를 가집니다. 따라서 위의 로딩 규칙은 여전히 적용됩니다. Hermes는 또한 에이전트가 프로젝트 스캔을 통해 찾은 내용으로 구성된 컨텍스트 파일(context file)을 에이전트에게 지정할 수 있습니다. 그러면 해당 파일이 규칙서 옆에 에이전트의 컨텍스트 안에 놓이게 됩니다.
새 프로젝트의 경우, ⌘N 작업 실행기에서 **New folder…**를 사용하면 폴더가 생성되고, 체크박스를 선택했다면 Git 레포지토리, .gitignore, README 및 에이전트 지침을 위한 AGENTS.md와 함께 시작됩니다. 그러면 에이전트는 그 폴더에서 시작합니다.
기존 레포의 경우, ⌘N (Windows 및 Linux에서는 Ctrl+Shift+N)은 각 작업을 자체 hermes/ 브랜치와 워크트리(worktree)에서 시작합니다. 워크트리는 Git이 추적하는 파일을 담고 있으므로, 커밋된 AGENTS.md와 CLAUDE.md 파일은 모든 브랜치에 존재합니다. Git이 무시하는 파일은 그렇지 않습니다. 만약 개인적인 CLAUDE.local.md나 무시되는 AGENTS.override.md를 유지한다면, 그것은 메인 체크아웃(main checkout)에 남아 있고 워크트리의 에이전트는 결코 그것을 보지 못합니다.
Hermes의 worktree recipe에 있는 copy 키는 지정된 무시 파일(ignored files)들을 각 새로운 worktree로 복사합니다. 이 키는 git이 무시하는 파일만 허용합니다:
# .hermes/worktree.toml
copy = ["CLAUDE.local.md", "apps/*/CLAUDE.local.md"]
A Claude Code session in Hermes IDE after pressing the Context chip, showing Claude Code's /context breakdown, sidebar context gauges and the status strip
Context 칩을 누른 후의 Claude Code 세션: Claude Code의 /context 분석 (1M 토큰 중 44.4k, 4%), 사이드바의 세션별 context 게이지, 그리고 토큰 총량과 예상 비용이 표시되는 상태 스트립.
Claude Code 세션 위의 바에 있는 Context 칩은 Claude Code 자체의 /context 분석을 보여주며, Memory 파일이 위치하는 곳과 동일합니다. 명령어를 입력할 필요 없이 단계 4 확인(step 4 check)을 실행할 수 있습니다.
규칙 파일은 잠금장치가 아니다
두 지침 파일 모두 가이드라인입니다. Claude Code의 문서에 명확하게 나와 있듯이, 이는 CLAUDE.md를 강제되는 설정이 아닌 context로 취급하며, Claude가 어떤 결정을 내리든 특정 행동을 차단하려면 PreToolUse hook을 사용해야 합니다. 권한 거부 규칙(permission deny rule)도 Claude의 파일 편집에 대해 같은 역할을 수행합니다.
따라서
이 규칙은 Claude의 내장 파일 도구를 다룹니다. 예를 들어 npm run codegen과 같은 스크립트를 Claude가 실행하면 파일을 직접 열고 여전히 거기에 쓸 수 있습니다. 이것이 여기서 원하는 바입니다. 상대 경로 패턴은 Claude를 시작한 디렉토리에 고정되므로, 이 규칙은 그 지점 아래의 모든 generated/ 폴더를 다룹니다. 프로젝트 설정은 CLAUDE.md 파일처럼 상위 폴더에서 상속되지 않습니다 따라서 apps/web에서 시작된 세션은 이 규칙이 아닌 apps/web/.claude/settings.json을 읽습니다. 해당 폴더에 자체 사본을 제공하세요. Codex 측에서는 /status가 세션의 승인 정책과 쓰기 가능한 루트를 보여주며, 이곳에 그 한계가 존재합니다.
규칙서를 추가하거나, 이동시키거나, 에이전트를 업그레이드할 때마다 4단계 확인을 반복하세요. 규칙 로딩은 버전별로 변경되며, 위의 문서는 이미 여러 버전 차단 시점을 나열하고 있습니다.
유용했다면
