AGENTS.md, 길게 쓸수록 AI가 느려집니다
Claude Code, OpenAI Codex, Gemini CLI 모두 AGENTS.md를 읽습니다. 근데 ETH Zurich 연구팀이 438개 실제 작업으로 실험해봤더니, LLM이 자동 생성한 파일은 성공률을 3% 떨어뜨리고 비용을 20% 이상 올렸습니다. 공식 문서와 논문 데이터를 같이 놓고 보니 이런 차이가 보였습니다.
32 KB 무음 절단 함정
Codex·Claude Code·Gemini CLI 공통 포맷
AGENTS.md가 뭔지, 한 줄로 정리하면
AGENTS.md는 AI 코딩 에이전트에게 건네는 ‘팀 입사 안내서’입니다. 사람이 읽는 README.md가 있다면, AGENTS.md는 AI가 읽는 것이라고 보면 됩니다. OpenAI 공식 사이트에는 이렇게 나와 있습니다. “Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide the context and instructions.” (출처: agents.md 공식 사이트)
2026년 3월 기준 GitHub 공개 저장소에서 AGENTS.md를 포함한 프로젝트가 60,000개를 넘었습니다. (출처: agents.md 공식 사이트, 2026.03 기준) 단순한 설정 파일이 아니라, AI 코딩 생태계가 사실상 표준처럼 쓰기 시작한 포맷입니다.
이 파일이 흥미로운 이유는 하나의 파일로 여러 도구를 동시에 제어할 수 있다는 점입니다. Codex CLI, Claude Code, Gemini CLI, Cursor, Amp, Jules(Google) 모두 AGENTS.md를 읽습니다. 각 도구마다 파일명을 따로 관리하던 시대가 슬슬 끝나가고 있는 셈입니다.
세 가지 도구가 각각 어떻게 읽는지
같은 파일명을 쓰지만 각 도구가 파일을 찾는 방식은 조금씩 다릅니다. 그 차이를 모르면 세심하게 작성한 규칙이 의도한 대로 전달되지 않을 수 있습니다.
OpenAI Codex CLI (버전 0.108.x 기준)
Codex는 세션 시작 시 딱 한 번 파일을 읽고 그 내용을 고정합니다. 탐색 순서는 이렇습니다. 먼저 전역 파일인 ~/.codex/AGENTS.md를 읽고, 그다음 Git 루트부터 현재 작업 디렉터리까지 내려오면서 각 폴더의 AGENTS.md를 찾아 합칩니다. 중요한 건 AGENTS.override.md라는 파일이 존재하면 같은 폴더의 AGENTS.md를 무시합니다. (출처: OpenAI Codex 공식 문서, developers.openai.com/codex/guides/agents-md/)
Claude Code (최신 버전 기준)
Claude Code는 원래 CLAUDE.md를 자체 포맷으로 쓰다가 AGENTS.md도 읽기 시작했습니다. 두 파일이 모두 있으면 AGENTS.md가 우선합니다. CLAUDE.md는 Claude Code 전용이라 다른 도구가 읽지 못하는 반면, AGENTS.md는 팀 전체가 어떤 도구를 써도 공유됩니다.
Gemini CLI · Android Studio Gemini
Gemini CLI는 기본 설정으로 GEMINI.md를 찾지만, .gemini/settings.json에서 파일명을 AGENTS.md로 바꿀 수 있습니다. Android Studio의 Gemini는 현재 디렉터리와 모든 상위 디렉터리를 자동으로 순회하며 AGENTS.md를 찾아 프롬프트 앞에 붙입니다. (출처: Android Studio 공식 문서, developer.android.com/studio/gemini/agent-files, 2026.03.06 업데이트)
💡 공식 발표문과 실제 사용 흐름을 같이 놓고 보니 이런 차이가 보였습니다 — Codex는 세션 시작 시 딱 한 번만 파일을 읽습니다. 작업 도중 파일을 수정해도 그 세션에는 반영되지 않습니다. 새 세션을 열어야 합니다.
열심히 쓸수록 오히려 더 느려지는 이유
솔직히 말하면, 대부분의 AI 코딩 도구 튜토리얼은 AGENTS.md를 최대한 자세하게 작성하라고 권장합니다. 그런데 2026년 2월, ETH Zurich와 LogicStar.ai 연구팀이 이 통념을 정면으로 뒤집는 논문을 냈습니다.
📊 논문 주요 수치 요약 (출처: arXiv:2602.11988, Gloaguen et al., 2026.02)
실험 조건: Claude Code(Sonnet 4.5), Codex(GPT-5.2 / GPT-5.1 Mini), Qwen Code(Qwen3-30B) 대상으로 SWE-Bench Lite 300건 + 자체 AgentBench 138건, 총 438건 실제 GitHub 이슈 수행.
• LLM 자동 생성 파일(/init 명령으로 만든 것): 성공률 약 3% 감소, 추론 비용 20% 이상 증가
• 개발자가 직접 작성한 파일: 성공률 약 4% 개선, 그러나 비용은 여전히 최대 19% 증가
• GPT-5.2는 AGENTS.md가 있을 때 추론 토큰을 22% 더 사용했고, GPT-5.1 Mini는 14% 더 사용했습니다.
에이전트가 파일을 무시해서 성능이 떨어지는 게 아닙니다. 오히려 너무 충실하게 지키려다 오버헤드가 생깁니다. 논문에서 추적한 실행 로그를 보면, AGENTS.md에 특정 테스트 명령어가 적혀 있으면 에이전트는 해당 명령을 매 태스크마다 실행하려 합니다. pnpm 사용 지시를 적어두면 거의 0에 가깝던 pnpm 호출이 평균 1.6회로 늘었습니다. 지시대로 움직이되, 그게 매번 필요한 단계는 아니었던 겁니다.
또 한 가지 흥미로운 점은 LLM이 생성한 AGENTS.md와 개발자가 직접 쓴 것을 서로 바꿔서 써도 성능 차이가 일관되지 않았습니다. 문제는 생성 품질이 아니라 파일의 내용 구성 방식 자체였습니다.
⚠️ GPT-5.1 Mini는 이미 컨텍스트에 로드된 AGENTS.md를 다시 찾아 읽는 추가 단계를 밟았습니다. 파일이 없었으면 생기지 않았을 작업이 파일 때문에 생긴 셈입니다.
32 KB에서 조용히 잘리는 문제
이 부분이 가장 실질적인 함정입니다. Codex CLI는 AGENTS.md를 기본값 32 KB(대략 600~800줄)까지만 읽습니다. 그 이상은 조용히 잘립니다. 경고 없이, 어떤 알림도 없이.
OpenAI GitHub 이슈 #13386(2026.03.03 접수)에서 사용자가 직접 재현 방법을 공개했습니다. “1. 32KB를 초과하는 AGENTS.md에 중요한 지시사항을 뒷부분에 배치. 2. 세션 시작. 3. 에이전트는 그 지시사항을 절대 읽지 않음.” (출처: github.com/openai/codex/issues/13386) 파일이 읽히고 있다고 착각한 채 에이전트가 지시를 무시한다고 오해할 수 있습니다.
반면 Claude Code는 CLAUDE.md가 너무 크면 세션 시작 시 눈에 띄는 경고를 표시합니다. 같은 문제를 다른 방식으로 처리한 겁니다. Codex를 쓰면서 AGENTS.md가 길다면 반드시 ~/.codex/config.toml에서 한도를 올려야 합니다.
🔧 Codex 32KB 한도 늘리는 설정
# ~/.codex/config.toml project_doc_max_bytes = 65536 # 기본 32768에서 64KB로 변경 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
(출처: OpenAI Codex 공식 문서 — Config Advanced, developers.openai.com/codex/config-advanced)
실제로 넣어야 할 것, 빼도 되는 것
ETH Zurich 논문이 확인한 핵심은 하나입니다. AI가 저장소를 탐색하면서 스스로 발견할 수 있는 정보는 AGENTS.md에 넣어도 의미가 없습니다. 심지어 성능을 떨어뜨립니다. LLM이 자동 생성한 AGENTS.md에서 100%에 가까운 파일이 ‘코드베이스 개요’ 섹션을 포함했지만, 해당 섹션이 있어도 에이전트가 관련 파일을 찾는 속도는 변하지 않았습니다.
| ✅ 넣을 것 | ❌ 빼도 되는 것 |
|---|---|
| 패키지 매니저 선호 (npm 대신 pnpm 등) | 디렉터리 구조 설명 (파일 시스템이 말해줌) |
| 커밋 전 필수 실행 명령어 (lint·test) | 사용 언어·프레임워크 (package.json이 말해줌) |
| 팀 내부 용어·비공개 API 명칭 | 일반 코딩 컨벤션 (기존 코드가 보여줌) |
| 절대 건드리면 안 되는 파일·폴더 | 프로젝트 전체 개요 (README가 말해줌) |
| PR 제목 형식, 브랜치 명명 규칙 | 일반적인 에러 핸들링 원칙 |
💡 실제 데이터와 권장 사례를 교차해서 보니 이런 기준이 나왔습니다 — 빈 파일로 시작해서 에이전트가 반복해서 틀리는 행동이 생길 때만 한 줄씩 추가하는 방식이 논문에서도 가장 효과적으로 나왔습니다. .gitignore처럼 운영하는 겁니다.
글로벌 파일과 프로젝트 파일, 뭘 어디에 쓸까
AGENTS.md의 레이어 구조를 활용하면 같은 규칙을 매 프로젝트마다 반복하지 않아도 됩니다. Codex 공식 문서는 두 레이어를 이렇게 구분합니다. (출처: developers.openai.com/codex/guides/agents-md/)
🏠 전역 파일 — ~/.codex/AGENTS.md
내가 어떻게 일하는지를 담습니다. strict typing 선호, 에러를 조용히 삼키지 말 것, 최소한의 변경만, 함수형 패턴 우선 같은 개인 코딩 원칙이 여기에 들어갑니다. 어느 저장소를 열어도 이 원칙이 기본 적용됩니다.
📁 저장소 파일 — (저장소 루트)/AGENTS.md
이 코드베이스가 어떻게 돌아가는지를 담습니다. 어떤 테스트 명령어, 어떤 폴더가 위험한지, PR 형식, 배포 전 체크리스트. 팀원과 버전 관리로 공유하는 파일이 됩니다.
한 가지 실용적인 팁입니다. Codex는 세션 시작 시 파일을 한 번만 빌드하므로, 특정 서브디렉터리에서 작업할 때는 해당 폴더 안에 AGENTS.override.md를 두면 상위 폴더의 AGENTS.md를 덮어씁니다. payments 모듈처럼 특수한 테스트 명령을 쓰는 경우에 유용합니다.
💡 전역 파일과 저장소 파일 역할을 섞으면 어느 쪽 파일에 뭘 써야 하는지 금방 헷갈립니다. 두 레이어를 개인 규칙과 팀 규칙으로 분리하면 관리가 훨씬 단순해집니다.
Gemini CLI에서 AGENTS.md 사용하는 방법
Gemini CLI는 기본적으로 GEMINI.md를 찾습니다. AGENTS.md를 쓰려면 설정 파일에 한 줄만 추가하면 됩니다. (출처: agents.md 공식 사이트)
# .gemini/settings.json
{
"context": {
"fileName": "AGENTS.md"
}
}
이렇게 하면 하나의 AGENTS.md로 Codex, Claude Code, Gemini CLI를 동시에 제어할 수 있습니다.
Q&A 5가지
Q1. AGENTS.md를 /init 명령으로 자동 생성해도 되나요?
ETH Zurich 논문 기준으로는 권장하지 않습니다. LLM이 자동 생성한 파일은 평균적으로 성공률을 약 3% 떨어뜨리고 비용을 20% 이상 올렸습니다. (arXiv:2602.11988) 빈 파일로 시작해서 실제 문제가 반복될 때만 규칙을 추가하는 방식이 더 효과적입니다.
Q2. AGENTS.md와 CLAUDE.md를 둘 다 만들어야 하나요?
팀에서 Claude Code 외에 Codex나 Gemini CLI도 함께 사용한다면 AGENTS.md 하나로 통일하는 게 맞습니다. Claude Code는 AGENTS.md를 읽으며, 두 파일이 공존할 경우 AGENTS.md가 우선됩니다. CLAUDE.md는 Claude Code 단독으로만 사용하는 경우에만 의미가 있습니다.
Q3. Codex에서 AGENTS.md가 적용됐는지 확인하는 방법은?
codex --ask-for-approval never "현재 로드된 지시사항을 요약해줘" 명령을 실행하면 Codex가 어떤 파일에서 어떤 내용을 읽었는지 출력합니다. 세션 로그는 ~/.codex/log/codex-tui.log에서도 확인 가능합니다. (출처: OpenAI Codex 공식 문서)
Q4. 모노레포에서는 어떻게 구성하는 게 좋을까요?
서브패키지마다 별도 AGENTS.md를 두는 방식이 공식 권장입니다. OpenAI 공식 저장소에는 2026년 3월 현재 88개의 AGENTS.md 파일이 있습니다. (출처: agents.md 공식 사이트) 루트 파일은 전체 공통 규칙만, 각 패키지 폴더에는 해당 서비스에 특화된 명령어만 담으면 됩니다. 가장 가까운 디렉터리의 파일이 우선 적용됩니다.
Q5. 기존에 AGENT.md(단수)로 쓰던 파일이 있는데 이름을 바꿔야 하나요?
공식 표준은 AGENTS.md(복수)입니다. 기존 파일을 마이그레이션하려면 이름을 바꾼 뒤 하위 호환을 위한 심볼릭 링크를 만들면 됩니다. mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md (출처: agents.md 공식 사이트)
마치며
AGENTS.md는 제대로 쓰면 분명히 효과가 있습니다. 개발자가 직접 작성한 파일은 평균 4%의 성공률 개선을 보였고, 팀 전체가 도구 상관없이 공유할 수 있는 유일한 포맷입니다. 문제는 ‘열심히 쓸수록 좋다’는 전제입니다. 그 전제가 틀렸습니다.
AI가 저장소를 직접 탐색해서 알 수 있는 내용은 적지 않아도 됩니다. AGENTS.md에 넣을 자격이 있는 건 에이전트가 반복해서 틀리는 행동, 코드베이스 어디에도 적혀 있지 않은 팀 암묵지, 그리고 절대 건드리면 안 되는 영역뿐입니다. Codex의 32KB 무음 절단 함정은 그냥 두면 모르고 지나치기 쉽습니다. 먼저 확인하고 필요하면 한도를 늘려두는 게 맞습니다. 개인적으로는 이번에 이 파일을 다시 들여다보고, 전체 내용의 절반 이상을 지웠습니다. 에이전트가 더 빠르게 움직이기 시작했고 이 부분이 좀 아쉬웠습니다 — 진작 줄일걸.
본 포스팅 참고 자료
- OpenAI Codex 공식 AGENTS.md 가이드 — developers.openai.com/codex/guides/agents-md/
- AGENTS.md 공식 오픈 포맷 사이트 (Agentic AI Foundation, Linux Foundation) — agents.md
- Android Studio Gemini AGENTS.md 공식 문서 (2026.03.06 업데이트) — developer.android.com/studio/gemini/agent-files
- Gloaguen et al. (2026.02), “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, ETH Zurich / LogicStar.ai — arxiv.org/abs/2602.11988
- OpenAI Codex GitHub Issue #13386 — AGENTS.md 32KB 무음 절단 버그 리포트 (2026.03.03) — github.com/openai/codex/issues/13386
본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. Codex CLI, Claude Code, Gemini CLI는 빠르게 업데이트되는 도구입니다. 본문의 수치·설정값은 2026.03.22 기준이며, 공식 문서에서 최신 정보를 확인하는 것을 권장합니다.
댓글 남기기