공식 참고 자료: AGENTS.md 가이드 · Config Basics · CLI Slash Commands · Best Practices
커리큘럼 흐름
- Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프
- Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙 ← 현재 문서
- Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인
- Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
- Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기
- Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임
- Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결
- Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영
- Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기
- Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
- Codex 검증 루프 — 머지 전에 동작을 증명하기
- Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
- Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
- Codex 팀 딜리버리 플레이북 — 중급 레인 운영
- Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
- Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
- Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
- Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
- Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
- Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
- Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기
이 문서에서 참고한 공식 문서
- 전역 지침 + 프로젝트 override를 합치는 방식 — Custom instructions with AGENTS.md
- 기본 model / approval / sandbox 설정 예시 — Config basics
- 현재 디렉터리에
AGENTS.md초안을 만드는/init— CLI Slash Commands
왜 AGENTS.md가 핵심인가
프롬프트만 길게 쓰는 방식은 매번 같은 맥락을 다시 설명해야 합니다. Codex 공식 가이드는 이 문제를 instruction chain으로 해결합니다.
즉,
- 오늘 해야 하는 일은 프롬프트에
- 저장소의 지속 규칙은 **
AGENTS.md**에 - Codex의 실행 성향은 config에
나눠 넣는 구조입니다.
Codex는 지시문을 어떻게 모으나
공식 AGENTS 가이드에 따르면 Codex는 작업 전에 여러 지침 파일을 합칩니다.
~/.codex/AGENTS.override.md또는~/.codex/AGENTS.md- 프로젝트 루트부터 현재 디렉터리까지의
AGENTS.override.md/AGENTS.md - 현재 디렉터리에 가까운 파일일수록 뒤에서 적용되어 override 효과를 냄
실무 감각으로 번역하면 이렇습니다.
- 홈 디렉터리 파일 = 내 개인 작업 습관
- 저장소 루트 파일 = 팀 공통 규칙
- 하위 폴더 파일 = 특정 도메인 예외
/init은 시작점이지 완성본이 아니다
Slash commands 문서에서 /init은 현재 디렉터리에 AGENTS.md scaffold를 생성하는 명령입니다.
초안 생성용으로 아주 좋지만, 그대로 두면 대개 너무 일반적입니다.
/init 이후에는 최소한 아래를 직접 손보세요.
- 실제 검증 명령
- 금지해야 할 경로
- 프로젝트의 source of truth
- 의존성 추가, migration, generated file에 대한 규칙
무엇을 어디에 둘까
| 표면 | 넣어야 할 것 | 넣지 말아야 할 것 |
|---|---|---|
AGENTS.md |
코딩 규칙, 테스트 명령, 안전 경계, 구조 설명 | 오늘 한 번만 필요한 작업 |
config.toml |
model, approval policy, sandbox mode | 비즈니스 규칙, 도메인 정책 |
| 프롬프트 | 현재 목표, 제약, 완료 조건 | 저장소의 영구 규칙 |
이 분리가 되면 프롬프트가 짧아지고, Codex의 동작도 덜 흔들립니다.
좋은 AGENTS.md의 최소 구성
공식 문서와 실제 사용 경험을 합치면 아래 네 섹션이 가장 중요합니다.
1. 프로젝트 컨텍스트
## 프로젝트 컨텍스트
- Next.js 16 App Router 앱
- 문서는 content/{locale}/{tool}/*.mdx 에 있음
- UI 컴포넌트는 src/components/ 아래에 있음2. 작업 원칙
## 작업 원칙
- 작은 diff 우선
- 새 의존성 추가 전 승인 필요
- 기존 패턴 재사용 우선3. 검증
## 검증
- npm run lint
- npm run build
- 실패 시 완료라고 주장하지 말 것4. 하지 말 것
## 하지 말 것
- 생성 파일 직접 수정 금지
- 민감 정보 커밋 금지
- 근거 없이 public API 변경 금지nested AGENTS는 예외일 때만
하위 디렉터리마다 AGENTS.md를 두는 건 강력하지만, 남발하면 혼란이 커집니다.
좋은 기준은 하나입니다.
그 폴더만의 규칙이 정말 다른가?
좋은 예:
apps/web/AGENTS.md— 렌더링/UI 규칙infra/AGENTS.md— 배포/보안 경계
좋지 않은 예:
- 루트 파일 내용을 거의 복붙만 한 하위 AGENTS
config에서 먼저 손볼 것
Config basics 문서에서 가장 자주 조정하는 항목은 아래입니다.
model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"여기서 중요한 포인트는 “최신 모델 이름”보다도 팀의 기본값을 명시해둔다는 점입니다.
AGENTS.md가 프로젝트 사고방식을 고정한다면, config는 실행 성향을 고정합니다.
프롬프트는 이슈처럼 쓰자
지시문이 좋아도 작업 프롬프트가 모호하면 결과는 흔들립니다. 그래서 Codex best practices는 프롬프트를 GitHub issue처럼 구조화하라고 권합니다.
짧게 정리하면:
- Goal
- Context
- Constraints
- Done when
이 네 줄기만 있어도 Codex는 덜 추측합니다.
흔한 실수
1. 모든 규칙을 프롬프트에만 적기
매번 반복되고, 세션마다 품질 편차가 커집니다.
2. AGENTS.md를 가치판단 없는 장문 설명서로 만들기
역사나 배경보다 실행 기준이 중요합니다.
3. 검증 명령이 실제 저장소와 맞지 않기
안 돌아가는 명령을 써두면 Codex도 사람도 함께 속습니다.
4. nested AGENTS를 너무 많이 두기
override가 많을수록 예측이 어려워집니다.
한 줄 정리
/init으로 초안을 만들고AGENTS.md에 저장소 규칙을 넣고- config에 실행 기본값을 넣고
- 오늘의 목표는 프롬프트에 남기세요.
이 분리만 잘해도 Codex는 훨씬 덜 흔들립니다.