AGENTS.md 소개
AGENTS.md는 OpenAI가 제안하는 새로운 문서 형식으로, AI 코딩 에이전트가 프로젝트를 이해하고 작업할 수 있도록 돕는 일종의 “에이전트 전용 README”입니다. 기존의 README.md 파일은 인간 개발자를 위한 프로젝트 개요, 설치 방법, 기여 지침 등을 담는 데 최적화되어 있습니다. 그러나 AI 에이전트가 프로젝트에 기여하기 위해 필요한 정보는 훨씬 더 구체적이고 절차 중심적일 때가 많습니다. 예를 들어, 빌드 명령어, 테스트 실행 절차, 코드 스타일 규칙 등은 사람이 직접 읽기에는 장황하거나 불필요할 수 있지만, 에이전트에게는 반드시 필요한 지침입니다.
이러한 필요를 충족하기 위해 AGENTS.md는 프로젝트 루트에 위치하여 AI 에이전트가 쉽게 접근할 수 있는 일관된 형식을 제공합니다. 현재 20,000개 이상의 오픈소스 프로젝트에서 이미 이 방식을 채택하고 있으며, OpenAI Codex, Cursor, Factory.ai 등 다양한 AI 기반 개발 도구와도 호환됩니다. 특히 모노레포(monorepo)와 같이 복잡한 프로젝트 구조를 가진 경우, 각 하위 프로젝트에 개별 AGENTS.md를 둘 수 있어 에이전트가 해당 영역에 최적화된 지침을 따를 수 있습니다.
즉, AGENTS.md의 가장 큰 가치는 “사람과 에이전트를 위한 문서의 역할 분리”에 있습니다. 인간은 README.md로 간결한 프로젝트 설명을 얻고, 에이전트는 AGENTS.md를 통해 세밀한 지침을 얻음으로써 양측 모두에게 최적화된 협업 환경을 구축할 수 있습니다.
README.md와 비교
README.md와 AGENTS.md는 서로를 대체하는 문서가 아니라 상호 보완적입니다. README.md는 인간 중심으로 작성되어야 하며, 설치 과정, 프로젝트 목적, 기여 방법 등을 주로 다룹니다. 반면, AGENTS.md는 에이전트 중심의 지침을 정리하여, 예를 들어 다음과 같은 내용들이 담길 수 있습니다:
- 빌드 및 테스트 명령어
- 코드 스타일 규칙
- CI/CD 실행 방법
- Pull Request 작성 규칙
- 보안 관련 주의사항
또한, 대규모 모노레포(monorepo) 환경에서는 각 서브 프로젝트마다 개별적인 AGENTS.md를 작성할 수 있어, 에이전트가 해당 디렉토리에서 가장 가까운 파일을 우선적으로 읽어 프로젝트 특화 지침을 적용하도록 할 수 있습니다. 이 방식은 에이전트가 다양한 하위 프로젝트를 다루는 상황에서 일관성과 효율성을 높여 줍니다.
정리하면, README.md는 프로젝트의 큰 그림을 제공하는 반면, AGENTS.md는 실행 가능한 절차와 규칙을 중심으로 합니다. 이러한 구분은 문서의 목적을 명확히 하여, 개발자와 AI 모두에게 더 나은 협업 경험을 제공합니다.
AGENTS.md의 주요 내용
작성 목적
AGENTS.md는 AI 코딩 에이전트가 프로젝트에 기여할 때 필요한 상세 지침을 제공하는 것을 목표로 합니다. 여기에는 빌드 및 테스트 명령어, 코드 스타일 규칙, 보안 주의사항, PR 작성 규칙 등이 포함될 수 있습니다. 이러한 정보를 별도의 파일에 분리함으로써, 인간 개발자가 보는 README는 간결하게 유지하면서도 AI 에이전트는 더 정확히 프로젝트를 이해할 수 있게 됩니다.
기본 예시
OpenAI의 agents.md 저장소에 제시된 최소 예시는 다음과 같습니다:
# Sample AGENTS.md file
## Dev environment tips
- `pnpm dlx turbo run where <project_name>`을 사용해 원하는 패키지로 빠르게 이동.
- `pnpm install --filter <project_name>`으로 특정 패키지를 워크스페이스에 추가해 Vite, ESLint, TypeScript에서 인식 가능.
- `pnpm create vite@latest <project_name> -- --template react-ts`로 React + TypeScript 패키지 생성.
- 각 패키지의 `package.json`의 name 필드를 확인.
## Testing instructions
- `.github/workflows` 폴더에서 CI 계획 확인.
- `pnpm turbo run test --filter <project_name>`으로 테스트 실행.
- 패키지 루트에서 `pnpm test` 실행.
- 특정 테스트 실행 시: `pnpm vitest run -t "<test name>"`.
- 모든 테스트가 통과해야 머지 가능.
- 파일 이동이나 import 변경 시 `pnpm lint --filter <project_name>` 실행.
- 코드 변경 시 반드시 테스트 추가/갱신.
## PR instructions
- PR 제목 형식: `[<project_name>] <Title>`
- 커밋 전 반드시 `pnpm lint` 및 `pnpm test` 실행.
이처럼 AGENTS.md는 단순한 설명이 아니라, AI 에이전트가 그대로 실행할 수 있는 행동 지침서 역할을 합니다.
사용 방법
- AGENTS.md 파일 생성: 프로젝트 루트에 작성합니다.
- 핵심 정보 추가: 빌드/테스트 절차, 코드 스타일, 보안 고려사항 등을 기재합니다.
- 추가 지침 포함: 커밋 메시지 규칙, 데이터셋 처리 방법, 배포 절차 등도 포함할 수 있습니다.
- 모노레포 지원: 하위 디렉토리에 개별 AGENTS.md를 작성하면, 에이전트는 가장 가까운 파일을 우선적으로 참조합니다.
FAQ 주요 정리
- 필수 항목은 없으며, Markdown 형식을 따릅니다.
- 충돌 시 가장 가까운 AGENTS.md 파일이 우선합니다.
- 테스트 명령어를 작성하면 에이전트가 실제로 실행하여 실패 시 수정까지 시도합니다.
- 문서는 “살아있는 문서(living document)”로 취급해 수시로 갱신할 수 있습니다.
- 기존 문서 마이그레이션은 간단히 mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md로 가능합니다.
AGENTS.md 웹사이트와 로컬 실행
AGENTS.md 프로젝트는 공식 웹사이트 agents.md에서도 설명과 예시를 제공합니다.
GitHub 저장소에는 Next.js 기반 웹사이트 코드가 포함되어 있으며, 다음과 같은 방식으로 로컬 실행이 가능합니다:
npm install
npm run dev
브라우저에서 http://localhost:3000 으로 접속하면 실행됩니다.
라이선스
AGENTS.md 프로젝트는 MIT License로 공개 및 배포되고 있습니다. 따라서 상업적 사용을 포함한 자유로운 활용이 가능합니다.
AGENTS.md 공식 홈페이지
AGENTS.md 프로젝트 GitHub 저장소
GitHub에서 AGENTS.md 문서 예제 찾아보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 