새 직원이 입사하면 온보딩 문서를 줍니다. "우리 회사는 이런 곳이고, 배포는 이렇게 하고, 이건 절대 하지 마세요" 같은 것들이요. AGENTS.md는 코덱스에게 주는 온보딩 문서입니다. 저장소 최상위 폴더에 이 파일을 만들어 두면, 코덱스는 어떤 작업이든 시작하기 전에 먼저 읽고 따릅니다.
왜 필요한가요?
- 반복 제거: "테스트는 npm test로 돌려"를 매 프롬프트마다 쓸 필요가 없어집니다.
- 일관성: 나 혼자가 아니라 팀원 누가 코덱스를 시켜도 같은 규칙으로 작업합니다.
- 사고 예방: "마이그레이션 파일은 직접 수정 금지" 같은 금지 사항을 미리 박아둘 수 있습니다.
- 표준 규격: AGENTS.md는 코덱스 전용이 아니라 여러 AI 코딩 도구가 함께 읽는 공개 표준이라, 한 번 쓰면 다른 도구에서도 재활용됩니다.
무엇을 적어야 하나요?
정해진 형식은 없고 그냥 마크다운 문서입니다. 다만 실전에서 효과가 좋은 구성은 다음과 같습니다: 프로젝트 한 줄 소개, 개발 환경과 명령어, 코딩 규칙, 테스트 규칙, 그리고 하지 말아야 할 것.
AGENTS.md 실제 예시
# AGENTS.md
## 프로젝트 소개
한국어 스터디 플랫폼. React + TypeScript + Vite로 만든 웹앱이며
백엔드는 Supabase를 사용한다.
## 개발 명령어
- 개발 서버: npm run dev
- 테스트: npm test
- 타입 체크: npx tsc --noEmit
- 린트: npm run lint
## 코딩 규칙
- TypeScript strict 모드. any 타입 금지.
- 컴포넌트는 함수형으로 작성하고 파일당 250줄을 넘기지 않는다.
- UI 문구는 모두 한국어 존댓말로 작성한다.
- 스타일은 Tailwind 클래스만 사용한다 (인라인 style 금지).
## 테스트 규칙
- 로직을 수정하면 반드시 npm test를 실행해 통과를 확인한다.
- 새 유틸 함수에는 유닛 테스트를 함께 추가한다.
## 하지 말 것
- supabase/migrations/ 안의 기존 파일 수정 금지 (새 파일로 추가만)
- .env 파일을 읽거나 커밋하지 않는다
- package.json의 의존성을 임의로 추가하지 않는다 (필요하면 먼저 제안)계층 구조: 전역 → 프로젝트 → 하위 폴더
AGENTS.md는 여러 위치에 둘 수 있고, 가까운 것이 우선합니다. 회사 전체 규칙집 위에 팀 규칙집이 있고, 그 위에 프로젝트 규칙집이 있는 구조와 같습니다.
- ~/.codex/AGENTS.md — 내 모든 프로젝트에 적용되는 전역 규칙 (예: "답변은 한국어로")
- 프로젝트 루트의 AGENTS.md — 이 저장소 전체 규칙
- 하위 폴더의 AGENTS.md — 특정 모듈에만 적용되는 세부 규칙 (예: frontend/ 폴더 전용 규칙)
처음부터 완벽하게 쓰려고 하지 마세요. 코덱스 대화 중에 /init 명령을 실행하면 프로젝트를 분석해 AGENTS.md 초안을 만들어 줍니다. 그 초안에서 시작해, 코덱스가 실수할 때마다 규칙을 한 줄씩 추가하는 방식이 가장 현실적입니다.
AGENTS.md가 너무 길면 오히려 독이 됩니다. 규칙이 100줄을 넘어가면 중요한 규칙이 묻히기 시작해요. "이 규칙이 없으면 실제로 사고가 나는가?"를 기준으로 다이어트하세요.
Claude Code의 CLAUDE.md를 써 봤다면 개념이 완전히 같다는 걸 눈치챘을 겁니다. 도구별 파일 이름만 다를 뿐, "AI에게 프로젝트 맥락을 미리 주는 파일"이라는 본질은 동일합니다. 이제 배운 것을 전부 모아서, 실전 버그 수정을 처음부터 끝까지 해 봅시다.