본문으로 건너뛰기

요즘은 Cursor, Claude Code, GitHub Copilot처럼 레포 안에서 바로 코드를 고쳐 주는 도구를 많이 씁니다. 그런데 새 세션을 열 때마다 “테스트는 이 명령”, “이 폴더에 두면 안 된다”, “이미 lodash 쓰고 있다” 같은 말을 반복하기 지치죠. 그래서 프로젝트 루트에 에이전트가 먼저 읽게 할 한 장짜리 안내를 두는 패턴이 퍼졌고, 그중에서 이름이 잘 고정된 쪽이 AGENTS.md입니다.

이 글에서는 AGENTS.md를 왜 두는지, README·CLAUDE.md와 어떻게 나누는지, 레포에선 어떻게 쓰는지까지 한번에 정리합니다.

1. AGENTS.md 한 줄 요약​

  • AGENTS.md는 에이전트용 README로 비유합니다.
  • 사람이 읽는 README.md에 넣기 애매한 빌드·테스트·팀 규칙을, 에이전트가 매번 같은 실수를 덜 하도록 한곳에 모아 두는 마크다운 파일입니다.
  • 스키마나 필수 필드는 없고, 그냥 마크다운입니다.

2. README와 AGENTS.md의 차이​

  • README.md는 보통 왜 이 프로젝트가 있는지, 설치·빠른 시작, 기여 방법, 라이선스처럼 사람에게 말하는 글에 가깝습니다.
  • AGENTS.md에는 에이전트가 코드를 쓰거나 고칠 때마다 참고해야 할 것을 적습니다.
  • 예를 들면 다음과 같은 내용을 적습니다.
    • 빌드·테스트·린트 명령
    • 디렉터리 구조나 “여기에 테스트 두지 마라” 같은 제약
    • 코드 스타일·금지 패턴
    • PR 제목 규칙, 배포 전 체크리스트
    • 보안상 주의할 점
  • 같은 내용을 README에 이미 친절하게 풀어 썼다면, AGENTS.md에 복붙하지 말고 README로 링크만 거는 편이 낫습니다.
  • 한곳만 진짜 본문으로 두고 나머지는 가리키면, 나중에 어긋나는 일이 줄어듭니다.

3. 왜 굳이 파일 이름까지 정했나​

  • 에이전트 도구마다 예전에는 제각각이었습니다.
  • Claude Code는 CLAUDE.md, Cursor는 .cursor/rules/, Copilot은 .github/copilot-instructions.md, Windsurf는 .windsurfrules처럼 경로도 이름도 달랐죠.
  • 팀에서 쓰는 도구가 두 가지 이상이면, 같은 규칙을 여러 포맷으로 복제해야 하고, 컨벤션이 바뀔 때마다 여러 파일을 같이 고쳐야 하는 부담이 생깁니다.
  • 그래서 “에이전트에게 줄 프로젝트 안내는 **레포 루트의 AGENTS.md**에 두자”는 식의 관습이 생겼고, 그 이름을 agents.md가 공개 포맷으로 한 번 더 고정해 준 셈입니다.
  • 벤더마다 독점 포맷을 하나 더 늘리자는 취지라기보다, 열린 이름으로 맞추자는 쪽에 가깝습니다.

4. 어디에 두고, 뭐를 적나​

4.1 위치​

  • 기본은 저장소 루트입니다.
  • 모노레포면 패키지마다 AGENTS.md를 또 두는 식으로 가까운 쪽이 우선하는 패턴이 흔합니다.
  • 충돌이 나면 지금 편집 중인 파일에 가까운 AGENTS.md 쪽이 더 먼 루트의 AGENTS.md보다 앞섭니다.
  • 채팅으로 이번 세션에서 직접 시킨 말은 AGENTS.md에 적어 둔 규칙보다 우선한다고 보면 됩니다.

4.2 목차 예시​

목차는 레포마다 다르지만, 저는 보통 아래 정도를 뼈대로 잡습니다.

  • 프로젝트 개요
  • 빌드·테스트 명령
  • 코드 스타일
  • 테스트 방법
  • 보안 고려

여기에 커밋 메시지 규칙·배포 절차·데이터셋 위치처럼 신입에게 구두로 넘기던 것을 그대로 붙이기도 합니다.

4.3 짧은 샘플​

# 이 레포에서 에이전트가 알아야 할 것

## 명령

- 의존성: `pnpm install`
- 개발: `pnpm dev`
- 테스트: `pnpm test`

## 스타일

- TypeScript strict
- 새 기능은 테스트와 같이

실제 레포에서는 CI 경로, 패키지 이름 규칙, “절대 any 쓰지 말 것” 같은 자주 틀리는 지점만 콕 집어 적는 쪽이 효과가 큽니다. 길게 베끼는 것보다 짧고 자주 고치는 쪽이 운영하기 편합니다.

5. CLAUDE.md와의 관계​

  • CLAUDE.md는 Claude Code가 프로젝트에서 익숙하게 쓰는 컨텍스트 파일입니다.
  • /init으로 초안을 만들거나, ~/.claude/CLAUDE.md에 모든 프로젝트에 공통으로 쓸 규칙을 두는 식의 워크플로와 잘 맞습니다.
  • AGENTS.md는 여러 에이전트·IDE가 같이 볼 수 있는 쪽에 두는 경우가 많습니다.
  • 팀원이 Cursor와 Copilot과 Claude Code를 섞어 쓰면, 범용 파일 하나를 기준으로 맞추는 편이 덜 꼬입니다.

5.1 둘 다 쓰고 싶을 때​

  • 한 레포에 Claude Code 사용자와 다른 도구 사용자가 같이 있으면, 규칙을 두 벌로 유지하기에는 관리가 어렵습니다.
  • 이럴 때는 흔히 이렇게 합니다.
  1. 내용은 전부 AGENTS.md에만 적는다.
  2. CLAUDE.md는 AGENTS.md를 가리키게 한다.

macOS·Linux에서는 예를 들어 다음과 같이 링크를 둘 수 있습니다.

mv CLAUDE.md AGENTS.md   # 이미 CLAUDE.md만 있었다면 이름만 바꿔도 됨
ln -s AGENTS.md CLAUDE.md