한 줄 정의
코딩 에이전트가 세션마다 자동으로 읽어 프로젝트 맥락·규칙을 파악하게 만드는 저장소 루트(또는 하위 폴더)의 마크다운 파일.
지금 상태 (2026-09 기준)
벤더별 전용 파일(CLAUDE.md, GEMINI.md 등)과 벤더 중립적 표준인 AGENTS.md가 공존합니다. AGENTS.md는 OpenAI Codex, Cursor, Google Jules, Amp, Factory 등이 함께 만든 개방형 포맷으로 6만 개 이상의 오픈소스 프로젝트가 채택했고, 이제 Linux Foundation 산하 Agentic AI Foundation(AAIF)이 관리합니다. Claude Code도 AGENTS.md를 폴백으로 인식하도록 확장되어, 한 저장소에 파일 하나만 두고 여러 에이전트에서 재사용하는 흐름이 자리 잡는 중입니다. Cursor의 .cursorrules는 사실상 폐기되어 .cursor/rules/*.mdc(파일별 glob·alwaysApply 메타데이터 포함)로 완전히 대체됐습니다.
개념
- CLAUDE.md: Claude Code가 세션 시작 시 자동 로드. 계층 구조를 가짐 — 전역(
~/.claude/CLAUDE.md) → 프로젝트 루트 → 하위 디렉터리, 하위 디렉터리 파일이 우선하며 상위 내용은 상속·누적됨.@경로/파일.md문법으로 다른 마크다운 파일을 임포트할 수 있어, 긴 규칙은.claude/rules/*.md로 분리해 필요한 것만 불러오는 패턴이 일반적입니다./init명령으로 저장소를 스캔해 초안을 생성할 수 있습니다. - AGENTS.md: 특정 벤더 전용 필드 없이 "빌드 명령, 테스트 명령, 코드 스타일, PR 규칙" 등을 표준 마크다운 섹션으로 적는 포맷. 모노레포에서는 여러 개(루트 + 하위 패키지별)를 둘 수 있고, 더 깊은 파일이 우선합니다.
- GEMINI.md: Gemini CLI가 동일한 계층 방식(전역/프로젝트/하위 폴더)으로 로드하는 자체 지침 파일.
- Cursor 규칙: 예전
.cursorrules(단일 파일, 컨텍스트 항상 포함)에서.cursor/rules/아래.mdc파일들로 이전. 각.mdc는 frontmatter로description,globs,alwaysApply여부를 지정해 특정 경로·상황에서만 로드되도록 스코프를 좁힐 수 있습니다. - GitHub Copilot: 저장소 전체에 적용되는
.github/copilot-instructions.md와, 경로별로 스코프를 지정하는.github/instructions/*.instructions.md(applyTo 프론트매터)를 지원. Copilot coding agent는 이후 AGENTS.md도 커스텀 지침으로 인식하도록 확장됐습니다. - Windsurf:
.windsurfrules(레포 단위)와global_rules.md(전역, Cascade 설정에서 관리) 두 계층으로 규칙을 적용. - Codex(OpenAI): AGENTS.md를 1급 지침 파일로 사용하며 CLI/IDE 확장 모두 동일 포맷을 공유.
벤더별 비교
| 항목 | Claude Code | Codex/AGENTS.md 표준 | Gemini CLI | Cursor | GitHub Copilot | Windsurf |
|---|---|---|---|---|---|---|
| 파일명 | CLAUDE.md | AGENTS.md | GEMINI.md | .cursor/rules/*.mdc (구 .cursorrules) | .github/copilot-instructions.md, *.instructions.md | .windsurfrules, global_rules.md |
| 계층/스코프 | 전역→프로젝트→하위 폴더, @import | 저장소별, 모노레포 다중 배치 | 전역→프로젝트→하위 폴더 | 파일별 globs/alwaysApply | 저장소 전체 + 경로별 applyTo | 레포 단위 + 전역 |
| 타 벤더 파일 인식 | AGENTS.md 폴백 인식 | 사실상 표준, 여러 도구가 채택 | 자체 포맷 위주 | 자체 포맷 위주 | AGENTS.md 병행 지원 | 자체 포맷 위주 |
| 거버넌스 | Anthropic 자체 | Agentic AI Foundation(Linux Foundation) | Google 자체 | Anysphere 자체 | GitHub 자체 | Windsurf(Cognition) 자체 |
잘 쓰는 법
- 짧게 유지합니다. 매 세션 컨텍스트로 통째로 들어가므로 수백 줄짜리 지침 파일은 오히려 핵심 규칙을 희석시킵니다 — 자주 언급되는 값(빌드/테스트 명령, 디렉터리 구조, 금지 사항)만 남기고 나머지는 링크나
@import로 분리. - "무엇을 하지 말라"보다 "무엇을 확인/실행하라"는 구체적 명령형으로 씁니다. 애매한 원칙 설명은 실제 동작에 잘 반영되지 않습니다.
- 빌드·테스트·린트 실행 명령, 커밋/PR 컨벤션처럼 도구가 매번 확인해야 하는 사실 정보를 최우선으로 넣습니다.
- 코드베이스 전반의 설명(아키텍처 개요, 사용 이유 등)은 별도 문서로 두고 지침 파일에는 "그 문서를 참고하라"는 포인터만 남깁니다.
- 모노레포는 하위 패키지별로 별도 AGENTS.md/CLAUDE.md를 둬서 스코프를 좁히는 것이 하나의 거대 파일보다 낫습니다.
- 여러 도구를 함께 쓴다면 AGENTS.md 하나를 기준으로 삼고, 벤더 전용 파일(CLAUDE.md 등)은 심볼릭 링크나 짧은 위임 문구("자세한 내용은 AGENTS.md 참고")로 중복을 줄입니다.
- 정기적으로 실제 에이전트 동작을 보고 지침을 다듬습니다 — 한 번 쓰고 방치하면 코드베이스가 바뀌어도 지침이 낡은 채로 남아 오히려 잘못된 방향을 유도합니다.
- 시크릿·API 키·내부 URL 같은 민감 정보는 넣지 않습니다 — 저장소를 보는 모든 에이전트·사람이 읽는 파일입니다.
타임라인
2025-08 · AGENTS.md 표준 공개
- 이전 대비: 최초 등장. 각 벤더가 자체 지침 파일 포맷(CLAUDE.md, .cursorrules 등)을 따로 쓰던 상황에서, OpenAI Codex·Cursor·Google Jules·Amp·Factory가 공동으로 벤더 중립 포맷을 제안. (Codex CLI는 2025-04 출시 때부터 AGENTS.md를 사용, 공동 표준 발표는 2025-08)
- README 스타일의 표준 섹션(설정, 빌드/테스트 명령, 코드 스타일, PR 지침)을 정의해 여러 에이전트가 하나의 파일을 공유하도록 함.
- 출처: AGENTS.md, Factory joins AGENTS.md collaboration
2025-08-28 · GitHub Copilot coding agent, AGENTS.md 지원 추가
- 이전 대비: 2025-07 도입된
.instructions.md(경로별 커스텀 지침)에 이어, Copilot이 벤더 중립 AGENTS.md도 읽도록 확장. - Copilot coding agent가 저장소의 AGENTS.md를 커스텀 지침으로 인식.
- 출처: Copilot coding agent now supports AGENTS.md custom instructions
2025-09 (추정) · Cursor, .cursorrules 폐기 → .cursor/rules/*.mdc 전환
- 이전 대비: 프로젝트 전체에 항상 주입되는 단일 파일에서, glob·alwaysApply로 스코프를 지정할 수 있는 다중
.mdc규칙 파일 구조로 전환. .cursorrules는 여전히 동작하지만 공식적으로 지원 종료(deprecated) 상태로 안내됨.- 출처: .cursorrules is deprecated — switch to .cursor/rules
2025-12-09 · AGENTS.md, Agentic AI Foundation(Linux Foundation) 창립 프로젝트로 이관
- 이전 대비: 특정 기업 컨소시엄이 관리하던 포맷에서, Linux Foundation 산하 재단(AAIF)의 공식 관리 프로젝트로 격상.
- 6만 개 이상 오픈소스 프로젝트 채택 규모를 기반으로 중립 거버넌스 체계 확립.
- 출처: Linux Foundation, AAIF 설립 발표, AAIF — AGENTS.md
2026-09 · Claude Code, AGENTS.md 폴백 인식 추가 (v2.1.277)
- 이전 대비: CLAUDE.md 전용에서, CLAUDE.md가 없을 때 AGENTS.md를 자동으로 읽어들이는 폴백 지원으로 확장 — 지침 파일 중복 관리 부담을 줄임. 병합이 아니라 폴백이므로 CLAUDE.md가 있으면 AGENTS.md는 무시됨.
- 출처: Claude Code Adds AGENTS.md Fallback
출처
- AGENTS.md 공식 사이트 (agents.md)
- Agentic AI Foundation, "AGENTS.md" 프로젝트 페이지 (aaif.io)
- GitHub Changelog, 2025-08-28
- FlowQL 블로그, Cursor rules 가이드
- DevOps.com, Claude Code AGENTS.md 폴백 기사
- Google Developers Blog, 2025-06-24