AGENTS.md

AGENTS.md는 AI 코딩 에이전트에게 프로젝트의 맥락과 작업 방식을 전달하기 위한 개방형 마크다운 포맷으로, 저장소 루트에 위치하는 “에이전트를 위한 README”라 할 수 있다. 별도의 JSON이나 YAML 스키마 없이 표준 마크다운 문법만으로 작성되며, 사람과 AI 에이전트가 동시에 읽을 수 있도록 설계되었다.
README.md가 사람 개발자를 위한 소개 문서라면, AGENTS.md는 빌드·테스트 명령, 코드 컨벤션, 보안 유의사항처럼 사람에게는 불필요하지만 에이전트 작업에는 필수적인 세부 맥락을 별도로 분리해 담는 역할을 한다. 현재는 Linux Foundation 산하 Agentic AI Foundation이 이 표준을 관리하고 있다.

주요 특징

표준 마크다운 기반: 특별한 스키마 없이 일반 마크다운 문법으로 작성되어 누구나 쉽게 만들고 수정할 수 있음.
저장소 루트 배치: 프로젝트 루트에 위치하며, 하위 디렉터리마다 별도 파일을 두어 서브프로젝트별 맞춤 지침을 제공할 수 있음.
폭넓은 도구 호환성: OpenAI Codex, Claude Code, GitHub Copilot, Cursor, Gemini CLI 등 30개 이상의 에이전트 도구가 이 포맷을 인식함.
가장 가까운 파일 우선 적용: 에이전트가 작업 중인 디렉터리 트리에서 가장 가까운 AGENTS.md를 자동으로 탐색해 참조함.
커뮤니티 주도 표준화: OpenAI, Google, Cursor, Factory 등 여러 AI 개발 도구 기업이 협력해 만든 개방형 표준임.

장점

일관된 에이전트 동작: 여러 AI 도구를 오가도 동일한 규칙과 맥락을 참조하므로 결과물의 일관성이 높아짐.
온보딩 시간 단축: 빌드·테스트·배포 절차를 명문화해 신규 기여자나 에이전트가 빠르게 프로젝트에 적응할 수 있음.
README와의 역할 분리: 사람을 위한 설명과 에이전트를 위한 세부 지침을 나눠 문서의 가독성을 유지함.
유지보수 효율성: 코드 컨벤션이나 보안 정책이 바뀌어도 한 파일만 갱신하면 모든 에이전트에 즉시 반영됨.
생태계 확장성: 표준화된 포맷 덕분에 새로운 AI 도구가 등장해도 별도 설정 없이 기존 지침을 그대로 활용 가능함.

주요 솔루션 및 사용 사례

주요 솔루션
- OpenAI Codex: AGENTS.md를 기본 컨텍스트 파일로 채택해 저장소 작업 지침을 읽어들임.
- GitHub Copilot Agent Mode: 저장소의 AGENTS.md를 참고해 이슈 처리와 PR 생성 작업을 수행함.
- Cursor: AGENTS.md 및 유사 규칙 파일을 인식해 코드베이스 맥락에 맞는 제안을 제공함.
- Google Jules: 백그라운드에서 작업하는 자율 에이전트로 AGENTS.md 지침을 반영함.
- Devin, Aider, Zed: 각 도구가 AGENTS.md 포맷을 지원해 프로젝트별 맞춤 작업을 수행함.
사용 사례
- 빌드·테스트 자동화 안내: 프로젝트별 빌드 명령과 테스트 실행 방법을 명시해 에이전트가 올바르게 검증하도록 함.
- 코드 스타일 가이드 전달: 팀의 코딩 컨벤션을 문서화해 에이전트가 생성하는 코드의 일관성을 유지함.
- 모노레포 서브프로젝트 관리: 각 하위 디렉터리에 맞춤 AGENTS.md를 배치해 프로젝트별 다른 지침을 적용함.
- 보안 및 컴플라이언스 안내: 민감한 파일 접근 제한이나 보안 검토 절차를 명시해 사고를 예방함.
- 기여 가이드라인 공유: 오픈소스 프로젝트에서 PR 작성 규칙과 리뷰 절차를 에이전트에게 안내함.

CNF Taxonomies

AGENTS.md

주요 특징

장점

관련 용어

주요 솔루션 및 사용 사례

AI 에이전트가 마크다운으로 문서 쓰는 이유 — 토큰 34% 절감 원리