GrepBoard/매뉴얼
51 편 ·

Codex 에 저장소 규칙 주기 — AGENTS.md

·Codex CLI 0.163.0 · Ubuntu 24.04 · 공식 문서 기준 2026-10·7 단계

Codex 가 작업 전에 읽는 AGENTS.md 를 저장소에 두고, 전역·루트·하위 폴더 순서와 AGENTS.override.md, 32 KiB 크기 제한을 확인하는 방법입니다.

AGENTS.md 는 코딩 에이전트에게 빌드 방법과 규칙을 알려 주는 마크다운 파일로, 사람용 README 와 따로 둡니다. 이 글은 Codex 가 이 파일을 읽는 위치와 순서, 쓸 내용을 다룹니다.

[1] 설치된 버전을 확인합니다. 아래 동작은 공식 문서 기준이며, 이 버전의 바이너리에도 AGENTS.override.md · project_doc_max_bytes · project_doc_fallback_filenames 문자열이 들어 있습니다.

console
$ codex --versioncodex-cli 0.163.0

[2] 읽는 순서를 이해합니다. Codex 는 작업을 시작할 때 한 번 지침 목록을 만듭니다.

  • 전역: Codex 홈(~/.codex, CODEX_HOME 으로 바꿀 수 있음)에서 AGENTS.override.md 가 있고 비어 있지 않으면 그것을, 아니면 AGENTS.md 를 읽습니다. 이 단계에서는 첫 번째 비어 있지 않은 파일 하나만 씁니다.
  • 프로젝트: 프로젝트 루트(보통 Git 루트)부터 현재 디렉터리까지 내려오며, 디렉터리마다 AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames 순으로 찾아 최대 한 개를 씁니다. 루트를 못 찾으면 현재 디렉터리만 봅니다.
  • 합치기: 루트에서 아래로 빈 줄을 사이에 두고 이어 붙입니다. 현재 디렉터리에 가까운 파일이 뒤에 오므로 앞의 규칙보다 우선합니다. 빈 파일은 건너뜁니다.

[3] 저장소 루트에 파일을 만듭니다. 빌드·시험 명령, 금지 사항, 코드 규칙을 짧게 씁니다. 형식 제한은 없는 일반 마크다운입니다.

AGENTS.md
# AGENTS.md+## 명령- 설치: `npm ci`- 시험: `npm test` (변경한 코드에는 시험을 추가합니다)- 검사: `npm run lint`+## 금지- `.env` 와 `secrets/` 는 읽거나 고치지 않습니다.- `package-lock.json` 은 직접 편집하지 않습니다.+## 코드 규칙- TypeScript strict 를 유지합니다.- 작은따옴표를 쓰고 세미콜론은 붙이지 않습니다.

[4] 하위 폴더에만 해당하는 규칙은 그 폴더에 AGENTS.md 를 따로 둡니다. 같은 폴더에서 임시로 덮어쓰려면 AGENTS.override.md 를 둡니다. 우선순위는 AGENTS.override.md 가 높고, 한 폴더에서는 둘 중 하나만 읽힙니다.

console
$ mkdir -p services/payments$ printf '# payments\n- 통화 금액은 정수(센트)로 다룹니다.\n' > services/payments/AGENTS.md

[5] 대상 폴더에서 어떤 지침이 읽혔는지 Codex 에게 물어 확인합니다. 로그인이 필요하므로 이 글에서는 실행하지 않았습니다. 공식 문서의 예시입니다.

console
$ codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

[6] 설정은 ~/.codex/config.toml 에서 합니다. 기본 크기 제한은 합친 지침 32 KiB(project_doc_max_bytes)이며, 이 값에 닿으면 파일 추가를 멈춥니다. AGENTS.md 대신 다른 이름을 쓰는 저장소라면 대체 이름을 등록합니다.

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

[7] 다른 도구와의 관계입니다. AGENTS.md 는 여러 도구가 읽는 공용 형식이고, Claude Code 는 CLAUDE.md 가 없으면 AGENTS.md 를 읽고(v2.1.277 이상, CLAUDE.md 가 있으면 그쪽만 읽음), Gemini CLI 는 .gemini/settings.json 에 "context": { "fileName": "AGENTS.md" } 를 넣으면 읽습니다. 파일 하나를 두 도구가 나눠 쓸 수 있습니다.

참고: Codex AGENTS.md 가이드 · agents.md · Claude Code 메모리 문서

#codex#agents-md