AI를 위한 프로젝트 안내서: AGENTS.md와 CLAUDE.md

요즘 Cursor나 Claude Code, Codex와 같은 AI 도구로 소프트웨어 개발을 많이 하시죠?

그런데 AI 에이전트에게 코딩을 시키다 보면 프로젝트에 대한 전반적인 지식이 부족하여 엉뚱하게 작업을 진행할 때가 있습니다. 예를 들어, 테스트 파일을 엉뚱한 위치에 생성하거나, 프로젝트의 코딩 컨벤션을 무시하거나, 마음대로 이미 쓰고 있는 라이브러리랑 비슷한 기능을 하는 다른 라이브러리를 설치해버리는 식이죠. 이럴 때는 AI 에이전트에게 좀 더 구체적으로 작업 방향을 알려줄 수 있지만, 새로운 대화 세션을 시작할 때마다 동일한 내용을 반복적으로 알려주는 것은 매우 피곤한 일입니다.

이런 문제를 해결하려면 AI 에이전트에게 프로젝트에 대한 컨텍스트를 미리 알려줘야 합니다. 그래서 등장한 것이 바로 AGENTS.md와 CLAUDE.md 같은 컨텍스트 파일입니다. 이 글에서는 이 파일들이 무엇인지, 어떻게 작성하고 관리하는지 알아보겠습니다.

다양한 컨텍스트 관리 방법

최근 AI 코딩 에이전트들이 우후죽순 등장하면서, 개발자들은 Claude Code, Cursor, GitHub Copilot, Windsurf 같은 다양한 도구들을 프로젝트에 활용하고 있습니다. 그런데 각 도구마다 프로젝트 컨텍스트를 전달하는 방식이 달라서 골칫거리가 생겼습니다. 예를 들어, Claude Code는 CLAUDE.md를, Cursor는 .cursor/rules/ 디렉토리를, GitHub Copilot은 .github/copilot-instructions.md, Windsurf는 .windsurfrules를 사용하죠.

예를 들어 Claude Code 사용자가 CLAUDE.md에 프로젝트 컨텍스트를 정리해뒀다고 해봅시다. 그런데 팀원 중 누군가가 Cursor를 선호한다면 어떻게 될까요? Cursor는 CLAUDE.md를 자동으로 읽지 않기 때문에, 똑같은 내용을 담은 규칙 파일을 .cursor/rules/ 디렉토리에 별도로 만들어야 합니다. 이렇게 도구마다 파일을 따로 관리하다 보면 내용이 중복되고, 프로젝트 구조가 바뀌거나 새로운 컨벤션이 추가될 때마다 여러 파일을 일일이 수정해야 하는 번거로움이 생깁니다.

AGENTS.md

이런 문제를 해결하기 위해 AI 코딩 에이전트들 간의 표준을 만들자는 움직임이 시작되었습니다. 그 결과물이 바로 AGENTS.md입니다.

AGENTS.md는 “에이전트를 위한 README”라고 불리는데요. README.md가 사람을 위한 프로젝트 안내서라면, AGENTS.md는 AI 에이전트를 위한 프로젝트 안내서인 셈이죠.

2025년 7월, OpenAI, Google(Jules), Cursor, Factory AI, Sourcegraph 등 주요 AI 코딩 에이전트 개발사들이 모여 이 표준을 만들었습니다. 특정 회사나 도구에 종속되지 않는 오픈 스탠다드를 지향하기 때문에, 어떤 AI 코딩 에이전트를 사용하든 하나의 파일로 프로젝트 컨텍스트를 공유할 수 있습니다.

현재 GitHub에는 2만 개 이상의 오픈소스 프로젝트가 AGENTS.md를 사용하고 있으며, 그 수는 빠르게 증가하는 추세입니다. OpenAI가 agents.md 도메인을 인수해서 공식 문서를 호스팅하고 있을 정도로 업계의 관심이 높습니다.

AGENTS.md를 지원하는 도구들은 다음과 같습니다:

• GitHub Copilot
• Cursor AI
• Windsurf
• Google Jules
• Aider
• Cline
• Roo-Code
• Zed, Warp 등

AGENTS.md의 형식은 매우 단순합니다. 그냥 일반 마크다운 파일이고, 엄격한 스키마나 필수 필드 같은 것이 없습니다. 프로젝트의 필요에 따라 자유롭게 구성할 수 있죠. 일반적으로는 다음과 같은 내용들이 포함됩니다:

# 프로젝트 이름

## 개발 환경

프로젝트 루트에서 `npm install`을 실행하세요.
Node.js 18 이상이 필요합니다.

## 테스트

테스트는 `npm test`로 실행할 수 있습니다.
새로운 기능을 추가할 때는 반드시 테스트 코드를 함께 작성해주세요.

## 코드 스타일

- TypeScript strict 모드를 사용합니다
- 함수형 컴포넌트를 선호합니다
- 200줄이 넘는 파일은 분리를 고려하세요

## 주요 명령어

- 개발 서버: `npm run dev`
- 프로덕션 빌드: `npm run build`
- 타입 체크: `npm run typecheck`

이렇게 작성해두면 어떤 AI 코딩 에이전트를 사용하든 프로젝트에 대한 기본적인 이해를 가지고 코드를 생성하거나 수정할 수 있습니다. agents.md 공식 문서에서 권장하는 작성 방법은 뒤에서 자세히 다루겠습니다.

CLAUDE.md

이 글을 작성하고 있는 2025년 10월 현재 Claude Code는 AGENTS.md를 공식적으로 지원하지 않습니다. 대신 CLAUDE.md라는 자체 파일 형식을 사용하죠.

이에 대한 커뮤니티의 불만이 적지 않아서, Claude Code의 GitHub 저장소에 올라온 관련 이슈에는 1000개가 넘는 👍 반응이 달려 있습니다. 많은 개발자들이 CLAUDE.md는 Claude Code에만 특화되어 있어서, 다른 도구를 사용하는 팀원들과 협업할 때 불편하다고 지적하고 있죠.

하지만 Claude Code의 CLAUDE.md도 나름의 장점이 있습니다. 홈 폴더(~/.claude/CLAUDE.md)에 사용자 수준의 설정을 둘 수 있어서, 모든 프로젝트에 공통으로 적용할 규칙을 한 곳에서 관리할 수 있습니다. 또한 Claude Code에서 간편하게 /init 커맨드를 실행하면 코드베이스를 분석해서 CLAUDE.md를 자동으로 생성해줍니다. CLAUDE.md의 위치별 스코프, .claude/rules/ 규칙 파일, @ 임포트 문법 등 상세한 내용은 CLAUDE.md 작성 가이드에서 다루고 있습니다.

아무래도 CLAUDE.md는 Claude Code를 위한 전용 파일이기 때문에 다른 AI 에이전트에는 없는 Claude Code의 특화 기능에 대한 내용도 담을 수 있습니다. 예를 들어, 특정 서브에이전트를 사용하는 방법, Claude에 최적화된 프롬프트, AGENTS.md를 참조하는 지시사항 같은 것들이죠.

Anthropic의 공식 문서에 따르면, CLAUDE.md에는 일반적인 bash 명령어, 핵심 파일 경로, 코드 스타일 가이드라인, 테스트 방법, 레포지토리 컨벤션 등을 포함하라고 권장합니다. 그리고 “간결하고 사람이 읽기 쉽게” 작성하되, “자주 사용하는 프롬프트처럼 반복적으로 다듬어 가라”고 조언합니다.

AGENTS.md와 CLAUDE.md의 가장 큰 차이는 호환성입니다. AGENTS.md는 여러 회사가 함께 만든 오픈 스탠다드라서 20개 이상의 도구에서 지원하지만, CLAUDE.md는 Claude Code에서만 사용할 수 있습니다. 팀원들이 서로 다른 AI 코딩 에이전트를 쓴다면 AGENTS.md가 유리하고, 모두가 Claude Code만 쓴다면 CLAUDE.md도 괜찮습니다. 두 파일을 동시에 사용하는 방법은 뒤에서 자세히 다루겠습니다.

README.md

README.md는 사람을 위한 문서, AGENTS.md는 AI를 위한 문서라고 하지만, 막상 두 문서를 어떻게 구분해서 작성해야 할지 헷갈릴 수 있습니다.

AGENTS.md는 “AI 에이전트가 코드를 작성하거나 수정할 때 항상 감안해야 하는 정보”에 집중해야 합니다. 프로젝트 아키텍처 설명, 빌드와 테스트 명령어, 코드 스타일 가이드라인, 테스트 작성 규칙, 보안 고려사항, 개발 환경 설정 방법, Pull Request 컨벤션, 흔한 실수나 주의사항, 사용하는 기술 스택과 버전 정보 등이 여기에 해당합니다.

반면에 README.md는 사람을 위한 문서이기 때문에 일반적으로 좀 더 고수준의 내용을 다룹니다. 프로젝트의 목적과 배경, 일반 사용자를 위한 설치 가이드, 빠른 시작 튜토리얼, 기여 가이드라인, 라이선스 정보 같은 것들은 README.md에 넣습니다.

AGENTS.md에 “빌드 명령어는 npm run build입니다”라고 적었다면, README.md에는 “이 프로젝트를 로컬에서 실행하려면 먼저 Node.js 18을 설치하고, npm install로 의존성을 설치한 다음…” 같은 친절한 설명을 넣는 거죠.

만약에 README.md와 AGENTS.md의 내용에 의미있는 차이가 없는 경우라면, README.md에 이미 있는 내용을 그대로 복사하지 마세요. 대신 README.md로 링크를 걸어주세요.

프로젝트에 대한 설명은 [README.md](./README.md#installation)를 참고하세요.

컨텍스트 파일 생성

이런 컨텍스트 파일들을 처음 만들 때, 빈 파일에서 시작하면 막막할 수 있습니다. 다행히 일부 도구들은 자동 생성 기능을 제공해서 시작을 쉽게 만들어줍니다.

Claude Code는 /init 슬래시 커맨드를 제공합니다. 프로젝트를 처음 열었을 때 /init을 실행하면, Claude Code가 코드베이스 전체를 분석해서 자동으로 CLAUDE.md를 생성해줍니다. package.json, README 파일, 기존의 다른 설정 파일들(.cursorrules, .github/copilot-instructions.md 등)을 찾아서 참고하고, 프로젝트 구조를 파악해서 적절한 내용을 채워 넣습니다. 생성된 파일에는 프로젝트 개요, 기술 스택, 폴더 구조, 개발 컨벤션, 빌드 명령어, 테스트 방법 등이 포함됩니다. 큰 변경이 있을 때마다 다시 /init을 실행해서 내용을 업데이트할 수도 있습니다.

Cursor도 /Generate Cursor Rules 커맨드를 통해서 비슷한 기능을 제공합니다. 채팅 인터페이스에서 이 커맨드를 실행하면 실시간으로 코드베이스를 분석해서 .mdc 형식의 규칙 파일을 .cursor/rules/ 디렉토리에 생성해줍니다. .mdc는 Cursor의 최신 형식으로, YAML frontmatter를 포함한 마크다운 파일입니다. 여기에는 설명, glob 패턴(어떤 파일에 자동으로 적용할지), 항상 적용 여부 등의 메타데이터가 들어갑니다.

GitHub Copilot은 아직 자동 생성 기능을 제공하지 않습니다. 2025년 8월부터 AGENTS.md를 공식 지원하기 시작했지만, 파일은 직접 만들어야 합니다. 대신 Copilot은 다양한 위치에서 설정 파일을 찾을 수 있습니다. 프로젝트 루트의 AGENTS.md, .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, 심지어 조직 레벨의 설정이나 사용자 전역 설정(~/.copilot/agents)까지 지원합니다. CLAUDE.md나 GEMINI.md 파일도 읽어들이는 유연함을 보여줍니다.

Windsurf는 독특한 방식을 사용합니다. 명시적인 /init 같은 커맨드는 없지만, 프로젝트를 스캔해서 여러 위치에 있는 규칙 파일들을 자동으로 발견합니다. .windsurfrules 파일이나 .windsurf/rules/ 디렉토리의 파일들을 찾아서 적용하죠. Cursor의 .cursorrules 형식과 호환되기 때문에, 기존에 Cursor를 사용하던 프로젝트라면 바로 활용할 수 있습니다. Windsurf는 작업 공간당 6,000자, 글로벌 컨텍스트로 추가 6,000자까지 지원합니다.

Aider나 Cline, Roo-Code 같은 도구들은 자동 생성 기능이 없어서 수동으로 파일을 만들어야 합니다. Aider는 CONVENTIONS.md 파일을 선호하는데, /read CONVENTIONS.md 명령어로 읽어들이거나 .aider.conf.yml 설정 파일에 명시할 수 있습니다. Cline은 .clinerules/ 디렉토리를 사용하고, Roo-Code는 v3.24.0부터 AGENTS.md를 지원하기 시작했습니다.

사용하시는 코딩 에이전트에 컨텍스트 파일 자동 생성 기능이 없는 경우에는 커뮤니티에서 제공하는 온라인 도구를 활용할 수 있습니다.

agents.md 공식 웹사이트나 agentsmd.net에서는 프로젝트 타입별로(Next.js, React, Python 등) 다양한 템플릿을 제공합니다. Cursor 사용자라면 cursorrules.org에서 프레임워크를 선택해서 설정 파일을 생성하거나, cursor.directory/generate에서 프로젝트 파일들(package.json, requirements.txt 등)을 업로드해서 자동으로 .mdc 규칙 파일을 만들 수도 있습니다. OpenAI의 공식 agents.md GitHub 저장소에도 예제들이 많으니 참고하면 좋습니다.

AGENTS.md와 CLAUDE.md 함께 쓰기

만약에 한 프로젝트에서 Claude Code를 쓰는 개발자와 쓰지 않는 개발자가 공존한다면 어떻게 해야 할까요? 그러면 AGENTS.md와 CLAUDE.md가 둘 다 필요할 텐데 두 파일을 동시에 관리하려면 상당히 번거로울 것입니다.

가장 추천하는 방법은 AGENTS.md를 “단일 진실 소스(single source of truth)“로 사용하는 것입니다. 모든 프로젝트 컨텍스트 정보를 AGENTS.md에 작성하고, CLAUDE.md는 심볼릭 링크로 만들어서 AGENTS.md를 가리키게 하는 거죠. 이렇게 하면 하나의 파일만 관리하면 되고, Claude Code를 사용할 때도 정상적으로 작동합니다.

macOS나 Linux에서는 다음과 같이 심볼릭 링크를 만들 수 있습니다:

# 기존 CLAUDE.md가 있다면 먼저 AGENTS.md로 이름 변경
mv CLAUDE.md AGENTS.md

# AGENTS.md를 가리키는 심볼릭 링크 생성
ln -s AGENTS.md CLAUDE.md

# .gitignore에 추가 (심볼릭 링크는 변경 추척하지 않음)
echo "CLAUDE.md" >> .gitignore

이제 AGENTS.md 파일 하나만 수정하면 Claude Code도 자동으로 그 내용을 읽습니다. Cursor나 GitHub Copilot을 사용하는 팀원들도 같은 AGENTS.md를 활용할 수 있죠.

Windows에서도 비슷한 방식으로 할 수 있습니다:

# 관리자 권한으로 실행
mklink CLAUDE.md AGENTS.md

만약 심볼릭 링크를 만들기 어렵다면 “참조 방식”을 사용할 수 있습니다. CLAUDE.md 파일을 다음과 같이 간단하게 작성하는 거죠:

./AGENTS.md의 규칙을 따르세요.

이렇게 하면 Claude Code가 CLAUDE.md를 읽을 때 AGENTS.md의 내용도 참조하게 됩니다. 완벽한 방법은 아니지만 (Claude가 한 번 더 파일을 읽어야 하니까요) 동작은 합니다.

Cursor와 Windsurf를 함께 사용한다면 다음과 같이 여러 개의 심볼릭 링크를 만들 수 있습니다:

# Cursor 호환
ln -s AGENTS.md .cursorrules

# Windsurf 호환
mkdir -p .windsurf/rules
ln -s ../../AGENTS.md .windsurf/rules/rules.md

모노레포 환경에서는 계층적 구조를 활용할 수 있습니다. 루트에 전체 프로젝트에 공통으로 적용되는 AGENTS.md를 두고, 각 패키지 디렉토리에는 패키지별 AGENTS.md를 배치하는 거죠:

/
├── AGENTS.md              # 루트 레벨, 전체 프로젝트 공통 규칙
├── CLAUDE.md -> AGENTS.md # 심볼릭 링크
├── packages/
│   ├── frontend/
│   │   └── AGENTS.md      # 프론트엔드 특화 규칙
│   └── backend/
│       └── AGENTS.md      # 백엔드 특화 규칙

대부분의 AI 코딩 에이전트들은 “가장 가까운” AGENTS.md를 우선적으로 읽습니다. frontend 패키지에서 작업할 때는 frontend/AGENTS.md를 읽고, 거기에 없는 내용은 상위의 루트 AGENTS.md를 참조하는 식입니다.

컨텍스트 파일 관리 팁

컨텍스트 파일을 효과적으로 활용하려면 몇 가지 원칙을 지키는 것이 좋습니다.

첫째, 간결하게 유지하세요. 이상적으로는 20~50줄 정도가 좋습니다. 너무 길면 AI가 읽는 데 시간이 오래 걸리고, 컨텍스트 윈도우를 많이 차지합니다. “AI가 자주 틀리는 부분”에 집중해서 작성하세요. 한 번 설명하면 알아서 잘하는 것까지 장황하게 적을 필요는 없습니다.

둘째, 지속적으로 업데이트하세요. 프로젝트는 계속 변합니다. 새로운 라이브러리를 도입하거나, 디렉토리 구조를 바꾸거나, 컨벤션을 수정할 때마다 AGENTS.md도 함께 업데이트해야 합니다. 오래된 정보는 오히려 AI를 혼란스럽게 만들 수 있습니다.

셋째, AI와 작업하면서 반복적으로 개선하세요. “왜 AI가 이 부분을 자꾸 틀리지?”싶은 패턴이 보이면, 그걸 AGENTS.md에 명시적으로 추가합니다. “Don’t 목록”에 “절대로 any 타입을 사용하지 마세요” 같은 규칙을 넣는 거죠. 자주 사용하는 프롬프트를 다듬듯이 AGENTS.md도 계속 다듬어가야 합니다.

넷째, 이미 있는 문서를 복사하지 마세요. README.md, 위키, Confluence 페이지에 이미 잘 정리된 내용이 있다면 링크만 걸어주세요. 같은 내용을 여러 곳에 중복으로 관리하면 나중에 동기화가 깨집니다.

다섯째, 마크다운 서식을 잘 활용하세요. 제목, 불릿 포인트, 넘버링 리스트, 코드 블록 등을 사용하면 AI가 구조를 더 잘 이해합니다. 특히 명령어는 코드 블록으로 감싸주세요.

여섯째, 팀과 공유하세요. AGENTS.md는 git에 커밋해서 팀 전체가 사용할 수 있게 만듭니다. 누군가 새로 프로젝트에 합류했을 때도 AGENTS.md가 있으면 온보딩이 훨씬 빨라집니다. AI뿐만 아니라 사람도 읽을 수 있는 좋은 참고 자료가 되니까요.

마치며

지금까지 프로젝트의 컨텍스트 파일을 통해서 AI 에이전트에게 코딩을 시킬 때 항상 염두에 두어야 하는 정보를 알려주는 방법에 대해서 알아보았습니다.

컨텍스트 파일은 범용성을 원한다면 AGENTS.md를, Claude Code만 사용한다면 CLAUDE.md를, Aider를 쓴다면 CONVENTIONS.md를 선택하면 됩니다. 아무래도 앞으로의 추세를 생각하면 AGENTS.md를 선택하는 것이 안전하겠죠? Claude Code도 함께 사용하는 상황이라면 본 글에서 안내해드린 것처럼 AGENTS.md와 CLAUDE.md를 심볼릭 링크로 연결하시면 됩니다. 그러면 나중에 다른 AI 코딩 에이전트를 시도해보고 싶을 때 훨씬 유연하게 대응할 수 있을 겁니다.

AGENTS.md는 빠르게 업계 표준으로 자리잡고 있습니다. GitHub Copilot이 2025년 8월에 공식 지원을 시작했고, 다른 도구들도 속속 지원을 추가하고 있습니다. Claude Code도 언젠가는 AGENTS.md를 지원할 가능성이 높습니다. 커뮤니티의 요구가 그만큼 강하니까요.

AI 코딩 에이전트를 사용하는 프로젝트에서 컨텍스트 파일은 작은 투자로 큰 효과를 볼 수 있는 모범 관례입니다. 한 번 작성해두면 AI와 작업할 때마다 같은 설명을 반복할 필요가 없고, 팀원들도 일관된 컨텍스트를 공유할 수 있습니다. AI 코딩 에이전트를 사용하기 시작했다면, 지금 바로 프로젝트에 컨텍스트 파일을 추가하셔서 효과를 누리셨으면 좋겠습니다.

AI 에이전트가 서로 소통하는 세상이 궁금하다면 Moltbook: AI 에이전트들의 소셜 네트워크도 흥미로운 읽을거리가 될 겁니다.