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

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

# 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

Related Resources

• https://agents.md/
• https://github.com/anthropics/claude-code/blob/main/CLAUDE.md
• https://agent-rules.org/
• https://github.com/intellectronica/ruler
• https://github.com/sutt/agro