Quick Flow

1. $CODEX_HOME의 AGENTS.override.md 또는 AGENTS.md를 읽는다.
2. project root에서 현재 working directory까지 내려간다.
3. 각 directory에서 override -> AGENTS.md -> configured fallback 순으로 하나만 고른다.
4. root -> current directory 순으로 합친다.

같은 directory의 AGENTS.override.md는 AGENTS.md만 대체한다.
상위와 하위 directory의 지침은 계속 합쳐진다.

더 가까운 directory의 지침이 합쳐진 prompt 뒤쪽에 오므로, 같은 주제에서는 더 구체적인 범위의 규칙이 우선한다. 이 규칙은 현재 working directory를 기준으로 하므로, Codex를 어느 directory에서 시작했는지도 결과에 영향을 준다.

지침 chain을 설계하는 방법

전역 지침은 ~/.codex 또는 CODEX_HOME에 둔다. repository를 찾으면 Codex는 보통 Git root부터 current directory까지 내려가며 각 directory에서 한 파일만 읽는다. project root를 찾지 못하면 current directory만 확인한다. 빈 파일은 건너뛴다.

~/.codex/AGENTS.md                 -> 개인의 공통 작업 약속
repository/AGENTS.md               -> 저장소 전체의 build·검증·제약
repository/services/payments/AGENTS.md -> payment 경로의 특수 규칙

공통 규칙을 이어받으면서 package 규칙을 더하고 싶으면 하위 AGENTS.md를 쓴다. 같은 directory의 AGENTS.override.md는 그 directory의 AGENTS.md를 대신하지만, global 파일과 상위 repository 파일까지 없애지는 않는다. 일시적인 global override는 ~/.codex/AGENTS.override.md에 두고 끝나면 제거한다.

# 현재 directory에서 적용된 지침을 확인한다.
codex --ask-for-approval never "Summarize the current instructions."

# 하위 directory 기준 chain을 확인한다.
codex --cd services/payments --ask-for-approval never "Show which instruction files are active."

fallback과 크기 제한

각 run은 시작할 때 instruction chain을 다시 만든다. 기본 결합 한도는 project_doc_max_bytes의 32 KiB이며, 그 뒤 파일은 더하지 않는다. 지침이 누락된 것처럼 보이면 cache를 지우려 하기보다 현재 working directory, 비어 있는 파일, 상위 override, 결합 크기를 먼저 확인한다.

기존 repository가 TEAM_GUIDE.md처럼 다른 파일명을 이미 쓴다면 project_doc_fallback_filenames에 등록할 수 있다. fallback은 AGENTS.override.md, AGENTS.md가 없을 때만 같은 directory에서 후보가 된다.

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