Codex CLAUDE.md 읽기 설정, fallback이 안 될 때 확인할 것

Codex CLAUDE.md 읽기는 파일을 두는 것만으로 끝나지 않는다. config.toml의 project_doc_fallback_filenames에 파일명을 등록하고, 같은 폴더에 먼저 선택될 AGENTS.override.md나 AGENTS.md가 없는지 확인한 뒤 새 Codex 프로세스에서 비민감 표식이 실제 입력에 들어왔는지 확인한다.

대체 파일명은 어떻게 설정하나?

먼저 Codex 설정 파일의 최상위에 fallback 배열을 한 줄 추가한다.

macOS·Linux 기본 위치는 ~/.codex/config.toml이다. Finder에서는 이동 → 폴더로 이동을 누르고 ~/.codex를 입력한다. Windows는 파일 탐색기 주소창에 %USERPROFILE%\.codex를 입력한다. config.toml이 없으면 이 폴더에 같은 이름의 텍스트 파일을 새로 만든다.

별도 CODEX_HOME을 쓰는 환경이라면 기본 폴더가 아니라 그 경로의 config.toml을 연다. 어느 파일인지 모르면 터미널에서 다음 명령으로 실제 후보 경로를 먼저 출력한다.

printf '%s\n' "${CODEX_HOME:-$HOME/.codex}/config.toml"

파일을 열었으면 최상위에 배열을 추가한다.

project_doc_fallback_filenames = ["CLAUDE.md"]

팀 문서 이름이 TEAM_GUIDE.md라면 그 이름을 넣는다. [project] 같은 임의의 섹션 아래로 옮기지 말고 공식 예제와 같은 최상위 키로 둔다. 설정 전체를 공개하거나 공유할 필요는 없다.

설정을 저장한 뒤 이미 열린 대화만 계속 쓰지 말고 대상 폴더에서 새 Codex 프로세스를 연다. OpenAI의 AGENTS.md 공식 안내도 fallback 이름의 오타를 확인하고 설정 변경 뒤 Codex를 다시 시작하라고 안내한다.

같은 폴더의 파일은 어떤 순서로 선택되나?

같은 폴더에서는 우선순위상 처음 발견된 지침 파일 하나만 선택된다.

Codex의 폴더별 탐색 순서는 다음과 같다.

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

한 폴더에서 최대 한 파일만 포함된다. 따라서 AGENTS.md와 CLAUDE.md를 함께 두고 fallback을 설정해도 두 파일을 합쳐 읽는 구성이 아니다. AGENTS.md가 먼저 선택되면 CLAUDE.md는 그 폴더의 지침으로 들어오지 않는다.

Codex CLI 0.154.0의 비민감 fixture에서 직접 확인한 결과도 같았다.

폴더 안 파일	새 prompt input 결과
CLAUDE.md만 있음	CLAUDE 표식 포함
AGENTS.md와 CLAUDE.md 모두 있음	AGENTS 표식만 포함
빈 AGENTS.md와 CLAUDE.md	두 로컬 표식 모두 미포함

마지막 빈 파일 조합은 현재 재현 결과일 뿐 의도된 동작이라고 단정하지 않는다. 이 경우 빈 AGENTS.md를 남겨 둔 채 내용만 고치지 말고, 임시 저장소에서 파일을 제거한 대조군과 사용 중인 Codex 버전을 함께 확인한다.

실제 로드는 어떻게 확인하나?

설정 성공 여부는 추측하지 말고 비민감 표식이 prompt input에 들어왔는지 확인한다.

테스트 파일에 실제 회사 규칙이나 비밀값 대신 임시 한 줄을 넣는다.

FALLBACK_LOAD_TEST_20260921

그다음 대상 폴더에서 현재 모델 입력 목록을 확인한다.

codex -C /실제/프로젝트 \
  -c 'project_doc_fallback_filenames=["CLAUDE.md"]' \
  debug prompt-input TEST

출력에서 표식을 찾는다. 표식이 없으면 다음 순서로 좁힌다.

위 명령의 -c 값은 저장 파일을 바꾸지 않고 이번 실행에만 같은 설정을 적용하는 대조군이다. 이 대조군에서 성공해도 config.toml 저장이 성공했다고 단정하지 않는다. 파일에 저장한 뒤 -c를 뺀 새 프로세스에서도 같은 표식이 보여야 영구 설정 경로까지 확인한 것이다.

• 설정 키가 최상위에 있고 파일명이 정확한가
• 같은 폴더에 AGENTS.override.md나 AGENTS.md가 있는가
• 설정을 바꾼 뒤 새 프로세스를 열었는가
• 다른 CODEX_HOME의 설정을 읽고 있지는 않은가

표식이 입력에 있는데 실제 행동만 어긋난다면 파일 발견 문제가 아니다. 그때는 충돌하는 지침, 모호한 문장, 모델 준수를 별도 재현한다.

공개 실패 보고의 실제 원인은 무엇이었나?

공개 실패 보고는 제목만 보고 버전 버그로 해석하면 안 된다.

공개 Codex 이슈 #22454는 CLI 0.130.0에서 CLAUDE.md fallback이 prompt input에 들어오지 않았다고 처음 보고했다. 그러나 공개 댓글에서 원인은 project_doc_fallback_filenames를 [project] 아래에 둔 설정 위치로 좁혀졌다. 작성자는 이 키를 최상위로 옮긴 뒤 정상 동작한다고 확인했고 이슈를 종료했다.

따라서 이 사례는 “0.130.0에서는 fallback이 고장 났고 0.154.0에서 고쳐졌다”는 근거가 아니다. 같은 키라도 TOML 섹션이 다르면 읽히지 않을 수 있으므로 최상위 위치부터 확인해야 한다는 근거다. 이번 0.154.0 직접 재현은 현재 환경의 성공 대조군일 뿐, 버전 사이의 수정 시점을 증명하지 않는다.

설정 뒤에도 실패하면 codex --version, 사용한 설정 한 줄, 파일 목록, 비민감 표식의 유무만 보존한다. 이 네 가지가 있으면 파일 내용 문제와 버전·탐색 문제를 분리할 수 있다.

검색 결과의 반대 방향 fallback은 어떻게 구분하나?

검색 결과에서는 Codex가 CLAUDE.md를 읽는 질문과 Claude Code가 AGENTS.md를 읽는 질문을 먼저 분리한다.

Codex CLAUDE.md fallback을 검색하면 두 질문이 함께 나온다.

• Codex가 CLAUDE.md를 대체 지침 파일로 읽게 하는 설정
• Claude Code가 CLAUDE.md가 없을 때 AGENTS.md를 읽는 동작

2026-09-22 KST Google 일반 결과 본문 3건은 GitHub #22454의 설정 위치 오류, AGENTS.md 전체 구조, 여섯 가지 로드 누락 조건을 각각 설명했다. Naver 일반 결과 본문 3건은 계층·32 KiB·fallback 개요, Codex/Claude의 기본 파일 구분, AI 지침 작성법을 중심으로 했다. 여섯 문서 모두를 열어 본 결과, config.toml 최상위 키부터 같은 폴더 우선 파일, 새 프로세스, 비민감 prompt input 표식까지 한 번에 확인하는 한국어 절차와 현재 버전의 3개 fixture 표는 없었다. 검색 결과가 있다는 사실은 정확 검색량을 뜻하지 않는다.

이 글은 두 번째 질문을 설명하는 글이 아니다. Codex CLI에서 fallback을 등록했는데도 파일이 안 들어오는 경우만 다룬다. 기존 CLAUDE.md에 남길 규칙과 AGENTS.md의 역할은 파일에 무엇을 넣을지를 답하지만 Codex의 fallback 등록과 실제 로드 확인은 답하지 않는다. 전체 활성 경로부터 확인해야 한다면 Codex가 어떤 AGENTS.md를 읽었는지 확인하는 순서를 먼저 따른다.

자주 묻는 질문

AGENTS.md와 CLAUDE.md를 같은 폴더에 두면 둘 다 읽나?

아니다. 현재 공식 탐색 순서에서는 같은 폴더의 첫 파일 하나만 선택된다. AGENTS.md가 있으면 fallback인 CLAUDE.md까지 합쳐 읽는다고 가정하지 않는다.

설정을 바꿨는데 기존 대화에서 바로 확인할 수 있나?

기존 대화만 계속 쓰지 말고 새 Codex 프로세스를 연다. 새 프로세스의 prompt input에서 비민감 표식을 확인해야 설정 반영과 모델 행동을 분리할 수 있다.

검증 기준

• 마지막 업데이트일: 2026-09-22
• 확인 환경: macOS, Codex CLI 0.154.0, codex debug prompt-input, 비민감 임시 저장소
• 주요 근거: OpenAI Codex AGENTS.md 공식 안내
• 공식 근거 확인: 2026-09-21
• 직접 환경: macOS, Codex CLI 0.154.0, codex debug prompt-input
• 확인한 것: fallback 단독 성공, 비어 있지 않은 AGENTS 우선, 빈 AGENTS 조합의 미로드
• 직접 재현 범위: -c 실행 옵션으로 적용한 일회성 설정. 영구 config.toml 저장 성공을 대신하지 않음
• 미확인: 정확 검색량, 실제 독자 피드백, 빈 파일 동작의 의도, 다른 버전과 Codex Desktop 화면
• 검색 대조: 2026-09-22 KST, Orca 기본 프로필의 Google·Naver 데스크톱 검색. 엔진별 일반 결과 본문 3건씩의 첫 답·목차·조건·누락을 대조 완료