소프트웨어 개발 환경에서 사람이 읽는 안내 문서로 README.md가 쓰이듯, AI 코딩 에이전트를 위한 전용 지침 문서 표준으로 AGENTS.md가 주목받고 있다. 코드베이스에 직접 드러나지 않는 프로젝트 맥락과 빌드 규칙을 에이전트에 전달함으로써 작업 정확도를 대폭 높인다. 클로드 코드를 비롯한 주요 AI 코딩 어시스턴트 생태계가 이 표준을 연이어 채택하며 개발 생태계의 새로운 관례로 자리 잡는 모습이다.
AI 에이전트를 위한 새로운 표준, AGENTS.md
AGENTS.md는 AI 코딩 에이전트가 프로젝트를 이해하도록 돕는 저장소 수준의 개방형 표준 파일 형식이다. 사람이 읽기 위해 작성하는 README.md와 달리, AGENTS.md는 LLM 기반 코딩 어시스턴트가 작업을 수행할 때 필요한 지침을 전달하는 전용 안내서 역할을 수행한다. 코드 자체만으로는 파악하기 어려운 프로젝트의 배경 맥락과 규칙을 예측 가능한 위치에서 정형화된 방식으로 전달한다.
이 파일은 OpenAI Codex, Claude Code, Cursor, Windsurf, GitHub Copilot 등 다양한 AI 에이전트가 공통으로 참조할 수 있도록 만들어졌다. 현재 리눅스 재단 산하 Agentic AI Foundation에서 체계적으로 관리하고 있으며, 이미 6만 개 이상의 오픈소스 프로젝트에서 이 개방형 형식을 도입하여 활용하고 있다. 30개 이상의 AI 에이전트 도구가 이를 직접 인식할 수 있어 에이전트 간 맥락 공유의 핵심 축이 되었다.
어떤 내용을 담고 어떻게 구성하는가
AGENTS.md는 저장소 최상위 루트에 위치하는 순수 마크다운(Plain Markdown) 파일이다. 문법적으로 강제되는 필수 필드가 없기 때문에 프로젝트의 성격과 규모에 맞춰 구성 요소를 자유롭게 선택하여 작성할 수 있다는 장점이 있다.
대부분의 저장소에서는 프로젝트 개요와 함께 빌드 및 테스트 실행 명령을 가장 우선적으로 배치한다. 여기에 코드 스타일 가이드라인, 보안 고려 사항, 테스트 실행 지침, 그리고 커밋 및 PR 작성 규칙 등을 권장 섹션으로 함께 작성한다. 이러한 명시적 안내는 에이전트가 코드를 수정하거나 새로운 기능을 추가할 때 발생할 수 있는 오작동을 줄이고 작업의 정확도를 높인다.
클로드 코드(Claude Code)의 공식 지원
앤트로픽의 AI 코딩 도구인 클로드 코드는 2026년 9월 18일 배포된 버전 2.1.277부터 AGENTS.md를 기본적으로 지원하기 시작했다. 이를 통해 개발자는 단일한 표준 지침 파일만으로 클로드 코드를 포함한 다양한 에이전트를 동시 제어할 수 있게 되었다.
클로드 코드는 기본적으로 폴백(Fallback) 방식을 적용하여 해당 파일을 읽어 들인다. 작업 디렉터리나 상위 디렉터리에 클로드 전용 지침 파일인 CLAUDE.md가 존재하지 않는 경우에만 AGENTS.md를 찾아 적용하는 구조다. 만약 디렉터리 체인 내에 CLAUDE.md가 존재한다면 AGENTS.md는 무시되고 전용 설정 파일이 우선권을 갖는다.
모드(Mods) 시스템과 두 파일의 동시 활용
클로드 코드에서 지원하는 AGENTS.md 기능은 AI 모델 자체가 아닌 코딩 하네스 레이어에 연결되는 내부 모드(Mod) 플러그인 형태로 구현되었다. 하네스는 맥락을 조립하고 도구를 호출하는 소프트웨어 계층이며, 현재 해당 플러그인 시스템은 초기 액세스 단계로 운영되고 있다.
개발자는 기본 폴백 동작에 얽매이지 않고 설정 변경을 통해 두 지침 파일을 함께 활용할 수 있다. /config 메뉴의 'Project instructions' 설정 항목을 조정하면 AGENTS.md와 CLAUDE.md를 동시에 로드하도록 지정 가능하다. 이를 통해 전체 에이전트가 공유하는 범용 표준 규칙 위에 클로드 코드 전용 맞춤형 지침을 레이어 방식으로 중첩하여 유연하게 구성할 수 있다.
참고
댓글 0개
아직 댓글이 없습니다. 첫 댓글을 남겨보세요.