AGENTS.md: OpenAI가 제안하는 AI 코딩 에이전트를 위한 새로운 문서 표준

AI와 개발자의 협업 방식이 바뀌고 있다

AI 코딩 어시스턴트의 발전은 개발자의 일하는 방식을 빠르게 변화시키고 있다.
GitHub Copilot, Cursor, OpenAI Codex 등 다양한 AI 기반 도구가 코드 작성과 테스트, 문서화까지 지원하는 시대다. 하지만 여기에는 한 가지 큰 문제가 있다.

AI는 사람이 작성한 프로젝트 문서를 완벽히 이해하지 못한다는 점이다.
README.md는 사람에게는 친절하지만, AI에게는 모호하다. 빌드 명령어나 테스트 실행 절차, 코드 스타일 규칙처럼 사람은 암묵적으로 이해할 수 있는 정보들이 AI에게는 불분명하게 남는다.

이 문제를 해결하기 위해 OpenAI가 제안한 새로운 표준이 바로 AGENTS.md다.
이 문서는 AI가 프로젝트를 정확히 이해하고, 스스로 작업할 수 있도록 돕는 “에이전트 전용 README”라고 할 수 있다.

반응형

---

AGENTS.md란 무엇인가

AGENTS.md는 AI 코딩 에이전트를 위한 프로젝트 전용 설명서다.
기존의 README.md가 인간 개발자를 위한 문서라면, AGENTS.md는 AI가 프로젝트 구조를 이해하고 행동할 수 있도록 만드는 지침서다.

이 문서는 프로젝트 루트 디렉터리에 위치하며, AI 도구가 자동으로 탐색해 읽을 수 있도록 설계된다.
현재 OpenAI Codex, Cursor, Factory.ai 등 다양한 AI 기반 개발 환경에서 이 포맷을 인식한다.

OpenAI에 따르면 이미 20,000개 이상의 오픈소스 프로젝트가 AGENTS.md를 채택하고 있다.
특히 복잡한 모노레포(monorepo) 환경에서는 각 하위 디렉터리에 개별 AGENTS.md를 배치해, AI가 해당 영역에 맞는 지침을 자동으로 따를 수 있게 구성할 수 있다.

즉, AGENTS.md의 핵심 가치는 “사람과 에이전트를 위한 문서의 역할을 분리”하는 것에 있다.

---

README.md와의 차이점

AGENTS.md는 README.md를 대체하지 않는다.
두 문서는 서로 보완적인 역할을 한다.

구분	README.md	AGENTS.md
목적	사람에게 프로젝트 개요 제공	AI에게 실행 가능한 지침 제공
내용	설치 방법, 사용법, 기여 지침 등	빌드 명령어, 테스트 절차, 코드 규칙 등
작성 대상	인간 개발자	AI 코딩 에이전트
사용 위치	루트 디렉토리(기본 문서)	루트 및 서브 디렉토리(에이전트 지침서)

README.md는 사람이 프로젝트의 큰 그림을 이해하도록 돕는 요약서이고,
AGENTS.md는 AI가 실제로 코드를 실행하고 테스트하며 빌드할 수 있도록 하는 “작업 매뉴얼”이다.

이 구분은 단순한 형식 차이를 넘어, 앞으로의 개발 문서화 문화에 중요한 변화를 예고한다.
개발자와 AI가 같은 프로젝트를 다루더라도, 서로에게 필요한 정보는 다르기 때문이다.

---

AGENTS.md의 핵심 구성 요소

AGENTS.md는 일반적인 텍스트 설명서가 아니라, AI가 직접 실행할 수 있는 명령과 절차 중심의 문서다.
OpenAI가 제시한 기본 구조는 다음과 같다.

1. 개발 환경 설정 (Dev environment tips)

• pnpm dlx turbo run where <project_name> : 특정 패키지 위치 확인
• pnpm install --filter <project_name> : 개별 패키지 설치
• pnpm create vite@latest <project_name> -- --template react-ts : React + TypeScript 템플릿 생성

2. 테스트 실행 방법 (Testing instructions)

• .github/workflows 폴더에서 CI 계획 확인
• pnpm turbo run test --filter <project_name> : 테스트 실행
• pnpm vitest run -t "<test name>" : 특정 테스트 실행
• 코드 변경 시 반드시 pnpm lint 및 테스트 실행 후 병합

3. PR 규칙 (PR instructions)

• PR 제목 형식: [<project_name>] <Title>
• 머지 전 필수 검사: pnpm lint, pnpm test

이처럼 AGENTS.md에는 AI가 프로젝트 내에서 정확히 무엇을, 어떤 순서로 해야 하는지를 명시적으로 기록한다.
README에는 불필요하거나 장황한 정보일 수 있지만, AI에게는 필수적인 정보다.

---

AGENTS.md 작성 및 활용 방법

AGENTS.md는 Markdown 형식을 사용하므로, 개발자는 기존 README.md를 작성하는 방식 그대로 쉽게 작성할 수 있다.

작성 절차

1. 프로젝트 루트에 AGENTS.md 파일 생성
2. 빌드 및 테스트 명령어 명시
3. 코드 스타일, 보안 주의사항, PR 규칙 추가
4. 모노레포 환경에서는 각 하위 프로젝트에도 개별 AGENTS.md 작성

실제 예시

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm install` to install dependencies.
- Run `pnpm dev` to start development server.

## Testing instructions
- Execute `pnpm test` for all tests.
- Run `pnpm lint` before committing.

## PR instructions
- PR title format: [frontend] Add new component
- Ensure all tests pass before merge.

이 문서는 AI가 직접 읽고, 명령을 실행하며, 테스트를 수행하는 데 사용된다.
예를 들어, AI 코딩 에이전트는 pnpm test 명령을 인식해 실제 테스트를 실행하고, 실패 시 오류를 자동으로 수정하려 시도할 수 있다.

---

AGENTS.md의 가치와 기대 효과

AGENTS.md는 단순한 문서 형식의 추가가 아니다.
이는 AI와 사람 간의 협업을 공식화하는 새로운 개발 문화의 출발점이다.

1. AI 이해도 향상
   AI가 프로젝트 구조와 실행 규칙을 더 정확히 파악해, 잘못된 코드 제안이나 실행 오류를 줄인다.
2. 협업 효율성 강화
   여러 개발자와 AI가 동시에 작업하더라도 동일한 지침을 따를 수 있어, 코드 품질의 일관성이 높아진다.
3. 모노레포 최적화
   대규모 프로젝트에서 하위 모듈별로 지침을 나누어 관리할 수 있다.
4. 문서 관리의 단순화
   README는 사람 중심으로 간결하게 유지하고, AGENTS.md는 세부 절차 중심으로 구성함으로써 문서 역할이 명확히 분리된다.

---

OpenAI가 제안한 AGENTS.md는 단순히 문서를 추가하는 개념이 아니다.
AI가 프로젝트에 직접 기여할 수 있도록 설계된 새로운 표준 문서다.

이 문서를 통해 AI 코딩 에이전트는 프로젝트 구조, 테스트 절차, 코드 스타일을 명확히 이해하고 실행할 수 있다.
결국 AGENTS.md의 도입은 “AI와 사람이 함께 개발하는 환경”을 현실로 만드는 기반이 된다.

앞으로 더 많은 오픈소스와 기업 프로젝트가 AGENTS.md를 채택할 것으로 예상된다.
이 변화는 코드 그 자체보다, AI와 인간이 협력하는 방식의 진화를 상징한다.

https://agents.md/

AGENTS.md