한 줄 요약: OpenAI Codex 공식 문서 "Custom instructions with AGENTS.md". Codex가 작업 전에 읽는 AGENTS.md를 전역(Codex 홈)과 프로젝트(루트에서 현재 디렉터리까지) 두 층으로 쌓는 방법, 디렉터리마다 하나만 고르는 탐색 순서(AGENTS.override.md → AGENTS.md → 대체 파일 이름), 합친 크기 한도(project_doc_max_bytes, 기본 32 KiB), 코드 리뷰 규칙 절, 설정 확인과 문제 해결을 다룬다.
원본 정보#
- 제목: Custom instructions with AGENTS.md
- 발행: OpenAI, Codex 공식 문서 (원본 날짜 미상)
- URL: https://learn.chatgpt.com/docs/agent-configuration/agents-md (새 창) (이전 주소 https://developers.openai.com/codex/guides/agents-md (새 창) 에서 옮겨 감. 원본 출처 블록 기준)
- 수집(fetch)일: 2026-10-18. 설정 키, 기본값, 명령어는 이 날짜 기준이다.
핵심 주장#
- Codex는 작업 전에 지시 체인을 만든다. 시작할 때 한 번(실행마다 한 번, TUI에서는 보통 띄운 세션마다 한 번) 만든다. 전역 지시에 프로젝트별 override를 겹쳐, 어느 저장소를 열든 같은 기대치로 시작하게 하는 것이 목적이다. → Codex
- 탐색은 전역 → 프로젝트 순이고, 층마다 고르는 규칙이 있다. 전역은 Codex 홈(
~/.codex,CODEX_HOME으로 변경)에서AGENTS.override.md가 있으면 그것, 없으면AGENTS.md를 읽되 비어 있지 않은 첫 파일 하나만 쓴다. 프로젝트는 프로젝트 루트(보통 Git 루트)에서 현재 작업 디렉터리까지 내려가며 디렉터리마다AGENTS.override.md,AGENTS.md,project_doc_fallback_filenames의 이름 순으로 확인하고 디렉터리당 최대 한 파일만 넣는다. → Codex, 스키마 파일 - 합칠 때는 루트에서 아래로 이어 붙이고, 가까운 파일이 이긴다. 빈 줄로 이어 붙이므로 현재 디렉터리에 가까운 파일이 합친 프롬프트에서 뒤에 와서 앞선 지시를 override한다. 빈 파일은 건너뛰고, 합친 크기가
project_doc_max_bytes(기본 32 KiB)에 닿으면 파일을 더 넣지 않는다. → AGENTS.md와 CLAUDE.md 함께 쓰기 - override 파일은 지우지 않고 잠시 바꾸는 장치다.
~/.codex/AGENTS.override.md는 기본 파일을 지우지 않고 전역 지시를 임시로 바꿀 때 쓰고, 지우면 원래 지시로 돌아간다. 하위 디렉터리의AGENTS.override.md는 같은 디렉터리의AGENTS.md를 무시하게 만든다. → Codex - 로드 여부는 Codex에게 직접 물어 확인한다.
codex --ask-for-approval never "Summarize the current instructions."처럼 지시를 요약하게 하거나 로드한 지시 출처를 나열하게 한다. 체인은 실행마다 다시 만들므로 지울 캐시가 없고, 지시가 낡아 보이면 대상 디렉터리에서 Codex를 다시 시작한다. → Codex
원본의 숫자·설정값·명령어 (2026-10-18 기준)#
- 전역 위치: Codex 홈 디렉터리. 기본
~/.codex, 환경 변수CODEX_HOME으로 변경. - 파일 이름 우선순위(디렉터리마다):
AGENTS.override.md→AGENTS.md→project_doc_fallback_filenames에 적은 이름. 디렉터리당 최대 1개. project_doc_max_bytes: 합친 지시의 크기 한도. 기본 32 KiB. 원본 설정 예는65536.project_doc_fallback_filenames: 원본 설정 예["TEAM_GUIDE.md", ".agents.md"]. 목록에 없는 이름은 지시 탐색에서 무시된다. 설정을 바꾸면 Codex를 다시 시작하거나 새 명령을 실행해야 적용된다.- 설정 파일:
~/.codex/config.toml - 확인 명령:
codex --ask-for-approval never "Summarize the current instructions.",codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded.",CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources",codex -c log_dir=./.codex-log(로그는./.codex-log/codex-tui.log),codex status - GitHub의 Codex 코드 리뷰용 규칙:
AGENTS.md의## Code Review Rules절.