Codex에서 AGENTS.md로 커스텀 인스트럭션 관리하기

Codex에서 AGENTS.md로 커스텀 인스트럭션 관리하기

Codex를 쓰다 보면 이런 생각이 든다.

“이 레포에서는 항상 lint를 먼저 돌렸으면 좋겠는데…”

“결제 서비스 쪽은 테스트 방식이 다른데 매번 설명하기 귀찮다…”

Codex는 이런 반복 설명을 없애기 위해 AGENTS.md라는 메커니즘을 제공한다.
이 파일을 통해 프로젝트 전반 혹은 디렉토리 단위로 Codex의 행동 규칙을 정의할 수 있다.

이번 글에서는 AGENTS.md가 무엇인지, 어떻게 로드되고, 실무에서 어떻게 활용하면 좋은지 정리해본다.

---

AGENTS.md란?

AGENTS.md는 Codex가 작업을 시작하기 전에 읽는 지침 파일이다.
사람으로 치면 “팀의 작업 규칙 문서”를 Codex에게 미리 읽히는 느낌이다.

• 코딩 스타일
• 테스트 실행 규칙
• 의존성 추가 시 주의사항
• 특정 디렉토리의 특수 룰

같은 내용을 프롬프트에 매번 적지 않아도 Codex가 자동으로 인지한다.

---

Codex는 AGENTS.md를 어떻게 찾을까?

Codex는 실행 시 Instruction Chain을 한 번 구성한다.
(TUI 기준으로는 세션 시작 시 1회)

우선순위 개요

1. Global scope
2. Project scope
3. Merge (아래로 갈수록 우선)

1️⃣ Global scope (전역 규칙)

Codex 홈 디렉토리(~/.codex)에서 먼저 찾는다.

우선순위:

1. AGENTS.override.md
2. AGENTS.md

둘 다 있으면 override만 사용한다.

mkdir -p ~/.codex

~/.codex/AGENTS.md

Working agreements

• JavaScript 파일 수정 후 항상 npm test 실행
• 패키지 설치는 pnpm 우선
• 프로덕션 의존성 추가 전 반드시 확인 요청

이제 어떤 레포에서 Codex를 실행해도 이 규칙이 기본으로 적용된다.

---

2️⃣ Project scope (프로젝트 / 디렉토리 규칙)

Codex는 프로젝트 루트부터 현재 디렉토리까지 내려오면서 다음 순서로 파일을 찾는다.

1. AGENTS.override.md
2. AGENTS.md
3. fallback 파일명 (설정 시)

각 디렉토리당 최대 1개만 로드한다.

# AGENTS.md (레포 루트)

## Repository expectations

- PR 전에 `npm run lint` 실행
- 공개 유틸 변경 시 `docs/` 문서 업데이트

---

3️⃣ 디렉토리별 override

특정 서비스나 팀에서 완전히 다른 규칙이 필요하다면 AGENTS.override.md를 쓴다.

# services/payments/AGENTS.override.md

## Payments service rules

- 테스트는 `make test-payments` 사용
- API 키 로테이션 시 보안 채널 공지 필수

이 상태에서 payments 디렉토리에서 Codex를 실행하면:

1. ~/.codex/AGENTS.md
2. 루트 AGENTS.md
3. services/payments/AGENTS.override.md

순서로 합쳐진 지침을 사용한다.

⚠️ override가 있으면 같은 디렉토리의 AGENTS.md는 무시된다.

---

지침 병합(Merge) 규칙

• 루트 → 하위 디렉토리 순서로 연결
• 나중에 등장한 지침이 더 우선
• 빈 파일은 무시
• 전체 크기가 project_doc_max_bytes(기본 32KB)를 넘으면 중단

즉, 현재 작업 위치에 가까울수록 더 강한 규칙이 된다.

---

기존 문서 파일을 AGENTS로 쓰고 싶다면?

이미 TEAM_GUIDE.md 같은 파일을 쓰고 있다면 fallback 파일명으로 등록할 수 있다.

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

이제 Codex는 다음 순서로 탐색한다:

1. AGENTS.override.md
2. AGENTS.md
3. TEAM_GUIDE.md
4. .agents.md

---

CODEX_HOME으로 프로필 분리하기

프로젝트 전용 Codex 프로필이 필요할 수도 있다.

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

• 자동화 계정
• CI용 Codex
• 실험용 설정

등을 분리해서 관리 가능하다.

---

설정이 잘 적용됐는지 확인하는 방법

현재 로드된 지침 요약

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

어떤 파일들이 활성화됐는지 확인

codex --cd services/payments --ask-for-approval never \
"Show which instruction files are active."

로그 확인

• ~/.codex/log/codex-tui.log
• 또는 session-*.jsonl

---

문제 해결 체크리스트

❌ 아무 것도 안 불러와질 때

• 파일이 비어 있지 않은지
• 올바른 디렉토리에서 실행 중인지
• codex status의 workspace root 확인

❌ 엉뚱한 규칙이 적용될 때

• 상위 디렉토리나 ~/.codex에 AGENTS.override.md 존재 여부

❌ fallback 파일이 무시될 때

• project_doc_fallback_filenames 오타
• Codex 재시작 여부

❌ 지침이 잘릴 때

• project_doc_max_bytes 증가
• 디렉토리별로 파일 분리

---

마무리

AGENTS.md는 Codex를
**“똑똑한 범용 AI” → “우리 팀에 맞춰진 동료”**로 바꿔주는 장치다.

• 반복 프롬프트 제거
• 팀 규칙의 자동 적용
• 디렉토리별 맥락 유지

Codex를 실무에서 제대로 쓰고 있다면,
AGENTS.md는 거의 필수에 가깝다.

👉 다음 단계로는 Prompting Codex 가이드를 함께 보면 궁합이 좋다.

---

원하면:
- **사내 기술 블로그 톤**으로 더 딱딱하게
- **개인 블로그용**으로 경험담 섞어서
- **예제 위주 / 그림 설명용 구조**

로도 다시 다듬어줄게.