Skip to content

AGENTS.md

AI 코딩 에이전트를 위한 오픈 포맷

About

  • 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

See also

Favorite site