AGENTS.md

AGENTS.md는 코딩 AI 에이전트에게 프로젝트의 규칙과 빌드 방법, 주의사항을 알려주는 표준 파일입니다. 흔히 "에이전트용 README"라고 부릅니다. 코드 저장소의 최상위 폴더에 마크다운 파일 하나를 두면, AI가 코드를 짜기 전에 이 파일을 먼저 읽고 "이 프로젝트는 테스트를 어떻게 돌리고, 어떤 코딩 규칙을 따르고, 무엇을 건드리면 안 되는지"를 파악합니다. OpenAI를 비롯한 여러 도구 제작사가 함께 만들어 2025년 8월 공개했고, 지금은 Linux Foundation(리눅스 재단) 산하 Agentic AI Foundation이 관리합니다.

AGENTS.md가 필요한 이유는 AI에게 매번 같은 설명을 반복하지 않기 위해서입니다. 사람 개발자라면 README와 위키, 동료의 말로 프로젝트 맥락을 익히지만, AI 에이전트는 채팅창에 그때그때 알려주지 않으면 모릅니다. 빌드 명령어, 폴더 구조, 금지 사항을 파일 하나에 적어두면 에이전트가 알아서 참고합니다. 예를 들어 "테스트는 npm test로 돌리고, 모든 파일은 150줄 이하로 유지하고, config 폴더는 손대지 마"라고 적어두면, 에이전트가 새 코드를 짤 때 이 규칙을 따릅니다. 공개 당시 2만 8천여 개 저장소에 있던 이 파일은 2026년 들어 6만 개 이상의 오픈소스 프로젝트로 퍼졌습니다.

쉽게 비유하면 AGENTS.md는 새 직원에게 건네는 업무 인수인계서입니다. 출근 첫날 "프린터는 저쪽, 점심은 12시, 이 서류는 절대 만지지 마세요"를 종이 한 장에 정리해 주듯이, AI 에이전트에게 "이 명령어로 테스트하고, 이 스타일로 코드를 쓰고, 이 폴더는 손대지 마"를 정리해 건네는 문서입니다. 직원이 바뀌어도 인수인계서는 그대로 쓰듯이, 쓰는 AI 도구가 바뀌어도 같은 파일을 다시 쓸 수 있습니다.

여기에 적으면 효과가 큰 내용은 따로 있습니다. 설치와 실행 명령어, 코드 스타일 규칙, 자주 쓰는 폴더의 역할, 그리고 건드리면 안 되는 부분이 대표적입니다. 반대로 비밀번호나 토큰 같은 민감한 정보는 절대 적지 않습니다. 이 파일은 사람도 읽을 수 있게 저장소에 그대로 들어가기 때문에, 공개돼도 괜찮은 내용만 담는 게 원칙입니다.

내용 구성은 자유롭지만 보통 이런 항목이 들어갑니다.

가장 헷갈리는 건 사람용 README와의 차이입니다. README는 사람이 읽고 프로젝트를 이해하는 소개문이라 마케팅 설명이나 스크린샷이 들어가지만, AGENTS.md는 AI가 실행할 수 있게 명령어와 규칙 위주로 적습니다. 그래서 둘을 같이 두는 경우가 많습니다. 또 회사마다 비슷한 파일을 따로 만들던 시절이 있었는데, 클로드는 CLAUDE.md를 쓰는 식이었습니다. AGENTS.md는 이렇게 도구마다 흩어진 형식을 하나로 모으자는 시도입니다.

규모가 큰 프로젝트에서는 AGENTS.md를 한 개만 두지 않고 하위 폴더마다 따로 두기도 합니다. 예를 들어 저장소 맨 위에 전체 규칙을 적은 파일을 두고, 프론트엔드 폴더와 백엔드 폴더에 각각 그 영역에만 해당하는 파일을 더 두는 식입니다. 에이전트는 지금 작업 중인 위치에서 가장 가까운 파일을 우선 따릅니다. 덕분에 큰 프로젝트에서도 폴더마다 다른 규칙을 깔끔하게 전달할 수 있습니다. 이 방식은 사람이 직접 코드를 짜던 시절의 맥락 전달을, AI 에이전트가 읽기 좋은 형태로 옮긴 것에 가깝습니다.

이 표준이 빠르게 자리 잡은 건 지원하는 도구가 많기 때문입니다. 클로드 코드, OpenAI Codex, Cursor, 깃허브 코파일럿, 구글 Gemini CLI, Windsurf, Devin 등 주요 코딩 에이전트가 AGENTS.md를 읽습니다. 한 번 작성해 두면 도구를 바꿔도 같은 파일을 그대로 쓸 수 있어서, AI 에이전트를 본격적으로 활용하는 팀이라면 거의 기본 준비물로 챙기는 분위기입니다. 다만 파일을 너무 길고 모호하게 적으면 오히려 에이전트가 헷갈리므로, 핵심 규칙만 간결하게 적는 편이 좋습니다.