AGENTS.md 최소 템플릿, 레포에 무엇을 먼저 적나

AGENTS.md 템플릿을 레포에 처음 넣을 때는 필수 스키마가 없습니다. agents.md가 권하는 최소 뼈대는 프로젝트 개요, 빌드·테스트 명령, 코드 스타일, 보안 고려 네 블록입니다. Codex는 시작 시 이 파일을 읽고, Cursor 등 여러 에이전트도 같은 이름을 인식합니다.

이 글은 최소 템플릿 뼈대만 다룹니다. CLAUDE.md와의 동기화 후기·운영 워크플로는 다루지 않습니다.

필수 섹션은?

한 줄 답: 개요 + 설치·실행·테스트 명령 + 스타일 + “하지 말 것”(시크릿·금지 경로)이면 충분합니다.

공식 사이트는 필수 필드를 두지 않고, 에이전트가 자주 쓰는 섹션만 추천합니다. 복붙용 최소 예:

# AGENTS.md

## Project overview
- What this repo ships in one paragraph.
- Primary language and package manager.

## Setup commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Code style
- TypeScript strict; prefer small PRs.
- Match existing file patterns before inventing new ones.

## Security
- Never commit `.env` or API keys.
- Do not run destructive git (`push --force`, hard reset) unless asked.

Codex 가이드 기준으로 전역 기본은 ~/.codex/AGENTS.md, 레포 규칙은 루트 AGENTS.md, 서브패키지는 중첩 AGENTS.md / AGENTS.override.md입니다. 기본 합산 한도는 project_doc_max_bytes(기본 32 KiB)입니다.

CLAUDE.md와 뭐를 공유하나?

한 줄 답: 빌드·테스트·린트 명령 문자열과 시크릿·금지 경로는 공유하고, 도구별 UI·훅·권한 문법은 각 파일에 둡니다.

실무에서 겹치는 축:

공유해도 좋은 것도구별로 둘 것
npm test / make check 등 정확한 명령Claude Code permissions JSON
디렉터리 맵, “건드릴 패키지”Cursor Hooks / rules 경로
PR 제목·커밋 전 체크 목록Codex config.toml sandbox·approval

동기화 전략은 최소로 유지합니다.

  1. 루트 AGENTS.md에 명령을 한 번만 적습니다.
  2. CLAUDE.md에는 “자세한 레포 규칙은 AGENTS.md를 따른다” 한 줄과 Claude 전용 권한·훅만 둡니다.
  3. Codex가 다른 파일명을 읽게 하려면 project_doc_fallback_filenames에 CLAUDE.md 등을 넣을 수 있지만, 단일 진실 원천은 루트 AGENTS.md로 두는 편이 단순합니다.

명령이 어긋나면 에이전트마다 다른 테스트를 돌리므로, 템플릿의 Setup 블록을 먼저 맞춥니다.

너무 길면?

한 줄 답: 루트는 짧게 두고, 패키지별 중첩 AGENTS.md로 나누며, Codex 한도(기본 32 KiB)를 넘기면 분할하거나 project_doc_max_bytes를 올립니다.

길어지는 신호:

  • 모노레포에서 패키지마다 다른 테스트 명령이 한 파일에 섞임
  • 스타일 가이드가 에세이 수준으로 늘어남
  • 동일 문장이 CLAUDE.md·README·rules에 복붙됨

대응:

  1. 루트: 워크스페이스 공통 명령·보안만.
  2. 중첩: services/payments/AGENTS.md처럼 가까운 파일이 우선(공식: closest wins).
  3. 임시 덮어쓰기: Codex는 AGENTS.override.md로 해당 디렉터리만 교체.
  4. 삭제 후보: 이미 CI/린터가 강제하는 포맷 규칙, 오래된 마이그레이션 노트.

에이전트는 나열된 테스트 명령을 실제로 실행하려 하므로, 문서용 장문보다 실행 가능한 짧은 목록이 가치가 큽니다.

마무리

레포에 처음 넣을 AGENTS.md는 개요 → Setup 명령 → 스타일 → 보안 네 블록이면 됩니다. CLAUDE.md와는 명령을 공유하고, 길면 중첩 파일로 쪼갭니다. 형식은 AGENTS.md, Codex 탐색 규칙은 Custom instructions with AGENTS.md를 참고하시기 바랍니다.

출처