AGENTS.md와 CLAUDE.md 차이, 멀티 에이전트 규칙을 맞추려면

여러 AI 코딩 어시스턴트를 함께 쓸 때는 AGENTS.md CLAUDE.md 규칙 파일을 어떻게 설정하고, 한 레포지토리 안에서 내용을 맞춰야 할지가 문제가 됩니다. 이 글은 공식 문서를 기준으로 두 파일의 역할 차이, 동기화 방법, 충돌 시 우선순위만 다룹니다.

이 글은 현재 공식 문서를 기준으로 작성되었으며, 각 도구의 정책은 이후 업데이트에 따라 달라질 수 있습니다.

AGENTS.md와 CLAUDE.md는 역할이 어떻게 다르나?

한 줄 답: AGENTS.md는 여러 에이전트가 공통으로 읽는 범용 마크다운 규칙 파일이고, CLAUDE.md는 Claude Code 전용 설정 파일입니다.

  • AGENTS.md는 agents.md 스펙을 따르는 크로스 에이전트 마크다운 컨벤션으로, 에이전트를 위한 README 역할을 합니다. 루트뿐 아니라 하위 폴더에도 중첩해서 둘 수 있습니다.
  • Cursor도 .cursor/rules 대신 평문 마크다운인 AGENTS.md를 읽을 수 있습니다. 다만 이 글에서는 .mdc 규칙 파일 작성법은 다루지 않습니다.
  • Claude Code는 기본적으로 AGENTS.md를 자동으로 읽지 않고, CLAUDE.md만 읽습니다.

한 레포에서 내용을 어떻게 맞추나?

한 줄 답: CLAUDE.md 안에 @AGENTS.md를 적어 실시간으로 불러오는 방식이 가장 권장됩니다.

  • CLAUDE.md를 만들고 맨 위에 @AGENTS.md 임포트 구문을 적은 뒤, 그 아래에 Claude 전용 설정을 추가합니다. 이 방식은 두 파일이 시간이 지나도 어긋나지 않도록 실시간으로 동기화됩니다.
  • ln -s AGENTS.md CLAUDE.md 같은 심볼릭 링크도 가능하지만, Windows에서는 관리자 권한이나 개발자 모드가 필요할 수 있어 @AGENTS.md 임포트가 더 간편합니다.
  • v2.1.213 이상부터 제공되는 /import 명령은 내용을 1회성으로 복사하기 때문에, 시간이 지나면서 두 파일 내용이 어긋날(drift) 수 있습니다. 지속적인 동기화가 필요하다면 실시간 임포트 방식을 우선하는 것이 좋습니다.

충돌이 나면 어떤 파일을 우선하나?

한 줄 답: 각 도구는 공식 문서에 정리된 규칙을 따르며, 도구와 무관하게 사용자가 채팅으로 입력한 프롬프트가 모든 파일 규칙보다 우선합니다.

  • Claude Code는 CLAUDE.md와 그 안에 명시된 임포트 내용만 따릅니다.
  • AGENTS.md 생태계(Cursor 포함)에서는 수정 중인 파일과 가장 가까운(closest) AGENTS.md가 우선합니다. 여러 단계로 중첩되어 있다면 더 구체적인 하위 경로의 파일이 결합되어 적용됩니다.
  • 파일에 어떤 내용이 있든, 사용자가 채팅으로 직접 입력한 프롬프트가 항상 최우선으로 적용되어 모든 규칙을 덮어씁니다.

두 파일이 서로 임포트하지 않고 동시에 존재하는 경우, 도구를 넘나드는 하나의 통일된 우선순위가 공식적으로 정해져 있지는 않습니다. 이 글은 각 도구가 공식 문서에서 밝힌 방식만 정리했습니다.

FAQ

Claude Code는 AGENTS.md를 아예 못 읽습니까?

환경변수 CLAUDE_CODE_NEW_INIT=1이 설정된 경우, /init 실행 시 AGENTS.md를 읽을 수 있습니다.

Cursor에서 .cursor/rules 대신 AGENTS.md만 써도 됩니까?

네, 가능합니다. Cursor는 루트 및 중첩된 평문 마크다운 AGENTS.md 파일을 읽습니다.

윈도우에서 심볼릭 링크를 써도 됩니까?

가능하지만 관리자 권한이 필요할 수 있어, 대부분의 경우 @AGENTS.md 임포트가 더 간편합니다.

출처