AGENTS.md 완전 가이드 — 표준 섹션 구조와 작성법
업데이트 2026-07-11 · 개발자를 위한 참고 가이드
1. AGENTS.md란 무엇인가
AGENTS.md는 코딩 에이전트에게 프로젝트의 규칙과 맥락을 전달하는 툴 중립적(tool-agnostic) 마크다운 파일입니다. 저장소 루트에 두면 Cursor, Claude Code, OpenAI Codex, GitHub Copilot, Google Jules 등 이 관례를 지원하는 에이전트가 코드를 생성·수정하기 전에 이 파일을 읽고, 셋업 방법·빌드/테스트 명령·코드 스타일·디렉토리 구조·커밋 규칙·보안 주의사항을 파악합니다. 사람에게 주는 README가 아니라, 에이전트에게 주는 운영 매뉴얼이라고 생각하면 됩니다.
2. 왜 필요한가 — 규칙 파일의 파편화
AI 코딩 도구마다 규칙 파일 이름이 달랐습니다. Claude Code는 CLAUDE.md, Cursor는 .cursorrules 또는 .cursor/rules, GitHub Copilot은 .github/copilot-instructions.md를 읽었죠. 같은 규칙을 여러 파일에 중복으로 유지하는 것은 고통스럽고, 하나만 바꾸면 나머지가 어긋납니다. AGENTS.md 표준은 이 파편화를 해결하기 위해 등장했고, 수만 개의 저장소가 채택하고 있습니다. 하나의 AGENTS.md를 원본(source of truth)으로 두고 나머지는 심볼릭 링크로 연결하는 방식이 권장됩니다.
3. 표준 섹션 구조 (8개)
AGENTS.md는 자유 형식 마크다운이지만, 실무에서 자리 잡은 섹션 구조가 있습니다. 이 생성기는 아래 8개 섹션을 표준 순서로 출력합니다.
- Project overview (프로젝트 개요) — 한 줄 설명과 기술 스택. 에이전트가 "이게 무슨 프로젝트인지" 즉시 알도록.
- Setup commands (셋업 명령) — 의존성 설치 명령(코드블록), 개발 서버·빌드·테스트·린트 명령.
- Code style (코드 스타일) — 들여쓰기, 네이밍, 포맷터(Prettier/Black/gofmt), 린터 규칙.
- Testing (테스트) — 테스트 실행 방법과 "커밋 전 테스트 필수" 같은 규칙.
- Project structure (프로젝트 구조) — 주요 디렉토리와 역할(코드 트리).
- Commit & PR conventions (커밋·PR 규칙) — Conventional Commits, 제목 길이, PR 단위.
- Security (보안) — 비밀키 취급, 로그 금지 항목, 입력 검증.
- Do not (하지 말 것) — 생성물 수정 금지, main 직접 커밋 금지 등 명확한 금지 목록.
4. 각 섹션 작성 팁
셋업 명령은 "복붙 가능하게"
에이전트가 그대로 실행할 수 있도록 정확한 명령을 코드블록에 넣으세요. "의존성을 설치한다"가 아니라 npm install, pip install -r requirements.txt처럼요.
코드 스타일은 한 줄에 하나
"들여쓰기 2칸", "TypeScript strict 모드", "Prettier로 포맷"처럼 짧고 검증 가능한 규칙을 나열하세요. 이 생성기는 한 줄을 하나의 불릿으로 변환합니다.
"하지 말 것"이 가장 강력하다
에이전트는 종종 생성된 파일을 수정하거나 불필요한 의존성을 추가합니다. dist/·build/ 수정 금지, 임의 의존성 추가 금지, main 직접 커밋 금지 같은 명시적 금지는 실수를 크게 줄입니다.
5. 스택 프리셋
이 생성기는 Node.js/TypeScript, React/Vite, Python, Go, Rust, Monorepo(pnpm/Turborepo) 프리셋을 제공합니다. 프리셋을 고르면 각 생태계의 관례(예: Python은 4칸 들여쓰기·PEP 8·pytest, Go는 gofmt·에러 명시 처리)에 맞춰 명령과 코드 스타일이 자동으로 채워집니다. 그 뒤 프로젝트에 맞게 손보면 됩니다.
6. CLAUDE.md · .cursorrules · copilot-instructions와의 관계
AGENTS.md를 지원하지 않는 도구를 위해 이 생성기는 동일한 내용을 네 가지 파일로 출력합니다.
AGENTS.md— 표준, 툴 중립.CLAUDE.md— Claude Code..cursorrules— Cursor..github/copilot-instructions.md— GitHub Copilot.
규칙이 바뀔 때마다 네 파일을 함께 재생성하거나, AGENTS.md를 원본으로 두고 나머지를 심볼릭 링크로 연결하세요.
ln -s AGENTS.md CLAUDE.md ln -s AGENTS.md .cursorrules7. 프라이버시
이 생성기는 100% 브라우저 클라이언트입니다. 입력한 프로젝트 정보는 서버로 전송되지 않고 localStorage와 공유 링크 토큰(?s=)에만 저장됩니다. 사내 코드베이스 정보를 다뤄도 안전합니다.