AGENTS.md는 코딩 에이전트가 저장소 작업을 시작할 때 읽는 프로젝트 지침 파일이다. 빌드·테스트 명령, 금지 경로, 완료 기준처럼 매 작업마다 반복 설명해야 하는 것을 한 곳에 적어 두는 용도다. 여러 도구가 같은 파일 이름을 읽기 시작하면서 사실상 공통 진입점이 됐다.
이 글은 파일을 "어디에 두느냐"보다 "무엇을 적느냐"에 초점을 둔다. 경험상 지침 파일의 효과는 길이에 반비례하고, 검증 가능한 문장의 비율에 비례한다.
처음 이 파일을 만들면 대부분 비슷한 실수를 한다. 나도 그랬다. 아키텍처 개요를 쓰고, 팀의 코드 리뷰 문화를 설명하고, 도메인 용어집을 붙였다. 결과는? 에이전트는 여전히 npm과 pnpm을 섞어 썼고, 생성 파일을 손으로 고쳤다. 정작 필요한 건 세 줄이었다. "패키지 매니저는 pnpm", "src/generated는 편집 금지", "커밋 전 pnpm test --run".
효과가 있는 것과 없는 것
| 분류 | 예시 | 효과 |
|---|---|---|
| 명령 | pnpm test --run, make lint | 매우 높음 — 그대로 실행된다 |
| 금지선 | "prisma/migrations 수정 금지" | 높음 — 위반 여부가 명확 |
| 완료 기준 | "테스트와 린트 통과 시 완료" | 높음 — 작업 종료 판단이 바뀐다 |
| 프로젝트 함정 | "개발 서버는 3000 고정, 재사용할 것" | 중간 — 반복 실수를 막는다 |
| 코딩 스타일 서술 | "가독성을 중시합니다" | 낮음 — 판단 기준이 모호 |
| 아키텍처 설명 | "계층형 아키텍처를 따릅니다" | 낮음 — 코드를 읽으면 알 수 있다 |
판단 기준 하나면 충분하다. "이 문장을 지켰는지 기계적으로 확인할 수 있는가?" 확인할 수 없는 문장은 대개 지켜지지도 않는다.
기본 뼈대
# AGENTS.md
## 명령
- 설치: pnpm install --frozen-lockfile
- 개발 서버: pnpm dev (포트 3000 고정, 이미 떠 있으면 재사용)
- 테스트: pnpm test --run
- 타입 체크: pnpm typecheck
- 린트: pnpm lint --fix
## 규칙
- 패키지 매니저는 pnpm 고정. npm/yarn 사용 금지.
- src/generated/** 는 코드 생성 산출물. 직접 편집 금지.
- prisma/migrations/** 는 수정하지 말 것. 스키마 변경은 새 마이그레이션 생성.
- 의존성 추가는 별도 커밋으로 분리하고 이유를 커밋 메시지에 남길 것.
## 완료 기준
작업은 다음이 모두 통과해야 끝난 것으로 본다.
1. pnpm typecheck
2. pnpm test --run
3. pnpm lint
## 함정
- .env 는 커밋 금지. 새 변수는 .env.example 에도 추가할 것.
- 테스트는 DB를 실제로 쓴다. 병렬 실행 시 포트 충돌 주의.모노레포에서의 배치
패키지마다 빌드 방식이 다르면 루트 파일 하나로는 부족하다. 계층적으로 두되, 하위 파일은 루트와 다른 부분만 적는다. 전체를 복사해 두면 반드시 어긋난다.
repo/
├── AGENTS.md # 공통: 패키지 매니저, 커밋 규칙, 완료 기준
├── apps/
│ ├── web/AGENTS.md # 이 앱만의 명령: pnpm --filter web dev
│ └── api/AGENTS.md # DB 마이그레이션 절차 등
└── packages/
└── ui/AGENTS.md # 스토리북 실행, 시각 회귀 테스트하위 파일에는 "루트 지침을 따르되, 이 패키지에서는 X가 다르다" 형태로 적는 게 좋다. 중복을 줄이면 갱신 누락도 줄어든다.
여러 도구를 함께 쓸 때 — 파일 동기화
도구마다 읽는 파일 이름이 다를 수 있다. 내용이 같다면 파일을 나누지 말고 링크로 묶는 게 정석이다. 가장 단순한 건 심볼릭 링크다.
# 방법 1: 심볼릭 링크 (가장 단순, 내용 원본은 하나)
ln -s AGENTS.md CLAUDE.md
# 방법 2: 얇은 참조 파일
echo "프로젝트 지침은 AGENTS.md 를 따른다." > CLAUDE.md
# 방법 3: CI에서 드리프트 검사
# 두 파일이 다르면 실패시켜 갱신 누락을 막는다
if ! diff -q AGENTS.md CLAUDE.md >/dev/null 2>&1; then
echo "AGENTS.md 와 CLAUDE.md 가 다릅니다"; exit 1
fi심볼릭 링크는 윈도우 환경이나 일부 CI에서 문제가 될 수 있으니, 팀 환경에 맞춰 고르면 된다. 어떤 방법이든 원본은 하나라는 원칙만 지키면 된다.
지침이 지켜지는지 확인하는 법
지침 파일은 쓰고 나서 방치되기 쉽다. 프로젝트가 바뀌었는데 파일은 6개월 전 명령을 가리키고 있는 경우가 흔하다. 검증 루프를 만들어 두면 이 문제가 줄어든다.
마지막 원칙이 핵심이다. 겪은 문제만 적는다. 상상으로 쓴 규칙은 대개 불필요하고, 파일만 길어지게 만든다.
안 적으면 손해 보는 항목들
보안 관점에서 한 가지
지침 파일은 저장소에 있는 텍스트이고, 에이전트가 읽는다. 즉 저장소에 쓰기 권한이 있는 사람은 에이전트의 동작에 영향을 줄 수 있다. 외부 기여를 받는 공개 저장소라면 이 파일의 변경을 리뷰 대상으로 명확히 하고, 포크의 PR에서 온 지침 파일이 자동으로 적용되지 않도록 하는 워크플로 설계가 필요하다.
자주 묻는 질문
AGENTS.md에는 무엇을 적어야 하나요?
빌드·테스트·린트 명령, 패키지 매니저 지정, 편집 금지 경로, 완료 기준, 프로젝트 고유의 함정을 적습니다. 기준은 "지켰는지 기계적으로 확인할 수 있는가"이며, 확인할 수 없는 서술형 문장은 효과가 거의 없습니다.
파일이 길면 안 되나요?
길수록 뒷부분이 흐려집니다. 한 화면 분량을 권장하며, 상세 설명이 필요하면 별도 문서로 분리하고 링크만 남기세요. 추가보다 삭제를 정기적으로 하는 편이 품질 유지에 효과적입니다.
모노레포에서는 어떻게 두나요?
루트에 공통 지침을 두고, 패키지별로 다른 부분만 하위 AGENTS.md에 적습니다. 전체 내용을 복사해 두면 갱신 누락으로 반드시 어긋나므로 차이점만 기술하세요.
CLAUDE.md와 AGENTS.md를 둘 다 둬야 하나요?
내용이 같다면 심볼릭 링크나 얇은 참조 파일로 묶어 원본을 하나로 유지하세요. 파일을 따로 관리하면 내용이 갈라지고, 어느 쪽이 적용됐는지 추적하기 어려워집니다.
지침이 오래돼 틀린 내용이 되는 문제는요?
CI에서 파일에 적힌 명령을 실제로 실행해 유효성을 검사하고, 분기마다 낡은 항목을 삭제하세요. 또한 새 규칙은 실제로 문제가 반복될 때만 추가하면 파일이 불필요하게 자라지 않습니다.
공개 저장소에서 보안 위험은 없나요?
지침 파일은 에이전트 동작에 영향을 주므로, 쓰기 권한이 있는 사람이 동작을 바꿀 수 있습니다. 외부 기여를 받는 저장소라면 이 파일 변경을 명시적 리뷰 대상으로 삼고, 포크 PR의 지침이 자동 적용되지 않도록 워크플로를 구성하세요.
댓글 0