AGENTS.md: AI 시대의 프로젝트 문서화 혁신

들어가며

AI와 함께 코딩하는 시대가 본격적으로 도래했습니다. GitHub Copilot, Cursor, Claude Code 등 다양한 AI 코딩 어시스턴트들이 개발자의 일상에 깊숙이 자리 잡으면서, 우리는 “바이브 코딩(Vibe Coding)”이라는 새로운 개발 패러다임을 경험하고 있습니다. 하지만 AI 에이전트가 우리의 프로젝트를 제대로 이해하고 효과적으로 기여하려면 무엇이 필요할까요?

바로 이 지점에서 AGENTS.md가 등장합니다. OpenAI, Google, Factory.ai, Cursor 등이 협력하여 만든 이 새로운 문서 형식은 AI 코딩 에이전트를 위한 “README”로, 현재 6만 개 이상의 오픈소스 프로젝트에서 이미 채택되고 있습니다.

<출처: agents.md>

AGENTS.md란 무엇인가?

핵심 개념

AGENTS.md는 프로젝트 루트에 위치하는 마크다운 파일로, AI 코딩 에이전트가 프로젝트를 이해하고 작업하는 데 필요한 맥락과 지침을 제공합니다. 간단히 말해, “에이전트를 위한 README“입니다.

# 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

README.md와의 차이점

많은 분들이 “그냥 README.md에 다 쓰면 되지 않나?”라고 생각하실 수 있습니다. 하지만 두 문서는 명확히 다른 목적을 가지고 있습니다.

README.md (인간을 위한 문서)

프로젝트 개요와 목적
빠른 시작 가이드
기여 방법과 라이선스 정보
마케팅과 홍보 요소

AGENTS.md (AI 에이전트를 위한 문서)

빌드 및 테스트 명령어
코드 스타일과 컨벤션
CI/CD 구성 상세
보안 고려사항
프로젝트 특화 규칙

이러한 분리는 README를 간결하게 유지하면서도, AI 에이전트에게는 필요한 세부 지침을 제공할 수 있게 해줍니다.

왜 AGENTS.md가 필요한가?

1. 명확하고 예측 가능한 위치

AI 에이전트들은 프로젝트를 이해하기 위해 다양한 문서를 읽어야 합니다. CONTRIBUTING.md, docs/, wiki 등 여러 곳에 흩어진 정보를 찾기보다는, 표준화된 하나의 위치에서 필요한 모든 지침을 얻을 수 있다면 훨씬 효율적입니다.

2. 컨텍스트 윈도우 최적화

LLM의 컨텍스트 윈도우는 제한적입니다. README.md는 종종 마케팅 요소나 장황한 설명이 포함되어 있어 전체를 컨텍스트에 넣기 부담스럽습니다. 반면 AGENTS.md는 에이전트에게 꼭 필요한 핵심 명령과 규칙만 간결하게 담아, 토큰을 효율적으로 사용할 수 있습니다.

3. 다양한 도구와의 호환성

AGENTS.md의 가장 큰 장점 중 하나는 단일 파일로 다양한 AI 코딩 도구와 호환된다는 점입니다.

지원하는 주요 도구들:

OpenAI Codex
Google Jules
Cursor
Windsurf (Codeium)
GitHub Copilot Coding Agent
VS Code
Devin (Cognition)
Factory.ai
Aider
Goose
RooCode
그 외 20개 이상의 도구

AGENTS.md 작성 가이드

기본 구조

AGENTS.md는 자유로운 마크다운 형식이므로 필수 필드는 없습니다. 하지만 일반적으로 다음과 같은 섹션들이 포함됩니다.

# AGENTS.md

## Project Overview
간단한 프로젝트 설명과 아키텍처 개요

## Development Environment
- Node.js 20.x 이상 필요
- pnpm 사용 (npm install -g pnpm)
- 환경 변수 .env.example 참고

## Build Commands
- Development: `pnpm dev`
- Production build: `pnpm build`
- Type check: `pnpm type-check`

## Testing
- Unit tests: `pnpm test`
- E2E tests: `pnpm test:e2e`
- Coverage: `pnpm test:coverage`
- 모든 PR은 테스트 통과 필수

## Code Style
- ESLint와 Prettier 설정 준수
- TypeScript strict mode 사용
- 함수형 프로그래밍 패턴 선호
- 파일명: kebab-case
- 컴포넌트명: PascalCase

## Commit & PR Guidelines
- Conventional Commits 사용
- PR 제목: `[scope] description`
- 커밋 전 `pnpm lint` 실행 필수

## Security Considerations
- API 키는 절대 하드코딩 금지
- 민감한 데이터는 환경 변수 사용
- 외부 입력은 항상 검증

실전 예시: Apache Airflow

Apache Airflow는 4,000명이 넘는 기여자를 가진 대규모 프로젝트로, AGENTS.md를 효과적으로 활용하고 있습니다.

# Apache Airflow AGENTS.md

## Development Setup
- Python 3.8+ required
- Use Breeze development environment
- `breeze shell` to enter dev environment

## Running Tests
- Unit tests: `pytest tests/`
- Integration tests: `pytest tests/integration/`
- Static checks: `breeze static-check-all-files`

## Code Guidelines
- Follow PEP 8 style guide
- Add type hints for all functions
- Write comprehensive docstrings
- Add tests for all new features

## Pull Request Process
- Run `breeze static-check-all-files` before commit
- Add entry to CHANGELOG.md
- Link related issue in PR description

모노레포에서의 활용

대규모 모노레포에서는 각 서브 프로젝트마다 개별 AGENTS.md를 배치할 수 있습니다. AI 에이전트는 현재 작업 중인 디렉토리에서 가장 가까운 AGENTS.md를 우선적으로 참조합니다.

my-monorepo/
├── AGENTS.md           # 전체 프로젝트 공통 규칙
├── packages/
│   ├── frontend/
│   │   └── AGENTS.md   # 프론트엔드 특화 지침
│   ├── backend/
│   │   └── AGENTS.md   # 백엔드 특화 지침
│   └── shared/
│       └── AGENTS.md   # 공유 라이브러리 지침

예를 들어, OpenAI의 메인 저장소는 무려 88개의 AGENTS.md 파일을 가지고 있습니다.

실무에서의 활용 팁

1. 점진적으로 작성하기

처음부터 완벽한 AGENTS.md를 만들려 하지 마세요. 프로젝트를 진행하면서 AI 에이전트가 자주 실수하거나 헷갈리는 부분을 발견할 때마다 문서를 보강하는 것이 효과적입니다.

2. 실행 가능한 명령어 중심으로

설명보다는 실제로 실행할 수 있는 명령어를 명시하세요. AI 에이전트는 AGENTS.md에 나열된 테스트 명령어를 실제로 실행하고, 실패 시 자동으로 수정을 시도합니다.

3. 팀 규칙도 포함하기

코드 리뷰 기준, 네이밍 컨벤션, 커밋 메시지 규칙 등 팀의 암묵적 규칙을 명시적으로 작성해두면, 신규 팀원뿐만 아니라 AI 에이전트도 팀의 문화를 따를 수 있습니다.

4. 살아있는 문서로 관리하기

AGENTS.md는 한 번 작성하고 끝나는 문서가 아닙니다. 프로젝트가 진화하면서 빌드 프로세스나 테스트 방식이 바뀔 수 있으므로, 주기적으로 업데이트하세요.

도구별 설정 방법

Aider

.aider.conf.yml 파일에 다음과 같이 설정:

read: AGENTS.md

Gemini CLI

.gemini/settings.json에 설정:

{
  "contextFileName": "AGENTS.md"
}

기존 문서 마이그레이션

이미 AGENT.md나 다른 이름의 에이전트 문서를 사용하고 있다면, 심볼릭 링크를 활용해 호환성을 유지할 수 있습니다.

mv AGENT.md AGENTS.md
ln -s AGENTS.md AGENT.md

긍정적 평가

문서화 문화 개선: “인간들이 서서히 프로젝트 문서를 제대로 작성하도록 유도당하고 있는 느낌”이라는 의견처럼, AGENTS.md는 결과적으로 전체 프로젝트 문서화 품질을 향상시키는 효과가 있습니다.

실용적 가치: AI 에이전트가 실제로 이 문서를 읽고 따르면서, 개발자는 반복적인 지시를 줄일 수 있습니다. “한 번 써두면 1000개의 에이전트가 읽을 테니 작성할 맛이 난다”는 반응도 있습니다.

비판적 시각

README와의 중복 우려: 일부 개발자들은 “잘 작성된 README.md 하나면 충분하지 않나?”라는 의문을 제기합니다. 실제로 두 문서 사이에 중복되는 내용이 발생할 수 있습니다.

표준화 부족: Anthropic의 Claude는 아직 AGENTS.md를 공식 지원하지 않고, 일부 도구들은 자체 형식(CLAUDE.md, .cursorrules 등)을 사용합니다. 완전한 표준화까지는 시간이 더 필요할 것으로 보입니다.

계층적 구조의 필요성: 복잡한 프로젝트에서는 단일 마크다운 파일보다 .agents/ 디렉토리 내에 주제별로 분리된 여러 파일(auth.md, performance.md 등)이 더 효과적일 수 있다는 의견도 있습니다.

거버넌스와 미래

2025년 1월, AGENTS.md는 Linux Foundation 산하의 Agentic AI Foundation으로 관리 주체가 이관되었습니다. 이는 특정 기업의 독점적 표준이 아닌, 진정한 오픈 표준으로 발전하겠다는 의지를 보여줍니다.

현재 AGENTS.md는 다음과 같은 방향으로 진화하고 있습니다:

더 많은 도구 지원: 주요 AI 코딩 도구들이 속속 AGENTS.md를 지원하고 있습니다.
베스트 프랙티스 공유: 대규모 오픈소스 프로젝트들의 AGENTS.md 예시가 계속 축적되고 있습니다.
자동화 도구: AGENTS.md를 자동 생성하거나 검증하는 도구들이 등장하고 있습니다.

마치며

AGENTS.md는 단순히 새로운 파일 하나를 추가하는 것 이상의 의미를 가집니다. 이는 AI와 협업하는 시대에 맞춰 프로젝트 문서화 방식을 재고하는 기회입니다.

시작은 간단합니다:

프로젝트 루트에 AGENTS.md 파일을 생성하세요.
가장 자주 사용하는 빌드와 테스트 명령어를 적으세요.
AI 에이전트와 작업하면서 필요한 지침을 점진적으로 추가하세요.

AI 코딩 에이전트는 이미 우리 가까이에 자리잡고 있습니다. 이제 그들이 우리의 프로젝트를 더 잘 이해하고, 더 효과적으로 기여할 수 있도록 도와줄 차례입니다. AGENTS.md로 시작해보세요.

참고 자료:

게시됨

2025년 12월 31일

카테고리

작성자

choonzang

태그:

agents.md, agents.md 예시, agents.md 작성가이드, ai agent를 위한 문서, 에이전트 README