Chapter 05. AGENTS.md의 모든 것
Codex를 처음 쓰면 많은 사람이 프롬프트부터 고치기 시작한다. 그런데 실무에서 더 큰 차이를 만드는 건 종종 프롬프트가 아니라 AGENTS.md다. 같은 모델, 같은 레포, 같은 작업이라도 AGENTS.md가 잘 잡혀 있으면 Codex는 "대충 그럴듯한 코드 생성기"가 아니라 "이 프로젝트의 룰을 이해한 작업 파트너"처럼 행동한다.
쉽게 말해 AGENTS.md는 AI에게 주는 프로젝트 인수인계 문서다. 사람 신입 개발자에게 "우린 pnpm 쓰고, 테스트는 Vitest고, app/api 밖에는 API 만들지 말고, generated/는 손대지 마세요"라고 알려주듯이, Codex에게도 같은 정보를 미리 주는 것이다. 이 파일 하나가 있으면 매 세션마다 같은 말을 반복할 필요가 줄어든다.12
이번 장에서는 AGENTS.md를 단순 소개 수준이 아니라, 실제로 Codex 품질을 바꾸는 핵심 도구로 다룬다. 어디에 두는지, 여러 개가 있을 때 무엇이 우선하는지, override는 언제 쓰는지, 왜 어떤 AGENTS.md는 팀을 살리고 어떤 AGENTS.md는 팀을 지치게 만드는지까지 한 번에 정리해보자.
이미지 출처: Anastasia Shuraeva on Pexels
AGENTS.md는 무엇이고, 왜 이렇게 중요한가
README가 사람을 위한 문서라면, AGENTS.md는 에이전트를 위한 문서다. README가 "이 프로젝트가 무엇인지"를 설명한다면, AGENTS.md는 "이 프로젝트에서 어떻게 일해야 하는지"를 알려준다.23
이 차이는 생각보다 크다. 예를 들어 Next.js + Supabase 프로젝트에서 Codex에게 "로그인 버그 고쳐줘"라고만 말하면, AI는 자신이 익숙한 일반적인 방식으로 움직인다. 어떤 경우엔 npm을 쓰고, 어떤 경우엔 Jest를 깔고, 어떤 경우엔 pages/api에 코드를 만든다. 하지만 AGENTS.md에 "패키지 매니저는 pnpm", "테스트는 Vitest", "인증은 Supabase Auth", "라우트는 App Router 기준 app/api/", "DB 변경은 migration 생성으로만"이 적혀 있으면, Codex는 첫 시도부터 훨씬 덜 엇나간다.12
즉 AGENTS.md의 역할은 똑똑함을 추가하는 게 아니라, 엉뚱함을 줄이는 것이다. 실무에서 생산성을 갉아먹는 건 종종 모델의 지능 부족이 아니라, 프로젝트 문맥 부재다. AGENTS.md는 바로 그 문맥을 고정한다.
Codex에서 AGENTS.md가 읽히는 방식
여기서 중요한 포인트가 하나 있다. Codex는 AGENTS.md를 하나만 읽지 않는다. 현재 작업 디렉터리를 기준으로 파일 시스템을 따라 내려가며 여러 지점의 문서를 모아서 읽는다. 공식 가이드 기준으로 각 디렉터리 레벨에서는 다음 순서로 문서를 찾는다. AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md 순서다. 이 목록에 없는 이름은 자동 발견 대상이 아니다.1
핵심은 두 가지다. 첫째, 가까운 문서가 더 강하다. 둘째, 같은 레벨에서는 override가 일반 AGENTS.md보다 우선한다.14
예를 들어 이런 구조를 보자.
~/.codex/AGENTS.md
my-superapp/
AGENTS.md
apps/
web/
AGENTS.md
api/
AGENTS.override.mdapps/web에서 작업하면 전역 규칙, 레포 루트 규칙, apps/web 규칙이 함께 읽힌다. 반면 apps/api에서 작업하면 apps/api/AGENTS.override.md가 그 레벨의 일반 AGENTS.md를 대신한다. 그래서 API 폴더에 더 강한 제약을 걸고 싶을 때 override가 유용하다.14
이 구조를 이해하지 못하면 이상한 일이 자주 생긴다. 분명 루트 AGENTS.md를 수정했는데 Codex가 말을 안 듣는 것처럼 보이는 순간이 온다. 실제로는 더 깊은 디렉터리의 규칙이 이미 우선하고 있었던 경우가 많다.
글로벌, 프로젝트, 디렉터리별 우선순위
실무에서는 AGENTS.md를 세 층으로 생각하면 이해가 쉽다.
글로벌: 내 개인 기본 습관
프로젝트 루트: 이 레포 전체의 공통 규칙
하위 디렉터리: 특정 패키지나 서비스만의 특수 규칙
글로벌 파일은 보통 ~/.codex/AGENTS.md에 둔다. 여기에 넣을 것은 "내가 어디서나 선호하는 일하는 방식"이다. 예를 들면 "새 공개 함수에는 테스트를 우선 고려", "가능하면 작은 diff 선호", "기존 린터 규칙을 우회하지 말 것" 같은 내용이다.25
반대로 프로젝트 루트의 AGENTS.md에는 레포에 종속된 사실이 들어가야 한다. 예를 들어 다음과 같다.
이 저장소는 Next.js App Router + Supabase + pnpm 기반이다.
개발 서버는
pnpm dev, 테스트는pnpm test, 타입체크는pnpm typecheck다.환경 변수는
src/env.ts를 통해 접근한다.supabase/migrations/의 기존 파일은 수정하지 않는다.
하위 디렉터리 AGENTS.md는 더 좁고 더 구체적이어야 한다. 예를 들어 apps/api/AGENTS.md라면 Express + MongoDB 서비스 전용 규칙만 넣는 식이다. "모든 DB 접근은 repository 레이어에서만", "mongoose schema 수정 시 fixture도 갱신", "에러 응답은 공통 핸들러를 통한다" 같은 내용이 여기에 어울린다.
이렇게 분리하는 이유는 단순하다. 글로벌에 프로젝트 정보를 넣으면 모든 레포에서 잡음이 생기고, 루트 파일에 모든 세부 규칙을 몰아넣으면 길어져서 정작 필요한 지점의 정보가 묻힌다. 좋은 AGENTS.md는 한 파일이 똑똑한 게 아니라, 계층 전체가 역할 분담을 잘하는 것이다.
AGENTS.md와 CLAUDE.md는 무엇이 다른가
한국 개발자 독자라면 이 질문이 가장 먼저 떠오를 수 있다. "이거 결국 Claude Code의 CLAUDE.md 비슷한 거 아닌가요?" 맞다. 개념적으로는 많이 닮았다. 둘 다 에이전트에게 프로젝트 규칙을 주는 문서다. 하지만 실무에서 느끼는 차이는 꽤 분명하다.
첫째, Codex에서 AGENTS.md는 기본 문서다. Codex는 AGENTS.md 계층을 중심으로 규칙을 발견하고 합친다. 즉 이 파일이 Codex 세계의 중심축이다.1
둘째, AGENTS.md는 도구 중립성을 확보하기 좋다. AGENTS.md는 Codex 전용 문법이 아니라 점점 여러 에이전트가 읽는 공통 포맷으로 자리 잡고 있다. 오픈 포맷으로 발전하면서 여러 도구가 채택하고 있기 때문에, 팀이 Codex와 다른 툴을 함께 쓰는 경우에도 공통 프로젝트 규칙을 하나로 유지하기 좋다.36
셋째, 역할 분리가 더 쉬운 편이다. 실무에서는 보통 이렇게 가져가면 덜 헷갈린다. 공통 레포 규칙은 AGENTS.md에 두고, 도구 고유 기능이나 권한 정책은 도구별 파일에 둔다. 예를 들어 "이 저장소는 pnpm, Vitest, Conventional Commits"는 AGENTS.md에 두고, Claude Code 전용 설정이나 특정 도구 UI에만 통하는 제약은 별도 문서에 두는 식이다.67
결론적으로 비교하면 이렇다. CLAUDE.md가 'Claude에게 주는 운영 매뉴얼'이라면, AGENTS.md는 '프로젝트 자체의 공용 운영 규칙집'에 더 가깝다. 그래서 팀 차원에서는 AGENTS.md를 중심축으로 잡아두는 편이 장기적으로 관리하기 쉽다.
좋은 AGENTS.md는 무엇을 담아야 하나
좋은 AGENTS.md는 길어서 좋은 것이 아니다. AI가 정말 몰라서 틀릴 만한 것만 적어야 한다. 실무에서 효과가 큰 내용은 보통 다음 다섯 묶음이다.25
필수 명령어: build, test, lint, dev, typecheck
구조 설명: 어디에 무엇을 두는지, 어떤 계층이 어떤 책임을 갖는지
비자명한 규칙: 코드만 읽어선 알기 어려운 팀 규칙
금지 구역: 손대면 안 되는 폴더, 생성 파일, 운영 설정
완료 기준: 무엇을 해야 "끝났다"고 볼지
예를 들어 Next.js + Supabase 프로젝트의 루트 AGENTS.md는 아래처럼 시작하면 충분히 강하다.
# AGENTS.md
## Stack
- Next.js App Router, TypeScript strict, Tailwind CSS
- Auth and DB: Supabase
- Package manager: pnpm
## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`
## Structure
- `app/`: routes, layouts, server actions
- `components/`: reusable UI
- `lib/`: clients and shared utilities
- `supabase/`: migrations and local config
## Rules
- Use `pnpm`, never `npm`
- All new API routes go under `app/api/`
- Never edit existing files in `supabase/migrations/`; create a new migration
- Access env only through `src/env.ts`
## Done when
- Relevant tests pass
- Typecheck passes
- Changed behavior includes test updates이 문서가 좋은 이유는 멋있어서가 아니다. Codex가 틀리기 쉬운 지점을 정확히 막기 때문이다. "좋은 코드를 써라" 같은 문장은 도움이 거의 안 된다. 반면 "npm 쓰지 마라", "migration은 새 파일만 추가"는 바로 행동을 바꾼다.23
나쁜 AGENTS.md는 왜 망하는가
반대로 실패하는 AGENTS.md에도 패턴이 있다.
첫 번째는 추상적이다. "깔끔하게 작성", "베스트 프랙티스 준수", "안전하게 변경" 같은 문장은 사람에게도 애매한데, 모델에게는 거의 배경 소음이다.
두 번째는 README를 통째로 옮겨놓는다. 제품 소개, 회사 연혁, 회고, 마케팅 메시지까지 들어간 AGENTS.md는 길기만 하고 실전 가치가 낮다. 에이전트는 사용법보다 작업 규칙이 필요하다.23
세 번째는 비밀 정보를 넣는다. API 키, 운영 URL, 토큰, 내부 접근 절차 같은 것은 절대로 넣으면 안 된다. AGENTS.md는 대개 버전 관리에 들어가므로, 여기엔 규칙만 있어야 한다.2
네 번째는 한 파일에 모든 걸 쑤셔 넣는다. 모노레포 루트 AGENTS.md 하나에 웹, API, 배치, 인프라 규칙을 전부 넣으면 결국 핵심이 안 보인다. 이런 경우 Codex는 중요도가 낮은 설명을 많이 읽고, 정작 현재 패키지에 꼭 필요한 규칙은 희미해진다.
재미있게 비유하면, 좋은 AGENTS.md는 현장 반장이고 나쁜 AGENTS.md는 회사 홍보 브로슈어다. 현장에서는 브로슈어가 아니라 "헬멧 쓰고, 여기선 우회전 금지, 위험 구역은 출입 금지"가 필요하다.
AGENTS.override.md는 언제 써야 하나
override는 이름이 주는 느낌 그대로, 같은 레벨의 일반 AGENTS.md를 대신하는 파일이다. 즉 추가 설명이 아니라 대체다.14
이게 빛나는 순간은 두 가지다.
하나는 임시 작업 모드다. 예를 들어 오늘 밤 결제 장애를 잡아야 한다고 하자. 잠깐 동안만 "services/payments/를 바꾸면 반드시 결제 테스트를 먼저 돌릴 것", "관련 없는 실패는 건드리지 말 것" 같은 강한 규칙을 쓰고 싶을 수 있다. 이럴 때 글로벌이나 해당 디렉터리에 AGENTS.override.md를 두면 기존 문서를 건드리지 않고 임시 모드로 전환할 수 있다.4
다른 하나는 서브시스템 성격이 완전히 다를 때다. 예를 들어 루트는 일반 웹앱 규칙인데 infra/는 Terraform과 GitHub Actions 위주라면, 단순 추가 규칙보다 완전히 다른 실행 규칙이 필요할 수 있다. 이런 경우 infra/AGENTS.override.md로 별도 세계를 만드는 편이 낫다.
다만 override는 강력한 만큼 남용하면 독이 된다. 여기저기 override를 뿌려두면 "왜 이 폴더에서만 다르게 동작하지?"라는 혼란이 생긴다. 실무 감각으로는 이렇게 기억하면 좋다.
루트 규칙에 살짝 덧붙이는 수준이면
AGENTS.md기존 규칙을 잠시 갈아끼우는 수준이면
AGENTS.override.md자주 바뀌는 임시 지시라면 작업 후 반드시 제거
32KiB 제한과 분할 전략
AGENTS.md 운영에서 가장 자주 터지는 함정이 있다. Codex는 프로젝트 문서 체인을 일정 크기까지만 읽는다. 기본값은 32KiB다. 이 한도를 넘기면 뒤쪽 문서가 일부 잘리거나 무시될 수 있다.245
이게 왜 위험하냐면, 대개 더 구체적인 규칙이 더 깊은 디렉터리에 있기 때문이다. 그런데 앞쪽 문서가 너무 길면, 정작 지금 작업 폴더에서 중요한 지침이 뒤로 밀려 안 읽힐 수 있다. 사용자는 "분명 AGENTS.md에 써놨는데 왜 말을 안 듣지?"라고 느끼지만, 실제 문제는 품질이 아니라 용량 초과다.24
그래서 실전 권장 방식은 이렇다.
첫째, 글로벌 AGENTS.md는 짧게 유지한다. 개인 습관 몇 줄이면 충분하다. 프로젝트 구조 설명을 넣는 순간 글로벌 파일은 비대해진다.
둘째, 루트 AGENTS.md에는 레포 전체 규칙만 둔다. 패키지별 세부 구현 규칙까지 다 넣지 않는다.
셋째, 세부 규칙은 필요한 디렉터리로 내려보낸다. 예를 들어 apps/web/AGENTS.md, apps/api/AGENTS.md, packages/design-system/AGENTS.md처럼 나누면, 현재 작업에 맞는 정보만 가까운 곳에서 읽힌다.45
예를 들어 슈퍼앱 클론 모노레포라면 이런 식이 좋다.
superapp/
AGENTS.md # 공통 명령, 패키지 매니저, 브랜치/PR 규칙
apps/
web/
AGENTS.md # Next.js, UI 규칙, Playwright 관련
api/
AGENTS.md # Express, MongoDB, validation 규칙
packages/
ui/
AGENTS.md # 디자인 시스템 규칙이 구조의 장점은 간단하다. 웹 작업할 땐 웹 규칙이 또렷하고, API 작업할 땐 API 규칙이 또렷하다. AI에게도 사람에게도 덜 시끄럽다.
fallback 파일은 어떻게 활용하면 좋은가
공식 가이드 기준으로 자동 발견 파일명에는 TEAM_GUIDE.md와 .agents.md 같은 대체 이름도 포함될 수 있고, 설정으로 fallback 파일명을 추가할 수도 있다.125
이 기능은 팀 전환기에 특히 유용하다. 이미 CONTRIBUTING.md나 docs/DEVELOPMENT.md에 개발 규칙이 잘 정리돼 있는데, 당장 모든 걸 AGENTS.md로 옮기기 부담스러운 팀이 많다. 이럴 때 config에서 fallback을 지정해 기존 문서를 읽게 하고, 점진적으로 AGENTS.md 체계로 정리할 수 있다.24
다만 운영 원칙은 분명하다. fallback은 이행용 다리로 쓰는 게 좋다. 장기적으로는 AI 작업 규칙이 AGENTS.md에 모이는 편이 관리가 쉽다. 개발자 문서와 에이전트 문서의 목적이 다르기 때문이다.
좋은 예시와 망하는 예시
이제 감으로 이해해보자. 아래는 Express + MongoDB API 서버를 가정한 예시다.
좋은 예시는 이렇다.
## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`
## Structure
- `src/routes`: routing only
- `src/services`: business logic only
- `src/repositories`: MongoDB access only
- `src/schemas`: zod request/response schemas
## Rules
- Do not query MongoDB directly from routes
- New endpoints require request validation with Zod
- Never modify `src/generated/`
- Use existing error middleware; do not add ad-hoc try/catch per route
## Done when
- Tests for changed behavior pass
- Lint passes
- New route includes schema and test반면 나쁜 예시는 보통 이런 식이다.
## Philosophy
- We believe in quality and innovation
- Write elegant code
- Follow best practices
- Be careful with security
- Understand the business deeply두 문서의 차이는 명확하다. 위 문서는 행동을 바꾸고, 아래 문서는 기분만 좋아지게 한다. Codex는 철학 강연보다 실행 규칙을 더 잘 따른다.
AGENTS.md를 실제 프로젝트에 맞게 쓰는 법
이 책의 독자를 기준으로, 가장 흔히 만들 법한 프로젝트 세 가지를 짚어보자.
Next.js + Supabase SaaS
이 조합에선 보통 인증, migration, 환경 변수, 서버/클라이언트 경계가 중요하다. 따라서 AGENTS.md에는 다음 정보를 우선 넣는 편이 좋다.
App Router 사용 여부
Supabase Auth가 인증의 기준임을 명시
migration은 새 파일 생성만 허용
서버 액션과 클라이언트 컴포넌트 경계
pnpm lint,pnpm typecheck,pnpm test순 검증
이렇게 해두면 Codex가 엉뚱하게 Prisma를 들여오거나, pages/ 구조로 코드를 짜거나, process.env를 여기저기 직접 읽는 실수를 크게 줄일 수 있다.
Express + MongoDB 백엔드
이 경우엔 레이어 분리와 검증 규칙이 핵심이다. MongoDB를 쓰는 팀은 특히 "라우트에서 바로 쿼리하지 말 것", "스키마 검증 필수", "트랜잭션 또는 멱등성 규칙" 같은 내용을 분명히 적는 게 좋다.
AI는 빠르게 결과를 내려고 종종 가장 짧은 경로를 택한다. 그래서 AGENTS.md에 "짧은 길이 곧 정답이 아니다"라는 걸 구조적으로 박아두는 셈이다.
슈퍼앱 클론 모노레포
이 경우엔 하나의 거대한 루트 AGENTS.md보다 하위 디렉터리 분할이 훨씬 중요하다. 루트에는 공통 규칙만 남기고, apps/passenger, apps/driver, apps/admin, services/payments처럼 역할별로 분리해야 한다. 특히 결제나 정산처럼 민감한 폴더는 override까지 고려할 만하다.
AGENTS.override.md를 활용한 임시 규칙 적용
이 기능은 디버깅 시즌에 특히 빛난다. 예를 들어 결제 이슈를 밤새 추적해야 하는 상황을 생각해보자. 평소 AGENTS.md는 일반 규칙을 담고 있지만, 오늘만큼은 Codex가 다음 원칙을 무조건 따르길 원한다.
services/payments/변경 후pnpm test payments실행checkout 이외 모듈은 수정하지 않음
실패하면 수정 시도보다 원인 보고 우선
이럴 때 글로벌 또는 해당 폴더에 AGENTS.override.md를 만들어 세션 동안만 적용하면 된다. 중요한 점은 이 파일이 같은 레벨의 AGENTS.md를 덮어쓴다는 것이다. 즉 "추가 규칙"이 아니라 "오늘만 다른 운영 모드"에 가깝다.14
개인적으로는 override를 세 가지 경우에만 쓰길 권한다. 핫픽스, 보안 감사, CI 모드다. 이 셋은 평상시 규칙보다 더 강하거나 더 좁은 작업 방식을 요구하기 때문이다.
팀 단위 표준화는 어떻게 해야 하나
개인이 Codex를 잘 쓰는 것과, 팀이 안정적으로 Codex를 쓰는 것은 완전히 다른 문제다. 팀에서 중요한 건 "누가 써도 비슷한 품질이 나오게 만드는 것"이다. AGENTS.md는 바로 그 표준화의 중심이 된다.89
가장 추천하는 운영 방식은 이렇다.
루트 AGENTS.md는 팀 합의로 관리한다.
변경은 코드처럼 PR로 리뷰한다.
새로 생긴 스크립트나 검증 절차는 즉시 반영한다.
하위 디렉터리 AGENTS.md는 각 도메인 오너가 유지한다.
개인 취향은 되도록 글로벌 AGENTS.md로 보낸다.
왜 PR 리뷰가 중요할까? AGENTS.md도 사실상 실행 로직이기 때문이다. 여기에 "테스트는 선택 사항" 같은 문장이 들어가면 AI의 행동이 즉시 바뀐다. 즉 코드가 아니어도 결과에 영향을 준다. 그래서 변경 이력과 리뷰가 필요하다.8
실무적으로는 다음 질문을 기준으로 합의하면 좋다.
이 레포의 필수 검증 명령은 무엇인가?
절대로 건드리면 안 되는 경로는 어디인가?
새 기능 추가 시 반드시 동반해야 할 테스트는 무엇인가?
보고 형식은 어느 정도까지 원하는가?
파괴적 변경은 승인 전까지 어디서 멈춰야 하는가?
이 다섯 가지만 합의돼도 팀 전체의 Codex 품질이 꽤 안정된다.
팀 표준 AGENTS.md 설계 예시
한국 스타트업에서 흔한 웹+API 모노레포를 가정해보자.
루트 AGENTS.md는 이런 역할을 맡는다.
패키지 매니저는 pnpm
공통 실행 명령
공통 PR 규칙
공통 금지 사항 (
.env,generated, 운영 비밀값)공통 완료 기준
apps/web/AGENTS.md는 이런 역할을 맡는다.
Next.js App Router 규칙
UI 컴포넌트 배치 규칙
접근성 체크 포인트
E2E 테스트 기준
apps/api/AGENTS.md는 이런 역할을 맡는다.
Express 계층 구조
MongoDB 접근 방식
입력 검증과 에러 처리 규칙
API 계약 테스트 기준
services/payments/AGENTS.override.md는 이런 역할을 맡는다.
결제 도메인 전용 테스트 명령
민감 파일 수정 금지
멱등성, 감사 로그, PII 표시 규칙
이렇게 설계하면 팀원 A가 웹 작업을 시키든, 팀원 B가 결제 핫픽스를 시키든, Codex는 같은 레포 안에서도 상황에 맞는 규칙을 읽고 행동하게 된다. 바로 이 지점에서 AGENTS.md는 "문서"를 넘어 "작업 운영 시스템"이 된다.
AGENTS.md와 Skills는 어떻게 나눠야 하나
이 장의 후반부에서 중요한 오해 하나를 정리하고 넘어가자. 많은 사용자가 AGENTS.md와 Skills를 섞어 쓴다. 하지만 둘은 역할이 다르다.10
AGENTS.md는 이 프로젝트의 현실을 설명한다. 예를 들면 "우린 pnpm을 쓴다", "이 폴더는 건드리면 안 된다", "테스트는 이 명령으로 돌린다" 같은 것이다.
반면 Skills는 재사용 가능한 작업 방식에 가깝다. 예를 들어 "PR 리뷰를 이런 순서로 하라", "테스트 실패를 진단하는 절차", "PRD를 작성하는 포맷" 같은 것이다.
구분 기준은 간단하다. 다른 프로젝트로 가져가도 유효하면 Skill 쪽이고, 이 레포에서만 맞는 이야기면 AGENTS.md 쪽이다. 예를 들어 "공개 함수에는 테스트를 붙인다"는 Skill 성격이 강하고, "이 레포는 pnpm test:web로 검증한다"는 AGENTS.md 성격이 강하다.
이 구분이 중요한 이유는 다음 장들에서 다룰 Codex의 4축, 즉 AGENTS.md / Skills / Plugins / Automations가 서로 다른 층을 담당하기 때문이다. AGENTS.md를 잘못 비대하게 만들면 이후 전체 구조가 다 흐트러진다.
실전 작성 원칙: 처음부터 완벽하게 쓰지 마라
처음 AGENTS.md를 만들 때 많은 팀이 두 극단으로 간다. 하나는 너무 대충 쓰는 것이고, 다른 하나는 모든 규칙을 한 번에 넣으려는 것이다. 둘 다 오래 못 간다.
실전에서는 오히려 다음 방식이 좋다.
먼저 최소한으로 시작한다. 실행 명령, 구조, 금지 구역, 완료 기준만 넣는다. 그리고 Codex가 반복적으로 틀리는 순간이 올 때마다 그 원인을 문서에 반영한다. 예를 들어 매번 npm을 쓴다면 "Use pnpm, never npm"을 추가하고, 매번 생성 파일을 건드린다면 "Never modify src/generated/"를 추가하는 식이다.28
이 방식의 장점은 문서가 실제 문제를 해결하는 방향으로 자란다는 점이다. 반대로 처음부터 백과사전처럼 써놓으면 유지보수도 어렵고, 팀원도 안 읽고, AI도 핵심을 놓친다.
바로 가져다 쓸 수 있는 추천 템플릿
아래 템플릿은 한국 개발자 팀이 바로 시작하기 좋은 최소 버전이다.
# AGENTS.md
## Project
- This repository is a [프로젝트 설명 한 줄]
- Main stack: [예: Next.js App Router, TypeScript, Supabase]
## Commands
- Install: `[설치 명령]`
- Dev: `[개발 서버 명령]`
- Lint: `[린트 명령]`
- Typecheck: `[타입체크 명령]`
- Test: `[테스트 명령]`
- Build: `[빌드 명령]`
## Structure
- `[디렉터리]`: [역할]
- `[디렉터리]`: [역할]
- `[디렉터리]`: [역할]
## Rules
- Use `[패키지 매니저]`, never `[금지 도구]`
- Do not modify `[금지 경로]`
- New `[기능 종류]` must include `[필수 산출물]`
- Access env only through `[진입점]`
- Follow existing `[검증/아키텍처 규칙]`
## Done when
- `[필수 검증 1]` passes
- `[필수 검증 2]` passes
- `[변경 시 필수 조건]` is satisfied이 템플릿을 복붙한 뒤, 자기 프로젝트에서 Codex가 자주 틀릴 만한 부분부터 채우면 된다. 시작은 단순하게, 하지만 규칙은 구체적으로 쓰는 것이 핵심이다.
이 장의 핵심 정리
AGENTS.md를 이해하면 Codex는 단순히 코드를 쓰는 도구에서, 프로젝트 규칙을 기억하고 따르는 협업자로 바뀐다. 그 전환점은 대단한 프롬프트 기술이 아니라, 명확한 운영 문서다.
기억해야 할 포인트는 네 가지다.
AGENTS.md는 README가 아니라 에이전트용 운영 규칙서다.
Codex는 전역 → 루트 → 하위 디렉터리 순으로 문서를 읽고, 가까운 규칙이 더 강하다.14
AGENTS.override.md는 추가가 아니라 대체다. 임시 모드나 성격이 완전히 다른 하위 시스템에만 신중히 쓰는 게 좋다.14좋은 AGENTS.md는 길지 않지만 구체적이다. 명령, 구조, 금지 구역, 완료 기준이 분명해야 한다.28
다음 장에서는 이 기반 위에서 Codex를 훨씬 빠르게 다루게 해주는 슬래시 명령어와 키보드 단축키를 본다. AGENTS.md가 Codex의 "성격과 습관"을 만든다면, 슬래시 명령어는 당신의 "조작감"을 만든다. 둘이 합쳐질 때 비로소 Codex는 손에 익는 도구가 된다.
참고
1Custom instructions with AGENTS.md - Codex OpenAI Developers
2AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide (2026)
4AGENTS.md Advanced Patterns: Nested Hierarchies, Override Files and Fallbacks Codex Blog
5Codex CLI Cheatsheet: config, commands, AGENTS.md, + best practices
6AGENTS.md: The Complete Guide to Configuring AI Coding Agents (2026)
7OpenAI Codex Setup: AGENTS.md, MCPs, Skills (Definitive Guide 2026)
92-3. AGENTS.md로 팀 규칙 심기 - Codex와 협업하는 개발 워크플로
10Multi-agent and sub-agent patterns in Codex — a practical guide
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.