핵심 정리

탐색 순서의 큰 흐름
1. ~/.codex/AGENTS.override.md 또는 ~/.codex/AGENTS.md
2. 저장소 루트의 AGENTS.override.md 또는 AGENTS.md
3. 현재 작업 디렉터리까지 내려오며 더 가까운 AGENTS 파일

원칙
- 더 가까운 디렉터리 지침이 더 강합니다.
- 여러 파일은 root -> leaf 순서로 합쳐집니다.

읽는 순서

더 가까운 디렉터리 지침이 더 강한 이유는 범위 특정성 때문이다

Codex는 전역 지침과 저장소 지침을 모두 읽고, 현재 작업 위치에 가까운 파일일수록 더 구체적인 규칙으로 취급합니다. 이 원칙은 "범위가 좁을수록 더 정확한 정보를 담는다"는 가정에서 나옵니다. ~/.codex/AGENTS.md는 개인의 모든 저장소에 공통 적용되는 말투나 기본 선호를 담기 좋고, 특정 패키지 안의 AGENTS.md는 그 패키지에만 해당하는 빌드 규칙이나 제약을 담기 좋습니다.

root에서 leaf로 병합되는 구조가 충돌을 결정한다

여러 AGENTS 파일이 있으면 루트에서 현재 작업 디렉터리 방향으로 순서대로 병합되며, 더 가까운 지침이 앞선 지침을 덮어씁니다. 각 디렉터리에서는 AGENTS.override.md가 있으면 먼저 읽고, 없으면 AGENTS.md를 읽습니다. 이 병합 방식 때문에 루트 파일에 모든 규칙을 몰아넣으면 특정 하위 패키지에만 필요한 지침이 전체 작업에 적용되는 문제가 생깁니다.

# 현재 활성 지침 확인 방법
codex --ask-for-approval never "Summarize the current instructions."
codex --cd packages/api --ask-for-approval never "Show which instruction files are active."

override 파일은 언제 필요하고 언제 과잉인가

AGENTS.override.md는 같은 위치의 AGENTS.md를 완전히 대체합니다. 팀 전체에 적용된 루트 지침 중 특정 디렉터리에서만 다르게 동작해야 하는 규칙이 있을 때 유용합니다. 하지만 단순히 일부 항목을 추가하고 싶을 때는 override 대신 하위 디렉터리에 새 AGENTS.md를 두는 편이 낫습니다. override는 "앞선 지침을 전부 무시하고 새로 시작"이기 때문에 의도치 않은 규칙 누락이 생길 수 있습니다.

읽기 상한과 비어 있는 파일의 처리 방식

비어 있는 파일은 건너뛰고, 전체 읽기 크기에도 기본 상한이 있으므로 여러 레벨에 걸쳐 장황한 문서를 누적하면 실질적으로 읽히는 지침이 줄어듭니다. 하위 패키지에만 적용되는 규칙은 그 패키지 가까이에 두고, 전역 커뮤니케이션 스타일 같은 내용은 ~/.codex에 두는 편이 자연스럽습니다. 각 파일은 짧고 범위 내 규칙만 담아야 병합 후에도 의도대로 작동합니다.

AGENTS.md와 override를 고르는 기준
- 공통 규칙을 이어받으면서 하위 규칙만 추가: 하위 디렉터리 AGENTS.md
- 같은 위치 규칙을 완전히 갈아엎어야 함: AGENTS.override.md
- 개인 기본 말투와 습관: ~/.codex/AGENTS.md
- 저장소 공통 규칙: repo-root/AGENTS.md

우선순위

주의할 점

실패 예시
- packages/api 에서 테스트 명령만 바꾸고 싶어서 같은 위치에 AGENTS.override.md 를 둠
- 결과: 상위 파일의 커밋 규칙과 검증 원칙까지 전부 사라져 의도치 않게 안전장치가 빠짐
- 대응: 상위 규칙을 유지하면서 추가만 필요하면 override 대신 하위 AGENTS.md 를 쓴다