AGENTS.md 작성법: AI 코딩 에이전트가 틀리기 쉬운 규칙만 적는다
AGENTS.md는 AI 코딩 에이전트가 작업 전에 읽는 지침 파일입니다. 에이전트가 틀리기 쉬운 것만 이유와 함께 적고, 중요한 규칙은 테스트로 막습니다.
SugarMount는 96줄짜리 AGENTS.md 하나로 Android 앱 4개를 냈고, 이 파일은 처음 만든 뒤 지금까지 19번 고쳐졌습니다.
예시는 SugarMount 앱 저장소(sugar-utils)의 AGENTS.md에서 옮겨 한국어로 줄였습니다. 기준일은 2026년 10월 18일입니다.
AGENTS.md는 무엇인가요?
저장소 맨 위에 두는 Markdown 파일입니다. 여러 AI 코딩 에이전트가 이 이름의 파일을 지침으로 읽습니다. Claude Code는 CLAUDE.md를 읽기 때문에, SugarMount는 같은 내용을 두 파일에 둡니다. 사람을 위한 README와 달리 독자가 에이전트이고, 에이전트는 매번 처음 보는 사람처럼 저장소를 읽기 때문에, 사람이라면 한 번 듣고 기억할 것도 적어 두어야 합니다.
적는 것
| 절 | 내용 | 왜 필요한가 |
|---|---|---|
| 이 저장소는 무엇인가 | 앱 목록, 각 앱이 지금 어느 단계인지(Play 공개, 내부 테스트), 기술 스택과 SDK 버전 | 에이전트가 "출시됐다"를 추측하지 않게 |
| 구조 | 디렉터리마다 무엇을 맡는지 한 줄씩 | 같은 기능을 다른 곳에 또 만들지 않게 |
| 빌드와 테스트 | 그대로 복사해 실행할 수 있는 명령 | 검증 방법을 매번 새로 찾지 않게 |
| 틀리기 쉬운 규칙 | 12개. 규칙, 이유, 예외의 범위 | 이 파일의 본론 |
| QA 방법 | 에뮬레이터·실기기 테스트 스크립트와 순서 | "빌드 성공"을 "완료"로 보고하지 않게 |
| 다음 앱 추가 | 생성 스크립트와 그 뒤에 손으로 바꿀 것 | 앱마다 같은 실수를 반복하지 않게 |
빼는 것
- 이력: 파일 첫머리에 "이 파일은 현재 사실만 담고, 이력은 CHANGELOG.md로 간다"고 적었습니다. 지난 버전 이야기가 섞이면 에이전트가 옛 규칙을 지금 규칙으로 읽습니다.
- 비밀값: 키 파일은 위치와 "커밋하지 말 것"만 적고, 내용은 절대 적지 않습니다.
- 일반 상식: "코드를 깔끔하게" 같은 문장은 에이전트도 이미 압니다. 이 저장소에서만 통하는 것만 남깁니다.
틀리기 쉬운 규칙은 어떻게 쓰나요?
규칙 하나에 하지 말 것, 그 이유, 예외의 범위를 같이 적습니다. 실제 규칙 몇 개를 옮기면 이렇습니다.
- 식별자는 앱마다 따로입니다. 패키지 이름, 광고 ID, Firebase 프로젝트, 결제 상품은 앱별 설정 파일에만 둡니다. 코드를 재사용해도 ID는 재사용하지 않습니다.
- 디버그는 광고 테스트 ID만, 릴리스는 테스트 ID 금지. 양쪽 방향을 모두 검사합니다.
- 통계와 로그에 사용자 내용을 넣지 않습니다. 이벤트에 자유 형식 파라미터를 일부러 두지 않았고, "
Map<String, Any>같은 우회로를 만들지 말 것"이라고 적었습니다. - 기기에서 확인한 것과 컴파일만 된 것을 나눠 보고합니다. 출시하지 않은 기능을 출시한 것처럼 쓰지 않습니다.
예외는 범위를 좁혀서 적습니다. 예를 들어 "임시 파일은 캐시에만 둔다"는 규칙에는 "문서 뷰어(한글뷰어 슈가독)만 받은 문서 보관함을 따로 둔다. 이것을 임시 파일 방식으로 되돌리지 말 것"이라는 예외가 붙어 있습니다. 이 문장이 없으면 에이전트는 예외를 버그로 보고 "고칩니다".
사람이 내린 결정에는 날짜를 붙입니다(예: "owner decision 2026-10-05"). 지금 AGENTS.md에는 날짜가 붙은 결정이 6건 있습니다. 날짜가 있으면 에이전트가 오래된 문서와 충돌할 때 어느 쪽이 최신인지 판단할 수 있습니다.
어기면 안 되는 규칙은 검사로 막기
에이전트는 지침을 대체로 따르지만, 긴 작업 중에 놓치기도 합니다. 그래서 어기면 큰일 나는 규칙은 테스트나 빌드 검사로 바꿉니다.
| 규칙 | 막는 장치 |
|---|---|
| 앱별 식별자, 릴리스에 광고 테스트 ID 금지 | 앱마다 ConfigGateTest, release_gate.sh가 PLACEHOLDER나 테스트 ID를 보면 빌드 중단 |
| 공통 문서 로직에 Android 의존 금지 | NoAndroidImportsTest |
| 모든 문구는 한국어·영어 둘 다 | lint의 MissingTranslation·ExtraTranslation을 경고가 아니라 오류로 |
| 전면 광고 간격과 횟수 | AdPacerTest. 새 숫자는 호출하는 곳이 아니라 설정에 테스트와 함께 추가 |
| 개인정보처리방침 링크가 살아 있을 것 | release_gate.sh가 방침·지원 URL이 HTTP 200인지 확인 |
마지막 줄의 URL이 바로 이 사이트의 앱별 개인정보처리방침입니다. 사이트 주소를 바꾸면 앱 출시가 막히도록 되어 있습니다.
최신으로 유지하는 방법
- 실수가 나온 자리에서 한 줄 추가: 첫 앱 사진 용량 줄이기의 출시용 빌드가 실행 직후 죽은 뒤에 "업로드 전에는 반드시
release_launch.sh를 돌린다"는 줄과 그 이유(어느 버전에서 무엇이 죽었는지)를 넣었습니다. - 사실이 바뀌면 같은 커밋에서 고치기: 앱이 Play에 공개되거나 버전이 올라가면 그 작업 커밋에서 AGENTS.md도 같이 고칩니다. 19번의 수정은 거의 모두 기능이나 출시 작업과 같은 커밋에 들어 있습니다.
- 길어지면 문서로 내보내기: 광고 정책, 디자인 규칙, 문서 뷰어 설계는 별도 문서로 두고 AGENTS.md에는 경로만 남깁니다.
자주 묻는 질문
AGENTS.md와 CLAUDE.md는 무엇이 다른가요?
읽는 도구가 다를 뿐 역할은 같습니다. Claude Code는 CLAUDE.md를 읽고, 다른 여러 에이전트는 AGENTS.md를 읽습니다. 두 파일 내용이 어긋나면 에이전트마다 다른 규칙을 따르게 되므로, SugarMount는 같은 내용을 둡니다.
얼마나 길게 써야 하나요?
정해진 길이는 없습니다. SugarMount 앱 4개를 내는 저장소는 96줄입니다. 길어질수록 에이전트가 중요한 규칙을 놓치기 쉬우니, 세부 사항은 다른 문서로 빼고 경로만 적는 편이 낫습니다.
템플릿을 받아 쓰면 되나요?
틀은 참고만 하고, 그 저장소에서 에이전트가 실제로 틀린 것을 적습니다. 첫 판은 짧게 시작하고 에이전트가 실수할 때마다 한 줄씩 늘리는 것을 권합니다.
이 글은 SugarMount가 직접 측정한 값으로 쓰고, 초안 작성에 AI 코딩 에이전트를 썼습니다.
다른 AX 노트
- Claude 세션 여러 개가 한 저장소를 고칠 때: 머지 13개로 확인한 파일 주인 표
- 설계 3안을 심사자 3명이 채점했다: 시장 심사자 혼자였다면 카톡 열기마다 죽는 안이 1위였다
- Co-Authored-By 트레일러 없는 커밋, 확인한 29개 중 26개는 에이전트가 만들었다
- AI 마케터를 하루 4번 예약 실행하며 정한 권한 표: 돈·계정·정책은 사람이 누른다
- Android assets를 미리 gzip한 실측: APK 이득은 0, .pack.gz는 .pack이 되어 FileNotFoundException
- SKT 판매 삼성 폰에서 market://을 열면 스토어 선택 창이 뜬다: Play 패키지부터 지정하기