AGENTS.override.md가 AGENTS.md를 가리는 조건과 되돌리는 법

같은 폴더에 AGENTS.override.md와 AGENTS.md가 모두 있으면 Codex는 override 하나를 선택하고 같은 폴더의 일반 파일은 읽지 않는다. 다만 상위 폴더에서 이미 선택된 지침까지 전부 꺼지는 것은 아니다. 적용이 끝났다면 override의 위치와 내용을 확인하고 이름을 바꾼다. 그런 다음 대상 폴더에서 새 Codex 세션을 열어 일반 파일로 돌아왔는지 확인한다.

먼저 두 파일이 같은 폴더에 있는지 확인

현재 폴더와 두 파일의 전체 경로부터 확인한다. Codex를 시작하는 프로젝트 폴더에서 아래 명령을 실행한다.

pwd
find .. -name AGENTS.override.md -o -name AGENTS.md

첫 줄은 현재 폴더다. find 결과에서는 같은 디렉터리에 두 파일이 함께 있는 위치를 찾는다. 검색 범위가 너무 넓으면 프로젝트 루트에서 다시 실행한다. Git 저장소라면 다음 명령으로 루트를 확인할 수 있다.

git rev-parse --show-toplevel

fatal: not a git repository가 나오면 현재 위치가 저장소 밖이거나 Git 저장소가 아니다. 이때는 파일을 지우지 말고 실제 프로젝트 폴더로 이동한 뒤 다시 확인한다.

같은 폴더에서는 override 하나만 선택된다

같은 디렉터리에서는 우선순위가 가장 높은 후보 파일 하나만 선택된다. OpenAI 공식 안내의 기본 파일 우선순위는 다음과 같다.

1. AGENTS.override.md
2. AGENTS.md
3. 설정한 대체 파일명

Codex는 각 디렉터리에서 이 순서로 찾고 첫 번째 파일 하나만 선택한다. 따라서 같은 폴더의 override와 일반 파일을 합치지 않는다.

Codex CLI 0.154.0과 gpt-5.6-sol low로 만든 비민감 임시 저장소에서도 이 조건을 확인했다. override가 없던 새 세션의 출력은 다음과 같았다.

GLOBAL_SCOPE_MARKER — global
ROOT_SCOPE_MARKER — repository root
SUB_SCOPE_MARKER — nearer subdirectory

같은 하위 폴더에 AGENTS.override.md를 추가하고 다시 연 새 세션에서는 이렇게 바뀌었다.

GLOBAL_SCOPE_MARKER — global
ROOT_SCOPE_MARKER — repository root
SUB_OVERRIDE_MARKER — nearer subdirectory override

상위의 전역·저장소 루트 표식은 남고, 같은 하위 폴더의 일반 표식만 override 표식으로 바뀌었다. 이 결과는 하위 override가 그 디렉터리의 일반 파일을 대신 선택한다는 공식 설명과 일치한다. 다른 버전 전체의 동작까지 보장하는 결과는 아니다.

원래 AGENTS.md로 안전하게 돌아가기

override를 보존한 채 이름을 바꾸고 새 세션에서 일반 파일의 표식을 확인한다. 먼저 override 내용을 읽어 현재 작업에 필요한 임시 규칙인지 확인한다.

sed -n '1,220p' path/to/AGENTS.override.md

임시 적용이 끝났다면 바로 삭제하기보다 이름을 바꿔 보존한다.

mv path/to/AGENTS.override.md path/to/AGENTS.override.md.disabled

이름을 바꾼 뒤 기존 Codex 대화를 계속 사용하지 말고, 일반 AGENTS.md가 있는 폴더를 --cd로 지정해 새 세션을 연다.

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

각 파일에는 비밀이나 실제 업무 지시 대신 서로 다른 비민감 표식을 잠시 넣는다. 새 출력에 일반 파일의 표식이 돌아오면 복귀를 확인한 것이다. 확인 뒤 테스트 표식은 제거한다.

override를 없앴는데도 예전 규칙이 보일 때

기존 세션, 다른 위치의 override, 잘못된 시작 폴더를 차례로 확인한다. 다음 세 가지를 순서대로 확인한다.

1. 기존 세션을 계속 쓰고 있는지: 파일을 바꾼 뒤에는 대상 폴더에서 새 세션을 연다.
2. 다른 상위·하위 폴더에 override가 있는지: find 결과의 전체 경로를 다시 본다.
3. 시작 폴더가 예상과 같은지: pwd와 git rev-parse --show-toplevel 결과를 대조한다.

활성 파일 전체를 확인해야 한다면 Codex가 어떤 AGENTS.md를 읽었는지 확인하는 순서에서 전역 파일, 프로젝트 루트, 현재 폴더를 함께 점검한다.

시작 폴더가 Git 기준점 자체를 찾지 못한다면 Codex worktree의 invalid reference: HEAD 해결 순서로 저장소 루트와 첫 커밋부터 확인한다.

자주 묻는 질문

override의 범위와 두 파일을 함께 쓰는 방법을 짧게 정리한다.

override가 있으면 저장소 루트 AGENTS.md도 무시되나?

같은 폴더의 파일 선택과 상위 폴더에서 내려오는 지침 누적은 별개다. 이번 재현에서는 하위 override를 추가해도 전역과 저장소 루트 표식이 유지됐다. 루트 폴더 자체에 override와 일반 파일이 함께 있다면 그 루트에서는 override가 선택된다.

두 파일 내용을 모두 적용하려면 어떻게 하나?

같은 폴더의 두 기본 파일을 자동으로 합칠 수 있다고 기대하면 안 된다. 함께 필요한 규칙은 선택될 한 파일에 명시적으로 정리하거나, 범위가 다른 규칙이라면 실제 적용할 하위 디렉터리의 파일로 옮긴다. 옮긴 뒤에는 새 세션의 비민감 표식으로 범위를 다시 확인한다.

검증 기준

• 마지막 업데이트일: 2026-09-21
• 확인 환경: macOS 비민감 Git 저장소, Codex CLI 0.154.0, gpt-5.6-sol low, 별도 CODEX_HOME
• 주요 근거: OpenAI Codex AGENTS.md 안내
• 직접 결과: override 추가 전후에 전역·루트 표식은 유지되고 같은 하위 폴더의 일반 표식만 override 표식으로 바뀌었다.
• 한계: 정확 검색 수요와 다른 Codex 버전은 미확인이다. 활성 표식 출력은 파일 발견 근거이며 모든 세부 지침 준수의 증명은 아니다.