Codex를 위한 AGENTS.md 완전 설정 가이드 (2026)
AGENTS.md는 Codex(OpenAI Codex CLI)의 영속적인 지시 파일로, 저장소에서 작업을 시작하기 전에 자동으로 읽혀요. Codex는 이 파일을 고정된 검색 순서(글로벌, 그다음 git-root에서 현재 디렉터리까지)로 찾고, 찾은 것을 모두 이어 붙인 다음, 합쳐진 크기를 32 KiB로 제한해요. 이를 넘어가면 나머지는 아무 알림 없이 조용히 버려져요. 한 가지 기억해 둘 점은, Codex는 CLAUDE.md를 읽지 않는다는 거예요. 이 가이드는 그 동작 방식(검색 순서, 파일이 합쳐지는 방법, 크기 제한, 그리고 그대로 복사해 쓸 수 있는 실제 AGENTS.md)을 다뤄요.
- Codex의 AGENTS.md 동작 방식은 빠르게 바뀌어요. 아래 내용은 작성 시점(2026년 8월)의 공식 문서와 대조해 확인했어요. 실제로 의존하기 전에 최신 문서를 꼭 확인하세요.
Codex에서 AGENTS.md가 하는 일 (그리고 CLAUDE.md 이야기)
AGENTS.md는 세션을 열 때마다 Codex가 컨텍스트에 불러오는 영속적인 지시 파일이에요 — 프로젝트 규칙, 테스트/빌드 명령, 어겨서는 안 되는 규칙 등을 적어 두면 매번 프롬프트에서 반복하지 않아도 돼요. 공식 learn.chatgpt.com/codex/agent-configuration/agents-md 문서에 따르면 Codex는 고정된 방식으로 AGENTS.md 파일을 찾아 불러오지만, 바로 그 페이지에서 CLAUDE.md는 한 번도 언급하지 않아요. 솔직히 말하면, 현재로서 Codex는 CLAUDE.md를 읽지 않아요. CLAUDE.md와 AGENTS.md가 정확히 같은 개념을 담고 있는데도요.
혼동을 피하기 위해 한마디 하자면, AGENTS.md(Codex의 설정 파일)는 AgentKit(Codex/Claude Code 안에서 실행되는 킷, agentkit.best)과도, OpenAI AgentKit(OpenAI의 Agent Builder/ChatKit)과도 달라요.
Claude Code도 함께 쓰고 있고 긴 컨텍스트 파일이 실제로 도움이 되는지 궁금하다면 AGENTS.md vs CLAUDE.md — 그리고 긴 파일이 정말 도움이 되는지를 보세요. 그 글은 관련 연구를 다루고, 이 글은 Codex 자체의 설정 동작 방식에 관한 거예요.
Codex가 AGENTS.md를 찾는 곳 — 정확한 검색 순서
Codex는 하나의 AGENTS.md 파일만 읽지 않고, 다음의 정확한 순서로 여러 계층을 훑어요(공식 문서 기준):
- 글로벌 계층: Codex는 먼저
~/.codex/AGENTS.override.md를 확인해요. 있으면~/.codex/AGENTS.md대신 그걸 사용해요. 오버라이드가 없으면~/.codex/AGENTS.md를 읽어요. - 디렉터리 계층(git-root에서 현재 디렉터리까지 내려가며): Codex는 git 저장소 루트를 찾은 다음, 거기서
cwd(Codex를 실행하는 위치)까지 각 디렉터리 계층을 내려가요. 모든 계층에서 같은 오버라이드 규칙을 적용해서, 그 계층에AGENTS.override.md가 있으면 그게 우선하고, 없으면AGENTS.md를 사용해요.
예를 들어 여러분이 ~/projects/shop/apps/web에 있고 git 루트가 ~/projects/shop이라고 해요. Codex는 다음 순서로 확인해요: 글로벌(~/.codex/) → ~/projects/shop/AGENTS.md(git-root) → ~/projects/shop/apps/AGENTS.md(있으면) → ~/projects/shop/apps/web/AGENTS.md(cwd). 없는 것은 그냥 건너뛰고, 오류도 나지 않아요.
오버라이드 파일이 실제로 유용한 지점은 이거예요: 팀 전체가 공유하는 AGENTS.md는 git에 커밋해 두고, 개인이나 특정 머신에 맞춘 조정은 같은 계층의 .override.md에 넣는 거죠 — 모두가 공유하는 파일은 건드리지 않고요.
기억해 둘 점: 이건 '가장 가까운 파일이 이기고 나머지는 무시된다'가 아니에요 — 찾은 파일은 모두 함께 합쳐지고(다음 섹션), 하나만 골라지는 게 아니에요.
파일이 어떻게 합쳐지는가 — 루트에서 아래로 이어 붙이기, 더 가까운 파일이 우선
Codex는 파일을 찾으면 하나를 고르는 게 아니라, 찾은 것을 모두 하나의 컨텍스트 블록으로 이어 붙여요 — 검색과 같은 순서로, 먼저 글로벌, 그다음 git-root, 그다음 각 하위 디렉터리 순이며 빈 줄로 구분돼요. cwd에 가까운 파일일수록 마지막에 덧붙여지기 때문에 컨텍스트의 끝에 놓이고, 두 지시가 충돌할 때는 나중에 나오는(cwd에 더 가까운) 쪽을 보통 에이전트가 따라요.
파일 3개 예시와, 충돌 시 어느 것이 이기는지:
~/.codex/AGENTS.md(글로벌): '커밋하기 전에 항상 전체 테스트 스위트를 실행하라.'~/projects/shop/AGENTS.md(git-root): 'npm이 아니라 pnpm을 사용하라.'~/projects/shop/apps/web/AGENTS.md(cwd): '이 디렉터리를 편집할 때는 유닛 테스트(pnpm test:unit)만 실행하라 — 전체 스위트는 반복 작업하기엔 너무 느리다.'
이 셋은 완전히 서로 모순되는 건 아니지만, 규칙 3은 규칙 1과 실제로 충돌해요. 규칙 3이 마지막에 덧붙여지므로, Codex는 apps/web 안에서 작업하는 동안 그것을 따르는 경향이 있어요. 바로 그래서 여러분에게 가장 가까운 파일에는 구체적이고 로컬한 지시를 담고, 글로벌/루트 파일에는 넓고 안정적인 규칙만 두는 게 좋아요. 실질적으로 이는 하위 디렉터리의 AGENTS.md가 글로벌 규칙을 완전히 '해제'할 수는 없다는 뜻이기도 해요 — 할 수 있는 건 나중에 오는 더 구체적인 지시를 추가하는 것뿐이고, 그 맥락에서는 에이전트가 그쪽을 더 무겁게 여기는 경향이 있어요.
32 KiB 제한 — project_doc_max_bytes
찾은 모든 AGENTS.md 파일의 합쳐진 크기(각 파일 개별이 아니라)는 project_doc_max_bytes로 제한되며, 기본값은 32 KiB예요. config-advanced 문서에 따르면 Codex는 빈 파일을 건너뛰고, 합쳐진 크기가 제한에 도달하는 순간 콘텐츠 추가를 멈춰요 — 그 지점을 넘어선 것은 컨텍스트에 전혀 들어가지 않고, TUI에 오류나 경고도 없어요.
제한을 높이려면 ~/.codex/config.toml에 다음을 추가하세요:
project_doc_max_bytes = 65536(65536바이트 = 64 KiB는 그냥 예시예요 — 실제로 필요한 값으로 설정하세요. '혹시 몰라서' 올리지는 마세요: 파일이 길수록 에이전트는 모든 줄에 과하게 반응하는 경향이 있어요 — 아래의 간결한 예시를 보세요.)
| 설정 | 값 |
|---|---|
| 기본값 | 32 KiB (모든 AGENTS.md 파일 합계에 적용) |
| 설정 위치 | ~/.codex/config.toml의 project_doc_max_bytes |
| 제한 초과 시 | 콘텐츠 추가 중단 — 오류도, 경고도 없음 |
| 빈 파일 | 건너뜀, 합계에 포함되지 않음 |
조용한 잘림이라는 함정 (실제 버그 보고)
이 부분은 다른 대부분의 가이드가 건너뛰는 곳이에요. GitHub Issue #7138(2025년 11월 22일 등록, 'not planned'로 종료)은 바로 이것을 기록하고 있어요: 어떤 사용자의 합쳐진 AGENTS.md가 대략 40 KB에 달했는데, Codex가 그것을 조용히 32 KB로 잘라냈어요 — TUI에도, /stats에도 경고가 없었죠. 이 이슈는 컨텍스트 파일이 예산을 초과할 때 경고해 주는 Claude Code와 이 점을 명확히 대비시켜요.
참고: 작성 시점 기준으로 이 이슈는 'not planned'로 종료되었어요 — 즉 Codex 팀은 경고를 추가할 계획이 없다는 뜻이에요. 인용하기 전에 이슈의 최신 상태를 다시 확인하세요; 트래커 상태는 바뀌어요.
현실적인 해결책: 모든 규칙을 거대한 하나의 루트 AGENTS.md에 몰아넣지 마세요. 디렉터리별로 나누고 — 글로벌 파일은 넓은 규칙을 위해 남겨 두고, 각 하위 디렉터리에는 거기에 관련된 것만 담으세요 — 이렇게 하면 32 KiB 제한 아래로 유지되고, AGENTS.md/CLAUDE.md 연구가 이미 밝혀낸 결론, 즉 '긴 파일은 도움이 되지 않고 비용만 더 든다'와도 맞아떨어져요.
project_doc_fallback_filenames와 CODEX_HOME
깊게 커스터마이즈한다면 알아 둘 만한 작은 설정 두 가지예요:
project_doc_fallback_filenames: 어떤 계층에 AGENTS.md가 없을 때 Codex가 그 계층에서 받아들이는 대체 파일명 배열이에요 — 팀이 이미TEAM_GUIDE.md를 쓰고 있고 아직 이름을 바꿀 준비가 안 됐다면 유용해요.~/.codex/config.toml에 설정하세요:project_doc_fallback_filenames = ["TEAM_GUIDE.md"].CODEX_HOME: Codex의 설정 디렉터리를 가리키는 환경 변수로, 기본값은~/.codex예요. 여기에는config.toml,auth.json,history.jsonl이 들어 있어요 — 프로파일이나 머신별로 Codex 설정을 나누고 싶을 때 변경하세요(예를 들어 CI 러너마다 별도의CODEX_HOME을 둬서 자동 세션이 개인auth.json을 건드리지 않도록 하는 식으로요).
그대로 쓸 수 있는 실제의 간결한 AGENTS.md
다음은 제가 Node/TypeScript 저장소에서 실제로 쓰는 루트 AGENTS.md예요 — 일부러 짧게 했어요. 파일이 길다고 Codex가 더 잘 동작하는 건 아니거든요(위의 함정과 컨텍스트 파일 연구를 보세요):
# Build & test
- Install: `pnpm install`
- Unit tests: `pnpm test` - e2e: `pnpm test:e2e` (Playwright, slow, run only when needed)
- Build: `pnpm build`
- Before committing: `pnpm lint && pnpm typecheck`
# Must not break
- Don't change the public API in `src/sdk/` without a major version bump.
- Never commit `.env*` files.
- Don't touch `infra/` (Terraform) outside a reviewed PR.
# Key paths
- API routes: `src/api/`
- Shared types: `src/types/`
- DB migrations: `db/migrations/` (never edit an applied migration, always add a new one)15줄이에요. '프로젝트 개요'도, 설명하는 문장도 없어요. 모든 줄이 실행 가능한 명령이거나 구체적인 '어겨서는 안 되는' 규칙이에요 — 바로 AGENTS.md vs CLAUDE.md 연구가 에이전트가 실제로 행동에 옮긴다고 밝혀낸 부분이죠.
AGENTS.md는 규칙을 정하고 — AgentKit은 스킬을 더해요
AGENTS.md는 Codex가 네이티브로 읽는 무료 설정이라 설치할 게 없어요. 이건 '무엇을 할지 / 무엇을 하지 말지'에 답해요. 가져오지 못하는 건 패키지화된 스킬이나 워크플로인데, 그걸 더해 주는 게 AgentKit(agentkit.best, ak CLI)이에요. AgentKit은 AGENTS.md를 대체하는 게 아니라 Codex 위에서 실행돼요.
Codex용으로 킷을 설치하려면: ak kit init engineer --target codex --global(모든 저장소에서 쓰려면 --global을 붙이세요). 그다음 새 Codex 세션 안에서 $ak:cook ...을 실행하세요(Codex에서는 $ak: 구문이라는 점에 유의하세요, Claude Code의 /ak:와 달라요 — Codex 제공은 현재 네이티브 전용이에요: 스킬, 규칙, 에이전트 디스패치, 일부 훅. 킷 명령은 아직 활성화되지 않았고, 상태 표시줄도 없어요).
무료/유료 경계를 분명히 하자면: AGENTS.md는 비용이 들지 않아요. AgentKit은 유료 애드온이에요(Engineer Kit은 약 $99, 스토어에서 종종 -20%가 적용되어 작성 시점 기준 대략 $79.20까지 내려가요 — 최신 가격을 확인하세요). Codex가 처음이신가요? 먼저 OpenAI Codex가 무엇인지를 보세요. SKILL.md가 실제로 무엇인지(AGENTS.md와는 다른, 항상 로드되는 컨텍스트가 아니라 온디맨드 기능이에요) 알고 싶다면 Codex Skills 설명을, Codex 안에서 AgentKit을 실행하는 과정을 알고 싶다면 AgentKit in Codex를 보세요.
간결한 AGENTS.md 위에서 패키지화된 스킬을 실행하고 싶으세요? AgentKit Engineer Kit은 Codex와 Claude Code를 위한 사전 구축된 워크플로/스킬을 더해 줘요 — 기본적인 규칙 설정 일은 여전히 여러분의 AGENTS.md가 맡고요.
자주 묻는 질문 (FAQ)
Codex는 CLAUDE.md를 읽나요?
아니요. 공식 문서에 따르면 Codex는 AGENTS.md(그리고 AGENTS.override.md) 파일만 검색해 불러오고, CLAUDE.md를 읽는 메커니즘은 없어요. 같은 저장소에서 Claude Code와 Codex를 둘 다 쓴다면 두 파일을 모두 두거나(또는 한쪽을 다른 쪽에 심볼릭 링크하세요).
Codex에서 AGENTS.md 크기 제한은 얼마인가요?
기본값은 32 KiB이며, 찾은 모든 AGENTS.md 파일의 합계(각 파일 개별이 아니라)에 project_doc_max_bytes로 적용돼요. 제한을 넘어선 것은 조용히 버려지고, 오류도 경고도 없어요. ~/.codex/config.toml에서 제한을 높일 수 있어요.
글로벌, 저장소 루트, 하위 디렉터리 AGENTS.md가 있으면 어느 것이 이기나요?
어느 것도 단독으로 '이기지' 않아요 — Codex는 글로벌에서 git-root, 그리고 현재 디렉터리로 내려가는 순서로 모두 합쳐요. 현재 디렉터리에 가장 가까운 파일이 마지막에 덧붙여지므로, 무언가 충돌할 때는 보통 그 파일의 지시가 따라져요.
AGENTS.override.md는 무엇을 위한 건가요?
어떤 계층(글로벌 또는 디렉터리)에 있으면, AGENTS.override.md는 같은 계층의 AGENTS.md 대신 사용돼요. 팀이 공유하는 AGENTS.md를 git에 두면서 공유 파일을 건드리지 않고 개인적인 오버라이드를 추가하는 데 유용해요.
파일이 너무 길면 Codex가 경고해 주나요?
아니요, 적어도 작성 시점에는요. GitHub Issue #7138은 40 KB 파일이 TUI 경고 없이 조용히 32 KB로 잘리는 것을 기록하고 있고, 'not planned'로 종료됐어요. 반면 Claude Code는 컨텍스트 파일이 예산을 초과하면 경고해요 — 기억해 둘 만한 차이예요.
Codex는 설정을 어디에 저장하나요?
CODEX_HOME 디렉터리 안, 기본값은 ~/.codex예요 — config.toml, auth.json, history.jsonl을 담고 있어요. 환경 변수를 통해 CODEX_HOME을 다른 디렉터리로 지정할 수 있어요.
결론
Codex의 AGENTS.md 동작 방식은 결국 세 가지로 요약돼요: 고정된 검색 순서(글로벌, 그다음 git-root에서 cwd까지), 루트에서 아래로 이어 붙이기(충돌 시 여러분에게 가장 가까운 파일이 이김), 그리고 넘치는 부분을 조용히 버리는 32 KiB 제한 — 그리고 그 어느 것도 CLAUDE.md는 절대 건드리지 않아요. 간결하게 쓰고, 거대한 하나의 루트 파일에 몰아넣는 대신 디렉터리별로 나누면 함정과 낭비 비용을 둘 다 피할 수 있어요. 애초에 긴 파일이 왜 도움이 되지 않는지는 AGENTS.md vs CLAUDE.md — 그리고 긴 파일이 정말 도움이 되는지를 보세요.