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
• Claude Code (v2.1.277부터)
• Cursor AI
• Windsurf
• Google Jules
• Aider
• Cline
• Roo-Code
• Zed, Warp 등

코드를 짜는 에이전트만 이 파일을 읽는 것도 아닙니다. Codex는 GitHub PR을 리뷰할 때 AGENTS.md의 ## Code Review Rules 섹션을 리뷰 기준으로 쓰는데요. 이 활용법은 Codex 코드 리뷰에서 따로 다뤘습니다.

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

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

그러다 2026년 9월에 나온 Claude Code v2.1.277부터 드디어 AGENTS.md를 직접 읽기 시작했습니다. 작업 디렉토리부터 루트까지 거슬러 올라가는 경로 어디에도 CLAUDE.md가 없으면 AGENTS.md를 프로젝트 지침으로 로드하는 방식이라, AGENTS.md만 있는 저장소에서는 별도 설정 없이 바로 동작합니다. 두 파일이 모두 있을 때는 기본적으로 CLAUDE.md만 읽는데, 이 동작은 /config의 Project instructions 항목에서 바꿀 수 있습니다.

그렇다고 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는 여러 회사가 함께 만든 오픈 스탠다드라서 Claude Code를 포함한 20개 이상의 도구에서 지원하지만, CLAUDE.md는 Claude Code에서만 사용할 수 있습니다. 이제 Claude Code도 AGENTS.md를 읽으니 특별한 이유가 없다면 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를 “단일 진실 소스(single source of truth)“로 사용하는 것입니다. 모든 프로젝트 컨텍스트 정보를 AGENTS.md에 작성하고, CLAUDE.md는 아예 만들지 않는 거죠. Claude Code v2.1.277부터는 작업 디렉토리부터 루트까지 거슬러 올라가는 경로 어디에도 CLAUDE.md(또는 .claude/CLAUDE.md, CLAUDE.local.md)가 없으면 AGENTS.md를 프로젝트 지침으로 읽습니다. 세션을 시작하면 no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md 같은 안내가 뜨는 것으로 확인할 수 있어요.

기존에 CLAUDE.md만 있던 프로젝트라면 파일 이름만 바꾸면 됩니다:

mv CLAUDE.md AGENTS.md

이제 AGENTS.md 파일 하나만 관리하면 Claude Code도, Cursor나 GitHub Copilot을 사용하는 팀원들도 같은 내용을 읽습니다.

Claude Code에만 해당하는 지시가 따로 필요하다면 CLAUDE.md를 만들되, 내용을 복사하는 대신 @ 임포트 문법으로 AGENTS.md를 불러옵니다:

@AGENTS.md

## Claude Code 전용

- `src/billing/` 아래를 수정할 때는 플랜 모드를 사용하세요.

여기서 한 가지 주의할 점이 있습니다. CLAUDE.md가 생기는 순간 Claude Code는 기본적으로 CLAUDE.md만 읽고 AGENTS.md는 건너뜁니다. 그래서 CLAUDE.md를 둘 거라면 위처럼 반드시 @AGENTS.md로 임포트해야 하고요. 개인용으로 쓰는 CLAUDE.local.md도 같은 취급을 받기 때문에, AGENTS.md만 쓰는 프로젝트에 개인 메모용 CLAUDE.local.md를 하나 추가했다가 AGENTS.md가 조용히 빠지는 일이 생길 수 있습니다. 이럴 땐 /config에서 Project instructions를 claude-md-and-agents-md로 바꾸면 두 파일을 모두 읽습니다. 설정값의 의미와 Claude Code 쪽 세부 동작은 CLAUDE.md 작성 가이드에서 정리해두었습니다.

예전에 널리 쓰이던 심볼릭 링크 방식(ln -s AGENTS.md CLAUDE.md)도 여전히 동작은 합니다. 다만 이제는 굳이 만들 이유가 없고, Windows에서는 관리자 권한이 필요한 데다 Git이 core.symlinks 없이 체크아웃하면 링크가 한 줄짜리 일반 파일로 풀려버리는 문제도 있습니다. 새로 설정한다면 AGENTS.md만 두거나 @AGENTS.md 임포트를 쓰는 편이 낫습니다. Amazon Bedrock이나 Vertex AI 같은 서드파티 프로바이더로 Claude Code를 쓰는 경우처럼 AGENTS.md 직접 읽기가 아직 지원되지 않는 환경이라면, @AGENTS.md 임포트가 있는 CLAUDE.md를 함께 두면 됩니다.

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              # 루트 레벨, 전체 프로젝트 공통 규칙
├── packages/
│   ├── frontend/
│   │   └── AGENTS.md      # 프론트엔드 특화 규칙
│   └── backend/
│       └── AGENTS.md      # 백엔드 특화 규칙

대부분의 AI 코딩 에이전트들은 “가장 가까운” AGENTS.md를 우선적으로 읽습니다. frontend 패키지에서 작업할 때는 frontend/AGENTS.md를 읽고, 거기에 없는 내용은 상위의 루트 AGENTS.md를 참조하는 식입니다. Claude Code도 세션 시작 시 작업 디렉토리와 상위 디렉토리의 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까지 AGENTS.md를 직접 읽게 되면서 범용성 면에서 AGENTS.md를 마다할 이유가 사라졌거든요. Claude Code 전용 지시가 필요할 때만 @AGENTS.md를 임포트하는 CLAUDE.md를 곁들이고, Aider를 쓴다면 CONVENTIONS.md를 추가하면 됩니다. 그러면 나중에 다른 AI 코딩 에이전트를 시도해보고 싶을 때 훨씬 유연하게 대응할 수 있을 겁니다.

AGENTS.md는 이제 업계 표준으로 자리잡았습니다. GitHub Copilot이 2025년 8월에 공식 지원을 시작했고, 자체 형식을 고수하던 Claude Code도 2026년 9월에 합류했습니다. 커뮤니티의 요구가 그만큼 강했던 거죠.

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

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