Codex AGENTS.md: 어디에 두고, 어떤 순서로 로드되고, 무엇을 쓸까

Codex가 AGENTS.md를 찾는 위치(로드 순서)

Codex는 시작할 때 지침 체인을 한 번 만들어요(터미널 UI에서는 세션마다 한 번). 파일은 이 표의 위에서 아래 순서로 이어 붙여지므로, 작업 디렉터리에 가까운 지침일수록 뒤에 오고 우선해요.

Codex용 AGENTS.md 설정하는 법

1. 전역 기본값 만들기

   mkdir -p ~/.codex를 실행하고, 모든 저장소에서 쓰고 싶은 선호를 ~/.codex/AGENTS.md에 적으세요. Codex에게 지침을 요약해 달라고 해서 로드되었는지 확인하세요.

   # ~/.codex/AGENTS.md
   
   ## Working agreements
   
   - Always run `npm test` after modifying JavaScript files.
   - Prefer `pnpm` when installing dependencies.
   - Ask for confirmation before adding new production dependencies.

2. 프로젝트 파일을 추가하고, 팀마다 다른 곳은 오버라이드하기

   공통 설정은 저장소 루트의 AGENTS.md에 두세요. 규칙이 다른 폴더에는 AGENTS.override.md를 추가하세요. 이 파일이 그 폴더의 AGENTS.md를 대체하고, Codex는 원래 파일을 무시해요.

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use `make test-payments` instead of `npm test`.
   - Never rotate API keys without notifying the security channel.

3. 무엇이 로드됐는지 확인하기

   원하는 폴더에서 Codex를 시작하고(예: codex --cd services/payments), 로드한 지침 출처를 나열해 달라고 하세요. 전역 파일, 루트 파일, 그 폴더의 파일 순으로 나와야 해요.

4. 기존 파일 이름을 재사용하거나 한도 올리기

   저장소가 이미 다른 파일에 지침을 두고 있다면 ~/.codex/config.toml의 project_doc_fallback_filenames에 추가하세요. 합친 크기가 project_doc_max_bytes(기본값 32 KiB)에 도달하면 Codex는 더 이상 파일을 추가하지 않아요.

   # ~/.codex/config.toml
   project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
   project_doc_max_bytes = 65536

5. Codex 코드 리뷰 규칙 추가하기

   GitHub의 @codex review에 적용하려면, 해당 코드에 가장 가까운 AGENTS.md에 ## Code Review Rules 섹션을 추가하세요. 무엇을 지적할지와 안전한 대안을 적고, 포맷과 lint는 CI에 맡기세요.

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

출처: Codex 문서, Custom instructions with AGENTS.md

AGENTS.md 모범 사례

• Codex가 스스로 알아낼 수 없는 것만 적으세요. 정확한 빌드, 테스트, lint 명령어(테스트 하나만 실행하는 방법 포함), 코드베이스의 함정, 어디에도 적혀 있지 않은 결정이요.
• 가장 구체적인 규칙은 코드 가까이에 두세요. services/payments/에 중첩된 AGENTS.md가 루트의 긴 파일 속 결제 섹션보다 나아요.
• 32 KiB 예산을 신경 쓰세요. 파일은 루트부터 차례로 추가되고 나머지는 잘리므로, 긴 파일은 중첩 파일로 나누거나 project_doc_max_bytes를 올리세요.
• 임시 변경에는 전역이든 폴더 하나든 AGENTS.override.md를 쓰고, 지우면 원래대로 돌아가요.
• 빈 AGENTS.md는 건너뛰고, 그 디렉터리에서는 다음 파일 이름을 확인해요.
• 자동화용 사용자에게는 별도의 CODEX_HOME을 써서 그 전역 지침이 내 것과 섞이지 않게 하세요.

Codex와 Claude Code 등에서의 AGENTS.md 비교

AGENTS.md는 많은 에이전트가 읽는 개방형 형식이라, 함께 쓰고 싶은 지침을 두기에 가장 좋은 곳이에요. Claude Code에는 자체 파일인 CLAUDE.md가 있어요. 자세한 내용은 CLAUDE.md 가이드를 보세요.

AGENTS.md는 Codex에게 방법을, Crewmark는 다음 할 일을 알려 줘요.

좋은 AGENTS.md가 있으면 모든 Codex 세션이 상황을 알고 시작하지만, 세션은 여전히 여러분의 프롬프트를 기다려요. Crewmark는 Codex, Claude Code, DeepSeek Harness, OpenCode 세션을 직무, 목표, 근무 시간을 갖춘 AI 직원으로 바꾸고, 하트비트로 깨워 보드에서 다음 이슈를 가져가게 해요.

1. AGENTS.md는 저장소에 그대로 두기

   직원의 Codex 세션도 여러분의 세션처럼 이 파일을 읽으니, 규칙과 테스트 명령어도 그대로 따라가요.

2. 하트비트로 일을 시작하게 하기

   근무 시간 동안 직원은 15분, 30분, 60분마다 같은 대화에서 깨어나요. Codex를 능동적으로 만드는 방법을 참고하세요.

3. 한 보드에서 여러 에이전트 함께 쓰기

   AGENTS.md 하나로 Codex 직원과 Claude Code 직원을 나란히 운영할 수 있어요. Claude Code vs Codex에서 비교해 보세요.

Codex AGENTS.md 자주 묻는 질문