AGENTS.md 제대로 쓰는 법 — Codex를 팀원처럼 만드는 파일

지난번에 Claude Code의 CLAUDE.md에 대해 글을 썼는데, Codex를 쓰는 사람들한테서 "Codex는 그런 거 없냐"는 질문을 받았다. 있다. AGENTS.md다. 개념은 비슷한데, 재밌는 건 이게 Codex 전용이 아니라 거의 표준처럼 굳어지고 있다는 점이다.

Codex 처음 쓸 때 매번 "pnpm 써", "테스트는 vitest로 돌려", "이 폴더는 건드리지 마" 같은 걸 반복하다가, AGENTS.md 하나 써두니까 그 뒤로 Codex가 알아서 프로젝트 규칙을 지키더라. 한 번 세팅에 한 시간 정도 투자했는데, 그 효과는 계속 누적된다.

오늘은 이 AGENTS.md를 어떻게 쓰는지, 어떻게 써야 Codex가 잘 따르는지 정리해본다.

---

AGENTS.md가 뭔데

한 줄로 말하면, AI 코딩 에이전트에게 주는 프로젝트 설명서다. README가 사람을 위한 문서라면, AGENTS.md는 AI 에이전트를 위한 문서다.

OpenAI 공식 설명을 빌리면, AGENTS.md는 README.md와 비슷한 텍스트 파일인데, Codex에게 코드베이스를 어떻게 탐색하고, 어떤 명령어로 테스트하고, 프로젝트의 표준 관행을 어떻게 따르는지 알려주는 파일이다.

Codex는 사람 개발자와 마찬가지로 잘 구성된 개발 환경, 신뢰할 수 있는 테스트 설정, 명확한 문서가 있을 때 가장 잘 동작한다. AGENTS.md가 바로 그 "명확한 문서" 역할을 한다.

---

AGENTS.md는 사실 Codex만의 것이 아니다

이게 CLAUDE.md와의 가장 큰 차이점이자 AGENTS.md의 강점이다. AGENTS.md는 여러 AI 도구가 공통으로 지원하는 사실상의 표준이 됐다.

AGENTS.md를 지원하는 도구들:
- OpenAI Codex
- GitHub Copilot (2025년 8월부터 네이티브 지원)
- Cursor
- Google Jules / Gemini
- Windsurf
- Zed
- Aider
- Factory, Amp, RooCode 등

무슨 뜻이냐면, AGENTS.md 하나만 잘 써두면 Codex를 쓰든 Copilot을 쓰든 Cursor를 쓰든 같은 설정이 적용된다는 거다. 도구마다 별도 설정 파일(.cursorrules, CLAUDE.md 등)을 따로 관리할 필요가 없다.

💡 팀에서 여러 AI 도구를 섞어 쓰는 경우라면 AGENTS.md가 특히 유용하다. 한 곳에서 관리하면 모두가 같은 규칙을 공유한다.

이 표준은 일부러 스키마 없이 단순하게 유지된다. 그냥 평범한 마크다운이고, 정해진 구조가 없다. 이 유연함 덕분에 빠르게 퍼졌다.

---

AGENTS.md 만들기

프로젝트 루트에 AGENTS.md 파일을 만들면 된다.

touch AGENTS.md

Codex는 저장소에서 AGENTS.md 파일을 자동으로 찾아서 읽는다. 별도 설정이 필요 없다. 파일을 만들고 내용을 채우기만 하면 된다.

---

핵심 원칙: 설명보다 명령어를 먼저

가장 효과적인 AGENTS.md의 공통점이 하나 있다. 설명(explanation)보다 명령어(command)를 앞세운다는 거다.

OpenAI 샘플과 여러 베스트 프랙티스에서 권장하는 순서:

1. 셋업(setup) 명령어 — 가장 먼저
2. 테스트(testing) 명령어 — 두 번째
3. 배포(deployment) 명령어 — 세 번째
4. 디버깅(debugging) — 마지막

왜냐하면 Codex는 에이전트라서, "이 코드는 클린 아키텍처를 따르고 도메인 주도 설계를..." 같은 추상적인 설명보다 "테스트는 pnpm test로 돌려라" 같은 구체적인 명령어에 훨씬 잘 반응한다. 에이전트한테 필요한 건 철학 강의가 아니라 실행 가능한 지시다.

---

잘 쓴 AGENTS.md 예시

내가 실제로 쓰는 구조다. 그대로 가져다 수정해서 써도 된다.

# AGENTS.md

## 프로젝트 개요
Next.js 14 기반 SaaS 대시보드. 사용자 구독 관리 및 사용량 추적 서비스.

## 개발 환경 셋업
- 의존성 설치: `pnpm install`
- 환경변수: `.env.example`을 복사해서 `.env.local` 생성
- DB 준비: `pnpm prisma migrate dev`
- 개발 서버: `pnpm dev`

## 테스트
- 전체 테스트: `pnpm test`
- 특정 파일: `pnpm test <파일명>`
- 커버리지: `pnpm test:coverage`
- 작업 완료 전에 반드시 `pnpm test`와 `pnpm typecheck`를 통과시킬 것

## 빌드 & 배포
- 빌드: `pnpm build`
- 린트: `pnpm lint`
- 배포: main 브랜치 푸시 시 Vercel 자동 배포

## 아키텍처 (코드만 봐서는 모를 수 있는 것들)
- 모든 DB 접근은 `src/lib/repository.ts`를 통해서만 (raw SQL 금지)
- `src/payments/` 모듈은 별도의 인증 흐름을 가짐 (`src/auth/`와 분리)
- API 응답은 `src/core/errors.ts`의 ErrorResponse 클래스 사용
- 클라이언트 컴포넌트는 최상단에 'use client' 명시

## 코딩 컨벤션
- 모든 새 코드는 TypeScript로 작성
- 각 파일의 기존 코드 스타일을 따를 것
- 컴포넌트: PascalCase, 유틸 함수: camelCase
- 들여쓰기 2칸, 세미콜론 사용

## 하지 말아야 할 것
- 새 프로덕션 의존성 추가 시 PR에서 먼저 논의 ([ASSUMPTION]으로 후보 명시)
- console.log를 프로덕션 코드에 남기지 말 것
- any 타입 사용 금지
- .env 파일 커밋 금지

## 작업 완료 전 체크리스트
- [ ] 테스트 통과 (`pnpm test`)
- [ ] 타입 체크 통과 (`pnpm typecheck`)
- [ ] 린트 통과 (`pnpm lint`)

## PR 메시지 규칙
- conventional commit 형식 사용 (feat:, fix:, refactor: 등)
- 변경 이유와 영향 범위를 본문에 명시

---

특히 중요한 섹션들

1. "코드만 봐서는 모르는 것"을 적어라

Codex는 코드를 읽고 많은 걸 추론한다. 그러니까 AGENTS.md에는 코드만 봐서는 추론할 수 없는 구조적 규칙을 적는 게 효과적이다.

✅ 좋은 예 (코드만으로는 모를 정보)
- 모든 DB 접근은 src/db/repository.py를 통해서만, 다른 곳에서 raw SQL 금지
- src/payments/ 모듈은 src/auth/와 분리된 별도 인증 흐름을 가짐
- 에러 응답은 src/core/errors.py의 ErrorResponse 클래스 사용

❌ 굳이 안 적어도 되는 것 (코드 보면 아는 것)
- 이 프로젝트는 React를 사용합니다 (package.json 보면 앎)
- 함수는 function 키워드로 정의합니다 (코드 보면 앎)

코드를 봐서 알 수 있는 건 Codex가 알아서 파악한다. 코드 어디에도 안 적혀있는 암묵적 규칙, 팀의 약속, 아키텍처 의도 — 이런 걸 적어야 가치가 있다.

2. "작업 완료 전 검증" 규칙

이게 진짜 중요하다. Codex는 가끔 자신감 넘치게 틀린 코드를 만든다. 특히 학습 데이터가 적은 프레임워크나 코드베이스에서. 그래서 AGENTS.md에 "작업을 완료했다고 선언하기 전에 무엇을 해야 하는지"를 명시해두는 게 좋다.

## 작업 완료 전 반드시
1. `pnpm test` 실행해서 전부 통과 확인
2. `pnpm typecheck`로 타입 에러 없는지 확인
3. `pnpm lint` 통과 확인
4. 위 셋 중 하나라도 실패하면 수정 후 재실행

이렇게 해두면 Codex가 코드를 던지고 끝내는 게 아니라, 스스로 검증하고 마무리한다. 테스트, 린터, 타입 체커는 선택이 아니다. Codex 출력을 무조건 신뢰하지 말고, 검증을 거치게 만들어야 한다.

3. PR 메시지 규칙

Codex는 GitHub Pull Request를 만들 수 있는데, AGENTS.md에 PR 메시지 형식을 지정해두면 일관된 PR을 만든다.

## PR 규칙
- 제목은 conventional commit 형식
- 본문에 "무엇을, 왜" 변경했는지 명시
- Breaking change가 있으면 명확히 표시
- 관련 이슈 번호 링크

---

계층 구조 — AGENTS.md도 여러 위치에 둘 수 있다

AGENTS.md도 디렉토리 계층에 따라 여러 개를 둘 수 있다. Codex는 가까운 파일, 중첩된(nested) 파일을 우선시한다.

my-monorepo/
├── AGENTS.md              ← 전체 공통 규칙
├── packages/
│   ├── frontend/
│   │   └── AGENTS.md      ← 프론트엔드 전용
│   └── backend/
│       └── AGENTS.md      ← 백엔드 전용

packages/frontend/에서 작업하면 루트 + 프론트엔드 AGENTS.md가 같이 적용된다. 모노레포에서 패키지마다 다른 규칙을 줄 때 유용하다. 가까운 파일일수록 더 큰 영향을 준다는 점만 기억하자.

---

효과 없는 AGENTS.md 피하기

CLAUDE.md 글에서도 다뤘지만, AI 설정 파일의 함정은 비슷하다.

1. 추상적인 성격 지시는 효과 없다

❌ 효과 없음
- 시니어 개발자처럼 신중하게 작업해줘
- 최선을 다해서 깔끔한 코드를 작성해줘
- 항상 모범 사례를 따라줘

이런 건 그럴듯해 보이지만 Codex의 행동을 측정 가능하게 바꾸지 못한다. 구체적인 규칙으로 바꿔야 한다.

✅ 효과 있음
- 함수는 한 가지 일만 하도록, 20줄 넘으면 분리
- 모든 public 함수에 JSDoc 주석
- 에러는 throw하지 말고 Result 타입으로 반환

2. 너무 길면 핵심이 묻힌다

토큰 한도가 있다(Codex는 보통 128k~192k 토큰). AGENTS.md가 길수록 실제 작업을 위한 컨텍스트가 줄어든다. 중요한 규칙만 간결하게.

3. AGENTS.md만으로 모든 걸 막을 순 없다

이건 솔직하게 알아둬야 한다. OpenAI 문서에서도 명시하는데, AGENTS.md는 규칙을 항상 보이게(always-on) 만들어서 위반을 줄이는 거지, 완전히 없애는 게 아니다.

그러니까 되돌릴 수 없거나 비용이 큰 작업(프로덕션 배포, DB 작업, 인증 정보 변경 같은)은 AGENTS.md 지시만 믿지 말고, 승인 게이트(approval gate)나 샌드박스 설정을 같이 써야 한다. 규칙을 적어두는 것과 강제하는 것은 다른 문제다.

# config.toml에서 승인 정책 설정
approval_policy = "on-request"
# 위험한 작업은 무조건 사람 승인을 거치게

---

AGENTS.md + config.toml 조합

AGENTS.md가 "무엇을, 어떻게" 작업할지 알려주는 거라면, config.toml은 Codex의 권한과 동작을 제어한다. 둘을 같이 쓰면 마찰이 크게 줄어든다.

AGENTS.md      → 프로젝트 규칙, 명령어, 컨벤션 (무엇을 할지)
config.toml    → 승인 정책, 샌드박스, 모델 설정 (어떻게 동작할지)

실제로 대부분의 지속적인 마찰은 이 둘이 프로젝트의 실제 동작 방식을 제대로 반영하면 사라진다. Codex가 일상적인 작업마다 자꾸 승인을 요청하면 신뢰할 수 있는 저장소에 한해 승인 정책을 완화하고, 파일을 못 쓰면 샌드박스 모드를 확인하는 식으로.

---

실전 팁

1. 작게 시작해서 키워가자

처음부터 완벽한 AGENTS.md를 쓰려고 하지 마라. 셋업 명령어, 테스트 명령어, 핵심 규칙 몇 개로 시작하고, 작업하면서 "이거 매번 설명하네" 싶은 게 나올 때마다 추가하자.

2. Git에 커밋하자

AGENTS.md를 저장소에 커밋하면 버전 관리되고, 리뷰 가능하고, 팀 전체가 일관되게 쓴다. 신입이 들어와도 Codex가 프로젝트 규칙을 이미 알고 있는 셈이다.

3. 명령어가 진짜 동작하는지 확인하자

AGENTS.md에 적은 명령어가 실제로 동작하는지 확인하자. pnpm test라고 적었는데 실제로는 npm run test면 Codex가 헷갈린다. 명령어는 정확하게.

4. "왜"를 적으면 더 잘 따른다

❌ "raw SQL 쓰지 마"
✅ "raw SQL 쓰지 마 (마이그레이션 추적이 안 되고 환경 간 스키마 불일치가 생김)"

이유를 적으면 Codex가 규칙의 의도를 이해하고 비슷한 상황에서도 일관되게 판단한다.

5. 검증을 항상 강제하자

다시 강조하지만, "작업 완료 전 테스트/타입체크/린트 통과" 규칙은 꼭 넣자. Codex 출력을 그냥 믿지 말고 검증을 거치게 만드는 것. 이게 안정적인 워크플로우의 핵심이다.

---

CLAUDE.md vs AGENTS.md

둘 다 써본 입장에서 비교하면:

공통점
- 둘 다 AI 에이전트에게 주는 프로젝트 설명서
- 세션마다 자동 로드
- 계층 구조 지원 (글로벌/프로젝트/하위)
- 마크다운 형식

차이점
- AGENTS.md: 범용 표준. Codex, Copilot, Cursor 등 여러 도구가 공통 지원
- CLAUDE.md: Claude Code 전용. Auto Memory 같은 Claude 고유 기능과 연동

여러 도구를 섞어 쓴다면 AGENTS.md가 관리 부담이 적다. Claude Code만 쓴다면 CLAUDE.md의 고유 기능(Auto Memory, @import 등)을 활용하는 게 낫고. 실제로 두 파일을 다 두고, 공통 내용은 한쪽에 쓰고 다른 쪽에서 참조하는 사람들도 있다.

---

마무리

AGENTS.md는 Codex를 "일회성 도구"가 아니라 "설정하고 개선해나가는 팀원"으로 만드는 핵심이다. OpenAI 표현을 빌리면 "지속적인 가이드(durable guidance)"를 두는 곳이다.

핵심 정리:

• AGENTS.md는 AI 에이전트에게 주는 프로젝트 설명서, 저장소 루트에 두면 자동 로드
• Codex 전용이 아니라 Copilot, Cursor 등 여러 도구가 지원하는 사실상 표준
• 설명보다 명령어를 먼저 (셋업 → 테스트 → 배포 → 디버깅 순)
• "코드만 봐서는 모르는" 구조적 규칙을 적어야 가치 있다
• "작업 완료 전 검증" 규칙을 꼭 넣자. Codex 출력을 무조건 믿지 말 것
• 추상적 성격 지시는 효과 없다. 구체적이고 측정 가능하게
• 되돌릴 수 없는 작업은 AGENTS.md만 믿지 말고 승인 게이트/샌드박스를 같이 쓰자
• Git에 커밋해서 팀과 공유하자