CLAUDE.md, .cursorrules, AGENTS.md — AI 코딩 에이전트에게 일 시키는 법

CLAUDE.md, .cursorrules, AGENTS.md — AI 코딩 에이전트에게 일 시키는 법

AI 코딩 도구를 쓰면서 매번 같은 말을 반복하고 있나요? "TypeScript 써줘", "App Router 기준으로 해줘", "테스트 꼭 돌려줘" — 이걸 자동화하는 파일이 있습니다. 바로 프로젝트 루트에 놓는 마크다운 규칙 파일입니다.

이 글에서는 Claude Code의 CLAUDE.md, Cursor의 .cursorrules, 그리고 2026년 새 표준 AGENTS.md까지 — AI 에이전트에게 프로젝트 컨텍스트를 주는 모든 방법을 정리합니다.

왜 규칙 파일이 필요한가

AI 코딩 도구는 똑똑하지만, 여러분의 프로젝트를 모릅니다.

❌ 매 세션마다:
"이 프로젝트는 Next.js 14 App Router를 씁니다."
"Supabase를 DB로 씁니다."
"테스트는 vitest로 합니다."
"커밋 메시지는 영어로 써주세요."

✅ 한 번만 쓰면:
규칙 파일에 적어두면 AI가 매번 자동으로 읽습니다.

규칙 파일은 AI에게 주는 프로젝트 온보딩 문서입니다. 새로 입사한 개발자에게 주는 문서와 같습니다. 다만 읽는 건 AI입니다.

도구별 규칙 파일 한눈에 보기

공통점: 전부 마크다운입니다. 특별한 문법 없이, 평소에 쓰는 마크다운으로 작성합니다.

CLAUDE.md 깊이 파기

CLAUDE.md란

Claude Code를 실행하면 가장 먼저 읽는 파일입니다. 프로젝트 루트에 CLAUDE.md를 만들어두면, 모든 세션에서 자동으로 컨텍스트에 포함됩니다.

가장 빠른 시작: /init

cd my-project
claude
# Claude Code 안에서:
/init

/init을 실행하면 Claude가 프로젝트 구조를 분석해서 CLAUDE.md 초안을 자동 생성합니다. 이미 파일이 있으면 개선 제안을 합니다.

잘 쓴 CLAUDE.md의 구조

실제로 효과가 좋은 CLAUDE.md는 공통적인 패턴이 있습니다. Builder.io, HumanLayer 등의 분석을 종합하면:

# Project: LinkHub

## Quick Facts
- Stack: Next.js 14 (App Router) + TypeScript + Supabase
- Package manager: pnpm
- Test: vitest
- Lint: eslint + prettier

## Commands
- `pnpm dev` — 개발 서버
- `pnpm test` — 테스트 실행
- `pnpm build` — 프로덕션 빌드
- `pnpm lint` — 린트 체크

## Architecture
- `src/app/` — App Router 페이지 & API 라우트
- `src/lib/` — 공유 유틸리티, DB 클라이언트
- `src/ui/` — UI 컴포넌트
- `supabase/migrations/` — DB 마이그레이션

## Rules
- Server Components 우선. 'use client'는 필요한 경우에만
- 모든 DB 쿼리는 src/lib/queries.ts에
- 환경변수는 절대 하드코딩 금지
- 커밋 메시지는 Conventional Commits (feat:, fix:, chore:)
- PR 전에 반드시 `pnpm test && pnpm build` 통과

핵심 원칙: 짧고, 의견이 있고, "왜"를 설명

200줄 이하로 유지하세요. CLAUDE.md는 매 세션마다 컨텍스트에 로딩됩니다. 길어지면 컨텍스트 윈도우 예산을 잡아먹고, Claude가 관련 없는 내용을 무시하기 시작합니다.

하지 말아야 할 것:

• 코드 스타일 규칙 전부 넣기 → ESLint/Prettier에 맡기세요
• 모든 가능한 명령어 나열 → 실제로 자주 쓰는 것만
• 장문의 아키텍처 설명 → 핵심만, 나머지는 별도 문서 링크

디렉토리 스코프 규칙: .claude/rules/

프로젝트가 커지면 하나의 CLAUDE.md로는 부족합니다. .claude/rules/ 디렉토리를 사용하면 주제별, 경로별로 규칙을 나눌 수 있습니다.

.claude/
└── rules/
    ├── general.md          # 항상 로딩
    ├── frontend.md         # paths: ["src/app/**", "src/ui/**"]
    ├── api.md              # paths: ["src/app/api/**"]
    └── database.md         # paths: ["supabase/**"]

경로 스코프 규칙은 YAML 프론트매터로 지정합니다:

---
paths:
  - "src/app/api/**"
  - "src/lib/queries.ts"
---

# API 규칙
- 모든 API 라우트에 인증 미들웨어 적용
- 에러 응답은 { error: string, code: number } 형식
- rate limiting은 middleware에서 처리

Claude가 해당 경로의 파일을 읽을 때만 이 규칙이 활성화됩니다.

.cursorrules 깊이 파기

.cursorrules란

Cursor IDE의 규칙 파일입니다. 프로젝트 루트에 .cursorrules를 만들면, Cursor의 모든 AI 기능(Composer, Tab, Chat)에서 이 규칙을 참조합니다.

실전 예시

You are an expert in TypeScript, Next.js 14 App Router, and Tailwind CSS.

## Code Style
- Use functional components with TypeScript interfaces
- Prefer named exports
- Use Tailwind for styling, no CSS modules
- All components go in src/components/

## Naming
- Components: PascalCase (UserProfile.tsx)
- Utilities: camelCase (formatDate.ts)
- Types: PascalCase with prefix (IUserProfile, TApiResponse)

## Patterns
- Use React Server Components by default
- Client components only when useState/useEffect is needed
- Data fetching in Server Components, not in useEffect
- Use Zod for runtime type validation

awesome-cursorrules: 커뮤니티 모음집

PatrickJS/awesome-cursorrules에 프레임워크/언어별 .cursorrules 템플릿이 수백 개 모여 있습니다. Next.js, React Native, Python FastAPI, Go, Rust 등 원하는 스택의 규칙을 가져다 쓸 수 있습니다.

.cursor/rules/ 디렉토리

Cursor도 디렉토리 기반 규칙을 지원합니다. .cursor/rules/ 안에 마크다운 파일을 넣으면 됩니다. Claude Code의 .claude/rules/와 동일한 개념입니다.

AGENTS.md: 2026년의 범용 표준

왜 새 표준이 필요한가

문제는 파편화입니다. Claude Code는 CLAUDE.md, Cursor는 .cursorrules, Copilot은 .github/copilot-instructions.md... 도구가 바뀔 때마다 규칙을 다시 쓰는 건 비효율적입니다.

2026년, Google, OpenAI, Sourcegraph, Cursor, Factory가 합의해서 AGENTS.md를 범용 표준으로 만들었습니다.

AGENTS.md의 작동 방식

프로젝트 루트/
├── AGENTS.md              ← 프로젝트 전체 규칙
├── src/
│   ├── AGENTS.md          ← src/ 하위에만 적용
│   └── api/
│       └── AGENTS.md      ← API 관련 규칙만
└── tests/
    └── AGENTS.md          ← 테스트 관련 규칙만

디렉토리 가장 가까운 파일이 우선. 에이전트는 자동으로 현재 작업 디렉토리에서 가장 가까운 AGENTS.md를 읽습니다. 하위 디렉토리의 파일이 상위를 덮어씁니다.

AGENTS.md에 넣어야 할 내용

GitHub 블로그가 2,500개 이상의 리포지토리를 분석한 결과, 효과적인 AGENTS.md의 공통 섹션은:

1. Build & Test — 빌드/테스트 명령어
2. Architecture — 주요 모듈 설명
3. Conventions — 네이밍, 폴더 구조, 코드 스타일
4. Security — 인증 흐름, API 키 관리, 민감 데이터
5. Git Workflow — 브랜치 전략, 커밋 규칙, PR 요구사항

기존 파일에서 마이그레이션

심볼릭 링크로 두 파일을 동시에 유지할 수 있습니다:

# AGENTS.md를 원본으로, 다른 파일은 심링크
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md .cursorrules

이러면 하나의 파일을 수정하면 모든 도구에 적용됩니다.

Claude Code 확장: Skills와 Commands

규칙 파일 너머로 Claude Code는 더 강력한 확장 시스템이 있습니다.

Custom Slash Commands

.claude/commands/ 디렉토리에 마크다운 파일을 만들면 자동으로 슬래시 커맨드가 됩니다.

.claude/commands/
├── review.md       → /review
├── test-all.md     → /test-all
└── deploy.md       → /deploy

review.md 예시:

현재 git diff를 분석해서 코드 리뷰를 해줘.
- 보안 취약점 체크
- 성능 이슈 체크
- 코드 스타일 일관성 체크
결과를 요약해서 마크다운으로 출력해줘.

이제 Claude Code에서 /review만 치면 이 프롬프트가 실행됩니다.

Skills (SKILL.md)

슬래시 커맨드의 고급 버전입니다. .claude/skills/ 디렉토리에 SKILL.md 파일을 만듭니다.

---
name: create-component
description: Creates a new React component with tests and stories
---

다음 규칙에 따라 새 컴포넌트를 생성해줘:

1. `src/ui/{ComponentName}/{ComponentName}.tsx` 에 컴포넌트
2. `src/ui/{ComponentName}/{ComponentName}.test.tsx` 에 테스트
3. Props는 interface로 정의
4. 기본 export 금지, named export만
5. Tailwind CSS 사용

$ARGUMENTS 를 컴포넌트 이름으로 사용해줘.

/create-component UserCard를 실행하면 3개 파일이 자동 생성됩니다.

Hooks

특정 이벤트에 자동으로 실행되는 스크립트입니다.

# Claude Code 안에서
/hooks

예를 들어:

• 파일 저장 후 → ESLint 자동 실행
• 커밋 전 → 테스트 자동 실행
• 세션 시작 시 → git pull 자동 실행

Peter Steinberger의 agent-rules: 실전 사례

iOS/macOS 개발자 Peter Steinberger(@steipete)는 자신의 AI 에이전트 규칙을 오픈소스로 공개했습니다. 20개 이상의 규칙 파일이 들어있으며, 실전에서 쓰이는 패턴을 볼 수 있습니다.

구성:

• global-rules/ — 모든 프로젝트에 적용되는 전역 규칙
• project-rules/ — 프로젝트별 규칙
• MCP 서버 설정, 멀티 에이전트 조율 규칙 등

이런 실전 사례가 공유되면서, AI 에이전트 규칙은 개인의 노하우에서 팀과 커뮤니티가 공유하는 표준으로 진화하고 있습니다.

지금 당장 시작하는 체크리스트

1단계: 현재 쓰는 도구에 맞는 파일 생성

# Claude Code
cd my-project && claude
# Claude Code 안에서 /init 실행

# Cursor
touch .cursorrules
# 또는 Cursor Settings > Rules for AI

2단계: 최소한 이것만 넣기

## Stack
- [프레임워크, 언어, DB, 배포 도구]

## Commands
- dev: [개발 서버 명령어]
- test: [테스트 명령어]
- build: [빌드 명령어]

## Rules
- [가장 중요한 규칙 3-5개]

3단계: 2주마다 점검

# Claude Code에서
"내 CLAUDE.md를 검토하고 개선 제안해줘"

시간이 지나면 규칙이 쌓이고, 중복되고, 서로 충돌합니다. 정기적으로 정리하세요.

정리

AI 코딩 도구의 성능은 도구 자체보다 어떻게 컨텍스트를 주느냐에 달려 있습니다. 규칙 파일은 가장 적은 노력으로 가장 큰 차이를 만드는 방법입니다.