CLAUDE.md 파일

이 파일이 해결하는 문제

CLAUDE.md 파일 없이 Claude Code를 열면 매번 처음부터 시작합니다. 코드베이스를 다시 탐색하고, 어떤 의존성이 필요한지 파악하고, 이미 구현된 기능이 무엇인지 이해해야 합니다. 때로는 가정을 하게 되는데, 이는 Claude를 올바른 방향으로 이끄는 것을 더 어렵게 만듭니다.

CLAUDE.md는 이 문제를 해결합니다. 프로젝트 루트에 추가하는 Markdown 파일로, Claude Code는 세션을 시작할 때마다 자동으로 이 파일을 읽습니다. 코드베이스를 위한 온보딩 스크립트라고 생각하면 됩니다. CLAUDE.md 파일의 내용은 프롬프트에 추가됩니다.

예시

일반적인 CLAUDE.md 파일은 다음과 같습니다:

# Project

This is a Next.js 15 app using the App Router, Tailwind, and Drizzle ORM.

# Commands
- Dev server: `pnpm dev`
- Run tests: `pnpm test`
- Lint: `pnpm lint`

# Code Style
- Use 2-space indentation
- Prefer named exports
- All API routes go in app/api/
- Use server actions instead of API routes where possible

간단합니다. 이제 Claude Code에 React 컴포넌트를 만들어 달라고 요청하면, 이미 스타일링에 Tailwind를 사용하고 코드 규칙을 따라야 한다는 것을 알고 있습니다.

CLAUDE.md는 팀을 위한 것입니다

CLAUDE.md를 버전 관리에 커밋할 수 있으며(그렇게 해야 합니다), 그러면 팀 전체가 이를 활용할 수 있습니다. 실제로 누구를 위한 것인지에 따라 메모리 파일의 계층 구조가 있습니다:

• 프로젝트 수준 CLAUDE.md는 프로젝트의 루트 디렉터리에 있습니다. 팀과 공유됩니다.

• 사용자 수준 CLAUDE.md는 구성 폴더에 있습니다. 이것은 오직 본인만을 위한 것이며 모든 프로젝트에 적용됩니다. 여기에 개인 설정을 넣으세요.

팁

수정 사항을 메모리에 저장하세요. API 라우트 대신 항상 서버 액션을 사용하라고 말하는 것처럼, Claude를 반복적으로 수정하고 있다면, 그 규칙을 메모리에 저장하라고 명시적으로 Claude에게 요청하세요. 다음에 프로젝트를 열면 Claude가 이를 알고 있을 것입니다.

프로젝트 문서를 참조하세요. Claude가 참조하기를 원하는 문서가 프로젝트에 있다면, 파일 경로와 함께 @ 기호를 사용하세요:

## README.md

Please read if you need more info: @README.md

파일 없이 시작하세요. CLAUDE.md 파일 없이 프로젝트를 시작하여 모델을 계속 수정해야 하는 부분이 어디인지 확인하는 것을 권장합니다. 이렇게 하면 CLAUDE.md를 간결하게 유지하고 필요한 정보에만 집중할 수 있습니다. 준비가 되면 /init을 실행하여 Claude가 파일을 생성하도록 하세요.

요약

답답한 Claude Code 세션과 생산적인 세션의 차이는 종종 컨텍스트에 달려 있으며, CLAUDE.md 파일은 그 컨텍스트를 제공하는 방법입니다. 스택, 설정, 명령어로 시작한 다음 진행하면서 거기서부터 구축해 나가세요.