Codex AGENTS.md 크기 제한, 일부 지침이 빠질 때 확인할 것

AGENTS.md의 앞 규칙은 보이는데 뒤 규칙이나 더 가까운 폴더 규칙만 빠진다면, 먼저 AGENTS.md 크기 제한에서 입력이 잘렸는지 확인한다. 비민감한 시작·끝 표식을 넣고 파일 byte 수를 잰 뒤 새 Codex 세션에서 실제로 보인 표식만 출력한다. 표식 자체가 없으면 로드 범위 문제를, 표식은 있는데 행동만 어긋나면 지침 준수 문제를 따로 점검한다.

먼저 파일별 byte 수를 잰다

프로젝트 루트에서 현재 폴더까지 적용되는 AGENTS.md와 AGENTS.override.md를 확인한 뒤 각 파일 크기를 잰다.

wc -c AGENTS.md
wc -c path/to/subdir/AGENTS.md

wc -c는 글자 수가 아니라 byte 수를 보여 준다. OpenAI 공식 문서는 Codex가 전역 지침과 프로젝트 루트에서 현재 폴더까지의 지침을 합치며, 합계가 project_doc_max_bytes에 도달하면 추가를 멈춘다고 설명한다. 기본값은 32 KiB다.

파일 하나만 보고 32 KiB 아래라고 끝내면 안 된다. 실제 비교 대상은 현재 실행에 들어오는 지침 체인의 합계다. 같은 폴더에 override가 있으면 그 폴더의 일반 파일 대신 override 하나가 선택된다는 점도 함께 확인한다.

시작·끝·하위 폴더에 비민감 표식을 넣는다

실제 업무 규칙이나 비밀값을 시험 문구로 쓰지 않는다. 각 범위의 시작과 끝에 서로 다른 한 줄을 임시로 둔다.

BOUNDARY_ROOT_START
...
BOUNDARY_ROOT_END

더 가까운 하위 폴더 파일에도 별도 표식을 둔다.

BOUNDARY_SUB_PRESENT
...
BOUNDARY_SUB_END

그런 다음 기존 대화를 계속 쓰지 말고 대상 폴더에서 새 세션을 연다.

codex --cd /실제/프로젝트/하위폴더 --ask-for-approval never \
  "활성 지침 메시지에 실제로 있는 BOUNDARY_ 표식만 그대로 출력해줘. 없는 표식은 추론하지 마."

Codex는 실행을 시작할 때 지침 체인을 만들기 때문에 파일을 바꾼 뒤에는 새 실행으로 확인해야 한다.

2026년 9월 22일 Codex CLI 0.155.1의 codex --help에서도 --cd와 --ask-for-approval never 조합이 유효함을 다시 확인했다. 버전에 따라 옵션 이름이 달라졌다고 추측해 명령을 고치기 전에, 먼저 codex --help에서 현재 설치본의 옵션을 확인한다.

32 KiB 아래와 초과 결과를 직접 비교했다

Codex CLI 0.154.0, gpt-5.6-sol low, 별도 CODEX_HOME, 읽기 전용 새 세션에서 project_doc_max_bytes=32768을 명시하고 두 비민감 저장소를 비교했다.

조건	지침 파일 합계	새 세션에서 보인 표식
상한 아래	31,991 bytes	루트 시작·끝, 하위 시작·끝 모두 출력
상한 초과	33,218 bytes	루트 시작과 잘린 루트 끝 일부만 출력, 하위 표식 없음

상한 초과 케이스의 루트 파일은 32,773 bytes였다. 끝 표식 BOUNDARY_ROOT_END_BEYOND는 실제 출력에서 BOUNDARY_ROOT_END_BE까지만 나타났다. 설정한 32,768-byte 상한보다 파일이 5 bytes 길었고 끝 표식도 그만큼 잘렸다. 뒤에 있던 445-byte 하위 파일의 표식은 들어오지 않았다.

한글처럼 여러 byte를 쓰는 문자가 경계에 걸리는 경우도 따로 확인했다. 3-byte 문자 가의 첫 byte가 32,768-byte 상한의 마지막 위치에 오도록 만든 32,774-byte 파일을 새 세션에서 읽히자 결과는 BOUNDARY_UTF8_�였다. 뒤의 끝은 나오지 않았다. 따라서 지침 끝에서 �가 보이면 원본 파일 인코딩 손상만 의심하지 말고 byte 상한이 문자 중간을 잘랐는지도 확인한다. 경계를 진단하는 임시 표식은 ASCII로 두는 편이 결과를 읽기 쉽다.

이 결과는 “모델이 하위 규칙을 보고도 무시했다”는 설명과 다르다. 이 재현에서는 하위 규칙이 모델 입력에 들어오기 전에 상한에 걸렸다. 다만 Codex 버전과 설정이 다르면 같은 숫자를 가정하지 말고 현재 환경에서 다시 확인해야 한다.

표식 유무로 문제를 두 갈래로 나눈다

새 세션 결과	먼저 볼 원인	다음 행동
끝 표식이나 하위 표식이 없음	크기 상한, 시작 폴더, override, 다른 CODEX_HOME	활성 경로와 byte 합계를 바로잡고 새 세션 재검증
표식은 모두 있음	지침의 모호함·충돌 또는 모델 준수	어긋난 한 줄과 실제 행동을 좁혀 재현
표식이 중간에서 끊김	byte 상한에서 내용 잘림	중복을 줄이거나 파일을 범위별로 나눔

표식 질문에 모델이 경로를 추측하거나 파일을 도구로 다시 읽었다면 그 응답은 로드 증거로 쓰지 않는다. 활성 지침 메시지에 이미 들어온 표식만 그대로 출력하도록 요청하고, 실행 로그와 최종 출력에서 도구 사용 여부를 확인한다.

먼저 줄이고 나눈 뒤 필요한 경우에만 상한을 높인다

긴 설명, 반복된 예시, 이미 CI가 검사하는 형식 규칙부터 덜어낸다. 특정 하위 폴더에서만 필요한 규칙은 그 폴더의 AGENTS.md로 옮긴다. 이렇게 하면 해당 작업 경로에서만 지침이 추가되어 전체 체인을 짧게 유지할 수 있다.

하나의 긴 지침 체인이 실제로 필요하다면 Codex 설정에 값을 명시한다.

project_doc_max_bytes = 65536

설정을 바꾼 뒤에는 대상 폴더에서 새 Codex 세션을 열고 같은 시작·끝 표식을 다시 확인한다. 조직이나 보안 정책이 값을 관리한다면 임의로 덮어쓰지 말고 관리되는 설정을 먼저 확인한다.

전체 활성 파일 경로가 맞는지부터 점검해야 한다면 Codex가 어떤 AGENTS.md를 읽었는지 확인하는 순서에서 현재 폴더, override, CODEX_HOME을 먼저 확인한다.

Claude Code의 지침 파일과 함께 운영하는 중이라면 CLAUDE.md에 남길 규칙과 AGENTS.md의 역할을 먼저 나눠 중복 지침 자체를 줄인다.

자주 묻는 질문

32 KiB는 파일 하나의 제한인가?

공식 설명은 합친 프로젝트 지침 체인의 project_doc_max_bytes 상한이다. 전역과 프로젝트 경로의 여러 파일이 들어오므로 파일별 크기만 보지 말고 현재 실행에 선택되는 파일들의 합계를 확인한다.

표식이 보이면 그 규칙을 반드시 지킨다는 뜻인가?

아니다. 표식이 보인다는 것은 그 내용이 활성 지침 입력에 포함됐다는 실행 근거다. 구체 행동이 어긋났다면 로드 누락과 분리해 지침 충돌·표현·모델 준수 문제를 따로 재현한다.

검증 기준

• 마지막 업데이트일: 2026-09-21
• 확인 환경: macOS 비민감 Git 저장소, Codex CLI 0.154.0, gpt-5.6-sol low, 별도 CODEX_HOME, project_doc_max_bytes=32768
• 명령 호환성 재확인: 2026-09-22, Codex CLI 0.155.1의 codex --help에서 --cd·--ask-for-approval never 확인
• 주요 근거: OpenAI Codex AGENTS.md 공식 안내
• 직접 결과: 합계 31,991 bytes는 루트·하위 끝 표식까지 출력, 합계 33,218 bytes는 32,773-byte 루트 파일 끝 표식이 중간에서 잘리고 하위 표식은 미출력. 별도 32,774-byte UTF-8 경계 케이스는 BOUNDARY_UTF8_� 출력
• 한계: 정확 검색 수요, 다른 버전, 대체 파일명과 더 많은 디렉터리 조합은 미확인이다. 로드 확인과 모든 지침 준수는 같은 뜻이 아니다.