CLAUDE.md 파일

요약대본

Claude Code에서 가장 유용한 기능 중 하나는 CLAUDE.md 파일입니다. 이 파일은 Claude Code에 프로젝트에 대한 지속적인 메모리를 제공합니다.

한국어 대본

00:00Claude Code의 가장 유용한 부분 중 하나는 Claude.md 파일입니다.
00:08이 파일은 Claude Code에 프로젝트에 대한 지속적인 메모리를 제공합니다.
00:13Claude.md 파일 없이 Claude Code를 열면 매번 처음부터 다시 시작해야 하는 것과 같습니다.
00:20코드베이스를 다시 탐색하고, 어떤 의존성이 필요한지, 이미 구현된 기능이 무엇인지 이해해야 합니다.
00:27때로는 가정을 해야 하며, 그로 인해 Claude의 방향을 올바르게 잡기가 더 어려워집니다.
00:31하지만 바로 여기서 Claude.md가 등장합니다.
00:34이것은 프로젝트 루트에 추가하는 Markdown 파일이며, Claude Code는 세션을 시작할 때마다 자동으로 읽습니다.
00:41코드베이스를 위한 온보딩 스크립트와 같습니다.
00:44간단히 말하면, Claude.md 파일의 내용은 프롬프트에 추가됩니다.
00:48슬래시 init 명령을 실행할 수 있으며, 그러면 Claude가 코드베이스를 기반으로 하나를 생성합니다.
00:53그럼 하나를 살펴보겠습니다. 이것은 App Router, Tailwind, Drizzle ORM을 사용하는 Next.js 15 앱입니다.
01:02개발 서버 실행 명령, 테스트 실행, 코드 스타일 린트, 두 칸 들여쓰기 사용, 모든 내보내기에 명명된 내보내기 선호
01:10API 라우트는 app/api에 있으며, 가능하면 API 라우트 대신 서버 액션을 사용하세요.
01:15그리고 이제는 매우 간단합니다. Claude Code에게 React 컴포넌트를 만들어 달라고 요청하면, 그것은 방법을 알고 있습니다.
01:21Tailwind 또는 제가 사용하는 다른 CSS 프레임워크로 스타일을 지정합니다. Claude가 더 잘하는 것을 볼 수 있습니다.
01:27처음부터 모든 것이 어디에 있는지 이해해야 하는 것보다 자신의 작업을 더 잘 수행합니다.
01:32처음에는. 그리고 물어보시기 전에, 대답은 예입니다. 이것을 버전 관리에 공유하여
01:39팀이 사용할 수 있습니다. 하지만 실제로는 누구를 위한 것인지에 따라 메모리 파일의 계층 구조가 있습니다.
01:44먼저 프로젝트의 루트 디렉터리에 있는 프로젝트 수준의 Claude.md가 있습니다.
01:48구성 폴더에 있는 사용자 수준의 Claude.md가 있습니다.
01:53이것은 오직 사용자만을 위한 것이며 모든 프로젝트에 적용됩니다.
01:56그러니 코드 주석을 작성하는 방식 같은 개인적인 선호 사항을 여기에 넣으세요.
02:01먼저, Claude가 항상 서버 액션을 사용하도록 교정해야 하는 경우
02:05API 라우트 대신, 그런 다음 Claude에게 이것을 메모리에 저장하도록 명시적으로 요청하세요. 그래야
02:11이 프로젝트로 돌아올 때마다 매번 알게 됩니다.
02:13둘째, 프로젝트에 Claude가 참조하길 원하는 문서가 있다면, 그냥
02:18@ 기호와 파일 경로를 사용하세요.
02:21셋째, 프로젝트를 시작할 때는
02:23Claude.md 파일 없이 시작하는 것이 좋으며,
02:25그래야 어디서 계속
02:27모델을 교정해야 하는지 볼 수 있습니다.
02:29이렇게 하면 Claude.md 파일이 간결하게 유지되고,
02:31Claude가 작업할 수 있는 필요한 정보만
02:33포함하게 됩니다.
02:39좌절스러운 Claude Code 세션과
02:41생산적인 세션의 차이는 컨텍스트에 달려 있으며,
02:44Claude.md 파일이 바로 그 컨텍스트를 제공하는 방법입니다.
02:48스택, 선호도, 그리고 명령어부터 시작하고, 그냥 진행하면서 그때그때 구축해 나가세요.

이 파일이 해결하는 문제

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

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

예시

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

markdown

# 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를 사용하고 코드 규칙을 따라야 한다는 것을 알고 있습니다.

VS Code에서 열린 CLAUDE.md 파일, 프로젝트 정보, 명령어, 코드 스타일 규칙을 보여줌

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

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

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

팁

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

Claude에게 규칙을 CLAUDE.md 파일에 저장하도록 요청하는 모습 — API 라우트 대신 항상 서버 액션 사용

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

markdown

## README.md

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

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

요약

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