AGENTS.md 작성법: Codex가 프로젝트 규칙과 개발 습관을 이해하게 만들기

Codex가 “완료했습니다”라고 말한 뒤 pnpm test를 실행했더니, 애초에 test를 돌리지 않았다는 사실을 발견할 때가 있습니다. 또는 monorepo 루트에서 엉뚱한 package의 test를 실행하기도 합니다. 이런 설명을 반복하는 일은 꽤 피곤합니다. npm run build, pnpm test, generated 디렉터리는 수정하지 않기, 끝내기 전에 lint 실행하기. AGENTS.md는 이런 규칙을 프로젝트 안에 적어 두는 파일입니다. 다음번에는 Codex에게 같은 말을 다시 하지 않아도 됩니다.

Codex 입문과 진입점 선택을 막 끝냈다면, 다음 단계는 전체 프로젝트 리팩터링을 맡기는 것이 아닙니다. 먼저 매번 반복해서 설명하던 프로젝트 규칙을 적어 두세요.

처음에는 12~20줄짜리 뼈대면 충분합니다. 그다음 3단계 로딩 방식, 적용 여부 확인, 넣지 말아야 할 내용, CLAUDE.md나 Cursor Rules와의 공존, 업데이트 시점을 정리하면 됩니다.

AGENTS.md는 README가 아니라 Codex의 지속적인 작업 지침서입니다

README.md는 사람을 위한 문서입니다. 프로젝트가 무엇인지, 어떻게 설치하고 시작하는지 설명합니다. AGENTS.md는 Codex를 위한 문서입니다. 매 작업 시작 때 자동으로 로드되는 규칙, 즉 build 방법, test 방법, 건드리면 안 되는 디렉터리, 완료 전 검사 항목을 적습니다.

OpenAI 공식 문서에 따르면 Codex는 작업을 시작하기 전에 AGENTS.md를 읽고 이를 컨텍스트 일부로 사용합니다. 매번 채팅에서 “npm run build”, “pnpm test”라고 반복하는 것과 다릅니다. AGENTS.md는 지속적인 프로젝트 지침입니다.

하지만 경계가 있습니다. AGENTS.md는 장기 기억 시스템도, 자동으로 학습하는 지식 베이스도 아닙니다. 시작할 때 로드되는 정적 지침 파일입니다. 세션을 넘어 지식을 축적하거나 메모리를 관리하려면 이전의 AI 에이전트 메모리 관리에서 다룬 장기 기억과 프로젝트 규칙의 분리를 참고하면 됩니다.

Codex는 AGENTS.md를 어떻게 찾나요: 3단계 로딩 구조

Codex의 읽기 순서는 전역 레이어, 프로젝트 레이어, 결합 순서로 나누어 볼 수 있습니다. 이 구조를 이해하면 어떤 규칙이 어디에서 적용되는지, 왜 규칙이 적용되지 않는 것처럼 보이는지 판단할 수 있습니다.

전역 레이어: 개인의 공통 습관

Codex는 먼저 사용자 디렉터리 ~/.codex를 확인합니다. 이 레이어에는 응답 언어, 코드 스타일 선호, 자주 쓰는 도구 습관 같은 개인 규칙을 둡니다. 주의할 점은 전역 레이어에서는 최대 한 파일만 읽는다는 것입니다. 순서는 AGENTS.override.md -> AGENTS.md이며, 둘을 함께 누적하지 않습니다.

프로젝트 레이어: Git 루트에서 현재 디렉터리까지 스캔

프로젝트 레이어는 Git 루트 또는 프로젝트 루트에서 현재 작업 디렉터리까지 순서대로 스캔합니다. 각 단계에서도 AGENTS.override.md -> AGENTS.md -> fallback filenames 순서로 최대 한 파일만 읽습니다. fallback 파일명은 project_doc_fallback_filenames로 설정할 수 있습니다. 예를 들어 TEAM_GUIDE.md를 추가할 수 있지만, 정확한 설정 이름은 공식 문서를 기준으로 봐야 합니다.

결합 순서: 가까운 디렉터리일수록 뒤에 나오고 더 구체적입니다

찾은 파일은 루트에서 현재 디렉터리 방향으로 이어 붙습니다. 현재 디렉터리에 가까운 규칙일수록 컨텍스트에서 뒤에 나타납니다. 그래서 Codex가 더 구체적인 지침으로 우선하기 쉽습니다.

예를 들어 monorepo 루트의 AGENTS.md에는 “test 명령은 pnpm test”라고 쓰여 있고, apps/web/AGENTS.md에는 “test 명령은 pnpm --filter web test”라고 쓰여 있다고 합시다. apps/web에서 Codex를 시작하면 읽는 순서는 루트 규칙 -> apps/web 규칙입니다. apps/web의 test 명령이 더 구체적인 지침입니다.

3단계 로딩 요약표

레이어	경로 범위	파일 우선순위	권장 용도
전역 레이어	~/.codex/	AGENTS.override.md -> AGENTS.md (최대 한 파일)	개인 공통 습관, repo에 commit하지 않음
프로젝트 레이어	Git 루트 -> 현재 디렉터리	각 단계에서 AGENTS.override.md -> AGENTS.md -> fallback 중 최대 한 파일	루트에는 공통 규칙, 하위 디렉터리에는 특수 규칙
결합 레이어	루트에서 현재 디렉터리까지 순서대로 결합	가까운 디렉터리일수록 뒤에 나오고 우선순위가 높음	monorepo에서 package별 규칙이 공통 규칙을 보완

루트에는 팀 공통 규칙을 두고, 하위 디렉터리에는 특수 규칙을 둡니다. 예를 들어 특정 package만 test 명령이 다를 때입니다. AGENTS.override.md는 임시 또는 로컬 override에 적합합니다. 팀 기본값으로 쓰면 규칙이 override 안에 숨어 협업이 헷갈리기 쉽습니다.

최소 시작 템플릿: 먼저 쓸 6개 블록

OpenAI는 AGENTS.md를 “open-format README for agents”라고 설명합니다. 핵심은 짧고, 실제이며, 검증 가능해야 한다는 것입니다. 인터넷에서 찾은 300줄짜리 템플릿을 그대로 복사하지 마세요. 먼저 6개 기본 블록을 쓰고, 필요할 때만 확장합니다.

시작 파일에는 이 6개 블록을 넣습니다.

1. repo layout: 기술 스택과 디렉터리 구조. Codex가 frontend, backend, test 위치를 파악합니다
2. Commands: 구체적인 build, test, lint 명령. “test 실행”이 아니라 pnpm test라고 씁니다
3. Constraints: 건드리면 안 되는 디렉터리나 행동. 예: src/generated/
4. PR expectations: 제출 전에 확인할 것과 review에서 기대하는 것
5. Done when: 완료 조건. 예: pnpm test와 pnpm build가 통과
6. 패키지 매니저, 코드 스타일, 이름 규칙 같은 특수 약속

SaaS 관리 대시보드 프로젝트라면 시작 파일은 이 정도면 충분합니다.

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

이 템플릿은 짧아서 컨텍스트를 흐리지 않습니다. 먼저 이 6개 블록을 쓰고, 문제가 생길 때마다 하나씩 확장합니다. 프로젝트 비전, 의존성 목록, 아키텍처 다이어그램, API 문서 색인을 처음부터 넣으면 파일이 길어지고 중요한 규칙이 묻힙니다.

Codex가 AGENTS.md를 정말 읽었는지 확인하는 방법

AGENTS.md를 작성한 뒤에는 적용됐다고 가정하지 말고 검증합니다. OpenAI 공식 문서가 권장하는 명령은 다음과 같습니다.

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

이 명령은 Codex가 현재 읽은 지침을 요약하게 합니다. 출력에 test 명령이나 금지 디렉터리 같은 규칙이 포함되어 있으면 적용된 것입니다. 전혀 나오지 않거나 다른 규칙이 나오면 로딩 경로를 확인해야 합니다.

문제 해결 체크리스트

확인 항목	가능한 원인	처리 방법
파일명 대소문자	파일명이 AGENTS.md가 아니라 Agent.md, agents.md 등으로 되어 있음	AGENTS.md로 바꾸고 A와 확장자를 대문자로 유지합니다
버전이 오래됨	오래된 버전에는 symlink, NFS, mount 경로 관련 문제가 있었습니다. 정확한 버전 경계는 공식 문서를 기준으로 봅니다	최신 버전으로 업데이트합니다
경로가 가려짐	프로젝트 경로가 symlink, NFS mount, bind mount라 탐색 경로에 영향을 줌	실제 경로에서 시작하는지 확인합니다
override가 우선됨	AGENTS.override.md 또는 하위 디렉터리 규칙이 기대한 규칙을 덮어씀	현재 디렉터리와 전역 디렉터리의 override 파일을 확인합니다
크기 제한	파일이 기본 크기 제한을 넘음. 공식 문서에서는 32 KiB 기준을 설명합니다	오래된 목록과 긴 설명을 줄입니다
시작 디렉터리가 틀림	Codex가 의도한 repo나 package 밖에서 시작됨	작업 디렉터리를 확인하거나 --cd를 사용합니다

그래도 적용되지 않는다면 OpenAI Custom instructions 문서를 확인하거나 Codex를 업데이트하세요. AGENTS.md 로딩을 마법처럼 여기면 안 됩니다. 경로, 버전, 설정, 현재 디렉터리가 모두 영향을 줍니다.

AGENTS.md에 쓰지 말아야 할 것

AGENTS.md는 만능 보관소가 아닙니다. 어떤 내용은 보안 위험, 유지보수 부담, 컨텍스트 노이즈를 만듭니다. 다음 항목은 제외합니다.

1. secret, API key, 프로덕션 비밀번호

secret, 프로덕션 비밀번호, API token은 AGENTS.md에 쓰지 않습니다. Codex가 이 파일을 컨텍스트에 읽고, 팀원이 볼 수도 있으며 Git에 commit될 수도 있습니다. secret은 환경 변수, commit하지 않는 .env, 전용 secrets 시스템으로 관리합니다. Codex가 sandbox workflow에서 secret을 써야 한다면 실행 계층 문제로 다룹니다.

2. 빨리 낡는 큰 목록

의존성, 생태계 숫자, 가격, quota, 전체 route, 전체 DB field를 나열하지 마세요. “React 18.2, Vue 3.4, TypeScript 5.0…” 같은 목록은 금방 낡습니다. 현재 목록을 쓰기보다 의존성을 추가하는 절차를 쓰는 편이 낫습니다.

3. 추상적인 구호

“높은 품질 유지”, “우아한 코드 작성”, “유지보수성 보장”은 실행할 수 없습니다. pnpm test 통과, pnpm lint 오류 없음, 새 기능에 test 추가, Lighthouse Performance 기준 이상처럼 검사 가능한 조건으로 바꿉니다.

4. 모호한 명령

“test 실행”, “build 확인”은 너무 모호합니다. pnpm test, pnpm build, lighthouse --preset=desktop처럼 그대로 실행할 수 있게 씁니다.

5. 검증할 수 없는 요구

“성능 향상 보장”이나 “UX 개선”에는 명확한 완료 기준이 없습니다. API 응답 200 ms 이하, Lighthouse 목표 점수 이상처럼 측정 가능한 기준을 둡니다.

6. repo 루트의 개인 취향

“중국어로 답변”, “100자 이하로 답변”, “VS Code 기본 사용”은 개인 도구 습관이지 팀 공유 규칙이 아닙니다. 이런 내용은 ~/.codex/AGENTS.md에 둡니다. repo 루트에는 팀 표준만 둡니다.

원칙은 단순합니다. 짧고, 실제이며, 검증 가능해야 합니다. AGENTS.md는 반복 설명을 줄이는 파일이지 모든 프로젝트 문서를 붙여 넣는 곳이 아닙니다.

이미 CLAUDE.md나 Cursor Rules가 있다면

Claude Code나 Cursor를 사용한다면 repo에 CLAUDE.md나 Cursor Rules가 이미 있을 수 있습니다. 같은 규칙을 세 벌로 유지할 필요는 없습니다. import와 공존 전략을 사용합니다.

AGENTS.md vs CLAUDE.md: 공유 규칙 import하기

Claude Code가 읽는 것은 CLAUDE.md이고, AGENTS.md가 아닙니다. repo에 이미 AGENTS.md가 있다면 다음처럼 작은 CLAUDE.md를 만들어 import할 수 있습니다.

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md는 import 문법입니다. Claude Code는 AGENTS.md를 먼저 읽고, 그 아래의 Claude-specific 지침을 이어서 읽습니다. 이렇게 하면 프로젝트 공통 규칙은 AGENTS.md에, Claude 전용 선호는 CLAUDE.md에 둘 수 있습니다.

AGENTS.md vs Cursor Rules: Cursor에는 자체 Rules 체계가 있습니다

Cursor에는 Project, Team, User Rules 등 자체 Rules 체계가 있습니다. Cursor 공식 문서와 검색 요약은 AGENTS.md 지원을 언급하지만, 구체적인 로딩 방식은 Cursor의 최신 공식 문서를 확인하는 것이 안전합니다. Cursor와 Codex를 함께 쓴다면 도구 공통 프로젝트 규칙은 AGENTS.md에 두고, Cursor 전용 편집기 동작은 Cursor Rules에 남깁니다.

AGENTS.md vs config.toml, Rules, Skills, MCP

AGENTS.md는 지침 계층입니다. Codex에게 어떻게 작업해야 하는지 알려 줍니다. 실행 제어는 다른 곳에 있습니다. 권한, sandbox, 명령 정책, 도구 연동은 별도 메커니즘입니다.

비교 항목	AGENTS.md	다른 메커니즘	차이
.codex/config.toml	build, test, 위험한 디렉터리 회피 같은 프로젝트 규칙	model, sandbox, approval, network, shell environment 같은 실행 설정	규칙은 AGENTS.md, 실행 설정은 config.toml
Rules	”위험한 명령을 실행하지 말라” 같은 지침	prefix_rule(pattern=["rm","-rf"], decision="forbidden") 같은 명령 정책	문장으로 된 지침은 강제 규칙과 다릅니다
Skills	항상 참고할 프로젝트 지침	scripts와 references를 가진 재사용 workflow	상시 규칙은 AGENTS.md, 복잡한 workflow는 Skills
MCP	지침 계층	도구 연동 계층	AGENTS.md는 MCP를 대체하지 않습니다

AGENTS.md는 반복되는 프로젝트 규칙 설명을 해결합니다. Rules, config, sandbox, permissions는 실행을 제어합니다. Skills는 재사용 workflow를 다룹니다. MCP는 외부 도구를 연결합니다. 이 경계를 섞지 않는 것이 좋습니다.

언제 AGENTS.md를 업데이트해야 하나요?

AGENTS.md는 프로젝트가 바뀔 때마다 수정할 필요가 없습니다. 같은 마찰이 반복될 때 업데이트합니다.

업데이트 트리거

OpenAI 공식 문서는 다음 상황에서 업데이트를 권장합니다.

1. Codex가 같은 실수를 반복할 때: 두 번 연속 잘못된 디렉터리를 수정하거나 매번 잘못된 package test를 실행합니다. 이때 “Do NOT edit src/generated/” 또는 “Use pnpm --filter web test for web changes” 같은 구체적 Constraints를 추가합니다.

2. PR review에서 같은 피드백이 반복될 때: reviewer가 “이 변경에는 test가 필요합니다”, “generated code는 건드리지 마세요”, “default export는 피하세요”라고 반복합니다. 이 패턴을 PR expectations에 넣습니다.

3. Codex가 답을 찾기 위해 문서를 너무 많이 읽을 때: 올바른 test 명령이나 build 흐름을 찾으려고 매번 여러 문서를 뒤진다면, 핵심 경로나 명령을 위쪽에 추가합니다.

가장 가까운 디렉터리에 업데이트하기

실수가 발생한 디렉터리에 규칙을 추가합니다. 모든 규칙을 루트에 넣을 필요는 없습니다. monorepo에서는 package마다 규칙이 다를 수 있으므로 각 package가 로컬 AGENTS.md를 가질 수 있습니다.

예를 들어 Codex가 apps/web에서 잘못된 test를 실행했다면 apps/web/AGENTS.md에 규칙을 추가합니다. 루트에 넓은 규칙을 추가하면 다른 package에 불필요하게 영향을 줄 수 있습니다.

장기 기억과의 차이

AGENTS.md는 시작할 때 로드되는 정적 지침 파일입니다. 자동으로 학습하는 memory store가 아닙니다. 명시적으로 요청하지 않는 한, Codex가 사용자의 교정을 바탕으로 AGENTS.md를 스스로 업데이트하지 않습니다.

세션을 넘는 프로젝트 지식이나 메모리 관리가 필요하면 AI 에이전트 메모리 관리 글을 다음 참고 자료로 보면 됩니다.

템플릿을 키우는 방식: seed 파일에서 확장 파일로

처음부터 300줄 템플릿을 만들 필요는 없습니다. 12~20줄 seed 파일에서 시작하고, 반복되는 트리거가 있을 때만 확장합니다.

seed 버전: 핵심 6개 블록만

seed 버전은 repo layout, 공통 명령, constraints, PR expectations, done/verify만 담습니다. 이렇게 작아도 충분합니다.

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

확장 트리거: 언제 블록을 추가할까

몇 번 실행한 뒤, 구체적인 문제에 맞춰 확장합니다.

1. 처음으로 Codex가 잘못된 디렉터리를 수정했을 때: migrations/나 generated/를 건드렸다면 Constraints에 “Do NOT commit migrations/ without team review” 또는 “Do NOT edit any file in src/generated/“를 추가합니다.

2. 처음으로 PR review 지적이 반복됐을 때: reviewer가 test 추가나 named exports를 반복해서 요구한다면 PR expectations에 “Add tests for new features”, “Use named exports, not default exports”를 추가합니다.

3. 처음으로 패키지 매니저를 잘못 썼을 때: pnpm 프로젝트에서 npm 명령을 썼다면 Commands에 “Always use pnpm, not npm or yarn”를 추가합니다.

4. 처음으로 lint를 빼먹었을 때: 완료 전에 lint를 실행하지 않았다면 Done when에 “pnpm lint passes with no errors”를 추가합니다.

확장 버전: 30~50줄

확장 버전은 constraints, PR expectations, 패키지 매니저 규칙, lint 요구사항을 추가해 30~50줄 정도가 될 수 있습니다.

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

핵심은 예상으로 키우지 말고, 트리거로 키우는 것입니다. AGENTS.md의 가치는 프로젝트 문서를 전시하는 데 있지 않고 반복 설명을 줄이는 데 있습니다.

결론

AGENTS.md는 지속적인 프로젝트 지침입니다. 만능 창고도, 장기 기억 시스템도 아닙니다. 해결하는 문제는 하나입니다. Codex가 작업을 시작할 때마다 같은 프로젝트 규칙을 반복해서 설명하지 않아도 됩니다.

실제 진행 순서는 다음과 같습니다.

1. 12~20줄 seed 파일에서 시작하기: repo layout, 명령, constraints, PR expectations, done/verify. 처음부터 거대한 템플릿으로 시작하지 않습니다.

2. Codex가 로드했는지 확인하기: codex --ask-for-approval never "Summarize the current instructions."를 실행하고, 출력에 내 규칙이 포함되는지 봅니다.

3. 반복 트리거로만 확장하기: Codex가 같은 실수를 반복하거나, PR review가 같은 지적을 반복하거나, Codex가 답을 찾기 위해 너무 많은 문서를 읽을 때만 추가합니다.

4. 위험하거나 빨리 낡는 내용은 넣지 않기: secret, 오래된 목록, 추상 구호, 모호한 명령, 검증할 수 없는 목표, 개인 취향은 루트 AGENTS.md에 넣지 않습니다.

5. CLAUDE.md나 Cursor Rules가 있다면 import와 공존으로 정리하기: 공통 프로젝트 규칙은 AGENTS.md에 모으고, 도구별 동작은 각 도구 파일에 남깁니다.

AGENTS.md는 Codex에 안정적인 프로젝트 컨텍스트를 전달합니다. 이 Codex 시리즈의 다음 글에서는 반복 workflow를 Skills로 옮기고, 권한과 secret 경계를 다루며, failure review와 PR checks로 done/verify를 더 안정적으로 만드는 흐름을 이어갈 수 있습니다.