AGENTS.md란? | GEO 용어집

AGENTS.md는 저장소나 웹사이트 루트에 두는 마크다운 파일로, AI 에이전트에게 해당 프로젝트의 빌드 방법, 테스트 명령, 코드 스타일, 작업 시 지켜야 할 규칙을 알려주는 사실상의 표준 지침 파일입니다. '에이전트를 위한 README'라고 불리며, OpenAI Codex를 비롯한 주요 코딩 에이전트들이 작업 시작 시 자동으로 읽어들입니다.

왜 중요한가

AI 코딩 에이전트는 강력하지만 프로젝트의 암묵지를 모릅니다. 어떤 명령으로 테스트를 돌리는지, 어떤 디렉터리를 건드리면 안 되는지를 프롬프트마다 다시 설명해야 했습니다. AGENTS.md는 이 맥락을 한 파일에 고정해 에이전트가 자동으로 참조하게 합니다. OpenAI Codex, Amp, Jules(Google), Cursor, Factory가 함께 설계했고 GitHub Copilot, Gemini CLI, Devin, Zed 등 20개 이상의 도구가 네이티브로 지원합니다. 2026년 기준 6만 개 이상의 오픈소스 프로젝트가 채택했으며, 2025년 12월에는 Anthropic의 MCP와 함께 Linux Foundation 산하 Agentic AI Foundation에 기증되어 중립 거버넌스로 관리되고 있습니다.

구조와 작성법

AGENTS.md는 필수 필드가 없는 순수 마크다운입니다. 정해진 스키마 대신 에이전트가 읽고 따를 수 있는 자연어 지침을 담습니다. 권장 구성은 다음과 같습니다.

프로젝트 개요: 무엇을 하는 코드베이스인지 한두 문단
빌드·테스트 명령: 의존성 설치, 개발 서버, 테스트 실행 명령
코드 스타일: 네이밍, 포매팅, 프레임워크 관례
보안·경계: 건드리면 안 되는 파일, 비밀값 취급 규칙
커밋·PR 규칙: 메시지 형식, 리뷰 절차

대규모 모노레포에서는 패키지별로 중첩된 AGENTS.md를 두며, 에이전트는 작업 위치에서 가장 가까운 파일을 우선 적용합니다.

llms.txt와의 차이

llms.txt가 'AI에게 어떤 콘텐츠가 있는지' 알려주는 안내 책자라면, AGENTS.md는 '여기서 어떻게 작업하는지' 알려주는 운영 매뉴얼입니다. 원래 코드 저장소에서 출발했지만, 최근에는 웹사이트 루트(/agents.md)에 두어 브라우징 에이전트에게 사이트 이용 방법을 안내하는 패턴도 등장했습니다. llms.txt·Schema.org 마크업과 함께 '에이전트 가독 신호(agent-readable signals)'라는 범주로 묶이며, AI 크롤링의 허용 여부를 다루는 robots.txt와 달리 '허용된 에이전트가 무엇을 어떻게 하면 되는지'를 다룹니다.

GEO 관점의 시사점

GEO의 무게중심이 'AI가 인용하는 콘텐츠'에서 'AI가 작업할 수 있는 사이트'로 확장되면서, 에이전트에게 명시적 지침을 제공하는 파일들이 새로운 최적화 레이어가 되고 있습니다. 개발 도구나 API 문서를 운영하는 팀이라면 AGENTS.md로 에이전트의 시행착오를 줄여줄수록 자사 제품이 에이전트 워크플로에 채택될 가능성이 높아집니다. 다만 AGENTS.md는 지침일 뿐 강제력이 없으므로, 콘텐츠 자체의 구조화 품질이 여전히 기본기입니다.

Sources:

inblog에서 활용하기

inblog로 제품 블로그나 문서 콘텐츠를 운영한다면 신호의 역할 분담을 기억하세요. llms.txt류 파일이 콘텐츠 안내를 맡고 AGENTS.md가 작업 지침을 맡는 동안, 블로그 본문은 에이전트가 인용·요약하기 좋은 구조를 갖추는 것이 기본입니다. inblog의 깨끗한 마크업과 명확한 소제목 구조는 이런 에이전트 가독 신호들과 결합될 때 효과가 커집니다.