CLAUDE.md 설정

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)
• 프로젝트 설명 (어떤 앱인지)
• 주요 명령어 (빌드, 테스트, 실행 방법)
• 코딩 스타일 (선호하는 패턴이나 규칙)
• 기술 스택 (사용하는 라이브러리, 프레임워크)

새 프로젝트에서 확인

create-next-app@latest 추천 기본값으로 만든 프로젝트라면 CLAUDE.md에 아래 줄이 들어 있습니다:

@AGENTS.md

이 줄은 Claude Code에게 AGENTS.md를 추가 컨텍스트로 읽으라는 뜻입니다.

/init으로 보강

CLAUDE.md가 없거나 내용이 너무 비어 있다면 Claude Code 안에서 아래 명령어를 입력합니다:

/init

Claude 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 v4

CLAUDE.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 Code에서 사용할 수 있는 주요 슬래시 명령어를 알아두면 편리합니다:

참고 자료

1. Claude Code 메모리 (CLAUDE.md)
2. Claude Code 슬래시 커맨드
3. Claude Code 베스트 프랙티스
4. Claude Code Hooks reference
5. Claude Code MCP 연결
6. Claude Code CLI 레퍼런스
7. Next.js AI Coding Agents