AGENTS.md

AGENTS.md

AI 코딩 에이전트가 읽도록 저장소에 두는 마크다운 지침 파일의 공용 규약

AGENTS.md는 AI 코딩 에이전트에게 프로젝트별 지침(빌드·테스트 명령, 코드 규칙, 커밋 관례 등)을 전하려고 저장소에 두는 평범한 마크다운 파일이자, 그 파일 이름을 여러 도구가 함께 쓰자는 규약이다. 공식 사이트는 이를 "에이전트를 위한 README"라고 소개한다. 사람이 읽는 README에 넣기에는 너무 세세한 내용을 에이전트용으로 따로 모으는 자리다.

2025년 8월 OpenAI가 Amp, 구글 Jules, 커서, Factory, Roo Code 개발진과 함께 agents.md 사이트를 열며 공개했다. 특정 회사 이름이 붙지 않은 중립적인 파일명을 고른 것도 다른 도구가 채택하기 쉽게 하려는 뜻이었다. 2025년 12월 9일 OpenAI가 리눅스 재단 산하에 새로 세워진 에이전틱 AI 재단(Agentic AI Foundation, AAIF)에 기증해, 지금은 이 재단이 관리한다.

등장 배경

AI 코딩 도구는 저마다 프로젝트 지침 파일을 따로 정해 왔다. 한 저장소에서 여러 회사의 도구를 함께 쓰면 내용이 거의 같은 파일을 도구마다 하나씩 두고 따로 고쳐야 했다.

도구	고유 지침 파일
클로드 코드	CLAUDE.md, CLAUDE.local.md
깃허브 코파일럿	.github/copilot-instructions.md, .github/instructions/*.instructions.md
커서	.cursor/rules/*.mdc (예전에는 .cursorrules)
제미나이 CLI	GEMINI.md

AGENTS.md는 이 파일들을 하나로 모으자는 제안이다. 공식 사이트는 6만 개가 넘는 오픈 소스 프로젝트가 이 파일을 쓰고 있다고 밝힌다.

파일 구성

정해진 필드나 필수 항목이 없다. 아무 제목이나 쓸 수 있는 보통 마크다운이며, 에이전트는 본문을 그대로 읽는다. 흔히 넣는 내용은 다음과 같다.

• 프로젝트 개요와 폴더 구조
• 의존성 설치, 개발 서버 실행, 빌드·테스트·린트 명령
• 코드 스타일(언어 설정, 따옴표, 세미콜론 같은 규칙)
• 풀 리퀘스트 제목 형식, 커밋 전 확인할 일
• 보안상 주의할 점

공식 사이트가 든 최소 예시를 옮기면 다음과 같다.

# AGENTS.md

## Setup commands
- Install deps: pnpm install
- Start dev server: pnpm dev
- Run tests: pnpm test

## Code style
- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

명령어처럼 한 글자만 틀려도 실패하는 내용, 커밋 규칙처럼 에이전트가 한 번 어기면 되돌리기 번거로운 내용을 적어 두는 것이 이 파일의 쓸모다. 에이전트는 적힌 테스트 명령을 실제로 돌려 보고, 실패하면 고친 뒤 작업을 마치려 한다.

중첩과 우선순위

• 저장소 루트뿐 아니라 하위 폴더마다 AGENTS.md를 둘 수 있다. 에이전트는 편집하는 파일에서 가장 가까운 AGENTS.md를 우선한다. 루트에는 공통 규칙을, 백엔드·프런트엔드 폴더에는 각자의 규칙을 두는 식으로 모노레포를 나눠 관리할 수 있다. 공식 사이트에 따르면 OpenAI의 주 저장소에는 AGENTS.md가 88개 있었다.
• 지침끼리 충돌하면 가장 가까운 파일이 이기고, 사용자가 대화에서 직접 내린 지시는 모든 파일보다 앞선다.
• 구체적인 합치는 방식은 도구마다 다르다. OpenAI 코덱스는 홈 폴더(~/.codex)의 전역 파일을 먼저 읽고, 프로젝트 루트(보통 git 루트)에서 현재 폴더까지 내려오며 폴더마다 AGENTS.override.md, AGENTS.md 순으로 하나씩 골라 이어 붙인다. 현재 폴더에 가까운 파일이 뒤에 붙어 앞의 지침을 덮어쓰며, 합친 크기가 기본 32KiB(project_doc_max_bytes)를 넘으면 더 붙이지 않는다.
• 깃허브 코파일럿도 작업 중인 위치에서 가장 가까운 AGENTS.md를 우선한다. 커서는 하위 폴더의 AGENTS.md를 상위 폴더의 것과 합치되, 더 구체적인 지침을 우선한다.

지원 도구

공식 사이트는 OpenAI 코덱스, 구글 Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, 커서, Roo Code, 제미나이 CLI, Kilo Code, 깃허브 코파일럿 코딩 에이전트, Windsurf, Augment Code 등을 지원 도구로 든다. 아래는 각 도구의 공식 문서로 확인한 것이다.

도구	지원 방식	비고
OpenAI 코덱스	기본 지침 파일	전역·프로젝트 단계, AGENTS.override.md, 대체 파일명 설정(project_doc_fallback_filenames)
깃허브 코파일럿	직접 읽음	저장소 어디에나 여러 개 둘 수 있다. 루트의 CLAUDE.md, GEMINI.md도 대신 읽는다. 코딩 에이전트는 2025년 8월 28일부터 지원
커서	직접 읽음	.cursor/rules의 단순한 대안. 하위 폴더 중첩 지원
클로드 코드	직접 읽음(2.1.277판부터)	CLAUDE.md가 없을 때만 읽는 것이 기본값. 아래 참고
제미나이 CLI	설정 필요	기본 파일은 GEMINI.md. settings.json의 context.fileName에 AGENTS.md를 넣으면 읽는다
Aider	설정 필요	.aider.conf.yml에 read: AGENTS.md를 적는다

클로드 코드

클로드 코드는 오랫동안 자체 파일인 CLAUDE.md만 읽었고, AGENTS.md를 쓰는 저장소는 CLAUDE.md 안에서 @AGENTS.md로 불러와야 했다. 2026년 9월 18일 2.1.277판에서 AGENTS.md 지원이 추가되었다. 동작은 다음과 같다.

• 작업 폴더나 그 위 폴더에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 하나도 없을 때만 AGENTS.md를 읽는다. 하나라도 있으면 CLAUDE.md 쪽만 읽는다. 사용자 홈(~/.claude/CLAUDE.md)과 조직 관리 CLAUDE.md는 이 판단에 들어가지 않는다.
• 세션 시작 때 작업 폴더와 그 위 폴더의 AGENTS.md를 읽고, 하위 폴더의 AGENTS.md는 그 폴더 파일을 열 때 불러온다.
• AGENTS.local.md, AGENTS.override.md, .agents/ 폴더 안의 파일은 읽지 않는다.
• /config의 Project instructions 설정으로 둘 다 읽기(claude-md-and-agents-md), CLAUDE.md만 읽기 등으로 바꿀 수 있다.

한계

• 순수 마크다운이라 적용 범위, 우선순위, 대상 도구 같은 메타데이터를 표준으로 담을 방법이 없다. 커서 규칙 파일(.mdc)이나 에이전트 스킬의 SKILL.md가 머리말(frontmatter)에 속성을 적는 것과 대조된다. 그래서 AGENTS.md를 공통 기본 지침으로 두고, 도구별 고급 기능은 고유 파일에 남겨 두면서 그 파일에서 AGENTS.md를 불러오는 절충이 쓰인다.
• 파일 내용은 모델이 참고하는 맥락일 뿐 강제 규칙이 아니다. 클로드 코드 문서도 지침 파일을 강제 설정이 아닌 맥락으로 다루며, 반드시 막아야 하는 행동은 훅 같은 별도 장치로 막으라고 안내한다.
• 남이 만든 저장소의 AGENTS.md도 에이전트에게는 지시로 읽힌다. 악의적인 지시를 숨겨 두는 간접 프롬프트 인젝션의 통로가 될 수 있다.

같이 보기

• 에이전트 스킬
• 에이전트 인공지능
• 클로드 코드
• 깃허브 코파일럿
• 커서 (소프트웨어)
• 모델 컨텍스트 프로토콜
• 프롬프트 엔지니어링
• 바이브 코딩

참고 문헌

• AGENTS.md 공식 사이트
• agentsmd/agents.md 저장소