CLAUDE.md가 기억이라면, AGENTS.md는 행동 매뉴얼이에요. AI 코딩 에이전트가 프로젝트에 투입될 때 "여기선 이렇게 일해"라고 알려주는 단 하나의 파일. 그런데 6만 개 넘는 오픈소스 프로젝트가 이미 쓰고 있는 이 파일을, 아직도 안 만들어놨다면? 지금이 시작할 타이밍이에요.
이게 뭔데?
AGENTS.md는 프로젝트 루트에 놓는 마크다운 파일이에요. AI 코딩 에이전트를 위한 README라고 생각하면 돼요. 사람이 README.md를 보고 프로젝트를 이해하듯, AI 에이전트는 AGENTS.md를 보고 "여기선 어떻게 일해야 하는지"를 파악해요.
2025년 8월 OpenAI Codex 팀에서 처음 제안했고, 지금은 Linux Foundation 산하 Agentic AI Foundation이 관리하는 오픈 표준이 됐어요. 핵심은 하나의 파일로 모든 AI 도구를 커버한다는 점이에요. 예전에는 .cursorrules, .builderrules 같은 도구별 설정 파일이 프로젝트를 어지럽혔는데, AGENTS.md 하나면 정리돼요.
CLAUDE.md와 뭐가 다른 건데?
CLAUDE.md는 Anthropic의 Claude 제품 전용이에요. AGENTS.md는 도구에 상관없이 작동하는 범용 표준이고요. 둘 다 쓰고 싶다면? CLAUDE.md에 Strictly follow the rules in./AGENTS.md 한 줄만 적거나, 심볼릭 링크로 연결하면 돼요.
지원하는 도구 목록이 이미 어마어마해요. GitHub Copilot, Cursor, Windsurf, Codex, VS Code, Gemini CLI, Devin, Junie(JetBrains), Amp, Aider, Zed, goose, Roo Code... 사실상 주요 AI 코딩 도구를 다 커버해요.
뭐가 달라지는 건데?
AGENTS.md가 없으면, AI 에이전트는 매번 탐험가가 돼요. 프로젝트 구조 탐색하고, 빌드 명령어 추측하고, 코딩 스타일 파악하느라 시간과 토큰을 소모해요. 그리고 높은 확률로 틀려요.
Builder.io의 Steve Sewell이 직접 실험한 결과가 인상적이에요. AGENTS.md 없이 Figma 디자인을 코드로 변환했더니 — MUI 버전을 잘못 참조해서 스타일이 깨지고, 내부 상태관리 라이브러리(mobx) 대신 useState를 쓰고, 다크모드 토큰을 빠뜨렸어요. AGENTS.md를 추가한 뒤에는? 같은 프롬프트로 UI 정확도, 토큰 사용, 코드 스타일 모두 눈에 띄게 개선됐어요.
| AGENTS.md 없이 | AGENTS.md 있으면 | |
|---|---|---|
| 프로젝트 파악 | 매 세션마다 구조 탐색 반복 | 핵심 파일 위치 즉시 참조 |
| 빌드/테스트 | 전체 빌드 실행 (수 분 소요) | 파일 단위 명령어로 수 초 만에 검증 |
| 코딩 스타일 | 버전 오류, 라이브러리 선택 실수 | 정확한 버전과 패턴을 첫 시도에 적용 |
| 안전성 | 예고 없이 패키지 설치, 파일 삭제 | 허용/금지 행동이 명확히 정의됨 |
| 일관성 | 에이전트마다 다른 결과 | 어떤 도구를 써도 같은 규칙 적용 |
GitHub의 Matt Nigh는 2,500개 이상의 AGENTS.md 파일을 분석해서 성공 패턴을 찾았어요. 결론은 명확했어요 — 잘 되는 AGENTS.md에는 6가지 영역이 반드시 포함돼 있었어요: 실행 명령어, 테스트, 프로젝트 구조, 코드 스타일, Git 워크플로우, 그리고 경계(Boundaries).
반면 실패하는 파일의 공통점도 뚜렷했어요. "You are a helpful coding assistant"처럼 모호한 지시, 기술 스택을 죄다 나열하는 장황함, 구체적 명령어 없이 추상적 설명만 있는 경우. Ben Tossell도 흥미로운 데이터를 공유했어요 — 기술 스택, 핵심 파일, 아키텍처를 상세히 적은 AGENTS.md가 오히려 성능을 저하시키고 비용을 20% 높였다는 연구 결과가 있대요. 에이전트가 그런 건 스스로 파악할 수 있거든요.
"AGENTS.md should be pretty empty. It should be your preferences and nudges to correct agent behaviour."
— Ben Tossell, Ben's Bites
핵심만 정리: 좋은 AGENTS.md 쓰는 법
- Do/Don't 리스트부터 시작하세요
가장 효과적인 출발점이에요. AI 에이전트에게 작업을 시켜보고, 마음에 안 드는 점이 나올 때마다 한 줄씩 추가하면 돼요. "MUI v3 호환 코드를 작성할 것", "색상값을 하드코딩하지 말 것" 같은 식으로요. 추상적 설명 대신 구체적 지시가 핵심이에요. - 파일 단위 명령어를 넣으세요
전체 빌드 대신 파일 하나만 빠르게 검증하는 명령어를 제공하면, 에이전트가 수 분이 아니라 수 초 만에 피드백 루프를 돌아요. 예를 들어npm run tsc --noEmit path/to/file.tsx처럼요. 빠르고 저렴하니까, "항상 실행하라"고 지시할 수 있어요. - 경계(Boundaries)를 3단계로 정의하세요
GitHub 분석에서 가장 효과적이었던 패턴이에요. 허용(Always do), 확인 후 진행(Ask first), 절대 금지(Never do)의 3단계로 나누세요. "절대 시크릿을 커밋하지 마라"가 가장 많이 등장한 제약이었어요. - 좋은 예시 파일을 가리키세요
설명 세 문단보다 실제 코드 예시 하나가 낫다는 게 2,500개 분석의 결론이에요. "폼은app/components/DashForm.tsx를 참고할 것", "레거시인Admin.tsx의 클래스 컴포넌트 패턴은 따라하지 말 것" — 이런 식으로 좋은 파일과 나쁜 파일을 콕 집어주세요. - 반복되는 실수가 보이면 한 줄 추가하세요
AGENTS.md는 완성품이 아니라 살아있는 문서예요. 에이전트가 같은 실수를 두 번 했다면, 그때 규칙을 추가하면 돼요. 처음부터 완벽하게 쓰려고 하지 마세요. 업프론트 플래닝보다 이터레이션이 더 효과적이라는 게 실전의 교훈이에요.
흔한 실수: 너무 많이 쓰는 것
기술 스택, 아키텍처, 파일 목록을 죄다 적으면 오히려 역효과예요. AI 에이전트는 프로젝트를 탐색해서 그런 건 스스로 파악할 수 있어요. 에이전트가 틀릴 만한 것만 적으세요 — 선호하는 라이브러리, 코딩 컨벤션, 절대 건드리면 안 되는 영역 같은 것들이요.
모노레포를 쓰고 있다면 한 가지 더. 하위 디렉토리마다 AGENTS.md를 중첩할 수 있어요. 에이전트는 작업 중인 파일에서 가장 가까운 AGENTS.md를 우선 적용하거든요. OpenAI Codex 레포에는 AGENTS.md가 88개나 있어요. 루트에는 공통 규칙, 하위 패키지에는 해당 패키지 전용 규칙을 넣으면 돼요.
