먼저 실험: 규칙 한 줄이 어디까지 전달되는가
작성법을 말하기 전에 파일이 실제로 읽히는지부터 확인했습니다. 빈 저장소에 AGENTS.md를 만들고 "패키지 매니저는 pnpm만 쓴다"와 "답변 첫 줄에 RULES: ROOT를 붙인다"는 두 규칙을 적었습니다. 하위 폴더 api/에는 두 번째 파일을 뒀습니다. 여기에는 "이 폴더는 uv sync를 쓴다", "첫 줄에 RULES: ROOT+API"라고 적었습니다. 첫 줄 표식은 규칙이 프롬프트에 들어갔는지 눈으로 확인하기 위한 장치입니다.
Codex는 문서대로 동작했습니다. 루트에서는 pnpm install, api 폴더에서는 uv sync를 답했고 첫 줄 표식도 두 파일이 합쳐진 형태로 나왔습니다. 실행 로그에서 별도의 파일 읽기 없이 첫 응답에 표식이 붙은 것으로 보아, 세션 시작 시점에 두 파일이 이미 프롬프트에 들어가 있었다고 해석했습니다. 도구 호출 내역까지 확인한 것은 아니므로 추정입니다.
Claude Code 결과가 이 글의 핵심입니다. 공식 문서는 "Claude Code는 CLAUDE.md를 읽고 AGENTS.md는 읽지 않는다"고 적고 있고, 실험 A가 그대로였습니다. 그런데 실험 C처럼 저장소를 탐색하는 작업에서는 에이전트가 파일 목록에서 AGENTS.md를 발견하고 내용으로서 읽은 뒤 규칙을 따랐습니다. 이 둘은 다릅니다. 시작할 때 로드된 규칙은 모든 응답에 걸립니다. 탐색 중에 우연히 읽은 규칙은 그 작업에서만, 그것도 에이전트가 그 파일을 열었을 때만 적용됩니다. "AGENTS.md만 두면 다 되더라"는 경험담이 여기서 나옵니다. 어느 날 갑자기 규칙이 무시되는 이유도 같습니다.
README for agents, 형식은 없고 위치만 있습니다
agents.md 사이트는 이 파일을 "코딩 에이전트를 안내하는 단순하고 열린 형식"이라고 소개합니다. 이미 6만 개 이상의 오픈소스 저장소가 쓰고 있다고도 밝힙니다. 문법이 따로 없다는 점이 중요합니다. 프런트매터도, 정해진 섹션 이름도 없습니다. 저장소 루트의 AGENTS.md라는 이름과 위치만 약속이고, 내용은 평범한 마크다운입니다. README가 사람을 위한 문서라면 AGENTS.md는 에이전트용 맥락을 담는 자리입니다. 빌드 명령, 테스트 방법, 컨벤션처럼 README에 넣으면 장황해지는 것들입니다.
사이트의 FAQ는 우선순위를 한 문장으로 정리합니다. 편집 중인 파일에 가장 가까운 AGENTS.md가 이깁니다. 사용자가 채팅에서 직접 준 지시는 모든 파일보다 앞섭니다. 이 원칙은 지원 도구들이 대체로 공유합니다. 다만 세부 구현이 도구마다 달라 아래 표로 갈라서 봐야 합니다.
도구별로 읽는 위치와 방식이 다릅니다
| 도구 | AGENTS.md 인식 | 동작과 확인 방법 |
|---|---|---|
| Codex CLI | 기본 지원 · 직접 실행 확인 | 전역 ~/.codex/AGENTS.md를 먼저 읽고, Git 루트에서 현재 폴더까지 내려오며 폴더마다 한 파일씩 이어 붙입니다. 합계 32KiB(project_doc_max_bytes)를 넘으면 그 뒤 파일은 잘립니다. |
| Claude Code | 직접 읽지 않음 · 직접 실행 확인 | CLAUDE.md에 @AGENTS.md 한 줄을 넣거나 심볼릭 링크로 연결합니다. /import 명령(2.1.213 이상)은 AGENTS.md를 CLAUDE.md에 복사해 옵니다. |
| Cursor | 기본 지원 · 공식 문서 기준 | 프로젝트 루트의 AGENTS.md를 .cursor/rules의 대안으로 읽고, 하위 폴더의 AGENTS.md는 그 폴더 파일을 다룰 때 상위 내용과 합쳐 적용합니다. |
| Gemini CLI | 설정 필요 · 공식 문서 기준 | 기본 파일명은 GEMINI.md입니다. settings.json의 context.fileName에 ["AGENTS.md","GEMINI.md"]처럼 목록을 넣으면 같은 계층 규칙으로 읽습니다. |
Codex 문서에서 놓치기 쉬운 문장이 둘 있습니다. 하나, 발견은 "실행당 한 번"입니다. 대화형 세션을 켠 상태에서 AGENTS.md를 고치면 그 세션은 옛 내용을 계속 씁니다. 다시 시작해야 반영됩니다. 둘, 폴더당 한 파일만 포함합니다. 같은 폴더에 AGENTS.md와 AGENTS.override.md가 함께 있으면 override만 읽힙니다. 팀 공용 규칙을 AGENTS.md에 두고 개인 실험용 규칙을 override에 두면 공용 규칙이 통째로 빠집니다. override는 이름 그대로 대체이지 추가가 아닙니다.
Claude Code에서 불러오기 방식을 택했다면 /context 명령으로 확인합니다. Memory files 목록에 CLAUDE.md가 보이면 그 안의 @AGENTS.md도 함께 로드된 것입니다. 실험 B에서 표식이 붙은 것이 바로 이 상태입니다. 심볼릭 링크는 Windows에서 관리자 권한이나 개발자 모드가 필요하므로 팀에 Windows 사용자가 있다면 불러오기 한 줄 쪽이 무난합니다.
무엇을 쓸까: 에이전트가 코드에서 알아낼 수 없는 것만
세 도구의 문서가 공통으로 권하는 내용은 결국 한 기준으로 모입니다. 저장소를 읽어서 알 수 있는 것은 쓰지 않습니다. 읽어도 알 수 없는 것을 씁니다. 디렉터리 구조와 의존성 목록은 전자입니다. "테스트는 반드시 pnpm test로 돌린다", "결제 모듈은 계획 모드로만 수정한다" 같은 규칙이 후자입니다. Claude Code 문서는 파일당 200줄 이하를 권하고 Codex는 32KiB에서 잘라 버립니다. 길이 제한은 곧 신호입니다. 파일이 길어졌다면 코드에서 알아낼 수 있는 설명이 섞였습니다.
# Repository rules - Package manager: use **pnpm** only. Never run npm or yarn. - Tests: `pnpm test`. Lint: `pnpm lint`. - Before answering any question, start the first line of your reply with `RULES: ROOT`.
실제 프로젝트라면 마지막 줄의 표식 대신 다음 네 묶음을 채우면 됩니다.
명령설치, 개발 서버, 테스트, 린트, 빌드 명령을 정확한 문자열로. "테스트를 돌려라"로는 모자랍니다. "pnpm vitest run -t "이름"으로 하나만 돌릴 수 있다"까지 씁니다.
경계건드리지 말 것과 사람 확인이 필요한 것. 마이그레이션 파일, 결제·인증 코드, 생성된 파일(dist/, 잠금 파일)이 흔합니다.
컨벤션 중 도구 기본값과 다른 것ESLint가 잡아 주는 규칙은 적지 않습니다. 린터가 모르는 팀 규칙만 남깁니다. "에러 메시지는 한국어로", "날짜는 항상 KST 문자열로 저장"이 여기에 해당합니다.
완료 조건PR 제목 형식, 커밋 전에 돌려야 하는 명령, 변경 뒤 갱신해야 하는 문서. agents.md 예시 파일의 PR instructions 절이 이 묶음입니다.
쓰지 말아야 할 것도 분명합니다. 비밀번호와 토큰은 평문 마크다운에 들어가면 컨텍스트로 모델에 전달되고 커밋 이력에도 남습니다. "항상 최선을 다해라" 같은 태도 지시는 토큰만 씁니다. 그리고 반드시 막아야 하는 동작은 AGENTS.md로 막을 수 없습니다. Claude Code 문서는 이 파일을 "강제 설정이 아니라 컨텍스트"라고 부릅니다. 반드시 차단할 동작은 권한 설정과 훅으로 걸라고 안내합니다. Codex도 같은 구조여서 실제 차단은 샌드박스와 승인 정책이 담당합니다.
계층 배치: 루트 하나로 시작해 필요한 폴더에만 덧붙입니다
모노레포처럼 폴더마다 언어와 도구가 다르면 실험의 api/AGENTS.md처럼 하위 파일을 둡니다. Codex는 루트부터 현재 폴더까지 순서대로 이어 붙입니다. 아래쪽 파일이 뒤에 오므로 같은 주제의 규칙이 충돌하면 뒤에 온 것이 실질적으로 이깁니다. Cursor도 상위와 합치되 더 구체적인 쪽을 우선한다고 문서에 적혀 있습니다. 실험에서 api 폴더의 답이 uv sync였던 것이 이 동작입니다.
# api/ rules - This directory is a Python service. Dependencies are installed with `uv sync`, not pnpm. - Start the first line of your reply with `RULES: ROOT+API`.
"현재 폴더"의 의미부터 도구마다 다릅니다. Codex는 명령을 실행한 위치 기준입니다. 루트에서 세션을 열고 api 파일을 고치면 api/AGENTS.md는 읽히지 않습니다. 반면 Claude Code(CLAUDE.md 기준)와 Gemini CLI는 그 폴더의 파일을 읽을 때가 되어서야 하위 폴더의 파일을 불러옵니다. Cursor도 해당 폴더 파일을 다룰 때 적용합니다. Codex에서 하위 규칙이 안 먹는다면 규칙 자체보다 실행 위치를 먼저 의심해야 합니다. 하위 규칙이 꼭 필요하면 그 폴더에서 세션을 열면 됩니다. 아니면 루트 파일에 "api/ 아래를 수정할 때는 api/AGENTS.md를 먼저 읽어라"라고 한 줄 적어 두는 편이 실용적입니다.
전역 파일은 저장소와 무관한 개인 습관용입니다. Codex의 ~/.codex/AGENTS.md, Claude Code의 ~/.claude/CLAUDE.md, Gemini CLI의 ~/.gemini/GEMINI.md가 같은 역할입니다. "답변은 한국어로", "커밋 메시지는 영어로" 같은 것은 여기에 두고 저장소 파일에는 넣지 않아야, 저장소를 다른 사람과 공유할 때 개인 취향이 팀 규칙으로 둔갑하지 않습니다.
자주 하는 실수 다섯 가지
파일을 고치고 세션을 안 다시 켠다Codex는 세션 시작 때 한 번만 읽으므로, 수정 뒤 반영이 안 되면 재시작부터 합니다.
Claude Code에서 AGENTS.md만 두고 끝낸다실험 A처럼 로드되지 않습니다. CLAUDE.md에 @AGENTS.md를 넣고 /context로 확인합니다.
override 파일에 개인 규칙을 추가로 적는다Codex에서 override는 같은 폴더의 AGENTS.md를 통째로 대체합니다. 추가하려면 원본에 쓰거나 하위 폴더 파일로 나눕니다.
README 내용을 그대로 복사한다프로젝트 소개와 설치 안내는 에이전트가 README에서 읽습니다. 중복은 컨텍스트만 늘립니다. 두 파일이 어긋나면 어느 쪽을 따를지 모델이 임의로 고릅니다.
금지 규칙을 여기에만 적고 안심한다"main에 직접 push 금지"는 AGENTS.md에 적어도 강제되지 않습니다. 브랜치 보호 설정, 권한 거부 규칙, 훅으로 막고 AGENTS.md에는 이유만 적습니다.
자주 묻는 질문
Q. CLAUDE.md와 AGENTS.md 중 하나만 유지하고 싶습니다.
문서가 권하는 형태는 이렇습니다. AGENTS.md를 원본으로 두고 CLAUDE.md에는 @AGENTS.md 한 줄과 Claude 전용 규칙만 남깁니다. Codex·Cursor는 AGENTS.md를 바로 읽고 Claude Code는 불러오기로 같은 내용을 봅니다.
Q. 이미 CLAUDE.md만 쓰고 있는데 Codex도 쓰게 됐습니다.
Codex 설정의 project_doc_fallback_filenames에 ["CLAUDE.md"]를 넣으면 AGENTS.md가 없는 폴더에서 CLAUDE.md를 대신 읽습니다. 다만 CLAUDE.md의 @경로 불러오기 문법은 Codex가 해석하지 않으므로 불러오기에 의존한 파일이라면 내용을 AGENTS.md로 옮기는 편이 안전합니다.
Q. 한국어로 써도 되나요?
규칙을 한국어로 적는 것 자체는 어느 도구 문서도 막지 않습니다. 다만 이 글의 실험은 규칙은 영어, 질문과 답변은 한국어로 진행한 것이라 한국어 규칙 자체를 시험한 결과는 아닙니다. 명령어와 파일 경로는 원문 그대로 적어야 에이전트가 문자열로 정확히 실행합니다.
서두의 “네 도구에서 직접 실행”이라는 표현을 고쳤습니다. 직접 실행한 것은 Codex CLI와 Claude Code 두 도구이고, Cursor와 Gemini CLI는 공식 문서로 확인했습니다. 표에도 확인 방법을 표시했고, 읽기 전용 샌드박스 관련 추론과 한국어 FAQ의 근거 범위를 실제 실험 범위에 맞게 좁혔습니다.
agents.md 사이트, OpenAI Codex의 AGENTS.md 문서, Anthropic Claude Code의 메모리 문서, Cursor의 Rules 문서, Gemini CLI의 GEMINI.md 문서를 2026년 9월 2일 확인했습니다. 실행 실험은 macOS에서 Codex CLI 0.148.0(codex exec --sandbox read-only)과 Claude Code 2.1.251(claude -p)로 같은 날 수행했고, 사용자 경로는 가렸습니다. 도구들이 빠르게 바뀌므로 기본값과 설정 키 이름은 버전에 따라 다를 수 있습니다.
agents.md ↗ · Codex · Custom instructions with AGENTS.md ↗ · Claude Code · How Claude remembers your project ↗ · Cursor · Rules ↗ · Gemini CLI · Provide context with GEMINI.md ↗