AGENTS.md - AI 코딩 에이전트를 위한 오픈 포맷

(agents.md)

28P by GN⁺ 4일전 | ★ favorite | 댓글 1개

AGENTS.md는 README의 보완 역할을 하며, AI 코딩 에이전트가 프로젝트에서 작업할 때 필요한 맥락과 지침을 담는 전용 파일
20,000개 이상의 오픈소스 프로젝트에서 사용 중으로, 빌드/테스트/코드 스타일 등 사람에게는 불필요하지만 에이전트에게 중요한 정보를 정리
명확하고 예측 가능한 위치에 에이전트 전용 지침을 제공해 README를 간결하게 유지하면서도 협업 효율성 강화
단일 AGENTS.md로 다양한 에이전트 및 툴과 호환되며, 대규모 모노레포에서는 하위 프로젝트별 개별 AGENTS.md 사용 가능
OpenAI Codex, Cursor, Google Jules 등 여러 생태계의 협업으로 만들어진 개방형 표준

Why AGENTS.md?

README.md는 사람을 위한 문서, 빠른 시작, 프로젝트 설명, 기여 가이드라인을 제공
AGENTS.md는 에이전트를 위한 보조 문서로, 빌드/테스트/코드 규칙 같은 세부 맥락을 담아 README를 복잡하게 만들지 않음
별도 파일로 둔 이유
- 에이전트가 참고할 예측 가능한 지침 위치 제공
- README는 인간 기여자 중심으로 간결하게 유지
- 기존 문서와 보완되는 정밀한 에이전트 전용 지침 제공
독점 포맷이 아닌 누구나 쓸 수 있는 오픈 표준 명칭을 채택
하나의 AGENTS.md로 여러 AI 코딩 에이전트 및 툴과 호환 가능

How to use AGENTS.md?

1. AGENTS.md 파일 생성
- 저장소 루트에 배치 (많은 에이전트가 자동 생성 지원)
2. 주요 항목 작성
- 프로젝트 개요
- 빌드 및 테스트 명령어
- 코드 스타일 가이드라인
- 테스트 방법
- 보안 고려사항
3. 추가 지침 포함
- 커밋/PR 규칙, 보안 주의사항, 대규모 데이터셋, 배포 단계 등 팀원에게 전할 내용
4. 모노레포 대응
- 각 패키지별 AGENTS.md 배치 가능
- 에이전트는 가장 가까운 파일을 읽어 해당 서브프로젝트에 맞는 지침을 따름
- 예시: OpenAI 저장소에는 88개의 AGENTS.md 존재

FAQ

필수 항목: 없음, 일반 마크다운 형식 자유 사용
충돌 발생 시: 가장 가까운 AGENTS.md가 우선, 사용자 명시 프롬프트가 최종 적용
자동 실행 여부: 파일에 명시된 테스트 명령어는 에이전트가 실행해 오류 수정 시도
업데이트 가능성: 언제든 변경 가능, 살아있는 문서로 관리
기존 문서 마이그레이션: 파일명 변경 후 심볼릭 링크로 호환 유지
- mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

▲

GN⁺ 4일전 [-]

Hacker News 의견

작은 프로젝트에는 하나의 .md 파일만으로도 충분하지만, 복잡한 프로젝트에는 계층적인 폴더 구조와 index.md가 훨씬 더 효과적임을 경험했음
index.md와 그 하위에 auth.md, performance.md 같은 파일들로 구성된 구조는 유지 관리도 쉽고, LLM이나 에이전트가 불필요한 토큰 소모 없이 관련 맥락만 추출할 수 있음
.docs 파일들이 인간과 LLM 모두에게 적합하게 되고, index.md에는 각 파일에 대한 간단한 안내와 조직 가이드도 포함 가능함
단, ".agents"라는 이름보다는 ".codebots" 또는 ".context" 등 더 직관적인 이름이 좋겠음
- 중요한 파일과 디렉토리는 굳이 숨길 필요가 없다고 생각함
  특히 문서는 숨겨두면 오히려 불투명해지는데, 전통 때문인지 모르겠지만 이런 방식은 좋은 패턴이 아님
  robot_docs 같은 이름은 어떨까 고민함
- 사실 이런 정보는 기여자들이 궁금해하는 내용과 겹치기 때문에, 원래 CONTRIBUTING.md에 들어가는 게 맞다고 생각함
- 이 구조는 인간과 로봇 모두를 위한 소프트웨어 설계/코딩 스타일 가이드 문서 느낌임
  나는 이런 .md 파일을 docs/ 폴더에 넣음, Claude Code가 직접 작성함
  AGENTS.md와 CLAUDE.md는 오직 로봇을 위한 용도여야 하고, 하나의 대형 파일에 h2 헤더로 구역을 나누든, 여러 파일로 분할하든 각각 장단점 있음
  Arc42처럼 둘 다 지원하는 아키텍처 문서 포맷도 있음
  대형 마크다운 내에서 특정 섹션을 참조하는 것보다, 별도 파일로 만들어서 @멘션하는 편이 쉽고 실수도 줄어듦
  특정 부분에 집중이 필요할 때는 작은 파일로 쪼개는 게 코드 에이전트에게도 더 좋음
  작은 파일들은 diff/PR 리뷰할 때도 더 편리함
- 코드베이스 안에 AGENTS.md 파일을 여러 개 둘 수도 있음
  툴링은 현재 디렉토리와 루트 디렉토리의 AGENTS.md를 모두 읽도록 하면, 정보가 코드 근처에 머무를 수 있어서 원하는 방식과 병행 가능함
- 나도 비슷한 구조를 쓰고 있는데, index.md에 각 파일별 간단 안내를 추가해 꽤 괜찮은 결과를 얻어왔음
  rules.md처럼 디렉토리별로 원하는 동작 규칙 파일을 넣는 방식도 실험 중임
  예를 들어 realtime-service.ts와 queue-service.ts처럼 다양한 서비스가 모인 디렉토리엔 그 옆에 rules.md를 두는 식임
  프롬프트에 이 규칙 파일을 지정해서 새로운 것들을 쉽게 만들어낼 수 있음, 이름은 고민이 더 필요함
현재는 에이전트가 코드베이스를 이해하도록, 인간이 필요로 하는 것 이상의 특별한 가이드를 추가로 작성해야 하는 과도기임
곧 있으면 이런 게 필요 없다고 생각함
우리의 프로젝트 문서가 본래부터 충분히 충실하게 작성되어 있다면 AGENTS.md에 있는 내용도 모두 포함될 수 있다고 봄
우리는 항상 인간을 대상으로 문서를 써야 하고, LLM의 장점은 인간이 쓴 글을 읽을 수 있다는 데 있음
이런 관점에서 설계를 하는 게 맞다고 생각함
- 단순히 코드베이스 이해 뿐 아니라, 특정 스타일(예: 어떤 assert 라이브러리로 테스트를 작성할 것, 코멘트 금지, 구조적 로깅 사용 등) 규정을 명시하는 용도로도 쓸모가 큼
  오히려 코드가 거의 없는 신규 프로젝트에 더 유용할 수 있음
- 기계가 읽을 수 있는 규칙이 사회 곳곳에 더 많이 도입될 거라 예상함
  예로 자율주행과 교통 법규가 있는데, 실제로 사람도 맥락을 파악하기 어려운 표지(예: "빨간불 우회전 금지, 학기일 7~9시")는 기계에게는 더 힘듦
  결국은 행정기관에서 맥락을 덜 요구하거나 기계 가독성(QR코드 등)이 있는 신호로 바꿔야 할 것임
  이런 변화가 없다면 기계들이 규칙을 어기는 일이 많아질 것임
- 비즈니스 로직 같은 영역에선 앞으로도 에이전트를 위한 특별한 안내가 꼭 필요하다고 생각함
  무엇을 만드는지, 의도가 무엇인지, 프로젝트 최종 목적 등은 사람이 구체적으로 알려주지 않는 이상 기계가 파악하지 못함
  아키텍처 같은 것 역시 사람마다 기준이 달라 머릿속에 구조가 잡혀 있어야 실제 변경 사항을 볼 때 이해에 도움이 됨, 결국 진짜 병목은 이 부분임
- 전반적으로는 동의하지만, 특정 정보(예: 매번 반드시 컨텍스트에 넣고 싶은 것)는 별도의 파일로 강제로 포함시키고 싶은 욕구가 생기기도 함
- 우리가 암묵적으로 생각하는 규칙, 전제를 문서화하지 않으면 LLM은 알 수 없음
  코드에서 일부 추론도 가능하겠지만 100%는 불가능하므로 명시적으로 요구사항을 작성해 두는 게 중요함
AGENTS.md라는 건 결국 README.md와 같은 역할을 하면서 하이프를 끌어, 실제로 사람들이 내용을 채우고 있다는 점이 신기함
사람들은 다른 사람을 위해 문서를 쓰는 건 귀찮아하는데, 로봇을 위해서라면 열심히 적고 있다니 흥미로움
이런 현상은 소수만을 위해 인체공학적 설계를 했는데 모두에게 더 잘 맞는 핸들 디자인 같은 것과 비슷함
- 오히려 반대로, 사람들이 문서를 읽지 않으니 아무도 쓸 동기가 생기지 않았던 것임
  에이전트를 위한 CLAUDE.md는 한 번 써두면 1000개의 에이전트에게 곧 읽힐 테니 작성할 맛이 남
- 어차피 README.md에다 최소한만 적으면 되는 거 아닌가 싶음
- 실제로는 에이전트들조차 이 문서를 안 읽거나, 몇 번 더 지시하면 전부 잊어버릴 상황임
- 지금 상황은 사람들이 인간 개발자(자신 포함)를 개발 과정에서 적극적으로 빼려고 노력하면서, 에이전트가 적절한 안내를 반드시 가져야만 하게 된 것임
  인간의 모든 소프트웨어 개발 관여를 없애고 싶은 욕구가 커졌기 때문임

build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. 이런 부분을 따로 빼자는 건 정말 세상이 어찌 돌아가고 있는지 모르겠는 감정임

요즘 분위기 자체가 vibe coding임을 농담 삼아 언급함
봇을 위한 문서를 쓰는 게 결국 잘 쓴 문서와 다르지 않다는 의견도 이전에 올라왔던 것 같음
결국 "AGENTS.md 파일을 만들고 마법을 채워넣으세요"라고만 써놓고 실제 사이트로 링크시키는 식이라는 느낌임
나의 경우, 5,000개 이상의 리포지토리를 관리하는 코딩 에이전트를 개발하고 있음
에이전트의 상태는 숨겨진 .agent 디렉토리 내에 저장되고, 각 에이전트 역할별 구성 폴더와 명확한 역할별 지침들을 포함함
프로젝트 폴더에 agents라는 폴더를 두고, 여러 파일을 역할별로 나눠 <Role> <instruction> 식으로 관리함
에이전트는 역할이 정의된 파일만 읽고, 상태는 dot<coding agent name> 폴더에 보관함
초기화는 /init으로 진행되며, 리포 전체 코드를 단순히 인덱싱하는 대신 전체 아키텍처와 논리를 요약한 high-level summary를 생성함
이 요약은 에디터 내에서 토글 가능한 "ghost comments"로 제공되고, 실제 코드에는 커밋되지 않는 메타데이터임
정교한 맵핑 시스템으로 요약마다 코드 줄과 정확히 연결됨
처음에 RAG를 코드에 직접 썼을 때 원하는 결과를 얻지 못해서 지금 구조를 도입함
현재는 AST 기반 빠른 문법적 검색과, 요약에 기반한 의미적 탐색(RAG)을 조합한 하이브리드 검색 모델을 사용함
예를 들어 "이 앱의 인증 방식이 어떻게 작동하는지?"를 물으면, 문법 검색은 login 같은 단어가 들어간 함수들만 찾지만, 의미 검색은 요약을 통해 인증 플로 전체를 서사적으로 파악해서 파일들에 흩어진 내용을 연결해 준다는 점에서 마치 마법처럼 작동함
- 여기에 덧붙여, 요약의 계층 구조(B트리 또는 일반 트리 형태)를 만들 수 있음
  즉, 메서드/클래스/모듈별로 summary가 존재하고, 각 계층이 더 하위 계층을 가리키게 설계함
  RAG가 의미적 쿼리에 따라 필요한 만큼 깊게 탐색 가능하고, 각 단계는 하위 내용을 요약해서 정보량은 줄이되 꼭 필요한 의미만 유지함
  이 방식은 코드의 추상화가 잘 되어 있을 때 특히 효과적임
  예시로 add(n1, n2)처럼 이름만으로 의미가 충분한 함수는 실제 구현을 몰라도 되지만, 현실 세계 함수들은 로깅이나 캐시 등 여러 역할을 하므로 상황에 따라 실제 코드도 맥락에 넣어야 할 수 있음
- 더 자세한 설명이 듣고 싶음
인간들이 서서히 프로젝트 문서를 제대로 작성하도록 유도당하고 있는 느낌임
- 농담이지만 사실 이런 부분을 팀에 어필하고 있음
  LLM이 실제로 생산성을 크게 높여주지 않더라도, 결과적으로는 문서화를 훨씬 더 잘 하게 되는 효과가 있음
- "Mission. Fucking. Accomplished." xkcd 810
README.md와 AGENTS.md를 굳이 분리해야 하는지 아직 확신이 없음
- 나도 계속 고민하고 있음
  관련 정리에 따르면,
  분리하는 이유로는

작성 스타일 문제(에이전트 문서에서 전체 대문자 강조가 인간 문서에선 불편함)
함축성 대 완전성(에이전트의 문서는 핵심 정보만 가져가야 하고, 인간용은 모든 것을 최대한 문서화해야 함)
필요 정보의 차이(LMM에게 필요한 정보와 인간에게 중요한 정보가 다름)
분리하지 말아야 할 이유는
중복 관리(핵심적으로 동일한 것을 두 군데에 따로 써야 하는 부담)임

README.md는 이젠 일종의 마케팅/랜딩 페이지 용, AGENTS.md와 CLAUDE.md는 코드/아키텍처/사용법 등의 실제 내용을 얻으러 가는 곳이라는 느낌임
예시를 읽으면서 나 역시 같은 생각을 했고, 사실 좋은 README.md 하나에 모든 내용이 담기면 충분하지 않을까 싶음
README는 인간을 위한 것, AGENTS.md 등은 LLM을 위한 것임
사용/설치 방법은 readme에, 컴파일/테스트 방법, 아키텍처 결정 사항, 코딩 표준, 레포 구조 등은 에이전트 문서에 정리함
LLM에서 context로 사용하는 용량 이슈도 생각해야 함
README.md는 내용이 많아서 전부 context에 넣기는 힘듦
AGENT.md에는 LLM에 꼭 필요한 테스트, 빌드명령 등 핵심 명령만 간결하게 넣음
README와 겹치는 부분이 있을 수 있지만, 불필요한 내용이 context에서 반복 전송되는 건 피하고 싶음
AI의 약속이 바로 우리가 굳이 정확한 포맷에 집착하지 않아도, 원하는 방식대로만 적으면 기계가 알아서 맞춰주는 거 아니었나?
- 실제로는 파일 이름만 표준화했고, 내용은 아무 형식을 강요하지 않고 아무든 원하는 방식으로 작성할 수 있는 게 맞은 선택임
  AGENTS.md는 표준 마크다운이니까 원하는 헤딩을 쓰면 되고, 에이전트가 텍스트를 파싱함
- 그래도 어느 정도 구조와 형식은 중요성을 가짐
  정확한 코드 문법 수준은 아니더라도 말임
- 결국은 내용을 명확히 적어야 한다는 결론임
  문서가 길어질수록 구조적인 접근법이 인간 입장에서 유지보수에 유리함
사용하는 각각의 에이전트(Claude Code, Gemini, Aider)마다 파일 이름이 다 다름
표준화된다면 좋겠지만, 지금은 ruler로 여러 포맷을 자동 생성하는 수고를 감수함
특히 에이전트마다 MCP 구성 파일 소비 방식도 달라서 표준화가 당장 이뤄지긴 어려울 거로 봄
ruler
- 약간 시니컬하게 보자면, 벤더 락인을 만들기 위한 움직임 때문이라고 봄
  표준화는 곧 상품화로 이어질 수 있어서 업체들이 꺼리는 듯함
- Jules는 AGENTS.md를 써서 구글이 이 표준에 동참하고 있음을 보여줌
  Gemini Code Assist도 계속 유지된다면 AGENTS.md를 지원할 것으로 예상함
  Aider 문서에 특정 파일명이 언급되어 있지 않은데, 혹시 링크가 있다면 알려줬으면 함
  Anthropic이 유일하게 아직 표준 파일명을 지원하지 않는 것으로 보임
- ruler 같은 도구가 실제 필요하다는 게 아쉽긴 함
이상하게 다가오는 웹사이트임
OpenAI가 만든 건 방문자 유치와 마케팅 포지셔닝 목적일까 싶음
실제로는 포맷 없이 파일명만 지정함
Anthropic/Claude가 빠져 있는 것도 눈에 띔; symbolic link 기법으로 CLAUDE.md를 AGENTS.md로 연결하는 식도 가능하긴 함
- 실제로는 sourcegraph에서 만든 거고, 5월부터 존재했음
  이전에는 agent.md였다가, 이제는 agents.md로 301 리다이렉트됨
  과거 링크 참고
  공식 발표문도 있음
  최근 OpenAI와 파트너십을 맺은 모양임
  흥미롭게도 처음엔 agent.md였지만 이제는 agents.md로 바뀜
- Claude가 목록에 없는 이유는 Claude만 표준 파일명 규칙을 아직 지원하지 않기 때문임

답변달기