AGENTS.md 완전 가이드: AI 코딩 도구 28개가 함께 읽는 단 하나의 파일

메타 설명: AGENTS.md 표준 가이드 — Cursor, GitHub Copilot, Claude Code 등 28개+ AI 도구가 공통으로 인식하는 설정 파일 작성법, 실제 사용 템플릿, 런타임 28% 단축 성능 수치, 안티패턴까지 한 번에 정리했습니다.

팀에 AI 코딩 도구가 두 개 이상 섞이면 진짜 문제가 생깁니다. Cursor 쓰는 개발자는 .cursorrules 관리하고, Claude Code 쓰는 개발자는 CLAUDE.md 업데이트하고, GitHub Copilot 쓰는 개발자는 또 copilot-instructions.md 따로 관리해요. 같은 프로젝트를 설명하는 파일이 세 개인 거죠. 어느 게 최신인지도 모르고.

AGENTS.md는 이 문제를 해결하기 위해 만들어진 표준 파일입니다. 지금 60,000개 이상의 오픈소스 프로젝트가 채택했고, 28개 이상의 AI 도구가 공식 지원합니다.

AGENTS.md가 뭔지 30초 요약

리포지토리 루트에 올려두는 마크다운 파일입니다. README.md가 사람 개발자에게 프로젝트를 설명하는 것처럼, AGENTS.md는 AI 에이전트에게 프로젝트 운영 방식을 설명합니다.

특별한 문법 없어요. 그냥 마크다운입니다. 필수 필드도 없고, 프레임워크나 라이브러리 설치도 필요 없습니다. 파일 하나 만들어서 리포에 올리면 끝이에요.

근데 이게 단순해 보이는데 실제 효과가 꽤 됩니다. arXiv에 올라온 연구(2601.20404)에서 10개 리포지토리, 124개 풀 리퀘스트를 분석했더니 AGENTS.md가 있는 프로젝트에서 에이전트 런타임이 28.64% 단축되고 출력 토큰 소비가 16.58% 절감됐어요. 에이전트가 프로젝트 구조 파악하는 데 헤매는 시간이 줄어들기 때문입니다.

AGENTS.md 도입 효과 수치 — 런타임 28.64% 단축, 토큰 16.58% 절감, 버그 35~55% 감소

탄생 배경: 왜 또 다른 파일 표준이 필요했나

2025년 8월, OpenAI와 Google, Cursor, Factory가 협력해서 AGENTS.md 오픈 표준을 공개했습니다. 그 전까지는 도구마다 파일 이름이 달랐어요.

도구	파일 이름
Cursor	`.cursorrules` / `.cursor/rules/*.mdc`
Claude Code	`CLAUDE.md`
GitHub Copilot	`.github/copilot-instructions.md`
Windsurf	`.windsurfrules`

팀에 여러 도구가 섞이면 지침이 분산되고, 업데이트하다 보면 파일마다 내용이 달라집니다. AGENTS.md는 이걸 하나로 통합하자는 취지입니다.

2025년 12월에는 Linux Foundation 산하 Agentic AI Foundation(AAIF)에 기증됐어요. OpenAI의 AGENTS.md, Anthropic의 MCP, Block의 Goose가 공동 창립 프로젝트로 들어갔습니다. AWS, Google, Microsoft, Anthropic, Cloudflare, Bloomberg 같은 회사들이 플래티넘 멤버로 참여 중이고요.

AGENTS.md 지원 도구 현황 (2026년 중반)

현재 28개 이상의 AI 코딩 도구가 AGENTS.md를 공식 지원합니다. 주요 도구만 추리면:

도구	개발사
OpenAI Codex CLI	OpenAI (표준 제안사)
GitHub Copilot	Microsoft/GitHub
Cursor	Cursor
Windsurf	Codeium
Aider	오픈소스
Gemini CLI	Google
Google Jules	Google
Devin	Cognition
VS Code	Microsoft
Cline	오픈소스
Zed	Zed Industries

솔직히 표준 제안사인 OpenAI Codex CLI가 지원이 가장 완전하고, 나머지 도구들은 기본 읽기는 되는데 고급 기능은 도구마다 차이가 있어요. 그래도 Cursor, GitHub Copilot, Windsurf 수준이면 실무에서 체감하기에 충분합니다.

AGENTS.md vs CLAUDE.md vs .cursorrules 뭘 써야 하나

이 세 가지를 직접 비교해볼게요.

항목	AGENTS.md	CLAUDE.md	.cursorrules
호환 도구	28개+	Claude Code 전용	Cursor 전용
표준 주체	Linux Foundation	Anthropic	Cursor
글로벌 설정	`~/.codex/AGENTS.md`	`~/.claude/CLAUDE.md`	불가
다단계 상속	지원	지원	`.cursor/rules/*.mdc`로 확장

멀티 도구 팀이라면 전략은 이렇게 잡는 게 좋습니다.

AGENTS.md — 모든 도구에 공통 적용되는 기본 지침 (빌드 명령, 프로젝트 구조, 코드 스타일)
CLAUDE.md — Claude Code 전용 심화 설정 (Hooks, Skills 같은 Claude 특화 기능)
간단하게 가고 싶다면 ln -s AGENTS.md CLAUDE.md 심볼릭 링크로 동기화

저는 현재 AGENTS.md에 프로젝트 공통 내용을 넣고, CLAUDE.md에 Claude 전용 설정을 추가하는 방식으로 쓰고 있어요. CLAUDE.md 상세 활용법은 CLAUDE.md 완벽 가이드에서, Claude Code의 고급 기능은 Claude Code Skills 가이드에서 별도로 다뤘습니다.

파일 위치와 우선순위 규칙

AGENTS.md는 여러 위치에 둘 수 있고, 에이전트가 읽는 순서가 있습니다. Codex 기준으로 탐색 우선순위는 이렇습니다.

~/.codex/AGENTS.override.md (전역 오버라이드)
~/.codex/AGENTS.md (전역 기본 설정)
Git 루트부터 현재 디렉터리까지 각 경로에서 AGENTS.override.md → AGENTS.md 순서로 탐색

파일들은 루트부터 순서대로 연결(concatenate)되고, 더 가까운 파일의 지침이 이전 지침을 덮어씁니다. 모노레포에서 패키지별로 다른 규칙이 필요할 때 활용할 수 있어요.

my-monorepo/
├── AGENTS.md              # 전체 프로젝트 공통 규칙
├── packages/
│   ├── api/
│   │   └── AGENTS.md      # API 서버 전용 추가 규칙
│   └── web/
│       └── AGENTS.md      # 프론트엔드 전용 추가 규칙

파일 크기는 기본 32KB 제한입니다. 근데 사실 그 전에 150줄 제한을 스스로 두는 게 낫습니다. 연구 결과에 따르면 150줄을 넘어도 성능 향상은 없고 추론 비용만 20~23% 증가했거든요.

효과적인 AGENTS.md 작성법

GitHub이 2,500개 이상의 공개 리포지토리를 분석해서 뽑아낸 권장 섹션입니다.

1. Commands — 가장 중요한 섹션

파일 최상단에 위치해야 합니다. AI 에이전트가 가장 먼저, 가장 자주 참조하는 정보예요.

# Commands
- 개발 서버: `npm run dev`
- 빌드: `npm run build`
- 테스트 전체: `npm test`
- 단일 파일 타입 체크: `npm run tsc --noEmit path/to/file.tsx`
- 단일 파일 린트: `npm run eslint --fix path/to/file.tsx`

단순히 npm test가 아니라 단일 파일 테스트 명령도 명시하세요. 에이전트가 전체 테스트 슈트를 돌리는 대신 수정한 파일만 체크하게 됩니다.

2. Project Structure — 추상이 아닌 실제 경로

# Project Structure
- `src/routes/` — 라우팅 설정
- `src/components/` — 재사용 가능한 UI 컴포넌트
- `src/hooks/` — 커스텀 React 훅
- `src/api/` — API 클라이언트

"MVC 패턴을 따른다" 같은 추상적 설명보다 실제 파일 경로가 훨씬 효과적입니다.

3. Code Style — 예제 코드로 보여주기

# Code Style
- 함수형 컴포넌트 + 훅 사용 (`src/components/Projects.tsx` 참고)
- 클래스형 컴포넌트 금지
- 상태 관리: Zustand (Redux 사용 금지)
- 비동기: async/await, Promise.then 금지

"클린 코드를 작성한다"는 에이전트에게 의미 없어요. 실제 예제 파일 경로를 참조하게 해주세요.

4. Boundaries — 명확한 경계 설정

# Boundaries
절대 금지:
- secrets, .env 파일 수정 또는 커밋
- node_modules/ 직접 수정
- 프로덕션 DB 설정 변경

먼저 확인:
- 새 npm 패키지 추가
- 기존 API 스펙 변경
- 데이터베이스 스키마 수정

에이전트가 "알아서" 잘 판단해줄 거라고 기대하면 안 됩니다. 경계를 명시적으로 그어줘야 해요.

실제 사용 템플릿

바로 복사해서 쓸 수 있는 최소 템플릿입니다.

# Project Overview
React 18 + TypeScript + Vite + Tailwind CSS 기반 SPA.
백엔드: Node.js/Express, PostgreSQL.

# Commands
- 개발 서버: `npm run dev`
- 빌드: `npm run build`
- 테스트 전체: `npm test`
- 단일 파일 타입 체크: `npm run tsc --noEmit path/to/file.tsx`
- 단일 파일 린트: `npm run eslint --fix path/to/file.tsx`

# Project Structure
- `src/routes/` — 라우팅 설정
- `src/components/` — 재사용 가능한 UI 컴포넌트
- `src/hooks/` — 커스텀 React 훅
- `src/api/` — API 클라이언트

# Code Style
- 함수형 컴포넌트 + 훅 사용 (`src/components/Projects.tsx` 참고)
- 클래스형 컴포넌트 금지
- 상태 관리: Zustand (Redux 사용 금지)

# Testing
- 단위 테스트: Vitest
- E2E: Playwright (`tests/` 디렉터리)
- 새 기능엔 반드시 테스트 추가

# Boundaries
절대 금지:
- secrets, .env 파일 수정 또는 커밋
- node_modules/ 직접 수정
- 프로덕션 DB 설정 변경

버전 명시는 중요합니다. "React 프로젝트"가 아니라 "React 18 + TypeScript + Vite + Tailwind CSS"처럼 구체적으로 써야 에이전트가 맞는 문법과 API를 사용해요.

AGENTS.md 작성 시 피해야 할 안티패턴

AI 생성 AGENTS.md는 역효과

흥미로운 연구 결과가 있어요. arXiv:2602.11988에 따르면 LLM으로 자동 생성한 AGENTS.md는 8가지 테스트 환경 중 5개에서 태스크 성공률이 오히려 낮아졌습니다. 자동 생성 시 태스크당 2.45~3.92단계가 추가로 소요됐고요.

AI가 만든 AGENTS.md가 왜 역효과냐면, 실제 프로젝트 맥락 없이 일반적인 지침만 생성되기 때문입니다. 에이전트가 읽어봤자 실제 도움이 안 되는 내용이 대부분이에요.

사람이 직접 작성한 구체적인 내용이 훨씬 효과적입니다.

모호한 페르소나 설명

"당신은 도움이 되는 코딩 어시스턴트입니다" — 이런 문장은 AI 에이전트에게 아무 의미 없습니다. 실행 가능한 명령어와 구체적인 경로로 채우세요.

비밀 정보 절대 금지

.env에 있는 API 키, DB 비밀번호 같은 정보를 AGENTS.md에 넣으면 안 됩니다. AGENTS.md는 git에 커밋되는 파일이에요.

커뮤니티 실사용 데이터

AGENTS.md를 도입한 프로젝트들의 보고된 수치들:

에이전트 생성 버그 35~55% 감소
새 AI 코딩 세션 설정 시간: 20~40분 → 2분 미만으로 단축
런타임 28.64% 단축, 출력 토큰 16.58% 절감 (arXiv 연구 기준)

새 세션마다 "이 프로젝트는 Next.js 14 씁니다, App Router 씁니다, 테스트는 Jest 씁니다..." 반복 설명하는 시간이 없어지는 게 체감상 가장 큰 차이입니다.

AGENTS.md와 MCP의 관계

AGENTS.md가 프로젝트 컨텍스트를 제공하는 정적 파일이라면, MCP(Model Context Protocol)는 AI 에이전트에게 동적 도구와 데이터 접근권을 주는 프로토콜입니다. 둘은 보완 관계예요.

AGENTS.md → "이 프로젝트에서 어떻게 일해야 하는지" 규칙 제공
MCP → "어떤 외부 도구와 데이터를 사용할 수 있는지" 도구 제공

둘 다 Agentic AI Foundation에 기증된 프로젝트라는 것도 흥미롭습니다. MCP 활용법이 궁금하다면 MCP Apps 완전 가이드를 참고하세요.

지금 당장 시작하는 법

리포지토리 루트에 AGENTS.md 파일 생성
위 템플릿을 복사해서 프로젝트에 맞게 수정
Commands 섹션부터 채우기 — 가장 중요하고 즉각적인 효과
에이전트가 실수할 때마다 규칙 추가 (최소로 시작, 반복 개선)

처음부터 완벽하게 만들려 하지 마세요. 5분 안에 Commands와 Project Structure만 채운 파일도 없는 것보다 훨씬 낫습니다. 에이전트 쓰다가 "아, 이게 빠졌구나" 싶을 때 한 줄씩 추가하면 됩니다.

'AI활용' 카테고리의 다른 글

Claude Code Task Budgets, 왜 안 될까 — API 비용 폭주 진짜로 막는 법 (2026) (0)	2026.07.05
Claude Code ultrareview 써보니, 아무 커밋에나 쓸 건 아니었다 (0)	2026.07.05
Claude Cowork 완벽 가이드, 파일 정리부터 보고서까지 맡기는 AI 동료 (0)	2026.07.04
RunCell로 주피터 노트북 자동화하기, 데이터 사이언티스트용 AI 에이전트 (0)	2026.07.03
Aider 완벽 가이드: 터미널에서 Git 커밋까지 자동으로 처리하는 AI 페어 프로그래머 (3)	2026.07.03

AGENTS.md가 뭔지 30초 요약

탄생 배경: 왜 또 다른 파일 표준이 필요했나

AGENTS.md 지원 도구 현황 (2026년 중반)

AGENTS.md vs CLAUDE.md vs .cursorrules 뭘 써야 하나

파일 위치와 우선순위 규칙

효과적인 AGENTS.md 작성법

1. Commands — 가장 중요한 섹션

2. Project Structure — 추상이 아닌 실제 경로

3. Code Style — 예제 코드로 보여주기

4. Boundaries — 명확한 경계 설정

실제 사용 템플릿

AGENTS.md 작성 시 피해야 할 안티패턴

AI 생성 AGENTS.md는 역효과

모호한 페르소나 설명

비밀 정보 절대 금지

커뮤니티 실사용 데이터

AGENTS.md와 MCP의 관계

지금 당장 시작하는 법

'AI활용' 카테고리의 다른 글

티스토리툴바