CLAUDE.md 설정
AGENTS.md와 CLAUDE.md로 프로젝트 맥락을 Claude Code에게 알려줍니다
핵심 요약
- CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일입니다. 프로젝트 설명·명령어·코딩 스타일·기술 스택을 담아 Claude Code에 맥락을 넘깁니다.
create-next-app추천 기본값으로 만든 프로젝트의 CLAUDE.md에는@AGENTS.md줄이 들어 있어, 설치된 Next.js 버전의 로컬 문서를 먼저 참고하게 합니다.- 파일이 없거나 비어 있으면 Claude Code 안에서
/init을 실행해 자동 생성하되, 기존@AGENTS.md줄은 그대로 유지합니다. - 프로젝트 설명·Style Guide·Important Notes·Debugging 같은 섹션을 직접 추가하면 응답 품질이 올라갑니다.
/help,/clear,/compact,/context,/cost,/model같은 슬래시 명령어를 익혀 두고, 대화가 길어지면/compact로 컨텍스트를 정리합니다.
CLAUDE.md는 Claude Code에게 프로젝트 맥락을 알려주는 특별한 파일입니다. 이 파일이 있으면 Claude Code가 프로젝트를 더 잘 이해하고 더 적절한 코드를 작성합니다.
Next.js 16.2 이후 create-next-app으로 만든 프로젝트라면 AGENTS.md와 CLAUDE.md가 함께 생성됩니다.
CLAUDE.md란?
CLAUDE.md는 프로젝트 루트(최상위 폴더)에 위치하는 마크다운 파일로, 아래와 같은 정보를 담습니다:
AGENTS.md연결 (@AGENTS.md)- 프로젝트 설명 (어떤 앱인지)
- 주요 명령어 (빌드, 테스트, 실행 방법)
- 코딩 스타일 (선호하는 패턴이나 규칙)
- 기술 스택 (사용하는 라이브러리, 프레임워크)
왜 필요한가요?
CLAUDE.md가 없어도 Claude Code는 동작합니다. 다만 이 파일이 있으면 매번 같은 맥락을 반복 설명할 필요가 없어 바이브코딩이 훨씬 효율적입니다.
@AGENTS.md를 넣어 두면 Claude Code가 설치된 Next.js 버전의 로컬 문서를 먼저 참고합니다.
새 프로젝트에서 확인
create-next-app@latest 추천 기본값으로 만든 프로젝트라면 CLAUDE.md에 아래 줄이 들어 있습니다:
@AGENTS.md이 줄은 Claude Code에게 AGENTS.md를 추가 컨텍스트로 읽으라는 뜻입니다.
@AGENTS.md를 지우지 마세요
Next.js 최신 문서 안내는 AGENTS.md에 들어 있습니다. CLAUDE.md를 수정하더라도 맨 위의 @AGENTS.md 줄은 유지하세요.
/init으로 보강
CLAUDE.md가 없거나 내용이 너무 비어 있다면 Claude Code 안에서 아래 명령어를 입력합니다:
/initClaude Code가 프로젝트를 분석해 적절한 내용으로 CLAUDE.md 파일을 만들어줍니다.
이미 @AGENTS.md가 있다면 그대로 두고 프로젝트 설명, 명령어, 규칙을 덧붙이는 식으로 정리하세요.
생성된 CLAUDE.md 확인
/init 실행 후 프로젝트 폴더에 CLAUDE.md 파일이 생깁니다. VS Code에서 열어 내용을 확인해 봅시다.
일반적으로 아래와 같은 내용이 포함됩니다:
@AGENTS.md
## Project Overview
Next.js 16.2 App Router 기반 웹 애플리케이션
## Commands
- `npm run dev` — 개발 서버 실행
- `npm run build` — 프로덕션 빌드
- `npm run lint` — 코드 검사
## Tech Stack
- Next.js 16.2, React 19, TypeScript
- Tailwind CSS v4CLAUDE.md에 추가하면 좋은 정보
자동 생성된 내용에 아래 정보를 추가하면 Claude Code가 더 잘 동작합니다:
프로젝트 설명
## Project Description
개인 포트폴리오 웹사이트입니다.
한국어로 작성하며, 반응형 디자인을 적용합니다.
Next.js App Router를 사용합니다.코딩 스타일
## Style Guide
- 모든 UI 텍스트는 한국어로 작성
- Server Component를 기본으로 사용하고, 상호작용이 필요할 때만 Client Component 사용
- CSS는 Tailwind CSS 클래스 사용주의사항
## Important Notes
- Next.js 코드를 수정하기 전 `node_modules/next/dist/docs/`의 관련 문서를 먼저 확인
- 커밋은 사용자가 요청할 때만 수행
- 불필요한 주석은 추가하지 않음
- 변경 후 가능하면 `npm run build` 실행디버깅 규칙
## Debugging
- 브라우저 오류는 개발 서버 터미널의 `[browser]` 로그를 먼저 확인
- MCP가 설정되어 있으면 현재 오류와 라우트 상태를 먼저 조회
- 두 번째 dev server가 켜졌다는 오류가 나오면 안내된 URL이나 PID를 확인편하게 수정하세요
CLAUDE.md는 일반 텍스트 파일이라 VS Code에서 자유롭게 편집할 수 있습니다. 바이브코딩을 하면서 필요한 내용을 계속 추가해 나가면 됩니다.
핵심 슬래시 명령어
Claude Code에서 사용할 수 있는 주요 슬래시 명령어를 알아두면 편리합니다:
| 명령어 | 기능 |
|---|---|
/init | CLAUDE.md 자동 생성 |
/help | 도움말 표시 |
/clear | 대화 내역 초기화 |
/compact | 대화 내역을 요약하여 컨텍스트 절약 |
/context | 컨텍스트 최적화 제안 표시 |
/cost | 현재 세션의 사용량 확인 |
/model | 사용 모델 변경 |
/exit | Claude Code 종료 |
/compact 활용 팁
대화가 길어지면 Claude Code의 응답 품질이 떨어질 수 있습니다. 주기적으로 /compact를 실행해 대화를 요약해 두면 좋습니다.