어떤 AI 코딩 에이전트든 프로젝트를 이해하게 만드는 AGENTS.md 파일 작성법

AI 코딩 에이전트가 엉뚱한 테스트 명령을 실행하거나, 프로젝트가 금지한 스타일로 코드를 포맷하거나, 이미 존재하는 헬퍼를 새로 만드는 모습을 본 적이 있다면, 그 해결책은 대개 더 똑똑한 모델이 아니라 맥락이다. AGENTS.md는 에이전트에게 그 맥락을 제공하는 표준적인 방법이며, 거의 모든 도구에서 작동한다.

AGENTS.md란 실제로 무엇인가

AGENTS.md는 "에이전트를 위한 README"다. 저장소 루트에 두어 AI 코딩 도구에게 프로젝트가 어떻게 돌아가는지 알려 주는 일반 Markdown 파일이다(agents.md). 새로운 설정 언어가 아니다 — 필수 항목도, 특별한 문법도 없다. 원하는 Markdown 제목을 자유롭게 쓰면 된다.

이 형식이 중요한 이유는 진정으로 도구를 넘나들기 때문이다. 2026년 중반 기준으로 OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie를 비롯한 수십 개의 도구가 이를 기본으로 읽어 들인다 — 28개 이상의 도구와 60,000개 이상의 오픈소스 저장소가 그렇다(agents.md; Codersera). 현재는 Anthropic의 Model Context Protocol과 함께 Linux Foundation의 Agentic AI Foundation이 관리하고 있다. Claude Code도 AGENTS.md를 읽지만, 더 풍부한 자체 형식은 여전히 CLAUDE.md다(DeployHQ).

파일 하나면, 대부분의 도구가 일관되게 동작한다.

채팅에서 같은 말을 반복하는 것보다 파일이 나은 이유

채팅 메시지에 지시 사항을 붙여 넣으면, 그것은 딱 그 대화 한 번만 유지된다. 다음 세션 — 또는 다음 동료, 아니면 밤새 여러분의 작업을 돌리는 클라우드 에이전트 — 는 처음부터 다시 시작한다. AGENTS.md는 매 실행이 시작될 때 자동으로 로드되므로, 여러분의 관례는 그것을 언급했는지 여부에 좌우되지 않고 기본적으로 강제된다. 바로 그것이 핵심이다. 프로젝트 지식을 머릿속과 일회성 채팅에서 꺼내, 도구가 매번 읽는 파일에 담아 두는 것이다.

무엇을 담아야 하는가

유능한 신규 동료가 첫날 필요로 할 것을 떠올려 보라 — 그게 바로 에이전트에게 필요한 것이다. 가장 유용한 섹션은 다음과 같다:

• 프로젝트 개요 — 이것이 무엇인지와 기술 스택을 한 단락으로.
• 설정 및 빌드 명령 — 설치, 실행, 빌드에 필요한 정확한 명령.
• 테스트 — 테스트를 실행하는 방법과, 변경이 완료되기 전에 테스트가 통과해야 한다는 규칙.
• 코드 스타일 — 포매터, 린터, 명명 규칙, 선호하거나 피해야 할 패턴.
• 커밋 및 PR 지침 — 메시지 형식, 브랜치 규칙, 건드리지 말아야 할 것.
• 함정 — 사람들이 걸려 넘어지는, 명백하지 않은 모든 것.

구체적으로 작성하라. "깔끔한 코드를 작성하라"는 에이전트에게 아무것도 말해 주지 않는다. "npm이 아니라 pnpm을 사용하라. 끝내기 전에 pnpm test를 실행하라. src/generated/의 파일은 절대 편집하지 말라"는 강제할 수 있다.

구체적인 예시

다음은 전형적인 웹 앱을 위한 간결한 AGENTS.md다:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

이것을 Claude Code, Cursor, Copilot에 건네주면 각 도구가 동일한 규칙을 그대로 받아들인다.

모노레포: 중첩된 파일을 사용하라

모노레포에서는 루트에 하나를 두는 것 외에도 각 패키지에 AGENTS.md를 둘 수 있다. 에이전트가 하위 디렉터리 안에서 작업할 때는 가장 가까운 파일이 우선한다(agents.md). 공유 관례는 루트에 두고 패키지별 명령은 중첩된 파일에 두면, packages/api/를 편집하는 에이전트가 해당 패키지의 빌드 및 테스트 명령을 자동으로 얻는다.

AGENTS.md vs CLAUDE.md vs Cursor 규칙

이미 CLAUDE.md나 .cursor/rules 같은 도구별 파일을 가지고 있을 수도 있다. 그것들을 버릴 필요는 없다. 실무에서 팀은 공유되는, 도구에 구애받지 않는 관례 — 모든 에이전트에게 필요한 내용 — 를 AGENTS.md에 두고, 더 풍부한 기능을 지원하는 도구를 위한 도구별 추가 사항은 그 도구의 자체 파일에 둔다(DeployHQ). 예를 들어 Claude Code는 둘 다 읽으며, CLAUDE.md를 더 표현력 있는 형식으로 삼는다. 흔한 패턴은 하나의 정본 AGENTS.md를 유지하고, 도구가 자체 파일을 필요로 하는 경우 그 파일이 AGENTS.md를 가리키도록 하여 단일한 진실의 출처를 두는 것이다. AGENTS.md로 시작하고, 도구만이 지원하는 기능이 필요할 때에만 도구별 파일로 손을 뻗어라.

짧고 구체적으로 유지하라

많다고 좋은 것이 아니다. 스타일 가이드 전체를 다시 옮겨 놓은 거대한 AGENTS.md는 모델의 주의를 두고 경쟁하며, 정작 중요한 규칙을 파묻어 버린다. 안내 없이는 에이전트가 틀리게 될 소수의 것들 — 명백하지 않은 명령, 건드리지 말아야 할 디렉터리, 여러분의 코드베이스가 선호하는 패턴 — 을 목표로 삼아라. 규칙이 이미 코드에서 명백하다면, 굳이 적어 둘 필요가 없을 것이다.

유용하게 유지하는 방법

AGENTS.md는 진실을 유지할 때에만 제 몫을 한다. 코드처럼 다루어라. 명령이나 관례가 바뀌면 같은 커밋에서 파일을 업데이트하라. 그리고 에이전트가 같은 실수를 두 번 저지르면, 채팅에서 고치는 데 그치지 말고 규칙을 적어 두어라. 그 습관 하나가 모든 실수를 영구적인 수정으로 바꾸며, AI 에이전트를 여러분의 프로젝트에서 믿을 만하게 만드는 데 가장 큰 지렛대가 되는 단 하나의 일이다.