agents.md 작성법 — 위치 우선순위와 claude.md 차이
AGENTS.md는 저장소 루트에 두는 "에이전트용 README"입니다. 규칙은 단순합니다 — 마크다운으로 그냥 쓰면 되고, 하위 폴더에 또 두면 편집하는 파일에서 가장 가까운 것이 이깁니다. 다만 여기서 많이들 헛짚는 게 하나 있습니다. "한 번 써 두면 모든 AI 코딩 도구가 읽는다"는 반만 맞습니다. Codex는 바로 읽지만, Claude Code는 CLAUDE.md만 읽고 AGENTS.md는 읽지 않으며(공식 문서에 그렇게 적혀 있습니다), Gemini CLI도 기본값은 GEMINI.md라 설정을 하나 넣어 줘야 합니다. 아래는 2026년 8월 27일 각 도구의 공식 문서를 원문으로 확인한 내용입니다.
1. AGENTS.md는 무엇이고, README와 뭐가 다른가
공식 사이트의 설명이 가장 간결합니다. "AGENTS.md를 에이전트를 위한 README라고 생각하라"는 것입니다. 지금 6만 개가 넘는 오픈소스 프로젝트가 쓰고 있다고 밝히고 있습니다.
왜 README를 그대로 쓰지 않고 파일을 따로 두느냐는 물음에도 답이 나와 있습니다. README.md는 사람을 위한 문서(빠른 시작·프로젝트 소개·기여 방법)이고, AGENTS.md는 거기에 넣으면 지저분해지거나 사람에게는 필요 없는 빌드 절차·테스트 명령·코딩 규칙을 담습니다. 사람용 문서는 짧게 두고, 에이전트에게는 예측 가능한 자리를 하나 준다는 취지입니다.
형식 제약은 없습니다. 공식 설명은 "그냥 표준 마크다운이고, 원하는 제목을 쓰면 에이전트가 그 텍스트를 읽을 뿐"이라고 적고 있습니다. 정해진 항목이나 스키마가 없다는 뜻입니다.
2. 어디에 두나 — 가장 가까운 파일이 이긴다
기본은 저장소 루트에 한 개입니다. 모노레포처럼 패키지마다 규칙이 다르면 패키지 폴더 안에 또 하나 두면 됩니다. 공식 문서의 표현은 이렇습니다 — "에이전트는 디렉터리 트리에서 가장 가까운 파일을 자동으로 읽으므로, 가장 가까운 것이 우선한다."
충돌이 나면 어떻게 되는지도 못 박혀 있습니다. "편집 중인 파일에서 가장 가까운 AGENTS.md가 이기고, 사용자가 대화창에 직접 적은 지시는 그 모두를 덮어쓴다." 즉 우선순위는 대화창 지시 > 가까운 파일 > 먼 파일 순입니다.
my-repo/
├─ AGENTS.md ← 저장소 공통 규칙
└─ services/
├─ payments/
│ ├─ AGENTS.md ← 결제 서비스 전용 규칙 (여기서 작업하면 이게 이긴다)
│ └─ README.md
└─ search/
└─ AGENTS.md3. Codex는 정확히 어떤 순서로 찾나
여기부터는 Codex 기준입니다. Codex는 일을 시작하기 전에 AGENTS.md를 읽고, 실행할 때마다 "지침 체인"을 새로 만듭니다. 순서가 문서에 단계별로 적혀 있습니다.
| 단계 | 보는 곳 | 규칙 |
|---|---|---|
| ① 전역 | Codex 홈 (기본 ~/.codex) |
AGENTS.override.md가 있으면 그것, 없으면 AGENTS.md. 이 단계에서는 비어 있지 않은 첫 파일 하나만 쓴다 |
| ② 프로젝트 | 프로젝트 루트(보통 깃 루트) → 현재 폴더 | 내려오는 각 디렉터리에서 AGENTS.override.md → AGENTS.md → 대체 파일명 순으로 확인. 디렉터리당 최대 한 개 |
| ③ 병합 | 모은 파일들 | 루트부터 아래로 이어 붙인다. 현재 폴더에 가까운 파일이 뒤에 오므로 앞선 지침을 덮어쓴다 |
여기서 놓치기 쉬운 게 AGENTS.override.md입니다. 이름 그대로 같은 폴더의 AGENTS.md를 무시하고 대신 읽히는 파일입니다. 공유 규칙 파일을 지우지 않고 잠깐 다른 규칙으로 돌리고 싶을 때 쓰고, 다 쓰면 지우면 원래대로 돌아옵니다.
AGENTS.override.md가 남아 있으면 내가 방금 고친 AGENTS.md는 아예 안 읽힙니다. 공식 문제해결 항목에도 같은 진단이 적혀 있습니다.
내용이 실제로 실렸는지 확인하는 명령도 문서에 있습니다.
# 지금 어떤 지침이 실렸는지 요약시켜 본다
codex --ask-for-approval never "Summarize the current instructions."
# 하위 폴더 기준으로 확인 (그 폴더의 override 가 먹는지)
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."지침이 낡아 보이면 그 폴더에서 다시 실행하면 됩니다. Codex는 실행할 때마다 지침 체인을 새로 만들기 때문에 따로 비울 캐시가 없습니다.
4. 길게 쓰면 잘린다 — 32 KiB 한도
AGENTS.md는 짧을수록 좋습니다. 취향 문제가 아니라 실제로 잘리기 때문입니다. Codex는 빈 파일은 건너뛰고, 크기가 project_doc_max_bytes(기본 32 KiB)에 닿으면 더 붙이지 않습니다.
참고로 이 한도의 적용 단위는 공식 문서 두 곳의 표현이 조금 다릅니다. AGENTS.md 전용 문서는 "합쳐진 크기" 기준으로 적고, 설정 문서는 "각 AGENTS.md 파일에서 얼마나 읽을지"라고 적습니다. 다만 어느 쪽이든 대응은 같습니다 — 한도를 올리거나, 지침을 하위 폴더로 나누는 것입니다.
# ~/.codex/config.toml
project_doc_max_bytes = 655365. 파일 이름이 이미 다르다면
저장소가 이미 TEAM_GUIDE.md 같은 이름을 쓰고 있다면 파일을 옮길 필요 없이 목록에 추가하면 됩니다.
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]이렇게 두면 Codex는 각 폴더에서 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md 순으로 찾습니다. 이 목록에 없는 파일명은 지침으로 취급되지 않습니다. 설정을 고쳤으면 Codex를 다시 실행해야 반영됩니다.
6. 도구마다 읽는 파일이 다르다 (가장 많이 착각하는 부분)
AGENTS.md는 열린 표준이고 지원 도구도 20개가 넘습니다. Codex·Gemini CLI·Cursor·Aider·Zed·Warp·VS Code·GitHub Copilot 코딩 에이전트·Jules·Devin·Windsurf 등이 공식 목록에 올라 있습니다. 그런데 그 목록에 Claude Code는 없습니다. 실제로 각 공식 문서를 확인하면 이렇게 갈립니다.
| 도구 | 기본으로 읽는 파일 | AGENTS.md를 읽게 하려면 |
|---|---|---|
| Codex | AGENTS.md |
그냥 두면 됨 |
| Claude Code | CLAUDE.md |
CLAUDE.md에서 @AGENTS.md로 불러오기 (또는 심볼릭 링크) |
| Gemini CLI | GEMINI.md |
settings.json의 context.fileName에 추가 |
Claude Code 공식 문서의 문장은 단호합니다 — "Claude Code는 CLAUDE.md를 읽고, AGENTS.md는 읽지 않는다." 그리고 이미 AGENTS.md를 쓰는 저장소라면 내용을 복사해 두 벌로 관리하지 말고 불러오라고 안내합니다. 이 방식이면 규칙은 한 곳에만 두고, 클로드 전용 규칙만 아래에 덧붙일 수 있습니다.
# CLAUDE.md
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.심볼릭 링크(ln -s AGENTS.md CLAUDE.md)로도 되지만, 윈도우에서는 관리자 권한이나 개발자 모드가 필요하므로 문서도 @AGENTS.md 불러오기를 권합니다. CLAUDE.md 자체를 어떻게 쓰는지는 claude.md 작성법에 위치와 로드 순서까지 정리해 뒀습니다.
Gemini CLI는 설정 파일에 이름을 알려 주면 됩니다. 여러 개를 배열로 줄 수 있습니다.
{
"context": {
"fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
}
}7. 그래서 뭘 적나
형식이 자유롭다는 건 뒤집으면 뭘 적을지는 내가 정해야 한다는 뜻입니다. 공식 예시가 보여 주는 방향은 분명합니다 — 에이전트가 추측하지 않고 그대로 실행할 수 있는 것을 적습니다.
# AGENTS.md
## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`
## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible차이가 보이시나요. "테스트를 돌려 주세요"가 아니라 pnpm test라고 적혀 있습니다. 프로젝트마다 명령이 다르고 에이전트는 그걸 알 방법이 없으니, 명령·경로·규칙을 그대로 실행 가능한 형태로 적는 게 핵심입니다. 반대로 CI가 알아서 잡아 주는 포맷·린트 규칙까지 옮겨 적으면 파일만 길어지고 32 KiB 한도만 갉아먹습니다.
AGENTS.md에 ## Code Review Rules 섹션을 두면 됩니다. 저장소 공통 검사는 루트에, 서비스별 검사는 하위 파일에 두는 식입니다.
자주 묻는 질문 (FAQ)
Q. 루트와 하위 폴더에 둘 다 있으면 어느 쪽이 적용되나요?
둘 다 실리되 가까운 쪽이 이깁니다. Codex는 루트부터 아래로 이어 붙이는데, 가까운 파일이 뒤에 와서 앞선 지침을 덮어씁니다. 다만 한 디렉터리에서는 파일 하나만 가져갑니다.
Q. 규칙을 고쳤는데 반영이 안 됩니다.
세 가지를 보세요. ① 상위 폴더나 Codex 홈에 AGENTS.override.md가 있는지, ② 파일이 비어 있지 않은지(빈 파일은 무시됩니다), ③ 내용이 길어 32 KiB에서 잘렸는지. 설정(config.toml)을 고쳤다면 Codex를 다시 실행해야 합니다.
Q. AGENTS.md 하나로 클로드까지 커버되나요?
안 됩니다. Claude Code는 CLAUDE.md만 읽습니다. CLAUDE.md를 만들어 @AGENTS.md 한 줄로 불러오면 파일 두 벌을 관리하지 않아도 됩니다.
Q. README.md에 다 적으면 안 되나요?
사람이 읽을 문서와 에이전트가 읽을 문서를 섞으면 양쪽 다 나빠집니다. 공식 설명도 README는 사람용으로 짧게 두고, 빌드·테스트·규칙처럼 사람에게는 굳이 필요 없는 세부를 AGENTS.md로 빼라고 안내합니다.
Q. 파일 이름을 꼭 AGENTS.md로 해야 하나요?
Codex라면 project_doc_fallback_filenames에 등록해 다른 이름을 쓸 수 있습니다. 다만 다른 도구들과 같이 쓸 거라면 표준 이름 그대로가 안전합니다.
마무리
정리하면 AGENTS.md는 루트에 하나 두고, 규칙이 갈리는 폴더에만 하나 더 두는 게 기본입니다. 짧게 쓰고(32 KiB에서 잘립니다), 명령을 그대로 실행 가능한 형태로 적고, 반영이 안 되면 AGENTS.override.md부터 찾으세요. 그리고 여러 도구를 같이 쓴다면 도구마다 읽는 파일 이름이 다르다는 것만 기억하면 됩니다 — Codex는 그대로, 클로드는 @AGENTS.md 한 줄, 제미나이는 설정 한 줄이면 같은 규칙을 셋이 나눠 씁니다.
📚 참고 출처 (2026년 8월 27일 확인)
· AGENTS.md 공식 사이트
· Codex — Custom instructions with AGENTS.md
· Codex — Advanced config
· Claude Code — Manage Claude's memory
COMMENTS