# 저장소 규칙을 에이전트에게 매번 자동 전달 (Codex AGENTS.md)
id: codex-agents-md · 종류: 워크플로 · 상태: 검수 대기 (사람 확인 전) · 주제: 개발
주소: https://opencurrent.ai/w/codex-agents-md
기준일: 2026-11-15 (여기서 고친 날)
도구: Codex CLI
평가 점수: 32/100 (확인 없음 · 검수 대기)

테스트 명령이나 패키지 관리자 같은 저장소 규칙을 작업마다 다시 말하지 않아도, Codex가 작업 전에 먼저 읽고 시작합니다.

설명: 모든 저장소에 쓸 공통 규칙은 ~/.codex/AGENTS.md에, 저장소 규칙은 루트의 AGENTS.md에 적습니다. 폴더마다 다른 규칙은 그 폴더에 따로 두고, 마지막으로 Codex가 어떤 규칙을 읽었는지 확인합니다.

준비물: Codex CLI 설치 · Git 저장소 하나

입력값 (프롬프트의 {{이름}}에 넣는다):
- {{subdir}} 하위 폴더 (선택) 예: services/payments

본문:

## 준비

- Codex CLI 설치
- Git 저장소 하나

### 1. 전역 규칙 파일 만들기

`~/.codex` 폴더를 만들고 `AGENTS.md`에 모든 저장소에 공통인 선호를 적습니다. 예를 들면 JavaScript를 고친 뒤 npm test 실행, pnpm 우선, 운영 의존성 추가 전 확인 같은 규칙입니다. 빈 파일은 건너뛰므로 몇 줄이라도 적습니다.

```bash
mkdir -p ~/.codex
$EDITOR ~/.codex/AGENTS.md
```

### 2. 전역 규칙 적용 확인

승인 없이 한 번 실행해 지금 읽힌 지시를 요약하게 합니다.

```bash
codex --ask-for-approval never "Summarize the current instructions."
```

방금 적은 규칙이 답에 나오면 됩니다.

### 3. 저장소 루트에 AGENTS.md 추가

Git 저장소 루트의 `AGENTS.md`에 이 저장소만의 규칙을 적습니다. 예를 들면 PR 전 npm run lint 실행, 공개 유틸리티는 docs/에 문서화 같은 규칙입니다.

### 4. 하위 폴더에 덮어쓰기 규칙 추가

명령이 다른 하위 폴더에는 `AGENTS.override.md`를 만듭니다. 예를 들어 npm test 대신 make test-payments를 쓰게 합니다. 깊은 폴더의 지시가 위쪽 지시보다 우선합니다.

```bash
$EDITOR <하위 폴더>/AGENTS.override.md
```

### 5. 읽힌 규칙 순서 확인

하위 폴더 기준으로 실행해 읽은 지시의 출처를 나열하게 합니다.

```bash
codex --cd <하위 폴더> --ask-for-approval never "List the instruction sources you loaded."
```

전역 파일, 루트 `AGENTS.md`, 하위 폴더의 override 순서로 세 파일이 나오면 됩니다.

### 6. 다른 파일 이름 쓰기 (선택)

이미 다른 이름의 안내 파일이 있으면 `config.toml`에 대체 이름을 등록하고 크기 한도도 함께 조정합니다. 저장한 뒤 Codex를 다시 시작합니다.

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

이제 폴더마다 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md 순서로 찾습니다. 다시 시작한 뒤 출처 목록에 TEAM_GUIDE.md가 보이면 됩니다.

## 주의

- 합친 크기가 `project_doc_max_bytes`(기본 32 KiB)에 닿으면 그 뒤 파일은 읽지 않습니다. 한도를 올리거나 하위 폴더로 나눕니다.
- 현재 폴더보다 아래는 찾지 않습니다. 덮어쓰기 파일은 해당 작업 폴더 가까이에 둡니다.
- 규칙이 엉뚱하게 적용되면 위쪽 폴더나 Codex 홈의 `AGENTS.override.md`를 확인합니다.
- 지시 목록은 실행(세션)마다 한 번 만들어집니다. 바뀐 내용이 안 보이면 대상 폴더에서 Codex를 다시 시작합니다.
- 프로필이 헷갈리면 실행 전에 `echo $CODEX_HOME`으로 확인합니다.

주의:
- 합친 크기가 project_doc_max_bytes(기본 32 KiB)에 닿으면 이후 파일은 읽지 않음. 한도를 올리거나 하위 폴더로 나누기
- 현재 폴더보다 아래는 탐색하지 않음. 덮어쓰기 파일은 해당 작업 폴더 가까이에 두기
- 규칙이 엉뚱하면 위쪽 폴더나 Codex 홈의 AGENTS.override.md 확인
- 지시 목록은 실행(세션)마다 한 번 만들어짐. 바뀐 내용이 안 보이면 대상 폴더에서 Codex 다시 시작
- 프로필이 헷갈리면 실행 전 echo $CODEX_HOME 확인

출처:
- Custom instructions with AGENTS.md https://learn.chatgpt.com/docs/agent-configuration/agents-md