Codex가 어떤 AGENTS.md를 읽었는지 확인하는 순서

프로젝트 AGENTS.md를 만들었다고 전역 파일이 자동으로 꺼지는 것은 공식 동작이 아니다. Codex는 새 실행을 시작할 때 전역 지침을 먼저 읽고, 프로젝트 루트에서 현재 작업 폴더까지의 지침을 차례로 합친다. 적용이 이상하면 각 후보에 비민감한 고유 표식을 넣고 대상 폴더에서 새 세션을 연다. 새 세션이 되돌려 주는 표식으로 어느 범위가 적용됐는지 확인한다.

codex --cd /실제/프로젝트/경로 --ask-for-approval never \
  "현재 지침에서 *_SCOPE_MARKER로 끝나는 표식을 적용 순서대로 그대로 출력해줘."

Codex CLI 0.154.0과 gpt-5.6-sol low를 사용한 비민감 임시 저장소 재현에서는 GLOBAL_SCOPE_MARKER → ROOT_SCOPE_MARKER → SUB_SCOPE_MARKER 순서로 출력됐다. 즉 이 환경에서는 공식 문서의 전역 파일 → 저장소 루트 파일 → 더 가까운 하위 폴더 파일 순서와 일치했다.

확인 순서는 다음 다섯 단계다.

1. 현재 작업 폴더와 Git 루트를 비교한다.
2. 프로젝트 루트에서 현재 폴더까지의 AGENTS.override.md와 AGENTS.md를 찾는다.
3. 현재 실행의 CODEX_HOME을 확인한다.
4. 지침 합산 크기 상한을 확인한다.
5. 대상 폴더에서 새 Codex 세션으로 활성 파일을 다시 묻는다.

1. 먼저 작업 폴더가 맞는지 확인

터미널을 열고 Codex를 시작하려는 폴더로 이동한다. Git 저장소라면 아래 두 명령으로 현재 폴더와 프로젝트 루트를 비교한다.

pwd
git rev-parse --show-toplevel

첫 줄에는 현재 폴더가, 둘째 줄에는 Git 루트의 절대 경로가 나온다. 둘째 명령이 fatal: not a git repository를 내면 현재 폴더 위에 Git 저장소가 없다. 이때는 pwd 결과를 Codex의 시작 폴더로 보고, Git 루트 기반 탐색을 기대하지 않는다. 저장소를 선택하려던 경우에는 cd /실제/저장소/경로로 이동한 뒤 두 명령을 다시 실행한다.

Codex는 보통 Git 루트를 프로젝트 루트로 삼고 그곳에서 현재 작업 폴더까지 내려오며 지침 파일을 찾는다. 프로젝트 루트를 찾지 못하면 현재 폴더만 확인한다. 하위 폴더의 규칙을 기대한다면 Codex의 현재 작업 폴더도 그 하위 폴더여야 한다.

2. AGENTS.override.md가 같은 폴더의 파일을 가리는지 확인

각 디렉터리에서 Codex가 선택하는 순서는 AGENTS.override.md, AGENTS.md, 설정한 대체 파일명이다. 같은 폴더에서 여러 파일을 모두 합치는 방식이 아니다. override가 있으면 같은 폴더의 일반 AGENTS.md는 선택되지 않는다.

python3 -c 'from pathlib import Path; import subprocess; cwd=Path.cwd().resolve(); root=Path(subprocess.check_output(["git","rev-parse","--show-toplevel"],text=True).strip()).resolve(); chain=[root]+list(reversed([p for p in cwd.parents if p != root and root in p.parents]))+[cwd]; [print(p) for d in chain for n in ("AGENTS.override.md","AGENTS.md") if (p:=d/n).is_file()]'

출력은 프로젝트 루트에서 현재 폴더까지 존재하는 후보 경로다. 명령이 Git 오류를 내면 1단계에서 확인한 현재 폴더가 저장소 안인지 먼저 고친다. 아무 경로도 나오지 않으면 그 경로에는 두 기본 파일명이 없다. 전역 파일은 이 명령 범위 밖이므로 CODEX_HOME을 따로 확인한다.

출력은 후보 위치를 찾는 데만 쓴다. 실제 활성 범위는 프로젝트 루트에서 현재 폴더까지의 경로에 있는 파일이다. 저장소 전체의 모든 하위 디렉터리 파일이 한 세션에 들어오는 것은 아니다.

같은 임시 저장소의 하위 폴더에 AGENTS.override.md를 추가한 두 번째 새 세션에서는 GLOBAL_SCOPE_MARKER → ROOT_SCOPE_MARKER → SUB_OVERRIDE_MARKER만 출력됐다. 같은 폴더의 SUB_SCOPE_MARKER는 출력되지 않았다. 이 결과는 이 버전과 재현 조건에서 override가 같은 폴더의 일반 파일을 대신 선택한다는 근거이며, 다른 버전의 모든 동작을 보장하지는 않는다.

3. 다른 CODEX_HOME을 쓰는지 확인

echo "$CODEX_HOME"

값이 비어 있으면 기본 Codex 홈은 ~/.codex다. 값이 있으면 Codex는 그 위치에서 전역 AGENTS.override.md 또는 AGENTS.md를 찾는다. 사용자가 편집한 ~/.codex/AGENTS.md와 실행이 보는 Codex 홈이 다르면 파일이 있어도 현재 세션에는 들어오지 않는다.

4. 지침이 길어 잘렸는지 확인

공식 문서는 프로젝트 지침 체인을 읽을 때 쓰는 project_doc_max_bytes의 기본값을 32 KiB로 설명한다. 이번 재현은 이 상한 전후를 시험하지 않았다. 따라서 일부 표식이 없을 때는 길이 때문이라고 단정하지 말고 작업 폴더·override·CODEX_HOME을 먼저 확인한다.

크기를 늘려야 한다면 ~/.codex/config.toml에서 값을 명시하고 새 세션을 시작한다.

project_doc_max_bytes = 65536

5. 새 세션에서 다시 확인

Codex는 실행을 시작할 때 지침 체인을 만든다. 실행 중 파일을 바꿨다면 기존 세션의 캐시를 지우는 명령을 찾기보다 대상 폴더에서 새 세션을 시작한다.

codex --cd /실제/프로젝트/경로 --ask-for-approval never \
  "현재 지침에서 *_SCOPE_MARKER로 끝나는 표식을 적용 순서대로 그대로 출력해줘."

예상 출력은 GLOBAL_SCOPE_MARKER 다음에 루트와 가까운 하위 폴더 표식이 이어지는 형태다. 모델이 경로만 말하거나 표식을 요약하면 그 응답을 발견 근거로 쓰지 않는다. 각 파일에 서로 다른 비민감 표식 한 줄을 넣은 뒤 새 세션에서 표식 그대로 출력을 다시 요청한다. 표식은 맞는데 행동이 어긋난다면 발견 문제와 지침 준수 문제를 구분한다. 이때는 실행한 Codex 버전, 작업 폴더, 확인된 표식, 지켜지지 않은 정확한 한 줄을 함께 남긴다.

관련 설정과 폴더 문제를 구분하기

Claude Code의 프로젝트 지침 파일을 함께 운영한다면 CLAUDE.md에 남길 규칙과 AGENTS.md의 역할을 먼저 나눈다. Codex가 잘못된 폴더를 프로젝트로 잡아 Git 기준점부터 읽지 못한다면 invalid reference: HEAD 확인 순서에서 저장소 루트와 첫 커밋 유무를 확인한다.

자주 묻는 질문

프로젝트 AGENTS.md가 있으면 전역 AGENTS.md는 무시되나?

아니다. 공식 로딩 순서는 전역 파일을 먼저 읽고 프로젝트 루트에서 현재 폴더까지 선택된 파일을 이어 붙인다. 같은 폴더의 AGENTS.override.md는 그 폴더의 일반 AGENTS.md를 대신한다.

파일을 고친 뒤 기존 세션에서 바로 확인해도 되나?

새 실행에서 확인한다. Codex는 실행 시작 때 지침 체인을 만들므로 대상 폴더를 --cd로 지정해 새 세션을 열고 활성 파일 경로를 다시 요청한다.

검증 기준

• 마지막 업데이트일: 2026-09-21
• 확인 환경: macOS 비민감 Git 저장소, Codex CLI 0.154.0, gpt-5.6-sol low, 별도 CODEX_HOME, 현재 폴더 repo/sub/task
• 주요 근거: OpenAI Codex AGENTS.md 공식 안내
• 공개 질문: 프로젝트 파일이 있을 때 전역 파일이 보이지 않았다는 Codex 이슈. 단일 자기보고이며 보편 동작으로 확대하지 않았다.
• 직접 결과: baseline은 전역→루트→하위 표식 3개였다. override 실행은 전역→루트→하위 override 표식 3개였고, 같은 폴더의 일반 하위 표식은 나오지 않았다.
• 한계: 기본 32 KiB 상한 전후에서 어느 지점까지 로드되는지는 이번 재현에 포함하지 않았다. 파일 발견과 모델의 개별 지침 준수도 같은 뜻이 아니다.