Codex AGENTS.md 중복, CODEX_HOME과 프로젝트가 같을 때

Codex AGENTS.md 중복은 CODEX_HOME과 현재 프로젝트 루트가 같은 폴더일 때 생길 수 있다. 같은 AGENTS.md가 global 지침과 project 지침으로 두 번 들어가는 조건이다. 파일 내용을 줄이거나 프로젝트 지침 전체를 끄기 전에 두 경로를 분리하고, 새 프로세스의 prompt input에서 비민감 표식이 한 번씩 들어가는지 확인한다.

한 파일이 왜 두 번 들어가나?

Codex는 시작할 때 두 경로에서 지침을 조립한다. 먼저 CODEX_HOME의 global 지침을 읽고, 그다음 프로젝트 루트부터 현재 폴더까지 project 지침을 찾는다. 두 시작점이 같은 실제 폴더면 동일한 AGENTS.md를 두 논리 층에서 만날 수 있다.

Codex CLI 0.155.1의 임시 fixture에서 CODEX_HOME과 -C를 같은 폴더로 지정하자 하나뿐인 표식이 prompt input에 두 번 나타났고 project-doc 구분자가 한 번 나타났다. 2026-09-22 확인 당시 공개 Codex 이슈 #34193도 open 상태로 같은 조건을 보고한다.

실행 조건	prompt input에서 확인한 결과
CODEX_HOME = 프로젝트 루트	동일 표식 2회
CODEX_HOME = 프로젝트의 .codex, 프로젝트 루트 = 상위 폴더	global 표식 1회 + project 표식 1회

중복을 어떻게 확인하나?

터미널을 열고 아래 명령으로 임시 폴더와 비민감 AGENTS.md를 만든다. 실제 회사 규칙이나 비밀값을 검색하지 말고 테스트 표식 한 줄만 쓴다.

mkdir -p /tmp/codex-agents-duplicate-test
printf '%s\n' 'CODEX_HOME_PROJECT_TEST_20260922' \
  > /tmp/codex-agents-duplicate-test/AGENTS.md

CODEX_HOME_PROJECT_TEST_20260922

그 폴더를 CODEX_HOME과 프로젝트 루트에 동시에 지정한 새 프로세스에서 prompt input을 확인한다.

CODEX_HOME=/tmp/codex-agents-duplicate-test \
  codex -C /tmp/codex-agents-duplicate-test debug prompt-input TEST

출력 JSON에서 CODEX_HOME_PROJECT_TEST_20260922가 두 번 보이고, 그중 한 번이 --- project-doc --- 뒤에 있다면 이 조건과 일치한다. 명령이 없다는 오류를 내면 먼저 codex --version으로 버전을 남기고, 이 글의 debug prompt-input을 지원하지 않는 버전임을 구분한다. 실제 설정 전체나 세션 원문을 공유하지 말고 버전, 두 경로가 같은지, 표식 횟수만 보존한다.

프로젝트 지침을 끄지 않고 어떻게 피하나?

CODEX_HOME을 프로젝트 루트 자체가 아닌 별도 profile 폴더로 옮긴다. 프로젝트 안에 둘 필요가 있다면 공식 예시처럼 .codex 하위 폴더를 사용한다.

my-project/
├── .codex/
│   ├── config.toml
│   └── AGENTS.md
└── AGENTS.md

이때 CODEX_HOME=/경로/my-project/.codex이고 프로젝트 루트는 /경로/my-project다. 두 파일은 역할이 다르므로 global 공통 규칙과 프로젝트 규칙을 나눠 쓴다. 설정을 바꾼 뒤에는 기존 세션만 계속 쓰지 말고 새 Codex 프로세스에서 각 비민감 표식이 한 번씩 보이는지 확인한다.

직접 대조한 구성은 .codex 하위 폴더가 아니라 별도 home과 project를 형제 폴더로 나눈 형태였다. 이 대조에서 global 표식 1회, project 표식 1회를 확인했다. 프로젝트 안의 .codex는 공식 문서의 구조 예시이며, 이 글의 직접 표식 대조 대상은 아니다.

분리했는데도 두 번 보이면?

아래 세 가지를 순서대로 확인한다.

1. echo "$CODEX_HOME"과 pwd가 실제로 다른 경로인지 확인한다.
2. 심볼릭 링크를 썼다면 pwd -P와 python3 -c 'import os; print(os.path.realpath(os.environ["CODEX_HOME"]))'로 실제 경로를 비교한다.
3. 기존 세션이 아니라 새 Codex 프로세스에서 비민감 표식 횟수를 다시 센다.

두 실제 경로가 다른데도 같은 파일 내용이 반복되면 파일 전체를 공개하지 말고 Codex 버전, 두 실제 경로의 동일 여부, 표식 횟수만 남긴다. 그 자료로 재현 가능한 문제를 분리한다.

어떤 지침 파일이 활성인지부터 불분명하다면 Codex가 어떤 AGENTS.md를 읽었는지 확인하는 순서로 CODEX_HOME, override, 현재 폴더를 먼저 점검한다. Codex와 Claude Code의 파일 역할 자체가 헷갈리면 두 도구의 프로젝트 지침 파일 역할 나누기를 함께 본다. 이 글은 그 다음 단계인 Codex의 동일 실제 경로 중복만 다룬다.

project_doc_max_bytes=0으로 끄면 되나?

일반 해법으로 쓰지 않는다. 이 값은 중복 파일 하나만 제외하는 옵션이 아니라 project 지침 체인 전체를 막을 수 있다. 중첩 폴더의 중요한 안전 규칙까지 빠질 수 있으므로 먼저 경로를 분리한다.

자주 묻는 질문

프로젝트 안에 .codex를 두어도 되나?

가능하다. CODEX_HOME은 프로젝트 루트 자체가 아니라 .codex를 가리키고, 프로젝트 전용 AGENTS.md는 상위 프로젝트 루트에 둔다. 두 파일에는 서로 다른 비민감 표식을 넣어 새 프로세스에서 각 1회인지 확인한다.

같은 문장이 두 파일에 있으면 이 문제인가?

반드시 그렇지는 않다. global과 project 파일에 같은 문장을 직접 복사해 둔 경우와, 하나의 실제 파일이 두 탐색 단계에 들어간 경우를 구분해야 한다. 고유 표식을 파일별로 달리하면 어느 경우인지 확인할 수 있다.

AGENTS.md를 짧게 줄이면 해결되나?

중복 입력량은 줄지만 원인은 남는다. 먼저 CODEX_HOME과 프로젝트 루트를 분리하고, 그다음 각 파일을 역할에 맞게 다듬는다.

검색 경쟁에서 확인한 빈틈

• OpenAI의 AGENTS.md 공식 안내: global과 project 탐색 순서 및 프로젝트별 .codex 예시
• 동일 경로 중복 공개 이슈 #34193: 같은 CODEX_HOME·프로젝트 루트 조건의 단일 공개 보고
• 2026-09-22 Google 일반 결과는 위 정확 이슈와 공식 안내를 상위에서 노출했다. Naver 일반 결과는 전역·프로젝트·override 우선순위 안내가 중심이었고 동일 실제 경로 중복을 직접 답하는 상위 문서는 확인하지 못했다. 이는 정확 검색량이나 수요 규모 증거가 아니다.

검증 기준

• 마지막 업데이트일: 2026-09-22
• 확인 환경: macOS, Codex CLI 0.155.1, codex debug prompt-input, 비민감 임시 fixture
• 주요 근거: OpenAI의 AGENTS.md 탐색 안내·2026-09-22 확인
• 확인한 것: 같은 루트의 동일 표식 2회, 분리 루트의 global/project 표식 각 1회
• 미확인: 정확 검색량, 실제 독자 피드백, 모든 OS와 이후 버전, 중복이 모델 행동과 비용에 미치는 실제 영향