코딩 에이전트를 위한 AGENTS.md 파일 작성법
설정·테스트 명령, 규칙, 경계를 담은 짧은 AGENTS.md를 작성하고, Claude Code와 Gemini CLI가 읽도록 설정한 뒤 작은 작업으로 시험해 보세요.
AGENTS.md 파일은 저장소 루트에 두는 평범한 Markdown 파일로, 코딩 에이전트에게 프로젝트에서 어떻게 작업할지 알려 줘요. 어떤 명령을 실행할지, 코드가 어디에 있는지, 무엇을 건드리지 말아야 하는지 같은 내용이에요. 꼭 넣어야 하는 섹션은 없어요. 짧게 쓰고, 모든 규칙을 확인할 수 있게 만들고, 각 에이전트가 이 파일을 불러오는지 확인하세요.
이 글에서는 무엇을 넣을지, 템플릿, Claude Code와 Gemini CLI가 파일을 찾는 방식, 간단한 시험 방법을 다뤄요. Reunified의 Mono로 휴대폰에서 에이전트를 시작할 때도 같은 단계가 적용돼요.
1. 파일에 넣을 내용 정하기
agents.md 사이트는 이 파일을 에이전트를 위한 README라고 불러요. 모든 세션에 필요한 사실은 넣고, 에이전트가 코드에서 알아낼 수 있는 내용은 빼세요.
| AGENTS.md에 넣을 것 | 뺄 것 |
|---|---|
| 설정, 테스트, 린트 명령 | 비밀번호, API 키, 토큰 |
| 주요 코드가 있는 위치 | 전체 파일 트리나 의존성 목록 |
| 일반적인 기본값과 다른 컨벤션 | 긴 절차(대신 문서 링크) |
| 절대 수정하면 안 되는 파일, 먼저 물어봐야 하는 작업 | 개인 취향(에이전트의 사용자 수준 파일 사용) |
모노레포에서는 패키지마다 AGENTS.md를 둘 수 있어요. 가장 가까운 파일이 우선하며, 채팅에서 직접 준 지시는 그 파일보다 우선해요.
2. 짧은 템플릿으로 시작하기
pnpm을 쓰는 TypeScript 웹 앱 “tidy-recipes”를 위한 가상의 예시예요.
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.이 저장소에서 직접 실행해 본 명령만 적으세요. 잘못된 명령이 있어도 에이전트는 그대로 믿어요.
3. 에이전트가 따랐는지 확인할 수 있는 규칙 쓰기
좋은 규칙은 에이전트가 그 규칙을 따랐는지 나중에 확인할 수 있게 해 줘요.
| 모호한 규칙 | 구체적인 규칙 |
|---|---|
| 변경 사항을 테스트할 것 | 끝내기 전에 pnpm test와 pnpm lint 실행 |
| 파일을 잘 정리할 것 | 컴포넌트는 src/components에 둠 |
| 데이터베이스는 조심해서 다룰 것 | db/migrations/는 절대 수정하지 않음 |
| 작업 내용을 요약할 것 | 변경한 파일과 테스트 결과를 나열 |
경계는 “절대 하지 말 것”과 “먼저 물어볼 것” 형태의 규칙으로, 한 줄에 하나씩 쓰세요.
4. Claude Code와 Gemini CLI가 파일을 읽게 하기
agents.md 사이트에는 이 형식을 지원하는 Codex, Gemini CLI, opencode 등 여러 에이전트가 나와 있지만, 일부는 먼저 설정이 필요해요.
Claude Code 최신 버전은 기본적으로 작업 디렉터리나 그 상위 디렉터리에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 없을 때만 AGENTS.md를 읽어요(메모리 문서 참고). 이런 파일이 있거나 이전 버전을 쓴다면 CLAUDE.md에서 AGENTS.md를 가져오세요. tidy-recipes 프로젝트에는 예전부터 쓰던 CLAUDE.md가 있으니, 맨 위에 다음 줄을 추가하고 Claude 전용 메모는 그 아래에 두세요.
@AGENTS.md
Prefer small commits.새 세션을 시작하고 /context를 실행해 메모리 파일(Memory files) 아래에 CLAUDE.md가 나오는지 확인하세요. CLAUDE.md가 없다면 /memory에 대신 AGENTS.md 경로가 표시돼요.
Gemini CLI는 기본적으로 GEMINI.md를 읽어요. AGENTS.md도 읽게 하려면 프로젝트의 .gemini/settings.json에 다음 내용을 넣으세요(GEMINI.md 문서 참고).
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}새 세션을 시작한 다음 /memory show를 실행해 무엇을 불러왔는지 확인하세요. 다른 에이전트는 각자의 문서를 확인하세요.
5. 작은 작업으로 파일 시험하기
새 세션에서 에이전트에게 다음 작업을 주세요.
먼저 불러온 프로젝트 규칙과 각 규칙이 나온 파일을 나열해 줘. 그다음 src/components/SaveButton.tsx에서 버튼 텍스트 “Save recipe”를 “Save”로 바꿔. 다른 것은 바꾸지 마.
결과를 파일 내용과 비교해 확인하세요.
- AGENTS.md(또는 가져오기 줄이 있는 CLAUDE.md)를 언급했는지
pnpm test와pnpm lint를 실행하고 결과를 보고했는지- db/migrations/를 건드리지 않았고 의존성도 추가하지 않았는지
- 변경한 파일을 나열했는지
수정 내용은 git diff로 직접 확인하세요(AI 코드 변경 검토하기 참고). 에이전트가 규칙을 대지 못한다면 파일을 불러오지 못했을 가능성이 크니 4단계로 돌아가세요. 규칙을 언급하고도 따르지 않았다면 그 규칙을 더 구체적으로 고치세요.
6. 짧고 최신 상태로 유지하기
Claude Code 문서는 CLAUDE.md를 200줄 미만으로 유지하라고 권해요. 파일이 길수록 컨텍스트를 더 많이 쓰고, 에이전트가 규칙을 덜 일관되게 따르기 때문이에요. AGENTS.md도 같은 기준을 목표로 하세요. 컨텍스트가 가득 차면 어떻게 되는지는 컨텍스트 윈도우 가이드에서 다뤄요.
에이전트가 같은 실수를 반복하면 파일을 고치고, 오래된 명령과 서로 충돌하는 규칙은 지우세요. 파일을 커밋하고, 이 파일의 변경도 코드처럼 검토하세요.
이 파일은 에이전트에게 방향을 알려 줄 뿐, 무언가를 강제하지는 않아요. 특정 작업을 막으려면 에이전트의 권한 설정을 쓰거나 요청을 거부하세요(도구 권한 가이드 참고).
Mono에서 에이전트는 컴퓨터에 있는 프로젝트의 작업 디렉터리에서 시작하고, 그곳에서 이 파일들을 찾아요. AGENTS.md, CLAUDE.md, .gemini/settings.json은 휴대폰에서도 Mono 편집기로 열 수 있고, 수정한 내용은 자동으로 저장돼요. 파일을 새로 만들려면 에이전트에게 요청하거나 프로젝트 카드에서 터미널을 여세요. Mono는 파일 내용을 검사하지 않으며, 에이전트가 어떤 파일을 불러올지도 바꾸지 않아요. Mono는 아직 출시 전이지만 대기자 명단에 등록할 수 있어요.
