AGENTS.md는 코덱스·클로드 코드·깃허브 코파일럿·커서가 모두 읽는 AI 에이전트용 표준 프로젝트 안내 파일이다. 6만 개 이상 오픈소스 프로젝트가 채택했지만 지나치게 상세한 파일이 오히려 에이전트 실패 원인이 된다는 연구가 있다. AGENTS.md vs CLAUDE.md vs .cursorrules 차이, 과다 명세 4가지 함정, 60줄 이내 최적 구조, 에이전트별 지원 현황, 규칙이 무시될 때 점검 체크리스트까지 실전 가이드로 정리했다.
AGENTS.md는 AI 코딩 에이전트에게 이 프로젝트가 어떻게 구성되어 있고, 어떤 명령을 실행해야 하며, 무엇을 하면 안 되는지 알려주는 프로젝트 루트 파일이다. "에이전트를 위한 README"라고 이해하면 된다. 마크다운 형식으로 작성하며 프로젝트 루트(또는 하위 디렉토리)에 놓으면 에이전트가 자동으로 읽는다.
오픈AI가 처음 코덱스를 공개하면서 이 형식을 제안했고, 이후 구글·앤트로픽·커서·소스그래프(Sourcegraph)가 2026년 상반기에 동일한 파일 형식을 지원하기로 합의했다. 에이전틱 AI 파운데이션(AAIF)이 이 표준을 리눅스 재단 프로젝트로 가져가면서 사실상 업계 표준이 됐다.
에이전트는 세션 시작 시 AGENTS.md를 읽고 컨텍스트로 유지한다. 파일의 모든 내용이 매 요청마다 에이전트에게 전달되기 때문에, 내용이 길수록 토큰 비용이 늘어나고 중요한 지시가 묻힐 위험도 커진다.
파일 이름이 다르면 역할도 다르다. 혼동하면 지시가 충돌하거나 에이전트가 무시한다.
AGENTS.md: 에이전트 중립 표준 파일이다. 코덱스·클로드 코드·깃허브 코파일럿·커서·아이더(Aider) 등 여러 에이전트가 모두 읽는다. 한 프로젝트에서 여러 에이전트를 쓴다면 이 파일 하나로 통일된 지시를 줄 수 있다.
CLAUDE.md: 클로드 코드 전용 파일이다. 앤트로픽 공식 형식으로, 클로드 코드가 시작할 때 자동으로 읽는다. AGENTS.md보다 클로드 코드 특화 기능(훅 설정, 허용/차단 패턴, 메모리 연동)을 세밀하게 제어할 수 있다. 클로드 코드만 쓴다면 CLAUDE.md가 더 적합하다.
.cursorrules: 커서(Cursor) 전용 구형 파일이다. 커서 3.0 이후로는 AGENTS.md를 읽으며 .cursorrules는 하위 호환으로 남아 있다. 새 프로젝트에서는 AGENTS.md로 시작하는 것이 낫다.
세 파일을 동시에 두면 에이전트마다 서로 다른 지시를 받을 수 있다. 모순되는 규칙이 있으면 에이전트는 두 파일 중 하나를 무시하거나 예측 불가능하게 동작한다. 표준을 하나로 통일하거나 각 파일의 역할을 명확히 분리해야 한다.
AI 타임스 보도에 따르면 코딩 에이전트 실패의 주된 원인 중 하나는 "지나치게 상세한 AGENTS.md"다. 이 역설적인 결과가 반복되는 이유를 이해하는 것이 올바른 작성의 출발점이다.
첫 번째 함정: 컨텍스트 포화. AGENTS.md가 300줄을 넘으면 에이전트가 파일 전체를 컨텍스트 창에 올리면서 실제 코드나 지시사항을 처리할 공간이 줄어든다. 특히 긴 설명 문단이나 "배경 설명" 섹션이 많을수록 에이전트는 중요한 규칙을 후반부에서 찾지 못하는 경우가 생긴다.
두 번째 함정: 추상적 지시. "항상 좋은 코드를 작성하라", "사용자 친화적으로 만들어라" 같은 문장은 에이전트가 실행 가능한 행동을 도출하기 어렵다. 에이전트는 이런 추상적 지시를 만나면 자체 판단으로 채우는데, 그 결과가 개발자의 의도와 다를 수 있다.
세 번째 함정: 금지 목록 중심. 해야 할 것보다 하지 말아야 할 것이 훨씬 많으면 에이전트가 소극적으로 동작한다. 취소 가능한 행동에도 계속 확인을 요청하거나, 지시를 이행하지 않고 "이 작업을 해도 되나요?"를 반복한다.
네 번째 함정: 날짜나 상태 정보 포함. "현재 우리 팀은 리팩토링 중이다", "마이그레이션 완료 후 삭제 예정"처럼 시간이 지나면 틀려지는 정보를 넣으면 에이전트가 잘못된 전제로 동작한다. AGENTS.md는 코드처럼 갱신되지 않는다.
효과적인 AGENTS.md는 4가지 섹션으로 구성된다. 순서도 중요하다. 에이전트는 위에서 아래로 읽으며 앞에 나온 내용에 더 높은 가중치를 둔다.
1. 빠른 시작 명령 — 파일 첫머리에 배치. "이 프로젝트를 실행하려면 어떻게 하는가"를 한눈에 보여준다. 설치, 빌드, 테스트 명령을 구체적인 쉘 명령어로 적는다. 에이전트가 처음 접근할 때 필요한 컨텍스트다.
2. 프로젝트 구조 — 핵심 파일·디렉토리만. 전체 디렉토리 트리를 나열하지 않는다. 에이전트가 코드를 수정할 때 어디를 봐야 하는지 안내하는 3~5줄이면 충분하다.
3. 경계(Boundaries) — 해야 할 것과 하지 말아야 할 것. 절대 건드리면 안 되는 파일, 수정 전 확인이 필요한 패턴, 스타일 규칙을 구체적으로 명시한다. "좋은 코드"가 아니라 "이 파일에 직접 쓰지 마라"처럼 행동 단위로 쓴다.
4. 코드 예시 — 가능하면 포함. 추상적인 설명보다 실제 코드 패턴 하나가 훨씬 효과적이다. "에러 처리는 try-catch 대신 Result 타입을 쓴다"보다 10줄짜리 예시 코드가 낫다.
AGENTS.md 기본 템플릿 (60줄 이내 권장)# Project: my-app ## 빠른 시작 ```bash npm install npm run dev # 로컬 서버 (포트 3000) npm test # 단위 테스트 npm run build # 프로덕션 빌드 ``` ## 프로젝트 구조 - src/app/ — Next.js App Router 페이지 - src/components/ — 재사용 UI 컴포넌트 - src/lib/ — 유틸리티 함수 - data/ — 정적 데이터 파일 ## 경계 규칙 - data/*.json은 직접 편집 금지. scripts/update-*.ts 를 사용 - src/lib/db.ts의 쿼리 함수를 바꾸기 전에 반드시 물어볼 것 - 환경변수는 .env.local 에만 — 절대 코드에 하드코딩 금지 ## 코딩 스타일 ```typescript // 에러 처리 예시 — try-catch 대신 이 패턴 const result = await fetchUser(id) if (!result.ok) { return { error: result.error } } ```
AGENTS.md를 작성하기 전에 자신이 쓰는 에이전트가 어떻게 파일을 읽는지 이해해야 한다. 지원 방식이 에이전트마다 다르다.
코덱스(Codex) CLI: AGENTS.md를 공식 채택한 원조다. 프로젝트 루트와 현재 작업 디렉토리를 모두 탐색해서 찾는다. 하위 디렉토리의 AGENTS.md도 스코프가 겹치면 자동으로 읽는다.
클로드 코드: CLAUDE.md를 우선 읽고 AGENTS.md도 지원한다. 두 파일이 모두 있으면 CLAUDE.md 내용이 우선 적용된다. 클로드 코드 전용 기능(훅, 허용 도구 설정)은 CLAUDE.md에서만 제어할 수 있다.
깃허브 코파일럿 에이전트 모드: VS Code 확장판 기준으로 AGENTS.md를 읽는다. 2026년 GA(정식 출시) 이후 리포지토리 루트에서 자동으로 탐색한다.
커서(Cursor) 3.0+: .cursorrules 대신 AGENTS.md를 권장 형식으로 채택했다. .cursorrules와 AGENTS.md가 동시에 있으면 AGENTS.md를 우선한다.
아이더(Aider): --read AGENTS.md 옵션으로 명시적으로 로드한다. 자동 탐색이 아니어서 명령어에 포함시켜야 한다.
AGENTS.md를 작성해도 에이전트가 규칙을 무시한다는 피드백이 많다. 이럴 때 확인할 것들이다.
길이 확인: 60줄 이하가 이상적이다. 300줄을 넘으면 에이전트가 파일 후반부를 사실상 읽지 못할 수 있다. 줄이기 어렵다면 "필수" 섹션과 "참고" 섹션을 나눠서 필수만 상단에 배치한다.
지시 문체 확인: "하지 마라(Don't)", "반드시 ~하라(Always)", "~를 사용하라(Use)" 같은 명령형이 추상 명사 설명보다 효과적이다. "프로젝트는 TypeScript로 작성된다" 대신 "TypeScript strict 모드를 사용하라. tsconfig.json의 strict: true를 변경하지 마라."로 구체화한다.
중복 제거: CLAUDE.md와 AGENTS.md에 같은 내용이 있으면 충돌 가능성이 있다. 에이전트 중립 규칙만 AGENTS.md에 두고, 클로드 코드 전용 설정은 CLAUDE.md로 분리한다.
테스트 방법: AGENTS.md를 수정한 후 에이전트에게 "이 프로젝트의 규칙을 요약해줘"라고 물어본다. 핵심 규칙이 응답에 나타나지 않으면 파일이 제대로 읽히지 않거나 너무 뒤에 위치한 것이다.
써도 되지만 역할 분리를 명확히 해야 한다. 에이전트 중립 규칙(빌드 명령, 디렉토리 구조, 코드 스타일)은 AGENTS.md에, 클로드 코드 전용 설정(훅, 허용 도구, 메모리)은 CLAUDE.md에 두는 방식이 권장된다. 두 파일에 같은 규칙이 있으면 충돌이 발생할 수 있다.
60줄 이하가 이상적이다. 300줄이 넘어가면 에이전트가 파일 후반부를 사실상 처리하지 못하는 사례가 보고되어 있다. 내용이 많다면 필수 규칙을 상단에, 참고 내용을 하단에 두거나 별도 docs/ 파일로 분리하고 AGENTS.md에서 링크로 참조한다.
AGENTS.md 하나를 기준으로 삼고 각 에이전트 전용 설정은 별도 파일(.claude/CLAUDE.md, .cursorrules)에 두는 방식이 관리하기 쉽다. AGENTS.md는 어느 에이전트든 읽을 수 있는 공통 규칙만 담고, 에이전트별 최적화는 각 전용 파일에서 처리한다.
먼저 파일 길이를 확인한다. 60줄 이내로 줄이는 것이 1순위다. 그다음 지시 문체를 점검한다. 추상적 설명 대신 명령형 동사("사용하라", "하지 마라")로 바꾼다. 그래도 안 되면 에이전트에게 "이 프로젝트의 핵심 규칙을 3가지로 요약해줘"라고 물어봐서 파일이 제대로 읽히는지 확인한다.
둘 수 있다. 코덱스와 클로드 코드는 현재 작업 디렉토리와 부모 디렉토리의 AGENTS.md를 모두 탐색해서 계층적으로 적용한다. 모노레포에서 패키지별로 다른 규칙이 필요할 때 유용하다. 단, 계층이 깊어질수록 어느 규칙이 적용되는지 혼란스러울 수 있으므로 너무 많이 두지 않는다.
세 가지를 피한다. 첫째, 시간이 지나면 틀려지는 상태 정보("현재 마이그레이션 진행 중"). 둘째, 이미 코드나 README에 있는 내용 중복. 셋째, 팀 문화나 가치관 서술("우리는 품질을 중시한다"). 이런 내용은 에이전트가 실행 가능한 행동으로 변환하기 어렵고 컨텍스트만 차지한다.
