AGENTS.md 제대로 쓰는 법: 코덱스가 프로젝트 규칙을 놓치지 않게 하려면

코덱스가 매번 패키지 관리자를 바꾸거나 엉뚱한 테스트를 실행한다면 같은 지시를 채팅마다 반복할 필요가 없다. 저장소가 항상 따라야 하는 작업 방식은 AGENTS.md에 둘 수 있다.

하지만 이 파일을 거대한 운영 매뉴얼로 만들면 정반대 문제가 생긴다. 중요한 규칙이 묻히고, 하위 서비스의 예외와 충돌하며, 모델이 이번 작업과 무관한 설명까지 읽는다. 좋은 AGENTS.md는 짧은 헌법이지 지식창고가 아니다.

Codex가 AGENTS.md를 찾는 정확한 순서

Codex는 실행을 시작할 때 지시 체인을 만든다. 전역 범위에서는 Codex 홈의 AGENTS.override.md가 있으면 그것을 읽고, 없으면 AGENTS.md를 읽는다. 이 수준에서는 첫 번째 비어 있지 않은 파일 하나만 사용한다.

프로젝트에서는 루트에서 현재 작업 디렉터리까지 내려오며 각 폴더에서 override, 기본 파일, 설정된 fallback 이름 순으로 하나를 선택한다. 루트 지침이 먼저, 더 가까운 폴더의 지침이 나중에 붙으므로 구체적인 규칙이 일반 규칙을 덮는 구조다.

• 전역: 개인의 공통 작업 선호
• 루트: 저장소 전체 빌드·테스트·아키텍처 규칙
• 하위 폴더: 서비스·패키지별 예외
• override: 기본 파일을 잠시 대체할 때만 사용

넣어야 할 것과 빼야 할 것

넣을 것은 저장소를 열 때마다 필요한 정보다. 패키지 관리자, 검증 명령, 생성 파일 금지, 공개 API 변경 규칙, 특정 디렉터리의 소유권과 안전한 자동 실행 범위가 좋은 예다.

이번 기능의 상세 요구, 일회성 마감, 특정 버그의 재현 과정은 프롬프트에 둔다. 반복 배포 절차처럼 여러 파일·스크립트·참고자료를 함께 써야 한다면 Skill이 더 맞다. 매번 달라지는 사실을 AGENTS.md에 넣으면 금방 낡는다.

실전 AGENTS.md 템플릿

명령은 추상적 원칙보다 강하다. “품질을 확인한다” 대신 실제 실행 가능한 명령과 적용 조건을 쓴다. 금지 규칙만 두기보다 안전한 대안도 함께 제시한다.

코드 리뷰 규칙은 가장 가까운 AGENTS.md의 ## Code Review Rules 아래에 둘 수 있다. CI가 이미 잡는 포맷팅보다, 사람이 놓치기 쉬운 도메인 오류와 안전 경로에 집중한다.

# AGENTS.md

## Repository workflow
- Use pnpm; do not create npm lockfiles.
- Read the affected package before editing shared code.
- Preserve unrelated user changes.

## Verification
- UI change: pnpm test:ui && pnpm build
- Shared types: pnpm typecheck
- If a command cannot run, report the exact blocker.

## Boundaries
- Do not deploy or change production data without explicit approval.
- Local tests use disposable fixtures and may be rerun freely.

모노레포는 하위 폴더로 규칙을 분리하라

루트 파일에 프런트엔드, 결제, 데이터 파이프라인 규칙을 모두 넣으면 모든 작업이 모든 설명을 읽는다. 공통 규칙만 루트에 남기고 서비스 전용 명령은 해당 디렉터리 가까이에 둔다.

예를 들어 루트는 pnpm과 공통 타입 검사를 정의하고, services/payments/AGENTS.override.md는 결제 테스트와 키 취급 규칙만 정의할 수 있다. 현재 디렉터리에 가까운 지침이 나중에 결합되므로 예외가 명시적으로 적용된다.

32KiB 한도보다 먼저 걱정할 것은 신호 대 잡음비다

공식 문서의 기본 결합 한도는 32KiB다. 한도를 넘으면 뒤의 지침이 포함되지 않을 수 있으므로 파일을 늘리거나 하위 폴더로 나눌 수 있다. 그러나 한도 안이라고 좋은 파일은 아니다.

긴 역사 설명, 모든 코딩 스타일, CI와 중복되는 포맷 규칙을 덜어내라. OpenAI는 최신 모델에서 누적 지시가 서로 모순되거나 Skill 선택을 방해할 수 있다고 경고한다. 규칙 하나마다 “모든 관련 작업에 정말 필요한가”를 묻는 편이 낫다.

5분 점검표

Codex에게 현재 로드한 지시 출처를 요약하게 하면 발견 경로를 확인할 수 있다. 예상한 하위 override가 보이지 않으면 실행 위치와 파일명을 확인한다.

분기마다 규칙을 추가하는 대신 삭제 검토를 한다. 현재 모델이 이미 안정적으로 처리하는 비계, 없어진 명령, 중복 CI 규칙을 지우면 실제 중요한 경계가 더 잘 보인다.

• 명령이 현재 package.json과 일치하는가
• 상위·하위 규칙이 모순되지 않는가
• 일회성 요구가 섞이지 않았는가
• 금지 규칙에 안전한 대안이 있는가
• 가까운 디렉터리로 옮길 규칙이 있는가

자주 묻는 질문