AGENTS.md 완벽 가이드: AI 코딩 에이전트를 위한 새로운 표준 🤖

작성일자 글쓴이

🤖 AGENTS.md란? AI 코딩 에이전트를 위한 새로운 표준

개발자 여러분, 혹시 AI 코딩 어시스턴트를 사용하면서 “왜 내 프로젝트 컨벤션을 이해 못 하지?”라고 답답했던 적 있으신가요? 바로 이 문제를 해결하기 위해 등장한 것이 AGENTS.md입니다! 🎯

AGENTS.md는 AI 코딩 에이전트를 안내하기 위한 심플하고 오픈된 포맷입니다. README.md가 인간 개발자를 위한 문서라면, AGENTS.md는 AI 에이전트를 위한 문서입니다. 현재 6만 개 이상의 오픈소스 프로젝트에서 이미 사용되고 있으며, OpenAI Codex, GitHub Copilot, Cursor, Google Jules 등 주요 AI 코딩 도구들이 이 표준을 지원합니다.

📜 AGENTS.md가 필요한 이유

기존의 README.md 파일은 프로젝트 소개, 빠른 시작 가이드, 기여 가이드라인 등 인간 개발자를 위한 내용을 담고 있습니다. 하지만 AI 코딩 에이전트는 다른 종류의 정보가 필요합니다.

README.md vs AGENTS.md 비교

구분 README.md AGENTS.md
대상 인간 개발자 AI 에이전트
내용 프로젝트 소개, 설치 방법 빌드 명령어, 테스트 방법, 코딩 컨벤션
스타일 읽기 쉬운 설명 중심 실행 가능한 명령어 중심
목적 프로젝트 이해 돕기 자동화 작업 가이드

AGENTS.md를 별도로 분리한 이유는 명확합니다:

  • 🎯 AI 에이전트에게 명확하고 예측 가능한 위치 제공
  • 📝 README를 간결하게 유지
  • 🔧 기존 README나 문서를 보완하는 정확한 가이드 제공

🌐 지원하는 AI 코딩 도구들

AGENTS.md의 가장 큰 장점은 하나의 파일로 여러 AI 도구를 지원한다는 것입니다. 현재 다음과 같은 주요 도구들이 AGENTS.md를 인식합니다:

  • OpenAI Codex – OpenAI의 AI 코딩 에이전트
  • GitHub Copilot – 가장 널리 사용되는 AI 페어 프로그래머
  • Cursor – AI-first 코드 에디터
  • Google Jules – Google의 AI 코딩 어시스턴트
  • Factory – AI 기반 소프트웨어 개발 플랫폼
  • Amp – AI 코딩 에이전트
  • Aider – 터미널 기반 AI 페어 프로그래머
  • Gemini CLI – Google의 AI CLI 도구

이러한 도구들은 프로젝트에서 AGENTS.md 파일을 자동으로 감지하고, 그 안의 지침을 따라 작업합니다!

📝 AGENTS.md 작성 방법

AGENTS.md 작성은 매우 간단합니다. 일반 마크다운 파일이며, 필수 필드가 없습니다. 원하는 헤딩을 자유롭게 사용할 수 있죠!

Step 1: 파일 생성

저장소 루트에 AGENTS.md 파일을 생성합니다. 대부분의 AI 코딩 에이전트는 요청하면 직접 생성해주기도 합니다!

touch AGENTS.md

Step 2: 핵심 섹션 추가

GitHub 블로그에서 2,500개 이상의 저장소를 분석한 결과, 성공적인 AGENTS.md는 다음 6가지 핵심 영역을 다룹니다:

  1. 명령어 (Commands) – 빌드, 테스트, 린트 명령어
  2. 테스팅 (Testing) – 테스트 실행 방법과 규칙
  3. 프로젝트 구조 (Project Structure) – 디렉토리 레이아웃
  4. 코드 스타일 (Code Style) – 코딩 컨벤션
  5. Git 워크플로우 – 커밋, PR 규칙
  6. 경계선 (Boundaries) – 하면 안 되는 것들

Step 3: 실행 예시

다음은 TypeScript 프로젝트를 위한 AGENTS.md 예시입니다:

# 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 test` before committing
- Add tests for new features
- Fix any failing tests before PR

## Boundaries
- Never commit secrets or API keys
- Don't modify files in `vendor/` directory
- Ask before adding new dependencies

🎯 효과적인 AGENTS.md 작성 팁

GitHub 블로그의 분석 결과를 바탕으로, 효과적인 AGENTS.md 작성 팁을 정리했습니다:

1. 명령어를 먼저 배치하세요 ⌨️

실행 가능한 명령어를 파일 상단에 배치하세요. npm test, npm run build, pytest -v 등을 플래그와 옵션까지 포함해서 작성합니다.

2. 설명보다 코드 예시를! 💻

세 문단의 설명보다 하나의 실제 코드 스니펫이 더 효과적입니다. AI 에이전트에게 좋은 출력이 어떻게 생겼는지 보여주세요.

3. 명확한 경계선을 설정하세요 🚫

“절대 시크릿을 커밋하지 마세요”가 가장 흔하면서도 유용한 제약 조건입니다. vendor 디렉토리, 프로덕션 설정 등 건드리면 안 되는 것을 명시하세요.

4. 기술 스택을 구체적으로 📋

“React 프로젝트”가 아니라 “React 18 with TypeScript, Vite, and Tailwind CSS”라고 작성하세요. 버전과 주요 의존성을 포함합니다.

📂 모노레포에서의 AGENTS.md

대규모 모노레포를 운영한다면, 중첩된 AGENTS.md 파일을 활용할 수 있습니다!

각 패키지 디렉토리에 AGENTS.md를 배치하면, AI 에이전트는 가장 가까운 파일을 우선 참조합니다. 예를 들어, OpenAI 메인 저장소에는 무려 88개의 AGENTS.md 파일이 있습니다!

my-monorepo/
├── AGENTS.md                    # 전역 설정
├── packages/
│   ├── frontend/
│   │   └── AGENTS.md            # 프론트엔드 전용 설정
│   └── backend/
│       └── AGENTS.md            # 백엔드 전용 설정
└── services/
    └── payments/
        └── AGENTS.override.md   # 결제 서비스 오버라이드

🤖 GitHub Copilot에서 커스텀 에이전트 만들기

GitHub Copilot은 AGENTS.md를 활용해 전문화된 에이전트 페르소나를 만들 수 있습니다. 하나의 범용 어시스턴트 대신, 역할별 전문가를 구성하는 거죠!

추천 에이전트 6가지

  • @docs-agent – 코드를 읽고 문서를 생성하는 기술 문서 전문가
  • @test-agent – 유닛 테스트, 통합 테스트를 작성하는 QA 엔지니어
  • @lint-agent – 코드 스타일과 포맷팅만 수정하는 안전한 에이전트
  • @api-agent – REST 엔드포인트, GraphQL 리졸버를 만드는 API 전문가
  • @security-agent – 보안 취약점을 분석하는 보안 전문가
  • @deploy-agent – 빌드와 배포를 담당하는 DevOps 에이전트

각 에이전트는 .github/agents/ 디렉토리에 별도의 md 파일로 정의합니다!

⚙️ 다양한 도구에서 AGENTS.md 설정

Aider 설정

.aider.conf.yml 파일에 다음을 추가합니다:

read: AGENTS.md

Gemini CLI 설정

.gemini/settings.json 파일에 다음을 추가합니다:

{ "contextFileName": "AGENTS.md" }

OpenAI Codex 설정

Codex는 자동으로 AGENTS.md를 감지합니다. 전역 설정은 ~/.codex/AGENTS.md에 배치하세요.

🏛️ Agentic AI Foundation – 표준의 미래

AGENTS.md는 이제 Linux Foundation 산하의 Agentic AI Foundation이 관리합니다! OpenAI, Google, Cursor, Factory 등 주요 플레이어들이 협력하여 이 오픈 표준을 발전시키고 있습니다.

이는 AGENTS.md가 단순한 임시 솔루션이 아니라, AI 코딩 에이전트 생태계의 공식 표준으로 자리잡았음을 의미합니다. 특정 벤더에 종속되지 않는 오픈 포맷이라는 점이 가장 큰 강점이죠!

❓ 자주 묻는 질문 (FAQ)

Q: 필수 필드가 있나요?

A: 아니요! AGENTS.md는 표준 마크다운입니다. 원하는 헤딩을 자유롭게 사용하세요.

Q: 지침이 충돌하면 어떻게 되나요?

A: 편집 중인 파일과 가장 가까운 AGENTS.md가 우선합니다. 사용자의 채팅 프롬프트는 모든 것을 오버라이드합니다.

Q: 에이전트가 테스트 명령어를 자동 실행하나요?

A: 네, 목록에 있다면 실행합니다. 에이전트는 관련 검사를 실행하고 실패를 수정한 후 작업을 완료합니다.

Q: 나중에 수정할 수 있나요?

A: 물론입니다! AGENTS.md를 살아있는 문서로 취급하세요.

🎉 마무리: AI와 함께하는 개발의 새로운 패러다임

AGENTS.md는 AI 코딩 에이전트와 인간 개발자 사이의 커뮤니케이션 표준입니다. 6만 개 이상의 프로젝트가 이미 채택했고, 주요 AI 코딩 도구들이 지원하며, Linux Foundation이 관리하는 공식 표준으로 성장했습니다.

여러분의 프로젝트에도 AGENTS.md를 추가해보세요! AI 에이전트가 여러분의 코딩 컨벤션을 이해하고, 더 정확한 코드를 생성하게 될 것입니다. 시작은 간단합니다 – 저장소 루트에 AGENTS.md 파일을 만들고, 빌드 명령어와 코딩 스타일을 적어보세요! 🚀

궁금한 점이 있으시다면 댓글로 남겨주세요! 🐰