Codex가 AGENTS.md 규칙을 조용히 건너뛰지 않도록 하는 방법 (2026)

디렉터리당 하나의 파일, 그리고 항상 우선하는 오버라이드

Codex는 시작할 때 문서화된 우선순위에 따라 지침 체인을 빌드합니다. 글로벌 수준의 Codex 홈 디렉터리(CODEX_HOME을 설정하지 않은 경우 기본값은 ~/.codex)에서 Codex는 "AGENTS.override.md가 존재하면 이를 읽습니다. 그렇지 않으면 AGENTS.md를 읽습니다. Codex는 이 수준에서 비어 있지 않은 첫 번째 파일만 사용합니다."

그 다음은 프로젝트 범위입니다. 프로젝트 루트에서 시작하여 작업 디렉터리까지 내려가면서 "경로상의 각 디렉터리에서 AGENTS.override.md, AGENTS.md, 그리고 project_doc_fallback_filenames에 지정된 대체 이름을 확인합니다. Codex는 디렉터리당 최대 하나의 파일만 포함합니다."

이 마지막 문장이 문제의 핵심입니다. AGENTS.override.md는 옆에 있는 AGENTS.md와 병합되지 않고 이를 대체합니다. 문서에서는 이를 임시 용도로 설명합니다: "기본 파일을 삭제하지 않고 임시 글로벌 오버라이드가 필요할 때 ~/.codex/AGENTS.override.md를 사용하세요. 공유 안내를 복원하려면 오버라이드를 제거하세요." 하지만 임시 파일은 영구적으로 남는 경향이 있으며, 6개월이 지나면 장애 대응 중에 누군가 커밋한 파일 때문에 리포지토리의 실제 규칙이 억제되고 있다는 사실을 아무도 기억하지 못하게 됩니다.

실행한 위치에서 검색이 중단되므로, 더 깊은 곳에 있는 것은 보이지 않습니다

"프로젝트 루트(일반적으로 Git 루트)에서 시작하여 Codex는 현재 작업 디렉터리까지 내려갑니다." 그리고 "Codex는 현재 디렉터리에 도달하면 검색을 중단하므로, 오버라이드를 전문 작업과 최대한 가까운 곳에 배치하세요."

이를 조언이 아닌 제약 조건으로 이해해야 합니다. 리포지토리 루트에서 Codex를 실행하면, services/payments/ 내부에 정성껏 작성된 AGENTS.md는 체인에 포함되지 않습니다. 여러분은 그 위에 있지 아래에 있는 것이 아니기 때문입니다. 형제 디렉터리도 체인에 절대 포함되지 않습니다. 로드되는 파일 세트는 단일 수직 경로이며, 어떤 경로가 될지는 시작할 때 어느 위치에 있었는지에 따라 전적으로 달라집니다.

이와 관련된 공백도 있습니다: "Codex가 프로젝트 루트를 찾을 수 없는 경우, 현재 디렉터리만 확인합니다."

체인 크기 제한이 있으며, 두 공식 페이지에서 이 제한을 다르게 설명합니다

"Codex는 빈 파일을 건너뛰고, 결합된 크기가 project_doc_max_bytes(기본값 32 KiB)로 정의된 제한에 도달하면 파일 추가를 중단합니다." 이어지는 조언은 구체적입니다: "제한에 도달하면 한도를 늘리거나 중첩된 디렉터리에 지침을 분할하세요."

모르는 척 넘어가기보다는 불일치하는 부분을 짚고 넘어갈 가치가 있습니다. 고급 설정 페이지에서는 동일한 설정을 "각 AGENTS.md 파일에서 읽을 양"으로 설명하는 반면, AGENTS.md 페이지에서는 이를 결합된 크기의 중단점으로 설명합니다. 이 둘은 같은 규칙이 아닙니다. 32 KiB를 실제로 도달할 수 있는 한계로 취급하고, 두 설명 중 하나를 유추하기보다는 아래의 덤프 명령어로 결과를 확인하세요. 이것이 바로 "Instructions truncated" 문제 해결 항목이 존재하는 이유입니다.

어느 쪽이든 잘림 현상은 조용히 일어나며, 체인의 끝 부분, 즉 여러분이 가장 원했던 작업 디렉터리에 가장 가까운 파일들이 잘려 나갑니다.

목록에 없는 파일 이름은 존재하지 않는 것과 같습니다

Codex는 AGENTS.override.md, AGENTS.md, 그리고 project_doc_fallback_filenames에 나열한 모든 파일을 읽습니다. 다음과 같이 확장할 수 있습니다:

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

이 설정이 적용되면 "Codex는 각 디렉터리를 AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md 순서로 확인합니다." 그리고 중요한 문장이 나옵니다: "이 목록에 없는 파일 이름은 지침 검색에서 무시됩니다."

즉, CONTRIBUTING.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md 등은 기본적으로 Codex에 보이지 않습니다. 여러 에이전트가 사용되는 리포지토리에서 이는 가장 흔히 발생하는 문제입니다. 지침이 존재하고 훌륭하더라도, Codex가 애초에 열어보지 않을 파일에 들어 있는 것입니다. 도구 간 파일 표준 문제는 CLAUDE.md를 AGENTS.md로 마이그레이션하기에서 다룹니다.

체인은 한 번만 빌드되므로, 세션 중간에 편집해도 아무것도 바뀌지 않습니다

"Codex는 시작할 때(실행당 한 번, TUI에서는 보통 실행된 세션당 한 번) 지침 체인을 빌드합니다." 그리고 검증 가이드에 따르면: "지침이 오래된 것처럼 보이면 대상 디렉터리에서 Codex를 다시 시작하세요. Codex는 매 실행 시(그리고 각 TUI 세션 시작 시) 지침 체인을 다시 빌드하므로 수동으로 지울 캐시가 없습니다."

따라서 Codex가 규칙을 무시하는 것을 발견하고, 규칙을 더 강조해서 추가한 뒤 다시 질문하는 자연스러운 디버깅 방식은 동일한 세션 내에서 작동할 수 없습니다. 이미 읽은 파일을 편집하고 있기 때문입니다. 다시 시작하는 것이 해결책이며, 방법을 알고 나면 매우 간단합니다.

빈 파일, 그리고 설정한 것을 잊어버린 CODEX_HOME

문제 해결 목록에 있는 두 가지 간단한 내용입니다. "Codex는 빈 파일을 무시합니다" — 도구에 의해 생성되고 채워지지 않은 플레이스홀더 AGENTS.md도 여전히 해당 디렉터리의 단 하나의 슬롯을 차지합니다. 그리고 "프로필 혼동: Codex를 실행하기 전에 echo $CODEX_HOME을 실행하세요. 기본값이 아닌 값은 여러분이 편집한 디렉터리가 아닌 다른 홈 디렉터리를 가리킵니다." 래퍼 스크립트나 프로젝트별 자동화 프로필이 이를 설정한 경우, 글로벌 파일은 여러분이 생각하는 위치에 있지 않습니다.

더 강력한 어조로 규칙 다시 쓰기. 이해는 가지만, 파일이 로드되지 않았다면 아무 소용이 없습니다. 문구를 확인하기 전에 로드 여부부터 확인하세요.

모든 내용을 하나의 거대한 루트 AGENTS.md로 이동하기. 이는 디렉터리당 하나의 파일 규칙을 우회할 수는 있지만, 32 KiB 제한에 곧바로 걸리게 됩니다. 문서에서는 반대로 중첩된 디렉터리에 분할할 것을 권장합니다.

매 실행마다 프롬프트에 제약 조건을 반복하기. 작동은 하지만, 매번 동일한 비용이 영구적으로 발생합니다. 이는 AI에게 컨텍스트를 반복해서 설명하지 않는 방법에서 설명한 루프와 같습니다.

보이는 대로 오버라이드 파일 삭제하기. 때로는 맞을 수도 있지만, 의도된 규칙을 삭제해 버릴 수도 있습니다. 먼저 파일 내용을 확인하세요.

지침을 강제 사항으로 가정하기. 지침은 첫 번째 턴에 포함되는 안내일 뿐입니다. 매번 반드시 준수해야 하는 사항은 CI 검사를 통해 보장해야 합니다. 이에 대한 일반적인 내용은 에이전트가 여러분이 작성한 지침 파일을 무시하는 이유에서 다룹니다.

CLAUDE.md를 AGENTS.md에 심볼릭 링크로 연결하고 기도하기. project_doc_fallback_filenames에 파일 이름을 추가하는 것이 문서에 명시된 방법이며, 단 한 줄이면 충분합니다.

두 개의 명령어와 정리 작업입니다. 먼저 추측하는 것을 멈추세요.

리포지토리 루트에서 체인 덤프하기. 문서에 명시된 확인 방법:

codex --ask-for-approval never "Summarize the current instructions."

"Codex는 우선순위에 따라 글로벌 및 프로젝트 파일의 안내를 출력해야 합니다." 작성한 규칙이 요약에 없다면 문제는 준수가 아니라 검색(discovery)에 있는 것입니다. 이로써 프롬프트 엔지니어링으로 오후 시간을 낭비하는 일을 방지할 수 있습니다.

실제로 작업하는 디렉터리에서 다시 덤프하기. 체인은 시작하는 위치에 따라 달라지기 때문입니다:

codex --cd services/payments --ask-for-approval never "Show which instruction files are active."

문서에서는 예상 출력을 "글로벌 파일이 첫 번째, 리포지토리 루트 AGENTS.md가 두 번째, 그리고 payments 오버라이드가 마지막"으로 설명합니다. 로드되어야 한다고 생각하는 내용과 비교해 보세요. 그 차이가 바로 버그입니다.

줄글 형태가 아닌 기록을 원한다면 로그를 확인하세요. "Codex가 로드한 지침 파일을 감사하려면 codex -c log_dir=./.codex-log를 사용하여 일반 텍스트 TUI 로그를 활성화하고 ./.codex-log/codex-tui.log를 확인하거나, 세션 로깅을 활성화한 경우 가장 최근의 session-*.jsonl 파일을 검사하세요." 또한 워크스페이스를 확인하세요: "의도한 리포지토리에 있는지 확인하고, codex status가 예상하는 워크스페이스 루트를 보고하는지 확인하세요."

그 다음, 이 순서대로 정리합니다. 리포지토리와 ~/.codex에서 모든 AGENTS.override.md를 찾아 억제가 의도된 것인지 결정하고, 그렇지 않은 것은 병합 후 삭제합니다. 다른 에이전트의 지침 파일 이름을 project_doc_fallback_filenames에 추가하여 더 이상 보이지 않는 상태가 되지 않도록 합니다. 32 KiB에 가까운 파일은 제한을 늘리고 잊어버리기보다 중첩된 디렉터리로 분할합니다. 빈 지침 파일은 슬롯을 차지하지 않도록 삭제합니다. 그리고 echo $CODEX_HOME을 확인합니다.

이렇게 하면 지침이 로드됩니다. 하지만 해결할 수 없는 것은 체인이 의도적으로 제한되어 있다는 점입니다. 검색이 올바르게 작동하더라도, 작업하는 모든 디렉터리에서 32 KiB 예산을 나누어 써야 합니다. 그리고 가장 먼저 밀려나는 것은 항상 동일한 범주입니다: 제약 조건이 존재하는 이유, 이전에 시도했던 것, 거부된 접근 방식과 그 이유 등입니다. 규칙은 살아남지만, 추론(reasoning)은 살아남지 못합니다.

이것이 바로 MemoryLake가 보관하는 것입니다. 도구가 읽을 수 있는 레이어에 프로젝트의 지속 가능한 지식을 보관하므로, 지침 파일은 작게 유지되고 추론은 계속 사용할 수 있습니다. 설정은 3단계로 진행됩니다.

1단계: API 키 생성

MemoryLake에 로그인하고 API 키를 생성합니다. 연결하는 도구 전반에 걸쳐 하나의 자격 증명만 사용하면 됩니다.

2단계: 첫 번째 기억 업로드

각각 하나의 주장만 담긴 짧은 항목들입니다. 체인 내부가 아닌 외부에 속해야 하는 내용들입니다:

이유가 첨부된 제약 조건. "npm 스크립트가 샌드박스 스텁을 시작하지 않으므로 Payments는 make test-payments를 사용합니다." AGENTS.md 라인에는 명령어만 명시되어 있습니다. 이유가 있어야만 누군가 이를 불필요한 것으로 보고 삭제하는 것을 막을 수 있습니다.

이 코드베이스에서 이미 거부된 접근 방식. 지침 파일의 그 어디에도 어울리지 않지만, 매번 새로 실행할 때마다 제안되는 범주입니다.

아무도 알려주지 않는 환경적 사실. 문서화되지 않은 속도 제한, CI에서만 실패하는 테스트, 두 마이그레이션 간의 순서 요구 사항 등입니다.

장애 대응 과정에서의 결정 사항. 애초에 오버라이드가 존재했던 이유를 명시하여, 다음 사람이 이것이 의도적인 억제인지 아니면 남겨진 찌꺼기인지 구별할 수 있도록 합니다.

3단계: AI 및 에이전트 연결

사용하는 도구를 연결합니다. MemoryLake는 MCP 및 API를 통해 액세스할 수 있으므로, Claude Code, Codex, OpenClaw를 포함한 MCP 네이티브 에이전트는 MCP 서버를 가리켜 연결하고, 다른 어시스턴트는 API를 통해 동일한 기억을 읽습니다. 실제 효과는 검색하는 내용이 첫 번째 턴에 전송되지 않기 때문에 지침 예산에 포함되지 않는다는 점입니다.

세 가지 솔직한 한계가 있습니다. MemoryLake는 AGENTS.md 파일을 작성하지 않으며 Codex가 이를 검색하는 방식을 변경하지 않습니다. 위의 6가지 메커니즘은 Codex의 것이며, 해결책은 모두 여러분의 몫입니다. MemoryLake는 여러분이나 에이전트가 넣은 내용만 보관하므로 2단계는 수동으로 진행됩니다. 또한 지침은 강제된 설정이 아니라 안내일 뿐입니다. 메모리 레이어가 컴플라이언스를 변경하지는 않으며, 엄격한 요구 사항의 경우 여전히 CI가 정답입니다.

"내 규칙을 무시했다"는 불만이 명령어 한 줄로 확인하는 질문으로 바뀝니다. Codex에 현재 지침을 요약해 달라고 요청하세요. 규칙이 목록에 있거나 없을 것이며, 두 경우의 해결책은 완전히 다릅니다.

오버라이드 파일이 더 이상 지뢰가 되지 않습니다. 한 번 평탄화하고 나면, 나중에 다시 발견하게 될 가려진 파일이 존재하지 않습니다.

지침 파일이 더 작아집니다. 체인이 두 가지 역할을 수행하느라 32 KiB 제한에 가까워지고 있었습니다. 역할을 분리하면 제한이 더 이상 제약이 되지 않습니다.

다른 에이전트의 파일이 더 이상 쓸모없는 짐이 되지 않습니다. config.toml에 한 줄만 추가하면 팀이 이미 유지 관리하고 있는 CLAUDE.md나 TEAM_GUIDE.md가 반영되기 시작합니다.

다시 시작하는 것이 반사적인 행동이 됩니다. 체인은 실행당 한 번 빌드됩니다. 이를 알면 혼란스러운 세션을 5초 만에 해결할 수 있습니다.

무엇이든 편집하기 전에 체인을 덤프하세요. 루트와 작업 디렉터리에서 Codex에 현재 지침을 요약해 달라고 요청하세요.

AGENTS.override.md를 영구적으로 남겨두지 마세요. 이는 옆에 있는 파일을 억제하며, 문서에서도 이를 임시 파일로 규정하고 있습니다.

규칙을 적용하려는 디렉터리에서 실행하세요. 체인은 작업 디렉터리에서 멈추므로, 더 깊은 곳에 있는 파일은 절대 로드되지 않습니다.

제한에 가까워지면 한도를 늘리기만 하지 말고 분할하세요. 중첩된 디렉터리는 project_doc_max_bytes에 도달했을 때 문서에 명시된 해결책입니다.

다른 모든 에이전트의 지침 파일 이름을 project_doc_fallback_filenames에 나열하세요. 목록에 없는 파일 이름은 지침 검색에서 무시됩니다.

빈 지침 파일을 삭제하세요. 빈 파일은 건너뛰어지지만, 여전히 해당 디렉터리의 단일 슬롯을 차지합니다.

편집 후에는 다시 시작하세요. 지침 체인은 실행당 한 번 빌드되므로 세션 중간에 편집한 내용은 적용되지 않습니다.

글로벌 파일이 아무런 효과가 없는 것처럼 보일 때는 echo $CODEX_HOME을 확인하세요. 기본값이 아닌 값은 여러분이 편집한 디렉터리가 아닌 다른 홈 디렉터리를 가리킵니다.

추론(reasoning)은 체인에서 제외하세요. 지침은 제한되어 있고 항상 켜져 있습니다. 규칙 뒤에 숨겨진 논거는 에이전트가 여러분이 기록하지 않은 상황을 처리할 수 있도록 돕는 핵심 요소입니다. 이는 RAG가 메모리가 아닌 이유에서 다루는 일반적인 문제입니다.

Codex는 지침을 찾는 방식에 대해 이례적일 정도로 명확하게 설명하고 있으므로, 이는 미스터리한 문제가 아니라 해결 가능한 문제입니다. 디렉터리당 최대 하나의 파일만 읽으며, AGENTS.override.md가 AGENTS.md보다 우선합니다. 프로젝트 루트에서 작업 디렉터리까지 내려가며 거기서 멈춥니다. 루트부터 차례대로 병합하며, 결합된 크기가 기본값 32 KiB인 project_doc_max_bytes에 도달하면 추가를 중단합니다. 검색 목록에 없는 파일 이름은 무시하고, 빈 파일도 무시하며, 실행당 한 번 전체 체인을 빌드합니다.

이 6가지 메커니즘은 모두 조용히 작동하지만, Codex에 로드된 지침을 요약해 달라고 요청하면 약 10초 만에 모두 확인할 수 있습니다. 루트와 실제 작업하는 디렉터리에서 이를 수행하고, 임시로 사용하려 했던 오버라이드를 평탄화하고, 다른 에이전트의 파일 이름을 대체 목록에 추가하고, 제한에 가까워지면 크기를 키우기보다 분할하세요.

그런 다음 제약 조건, 장애 대응 기록, 거부된 접근 방식을 첫 번째 턴에 전송하는 레이어가 아닌 쿼리할 수 있는 레이어에 배치하세요. 이렇게 하면 지침 체인은 완전히 로드될 수 있을 만큼 작게 유지되면서도, 중요한 순간에 추론을 계속 활용할 수 있습니다.