AGENTS.md, AI 코딩 에이전트를 위한 표준 지침 파일
목차
개요
AGENTS.md는 AI 코딩 에이전트에게 프로젝트의 맥락과 지시사항을 전달하기 위한 전용 마크다운 파일이다. README.md가 사람 독자를 위한 것이라면, AGENTS.md는 에이전트가 작업하기 위해 필요한 기술적 가이드를 담는다. 현재 6만 개 이상의 오픈소스 프로젝트가 이 포맷을 채택하고 있다.
배경
AI 코딩 에이전트가 본격적으로 확산되면서, 각 도구마다 고유의 지침 파일 형식(예: CLAUDE.md, .cursorrules 등)이 난립했다. 프로젝트 관리자는 같은 내용을 여러 파일에 중복 관리해야 했고, 에이전트 간 호환성도 떨어졌다. AGENTS.md는 AI 개발 생태계 전반의 협업을 통해 탄생한 비독점적 표준 규약을 지향한다.
핵심 내용
포맷과 스펙
AGENTS.md는 일반 마크다운 파일이며, 필수 필드가 없다. 개발자는 프로젝트 특성에 맞게 빌드 커맨드, 코드 스타일, 테스트 절차, PR 가이드라인 등 자유로운 섹션을 구성할 수 있다. 스펙은 의도적으로 유연하고 개방적으로 설계되었다.
동작 방식
에이전트는 현재 작업 디렉토리에서 가장 가까운 AGENTS.md를 읽는다. 모노레포에서는 서브프로젝트별로 중첩된 AGENTS.md를 둘 수 있으며, 하위 경로의 파일이 상위 파일보다 우선된다. 사용자의 명시적 프롬프트는 언제나 파일 기반 지시를 덮어쓴다.
채택 현황
| 플랫폼 | 지원 |
|---|---|
| OpenAI Codex | O |
| Google Jules | O |
| Cursor | O |
| VS Code | O |
| GitHub Copilot | O |
| Devin | O |
메이저 AI 코딩 도구 대부분이 이 규약을 따르고 있다.
의미와 시사점
AGENTS.md는 에이전트 중심 개발의 첫 번째 상호운용 표준에 가깝다. 프로젝트 소유자는 한 파일만 유지하면 여러 에이전트가 동일한 맥락을 공유할 수 있다. 사람용 문서와 에이전트용 문서를 분리함으로써 README의 복잡도도 낮아진다. 장기적으로는 package.json처럼 에이전트 지원의 기본 메타데이터로 자리 잡을 가능성이 있다.
결론
AGENTS.md는 간단한 마크다운 규약이지만, AI 코딩 시대에 프로젝트와 에이전트를 연결하는 실질적 접점이 되고 있다. 6만 개 프로젝트와 주요 플랫폼 대부분이 지원한다는 사실은 이 포맷이 사실상의 표준에 근접했음을 보여준다.