AGENTS.md 생성기
양식을 작성하면 명령어, 규칙, 엄격한 제한이 포함된 AGENTS.md를 받을 수 있습니다. Cursor, GitHub Copilot, Claude Code, Cline, Devin Desktop용 경로 범위 규칙도 함께 생성됩니다. 기본적으로 AGENTS.md를 읽지 않는 도구를 위한 브리지 파일도 제공됩니다.
# Acme 웹 앱
관리자 영역과 소규모 REST API를 갖춘 고객용 웹 앱입니다.
## 기술 스택을 따르세요
Next.js, React, TypeScript, pnpm
## 명령어를 사용하세요
- 설치하세요: `pnpm install`
- 로컬에서 실행하세요: `pnpm dev`
- 테스트를 실행하세요: `pnpm test`
- 린트와 타입 검사를 실행하세요: `pnpm lint && pnpm tsc --noEmit`
- 빌드하세요: `pnpm build`
## 코드 스타일을 따르세요
- 린터가 적용하는 포맷을 따르고, 수정하지 않은 파일은 그대로 두세요.
- 입력과 출력이 명확한 작은 함수를 선호하고, 부수 효과는 경계 부분에 두세요.
- 새 dependency를 추가하기 전에 확인을 요청하세요.
- 명확하지 않은 코드에는 각 줄의 동작이 아니라 그 이유를 주석으로 남기세요.
## 테스트
- 변경한 동작마다 테스트를 추가하거나 업데이트하세요.
- 작업을 마쳤다고 알리기 전에 테스트 명령을 실행하고 실패를 해결하세요.
- 테스트 통과를 위해 실패하는 테스트를 삭제하거나 건너뛰지 마세요.
## 커밋 및 pull request
- 커밋 제목은 명령형으로 작성하고 72자 미만으로 유지하세요.
- 각 pull request에는 변경 사항 하나만 담고, 설명에 테스트 방법을 적으세요.
- 커밋하기 전에 lint와 테스트를 실행하세요.
## 금지 사항
- secret, API key 또는 .env 파일을 커밋하지 마세요.
- src/generated/ 아래의 생성된 파일을 직접 수정하지 말고 다시 생성하세요.
- 프로덕션에서 데이터베이스를 파괴할 수 있는 명령을 실행하지 마세요.
- main에 force-push하거나 공유된 이력을 다시 작성하지 마세요.
다섯 가지 도구에 동일한 규칙
---
description: 이 glob과 일치하는 파일에 적용할 규칙
globs: app/**/*.tsx
alwaysApply: false
---
이 폴더의 인접한 파일에서 이미 사용하는 패턴을 따르세요. export된 모든 함수에 docstring과 해당 테스트 파일의 테스트를 추가하세요.
---
applyTo: "app/**/*.tsx"
---
이 폴더의 인접한 파일에서 이미 사용하는 패턴을 따르세요. export된 모든 함수에 docstring과 해당 테스트 파일의 테스트를 추가하세요.
---
paths:
- "app/**/*.tsx"
---
이 폴더의 인접한 파일에서 이미 사용하는 패턴을 따르세요. export된 모든 함수에 docstring과 해당 테스트 파일의 테스트를 추가하세요.
---
paths:
- "app/**/*.tsx"
---
이 폴더의 인접한 파일에서 이미 사용하는 패턴을 따르세요. export된 모든 함수에 docstring과 해당 테스트 파일의 테스트를 추가하세요.
---
trigger: glob
globs: app/**/*.tsx
---
이 폴더의 인접한 파일에서 이미 사용하는 패턴을 따르세요. export된 모든 함수에 docstring과 해당 테스트 파일의 테스트를 추가하세요.
효과적인 지침 파일을 만드는 방법
정확한 명령어를 파일 앞부분에 배치하세요
실제 설치, 테스트, 린트 명령어와 플래그를 파일 앞부분에 적으세요. 기술 스택과 버전을 정확히 명시하고, 설명만으로 모호해질 수 있는 부분은 짧은 코드 예시로 보여주세요.
금지 사항을 명확히 작성하세요
에이전트가 해서는 안 되는 일을 분명히 명시하세요. 예를 들면 secrets, vendored code 또는 production 환경을 건드리지 않는 것입니다. GitHub가 검토한 파일에서 가장 유용한 제약 사항은 secrets를 커밋하지 말라는 규칙이었습니다.
각 지침을 검증 가능하게 작성하세요
커밋 전에 npm test를 실행하라는 지침은 확인할 수 있지만, 변경 사항을 테스트하라는 지침은 확인하기 어렵습니다. 두 문장이 서로 다르면 모델이 어느 쪽이든 따를 수 있으므로 모순을 제거하세요.
간결하게 작성하고 경로별로 나누세요
Anthropic은 파일당 200줄 미만, Cursor는 규칙당 500줄 미만을 권장합니다. 특정 영역에 대한 지침은 경로 범위를 지정한 규칙으로 옮겨 해당 파일을 다룰 때만 불러오도록 하세요. import는 파일을 깔끔하게 정리하지만 컨텍스트 비용을 줄이지는 않습니다.
에이전트가 이미 아는 내용은 생략하세요
코딩 에이전트 4종을 대상으로 한 연구에서 컨텍스트 파일은 작업 성공률을 일관되게 높이지 못했고 추론 비용을 20% 넘게 늘렸습니다. LLM이 작성한 파일은 성능을 약간 떨어뜨렸고 저장소 개요도 도움이 되지 않았습니다. 따라서 특정 도구처럼 당연하지 않은 요구 사항만 파일에 담으세요.
실수가 반복되면 규칙을 추가하세요
간단하게 시작하고 에이전트가 같은 실수를 두 번 이상 하는 것을 확인하면 규칙을 한 줄 추가하세요. 스타일 가이드 전체를 붙여 넣는 대신 기존 파일을 패턴으로 참조하세요.
AGENTS.md 관련 질문
Claude Code는 AGENTS.md를 읽나요?
예. v2.1.277부터 지원합니다. 기본적으로 작업 디렉터리 또는 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md 또는 CLAUDE.local.md가 없을 때만 AGENTS.md 또는 .claude/AGENTS.md를 읽습니다. claude-md-and-agents-md 설정을 사용하면 두 파일을 모두 불러올 수 있으며, @AGENTS.md를 포함한 CLAUDE.md는 모든 버전에서 작동합니다.
AGENTS.md에 frontmatter나 정해진 제목이 필요한가요?
아니요. AGENTS.md는 필수 필드가 없는 일반 Markdown 파일이며, 원하는 제목을 사용할 수 있습니다. agents.md 사이트는 프로젝트 개요, 빌드 및 테스트 명령어, 코드 스타일, 테스트, 보안 참고 사항, pull request 지침 등의 섹션을 제안합니다.
모노레포에서 AGENTS.md를 어떻게 사용하나요?
루트에 AGENTS.md 하나를 두고, 자체 규칙이 필요한 각 패키지 안에도 파일을 추가하세요. 에이전트는 편집 대상 코드와 가장 가까운 파일을 읽으며, 규칙이 충돌하면 해당 파일의 내용이 우선합니다. agents.md에 이 내용이 기록될 당시 OpenAI의 기본 저장소에는 AGENTS.md가 88개 있었습니다.
Gemini CLI가 AGENTS.md를 읽게 하려면 어떻게 하나요?
Gemini CLI는 기본적으로 GEMINI.md를 읽습니다. .gemini/settings.json의 context.fileName에 AGENTS.md를 추가하세요. 예를 들면 ["AGENTS.md", "GEMINI.md"]입니다. 어떤 파일이 불러와졌는지 확인하려면 /memory show를 실행하세요.
AGENTS.md를 지원하는 코딩 에이전트는 무엇인가요?
OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Devin Desktop, Cline, OpenClaw의 문서를 확인했습니다. 이 도구들은 모두 AGENTS.md를 기본으로 읽습니다. Gemini CLI와 Aider는 설정 한 줄이 필요합니다. agents.md 사이트에 따르면 Zed, Warp, goose, opencode, Jules, JetBrains Junie를 포함해 총 23개 도구가 호환됩니다.
AGENTS.md 형식은 누가 관리하나요?
OpenAI는 2025-12-09에 MCP 및 goose와 함께 발표된 Linux Foundation 산하 기금인 Agentic AI Foundation에 AGENTS.md를 기여했습니다. agents.md 사이트에 따르면 오픈소스 프로젝트 60k개 이상에서 AGENTS.md를 사용합니다.