AGENTS.md는 AI 코딩 에이전트가 작업 전에 읽는 프로젝트 안내서다. 사람이 읽는 README와 따로 두고 빌드·테스트 명령, 코드 규칙, 금지 사항을 적는다. 공개 형식이라 Codex를 비롯한 여러 에이전트가 같은 파일을 읽고 같은 규칙을 따른다.
| 파일 | 누가 읽나 | 담는 내용 |
|---|---|---|
| README.md | 사람 | 프로젝트 소개, 설치 방법 |
| AGENTS.md | 여러 AI 에이전트 | 명령어, 작업 규칙, 금지 사항 |
| CLAUDE.md | Claude Code | AGENTS.md와 비슷한 지침 |
리포지토리 루트에 AGENTS.md를 만들고 평범한 마크다운으로 쓰면 된다. 꼭 넣어야 하는 항목은 정해져 있지 않다. 모노레포처럼 영역마다 규칙이 다르면 하위 폴더에 따로 둔다. 에이전트는 작업 중인 파일에서 가장 가까운 AGENTS.md를 먼저 따른다.
AGENTS.md를 지원하는 도구는 따로 설정하지 않아도 알아서 읽는다. Claude Code처럼 다른 이름의 지침 파일을 쓰는 도구도 함께 쓴다면, CLAUDE.md 안에서 @AGENTS.md로 불러와 내용을 한 곳에서만 관리하는 게 편하다.
에이전트가 가장 자주 찾는 건 실제로 실행할 명령이다. "테스트를 잘 하라" 같은 막연한 말보다 그대로 복사해 쓸 수 있는 명령과 짧은 예시가 훨씬 잘 먹힌다.
| 항목 | 이렇게 적는다 |
|---|---|
| 빌드·테스트 | 커밋 전에 npm test 실행 |
| 코드 스타일 | 커밋 메시지는 Conventional Commits 형식 |
| 작업 흐름 | PR은 feature/ 브랜치에서 올린다 |
| 금지 사항 | 비밀 키·배포 설정 파일은 건드리지 않는다 |
길게 쓴다고 좋아지지 않는다. 파일 내용은 작업할 때마다 컨텍스트에 들어가서 자리를 차지하고, 내용이 많으면 중요한 규칙이 묻힌다. 꼭 지켜야 할 것만 짧게 적고, 긴 문서는 위치만 알려 주면 된다.
AGENTS.md는 안내일 뿐 규칙을 강제하지는 못한다. 에이전트가 가끔 어길 수 있으니 테스트·린트·권한 설정처럼 실제로 막아 주는 장치와 함께 쓴다. 코드가 바뀌면 이 파일도 같이 고쳐야 에이전트가 낡은 규칙을 따르지 않는다.
가장 흔한 건 에이전트에게 일을 맡길 때마다 되풀이하던 설명을 리포에 한 번 적어 두는 방식이다. 이렇게 해 두면 프롬프트마다 명령과 규칙을 붙여 넣지 않아도 된다.
| 어디서 | 어떻게 쓰나 |
|---|---|
| 코딩 에이전트 작업 | 기능 구현·버그 수정을 맡기기 전에 테스트 명령을 적어 두고, 끝나면 에이전트가 직접 테스트를 돌리게 한다 |
| 여러 도구를 함께 쓰는 팀 | 규칙은 AGENTS.md 한 곳에만 쓰고, CLAUDE.md 같은 파일은 이 파일을 불러오게 한다 |
| 모노레포 | 루트에는 공통 규칙, 패키지 폴더마다 그 영역의 빌드 명령과 규칙을 둔다 |
| 오픈소스 프로젝트 | 리포에 함께 커밋해서 기여자가 쓰는 에이전트도 같은 규칙을 따르게 한다 |