AGENTS.md: 모든 코딩 에이전트를 위한 단 하나의 컨텍스트 파일 (Codex, Gemini, Claude)

깔끔한 CLAUDE.md를 작성하느라 한나절을 보냈습니다. 그제서야 에이전트가 스택을 추측하는 일을 멈추고 올바른 테스트 명령을 실행하기 시작했죠. 그런데 동료가 같은 저장소를 Codex로 열고, 당신은 사이드 브랜치에서 Gemini CLI를 시험해 보는데, 그 어렵게 쌓은 컨텍스트가 전혀 따라오질 않습니다. 도구마다 자기만의 파일을, 자기만의 위치에 두길 원하니까요.

AGENTS.md는 바로 그 혼란에 대한 답입니다. 저장소 루트에 두는 단 하나의 일반 Markdown 파일로, 어떤 코딩 에이전트든 코드를 건드리기 전에 읽는 파일이죠.

AGENTS.md가 정확히 무엇인가

마법은 없습니다. AGENTS.md라는 이름의 Markdown 파일로, 보통 저장소 루트에 두며, 에이전트가 작업을 시작하기 전에 상시 지침으로 불러오는 파일입니다. 사람 동료가 아니라 AI 동료를 위해 쓰는 README라고 생각하면 됩니다. 이 프로젝트가 무엇인지, 어떻게 빌드하고 테스트하는지, 지켜야 할 컨벤션은 무엇인지, 피해야 할 함정은 무엇인지를 담죠.

이것은 이미 Codex를 비롯해 점점 늘어나는 에이전트 도구들이 읽고 있는 열린 컨벤션이며, 도구 사이에서 이식 가능하도록 만든다는 명확한 목표를 가지고 있습니다. 도구마다 맞춤 파일 하나가 아니라, 파일 하나에 여러 에이전트입니다.

AGENTS.md vs CLAUDE.md vs GEMINI.md

지금은 도구마다 지형이 갈라져 있습니다.

• CLAUDE.md는 Claude Code가 찾는 파일입니다.
• GEMINI.md는 Gemini CLI의 컨벤션입니다.
• AGENTS.md는 Codex를 비롯한 여러 도구가 읽는 도구 간 표준으로, 중립적인 파일이 되도록 설계됐습니다.

내용은 세 파일 모두 거의 같습니다. 프로젝트 컨텍스트, 명령, 컨벤션이죠. 진짜 차이는 각 도구가 기본으로 읽는 파일 이름뿐입니다. 그래서 같은 규칙을 손으로 세 파일에 복제하는 건 처음부터 이길 수 없는 싸움입니다(동기화를 유지하는 방법은 아래에서 다룹니다).

주로 Claude Code에서 작업한다면, CLAUDE.md 가이드가 Claude에 특화된 구조를 깊이 다룹니다. AGENTS.md는 그 파일의 프로바이더 중립적인 형제뻘이라고 보면 됩니다.

무엇을 담아야 하는가

짧고 신호가 강하게 유지하세요. 에이전트는 작업할 때마다 이 파일을 읽으므로, 모든 줄이 주의를 끌기 위해 경쟁합니다. 핵심은 다음과 같습니다.

• 스택은 한 호흡에. "Next.js 16, TypeScript, Prisma, MariaDB." 연혁도, 마케팅 문구도 필요 없습니다.
• 중요한 명령들. 어떻게 설치하고, 실행하고, 빌드하고, 테스트하고, 린트하는지. 정확한 명령으로: "테스트를 돌려라"가 아니라 npm test.
• 컨벤션. 네이밍, 파일 배치, 에러 처리, 그리고 리뷰에서 실제로 강제하는 패턴들.
• 디렉터리 지도. 무엇이 어디에 있는지 두 줄로 적어, 에이전트가 무작정 grep하는 걸 멈추게 합니다.
• 건드리기 전에 읽기 규칙. "billing/ 아래의 무언가를 수정하기 전에 docs/payments.md를 읽어라." 이 습관 하나가 많은 피해를 막아 줍니다.
• 확실한 금지 사항. "요청받지 않은 채로 브랜치를 만들지 마라." "커밋되는 파일에 머신 절대 경로를 두지 마라."

에이전트가 파일을 무시하게 만드는 실수들

컨텍스트 파일은 조용히 실패합니다. 에이전트가 에러를 던지는 게 아니라, 그냥 표류하죠. 흔한 원인은 다음과 같습니다.

1. 너무 길다. 600줄짜리 파일은 정작 중요한 다섯 가지 규칙을 묻어 버립니다. 에이전트가 코드 자체에서 유추할 수 있는 건 모두 쳐 내세요.
2. 모순. 한 섹션에서는 "항상 테스트를 작성하라", 다른 섹션에서는 "프로토타입은 테스트를 건너뛰어라". 에이전트는 그중 하나를 무작위로 고릅니다.
3. 머신에 묶인 경로. 커밋된 파일 속 /Users/you/project/...는 모든 동료에게, 그리고 다른 모든 머신의 모든 에이전트에게 깨집니다. 경로는 상대 경로로 유지하세요.
4. 낡은 명령. 테스트 명령은 여섯 달 전에 바뀌었는데 파일은 그대로입니다. 이제 에이전트는 완전한 확신을 가지고 엉뚱한 걸 실행합니다.
5. 우선순위가 없다. 모든 게 "중요"하면, 결국 아무것도 중요하지 않습니다. 양보할 수 없는 것을 맨 앞에 두고 라벨을 붙이세요.
6. 문서 쏟아붓기. 이건 지침이지 위키가 아닙니다. 문서로 링크를 걸되, 그 내용을 붙여넣지 마세요.

프로바이더 사이에서 하나의 컨텍스트 유지하기

대부분의 가이드가 건너뛰는 실전 부분이 여기입니다. 당신이나 팀이 둘 이상의 에이전트 CLI를 돌린다면, 같은 규칙의 세 가지 갈라지는 사본을 두고 싶지는 않을 겁니다.

깔끔한 두 가지 접근법이 있습니다.

• 하나의 정식 파일, 얇은 포인터. 모든 것을 AGENTS.md에 담고, CLAUDE.md와 GEMINI.md는 "AGENTS.md를 참조"라고 적은 한 줄짜리 파일로 만들거나, 심볼릭 링크로 연결하세요. 진실의 원천은 하나, 모든 도구는 공급받습니다.
• 하나의 파일, 컨벤션으로 공유. 도구들이 커스텀 경로를 가리킬 수 있다면, 전부 AGENTS.md를 향하게 하고 나머지는 삭제하세요.

어느 쪽이든 규칙은 같습니다. 컨텍스트는 한 번만 쓰되, 프로바이더마다 한 번씩 쓰지 마세요. 이것이 컨텍스트를 정확하게 유지하는 유일한 방법이기도 합니다. 사람들이 실제로 유지보수하는 파일은 단 하나뿐이니까요.

여러 에이전트를 동시에 돌릴 때

저장소 수준의 AGENTS.md는 "이 프로젝트가 무엇인가"에 답합니다. "이 에이전트가 누구인가"에는 답하지 않죠. 같은 코드 위에서 Backend 에이전트, Frontend 에이전트, QA 에이전트를 병렬로 돌릴 때, 각 에이전트는 공유 프로젝트 컨텍스트에 더해 자신만의 역할이 필요합니다.

바로 그 계층을 AgentsRoom이 당신의 AGENTS.md 위에 더해 줍니다. 각 에이전트는 자기만의 시스템 프롬프트를 가진 전용 역할(DevOps, Frontend, Security 등)을 부여받으므로, 공유 파일은 가볍게 유지되면서도 각 에이전트는 여전히 자기 일이 무엇인지 압니다. 설계부터 프로바이더에 구애받지 않으므로 같은 구성으로 Claude, Codex, Gemini를 나란히 돌릴 수 있고, 반복해서 쓰는 지침은 매 세션마다 다시 타이핑하는 대신 프롬프트 라이브러리에 살아 있습니다.

그 지점에 이르면, 흐름을 놓치지 않고 여러 에이전트를 병렬로 돌리는 방법이 자연스러운 다음 읽을거리입니다.

핵심 정리

AGENTS.md는 하나만 쓰세요. 짧게, 최신으로, 이식 가능하게 유지하세요. 에이전트마다 파일을 유지보수하는 대신, 모든 도구가 그 하나를 가리키게 하세요. 그러면 컨텍스트가 처음 시작한 CLI에 묶이는 일이 사라지고, 어떤 에이전트를 돌리든 모두 같은 출발점에서 시작합니다.

모든 에이전트를 한 화면에, 각자의 역할과 공유 컨텍스트와 함께 두고 싶으신가요? AgentsRoom 다운로드하고, 프로바이더를 연결한 뒤, 당신의 함대를 일하게 하세요.