AGENTS.md – AI 코딩 에이전트를 위한 오픈 포맷 가이드 파일 | AI Paper Digest

TL;DR Highlight

AGENTS.md가 AI 코딩 에이전트를 위한 프로젝트 안내서로 기능하며 6만 개 이상의 오픈소스 프로젝트에 채택되었다.

Who Should Read

AI 코딩 에이전트(Cursor, Copilot, Codex, Claude Code 등)를 실무에서 쓰고 있고, 에이전트가 프로젝트 컨텍스트를 더 잘 이해하게 만들고 싶은 개발자.

Core Mechanics

AGENTS.md는 AI 코딩 에이전트에게 프로젝트의 빌드 명령어, 테스트 방법, 코드 스타일 규칙 등을 알려주는 마크다운 파일이다. README.md가 사람 온보딩용이라면, AGENTS.md는 에이전트 온보딩용으로 분리해서 쓰자는 취지다.
OpenAI Codex, Google Jules, Cursor, Windsurf, Aider, GitHub Copilot, Gemini CLI, Factory, Zed, Warp 등 20개 이상의 코딩 에이전트/도구가 이미 AGENTS.md를 지원한다. 하나의 파일로 여러 에이전트에 동시에 적용할 수 있다는 게 핵심 셀링 포인트다.
사용법은 단순하다. 프로젝트 루트에 AGENTS.md를 만들고, 프로젝트 개요·빌드/테스트 커맨드·코드 스타일·PR 규칙 등 에이전트가 알아야 할 내용을 적으면 된다. 필수 필드나 스키마 같은 건 없고, 그냥 마크다운이다.
모노레포의 경우 서브프로젝트마다 별도의 AGENTS.md를 둘 수 있다. 에이전트가 디렉토리 트리에서 가장 가까운 파일을 읽기 때문에, 패키지별로 맞춤 지침을 줄 수 있다. OpenAI 메인 레포에는 AGENTS.md가 88개 들어있다고 한다.
Linux Foundation 산하 Agentic AI Foundation이 이 포맷을 공식 관리(steward)하게 되었다. OpenAI, Google, Cursor, Amp, Factory 등이 협력해서 만든 오픈 포맷이라는 점을 강조하고 있다.
GitHub에서 이미 6만 개 이상의 오픈소스 프로젝트가 AGENTS.md를 사용 중이며, Apache Airflow(4,215줄), Temporal SDK(122줄) 같은 대형 프로젝트도 포함되어 있다.
실질적으로 포맷이나 표준이라 부르기엔 단순한 파일명 컨벤션에 가깝다. 마크다운 안에 뭘 쓰든 자유이고, 강제되는 구조가 없다. 이게 장점이자 한계다.

Evidence

현재 Claude Code는 CLAUDE.md, Cursor는 .cursorrules, Windsurf는 .windsurfrules 등 각 에이전트마다 고유 파일명을 쓰고 있어서, 실제로는 하나의 AGENTS.md로 통일이 안 된다는 비판이 많았다. ruler(https://github.com/intellectronica/ruler) 같은 도구로 여러 포맷을 자동 생성하는 사람도 있다.
"사람한테 문서 쓰라고 하면 안 쓰더니, 로봇한테 문서 쓰라니까 쓴다"는 아이러니한 반응이 많았다. 결과적으로 AI를 위해 문서를 정리하면 사람도 혜택을 본다는 '인체공학적 손잡이(ergonomic handles)' 비유가 공감을 얻었다.
폴더 구조(.agents/index.md + auth.md + testing.md 등)로 분리하는 게 하나의 거대한 마크다운보다 훨씬 낫다는 경험 공유가 있었다. 토큰 낭비를 줄이고 관련 컨텍스트만 선택적으로 로드할 수 있기 때문이다.
"에이전트가 특별한 가이드 없이도 코드베이스를 이해하는 게 LLM의 약속 아닌가"라는 근본적 회의론도 있었다. 과도기일 뿐이고, 결국 좋은 문서를 사람 중심으로 쓰면 에이전트도 알아서 읽을 것이라는 의견과, 5,000개 레포를 관리하면서 AST+RAG 하이브리드 검색으로 코드 요약 메타데이터를 만드는 게 훨씬 효과적이라는 실전 사례가 대비되었다.
Anthropic/Claude가 지원 목록에 빠져있다는 지적이 있었다. Claude Code는 CLAUDE.md라는 자체 파일명을 쓰고 있어서, 심볼릭 링크로 AGENTS.md → CLAUDE.md를 연결하는 우회 방법이 언급되었다.

How to Apply

오픈소스 프로젝트를 운영 중이라면 프로젝트 루트에 AGENTS.md를 추가하고, 빌드 커맨드·테스트 실행법·코드 스타일 규칙·PR 컨벤션을 적어두면 외부 기여자가 AI 에이전트로 작업할 때 품질이 올라간다.
여러 에이전트(Claude Code + Cursor 등)를 동시에 쓰는 경우, AGENTS.md를 마스터로 작성한 뒤 ln -s AGENTS.md CLAUDE.md, ln -s AGENTS.md .cursorrules 식으로 심볼릭 링크를 걸면 중복 관리를 피할 수 있다. 또는 ruler 도구(https://github.com/intellectronica/ruler)로 자동 생성할 수 있다.
모노레포에서 패키지별로 빌드/테스트 방식이 다르면 각 패키지 디렉토리에 별도 AGENTS.md를 두어라. 에이전트가 해당 디렉토리에서 작업할 때 가장 가까운 파일을 읽으므로, 불필요한 컨텍스트 로딩을 줄일 수 있다.
AGENTS.md가 너무 커지면 .agents/ 폴더 구조로 전환을 고려하라. index.md에 전체 가이드를 두고, auth.md·testing.md·data_layer.md 등으로 분리하면 토큰 효율과 유지보수성이 모두 좋아진다.

Code Example

snippet

# AGENTS.md 예시

## Setup commands
- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>`
- Fix any test or type errors until the whole suite is green
- Add or update tests for the code you change

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

# 심볼릭 링크로 여러 에이전트 지원
$ ln -s AGENTS.md CLAUDE.md
$ ln -s AGENTS.md .cursorrules

Terminology

AGENTS.mdAI 코딩 에이전트가 프로젝트를 이해하도록 돕는 마크다운 가이드 파일. 사람용 README.md의 AI 버전이라고 보면 된다.

ASTAbstract Syntax Tree. 코드를 트리 구조로 파싱한 것으로, 변수·함수·클래스 간의 관계를 구조적으로 탐색할 때 쓴다.

RAGRetrieval-Augmented Generation. LLM이 답변할 때 외부 문서를 검색해서 참고하는 방식. 코드베이스 검색에도 적용할 수 있다.

모노레포여러 프로젝트/패키지를 하나의 Git 저장소에서 관리하는 방식. 구글, 메타 등 대형 회사에서 많이 사용한다.

심볼릭 링크실제 파일을 가리키는 바로가기 파일. ln -s 원본 링크명으로 만들면 하나의 파일을 여러 이름으로 참조할 수 있다.

AGENTS.md – AI 코딩 에이전트를 위한 오픈 포맷 가이드 파일