딱 하나의 파일이 매 대화 전에 로드됩니다. Claude Code를 사용한다면, 이 설정 시간이 가장 큰 효과를 발휘하는 부분입니다.
CLAUDE.md 는 클로드가 각 세션 시작 시 자동으로 읽어들이는 마크다운 파일입니다. 이 파일에는 프로젝트별 지침이 담겨 있어, 그렇지 않으면 매번 프롬프트에 반복해서 작성해야 할 내용을 간소화합니다. 구조, 규칙, 워크플로, 스타일 등이 여기에 포함됩니다.
저는 CLAUDE.md 파일 설정을 꽤 오랫동안 개선해 왔습니다. 이 가이드에서는 제가 이 파일을 생성, 구성, 유지 관리 및 발전시키는 과정에서 배운 모든 것을 다룹니다. 다른 AI 코딩 도구를 사용하는 경우에도 AGENTS.md 파일(Cursor, Zed, OpenCode 등 다른 AI 코딩 도구 의 해당 파일)에 동일한 개념이 적용됩니다.
CLAUDE.md 파일이 필요한 이유
클로드는 이전 세션에 대한 기억 없이 매 세션을 시작합니다. 사용자의 코드 스타일 선호도를 알지 못하고, 테스트 실행 방법도 알지 못하며, 팀에서 특정 브랜치 명명 규칙을 사용한다는 사실이나 인증 모듈에 특이한 해결 방법이 있다는 사실도 알지 못합니다.
결국 같은 말을 반복하게 되거나, 더 심각하게는 중요한 내용을 언급하는 것을 잊어버리고 관례를 따르지 않은 코드를 수정하는 데 시간을 허비하게 됩니다.
CLAUDE.md 파일이 이 문제를 해결합니다. 클로드는 자동으로 환경설정을 읽어오므로 세션 간에 환경설정이 유지됩니다.
CLAUDE.md 파일을 만드는 방법
가장 빠른 시작 방법은 /init 명령어를 사용하는 것입니다. 프로젝트 디렉토리에서 이 명령어를 실행하면 클로드가 프로젝트 구조와 감지된 기술 스택을 기반으로 CLAUDE.md 시작 파일을 생성합니다.
어떤 사람들은 처음부터 직접 작성하는 것을 추천하지만, 저는 /init을 시작점으로 삼아 필요 없는 부분을 삭제합니다. 처음부터 새로 만드는 것보다 삭제하는 것이 훨씬 쉽습니다. 생성된 파일에는 종종 명시할 필요가 없는 명백한 내용이나 가치를 더하지 않는 불필요한 내용이 포함되는 경우가 많습니다.
생성기에 포함된 내용을 전부 그대로 두면 되지 않느냐고 생각하실 수도 있지만, 컨텍스트는 매우 중요하기 때문입니다. CLAUDE.md 파일의 모든 줄은 여러분이 Claude에게 실제로 요청하는 작업 내용과 주의(attention)를 끌기 위해 경쟁합니다.
CLAUDE.md 은 다음 몇 군데에 배치할 수 있습니다.
- 프로젝트 루트 : 가장 일반적인 위치입니다. 팀원들이 동일한 컨텍스트를 공유할 수 있도록 버전 관리 시스템에 등록하세요.
.claude/CLAUDE.md: 설정 파일을 하위 디렉토리에 보관하는 것을 선호하는 경우 사용할 수 있는 대안입니다.~/.claude/CLAUDE.md: 모든 프로젝트에 적용되는 사용자 수준 기본 설정입니다.
버전 관리에 포함되지 않아야 하는 개인적인 설정(편집기 선호도, 출력 상세 수준 등)은 CLAUDE.local.md 파일을 사용하세요. 버전 관리에서 제외하려면 .gitignore 파일에 추가하면 됩니다.
파일 이름은 대소문자를 구분합니다. 정확히 CLAUDE.md (대문자 CLAUDE, 소문자 .md) 형식이어야 합니다. Claude Code는 메모리 파일을 로드할 때 이 특정 파일 이름을 찾습니다. 이 내용은 공식 문서에 명시적으로 나와 있지는 않지만, 공식 문서의 AI 도우미에게 문의한 결과, 메모리 파일에도 스킬 파일과 마찬가지로 대소문자를 구분하는 규칙이 적용되는 것을 확인했습니다.
CLAUDE.md 파일 구조화 방법
이제 핵심을 살펴보죠. 파일에 실제로 포함되어야 할 내용은 무엇일까요?
필수 요소
프로젝트 컨텍스트 : 이 프로젝트는 무엇인가요? 클로드에게 프로젝트 방향을 제시하는 한 줄짜리 설명입니다. "이 프로젝트는 Stripe 결제 시스템과 연동되는 Next.js 기반 전자상거래 앱입니다." 이 설명은 생각보다 훨씬 더 많은 정보를 클로드에게 전달합니다.
코드 스타일 : 선호하는 서식 및 패턴이 무엇인가요? ES 모듈 또는 CommonJS를 사용하시나요? 명명된 내보내기(named export)를 선호하시나요? 구체적으로 설명해 주세요. "코드를 제대로 서식화하세요"라는 표현은 모호합니다.
명령어 : 테스트 실행, 빌드, 린트, 배포 방법. 클로드는 사용자가 실행을 요청할 때 이러한 명령어를 정확히 사용합니다.
주의 사항 : 프로젝트별 경고. 이상한 재시도 로직이 있는 인증 모듈. 특정 헤더 형식을 요구하는 API 엔드포인트. 직접 수정해서는 안 되는 파일.
완전한 예시
Next.js 프로젝트의 CLAUDE.md 파일은 다음과 같은 형태일 수 있습니다.
# 프로젝트: ShopFront
App Router, Stripe 결제, Prisma ORM을 사용하는 Next.js 14 전자상거래 애플리케이션입니다.
## 코드 스타일
- TypeScript strict 모드 사용, `any` 타입 금지
- default export 대신 named export 사용
- CSS: Tailwind 유틸리티 클래스 사용, 커스텀 CSS 파일 금지
## 명령어
- `npm run dev`: 개발 서버 시작 (포트 3000)
- `npm run test`: Jest 테스트 실행
- `npm run test:e2e`: Playwright end-to-end 테스트 실행
- `npm run lint`: ESLint 검사
- `npm run db:migrate`: Prisma 마이그레이션 실행
## 아키텍처
- `/app`: Next.js App Router 페이지 및 레이아웃
- `/components/ui`: 재사용 가능한 UI 컴포넌트
- `/lib`: 유틸리티 및 공유 로직
- `/prisma`: 데이터베이스 스키마 및 마이그레이션
- `/app/api`: API 라우트
## 중요 사항
- .env 파일은 절대 커밋하지 마세요
- /app/api/webhooks/stripe의 Stripe webhook 핸들러는 반드시 서명을 검증해야 합니다
- 제품 이미지는 로컬이 아닌 Cloudinary에 저장됩니다
- 인증 플로우에 대한 자세한 내용은 @docs/authentication.md를 참고하세요클로드는 이 자료가 명확한 제목, 쉽게 훑어볼 수 있도록 글머리 기호로 정리되어 있고, 모호한 지시사항 대신 구체적인 명령이 포함되어 있기 때문에 효율적으로 처리합니다.
길이는 어느정도가 좋을까요?
일반적으로 300줄 미만을 권장합니다. 짧을수록 좋습니다. 컨텍스트 토큰은 소중합니다.
하지만 저는 파일 길이가 길어도 괜찮은 프로젝트들을 본 적이 있습니다. 코드베이스에 복잡한 규칙이나 특이한 패턴이 있다면, 해당 컨텍스트를 파일 앞에 배치함으로써 클로드가 잘못된 가정을 하고 수정하는 데 시간을 낭비하는 것을 방지할 수 있습니다.
제가 사용하는 방법은 클로드가 작업을 시작하기 전에 필요한 정보를 모두 포함시키는 것입니다. 특정 상황에서만 중요한 정보는 별도의 파일에 저장해 두고 참조합니다.
@imports 시스템
CLAUDE.md는 @path/to/file 구문을 사용하여 다른 파일을 가져오는 것을 지원합니다.
See @README.md for project overview
See @docs/api-patterns.md for API conventions
See @package.json for available npm scripts이 방법은 메인 파일을 간결하게 유지하는 데 매우 효과적입니다. 자세한 지침은 별도의 마크다운 파일에 작성하고, 나중에 해당 파일을 참조하세요. 클로드는 필요할 때 해당 파일의 내용을 불러옵니다.
어디에서든 파일을 참조할 수 있습니다.
- 상대 경로:
@docs/style-guide.md - 절대 경로도 작동합니다.
- 사용자 수준 파일도 마찬가지입니다:
@~/.claude/my-preferences.md
import는 재귀적으로 이루어질 수 있으므로 참조된 파일에서 다른 파일을 참조할 수 있습니다. 하지만 참조가 복잡하게 얽히는 것을 방지하기 위해 이 기능은 신중하게 사용해야 합니다.
제가 선택한 패턴은 핵심 내용은 CLAUDE.md 에 유지하고, 주제별 상세 지침은 별도의 파일로 옮겨 @imports를 사용하여 참조하는 것입니다.
.claude/rules/를 사용한 모듈형 규칙
규모가 큰 프로젝트의 경우, 또 다른 옵션이 있습니다. 바로 .claude/rules/ 디렉토리입니다. 모든 내용을 담은 하나의 큰 파일 대신, 지침을 특정 목적에 맞는 규칙 파일로 분할할 수 있습니다.
your-project/
├── .claude/
│ ├── CLAUDE.md # 주요 프로젝트 지침
│ └── rules/
│ ├── code-style.md # 코드 스타일 가이드라인
│ ├── testing.md # 테스트 컨벤션
│ └── security.md # 보안 요구사항.claude/rules/ 디렉터리에 있는 모든 마크다운 파일은 메인 CLAUDE.md 파일과 동일한 우선순위로 자동으로 로드됩니다. 별도의 import 작업이 필요 없으며, 파일을 해당 디렉터리에 넣기만 하면 바로 포함됩니다.
이 방식은 팀 구성원들이 각기 다른 규칙 세트를 담당할 때 효과적입니다. 프런트엔드 팀은 code-style.md , 보안 팀은 security.md 파일을 관리합니다. 이렇게 하면 누구도 충돌하는 규칙들을 하나의 거대한 파일로 병합할 필요가 없습니다.
저는 아직 이런 기능이 필요하지 않았습니다. 제 프로젝트 규모가 작아서 규칙을 여러 파일로 나눌 필요가 없었거든요. 하지만 도메인이 명확하게 구분된 대규모 팀이라면 이런 구조가 유용할 겁니다.
CLAUDE.md 하위 디렉토리 파일
계층 구조에는 한 단계가 더 있습니다. 바로 프로젝트 하위 디렉터리에 있는 CLAUDE.md 파일입니다.
클로드가 하위 디렉터리의 파일을 읽을 때, 해당 하위 디렉터리에 있는 CLAUDE.md 파일을 자동으로 가져옵니다. 이 파일들은 실행 시에는 로드되지 않으며, 클로드가 코드베이스의 해당 부분에서 활발하게 작업할 때만 포함됩니다.
이 기능은 모노레포나 모듈이 명확하게 구분된 프로젝트에 유용합니다. /api 폴더에는 API별 규칙을 담은 CLAUDE.md를 따로 만들 수 있고, /packages/ui 폴더에는 컴포넌트 개발에 대한 다른 규칙을 적용할 수 있습니다. 클로드는 작업 위치에 따라 관련 컨텍스트를 로드합니다.
CLAUDE.md 파일을 관리하는 방법
CLAUDE.md 파일은 한 번 만들어 놓으면 신경 쓸 필요가 없는 파일이 아닙니다. 프로젝트가 발전하고, 선호도가 바뀌면 파일 내용도 그에 맞춰 변경되어야 합니다.
작업하면서 지침을 추가하세요
클로드가 당신이 정정하고 싶은 가정을 했을 때, 그 자리에서 바로 수정하지 마세요. 클로드에게 그 내용을 CLAUDE.md 파일에 추가하도록 지시하세요.
저는 이 작업을 항상 합니다. 클로드는 디버깅을 위해 console.log를 사용하라고 권장하지만, 저는 로거를 사용하고 싶습니다. 한 번만 수정하는 대신, "CLAUDE.md 에 'console.log 대신 항상 로거를 사용하라'는 내용을 추가해 주세요"라고 말합니다. 그러면 이 지침이 이후 세션에도 적용됩니다.
이렇게 하면 CLAUDE.md 파일이 자연스럽게 구축됩니다. 모든 것을 미리 예측하려고 애쓰는 대신, 발생하는 상황을 통해 학습 내용을 기록하는 것입니다. 마치 회의 중에 메모하는 것과 같지만, 그 메모가 실제로 활용된다는 점이 다릅니다.
Note: 이전 버전의 Claude Code에서는 지침/지시사항(instructions) 추가하는 단축키로 # 키를 사용할 수 있었습니다. 하지만 이 기능은 2.0.70 버전에서 제거 되었습니다. 현재는 클로드에게 직접 CLAUDE.md 파일을 편집하도록 요청하는 방식으로 사용해야 합니다.
정기 검토
몇 주에 한 번씩 클로드에게 CLAUDE.md 파일을 검토하고 최적화해달라고 요청합니다. 시간이 지나면서 지침이 쌓이고, 일부는 중복되고, 일부는 새로 추가된 내용과 충돌합니다.
"CLAUDE.md를 검토하고 개선 사항을 제안해 주세요"라는 간단한 요청을 통해 이러한 문제점들을 파악할 수 있습니다. 더 이상 필요 없는 내용은 삭제하고, 중복되는 내용은 통합하며, 모호한 부분은 명확히 하세요.
이건 유지보수 부담처럼 들리죠? 맞습니다. 하지만 매 세션마다 같은 말을 반복하거나 규칙을 무시한 코드를 수정하는 것보다는 부담이 적습니다.
중요 지침에 대한 강조
반드시 지켜야 하는 규칙의 경우, 강조어를 사용하면 주의를 끌 수 있습니다. 예를 들어, "IMPORTANT: Never modify the migrations folder directly (중요: 마이그레이션 폴더를 직접 수정하지 마십시오)" 또는 "YOU MUST run tests before committing. (커밋하기 전에 반드시 테스트를 실행해야 합니다"와 같이 사용할 수 있습니다.)"
이 방법이 완벽할 거라고 기대하지 마세요. 특히 대화가 길어지고 컨텍스트가 복잡해질수록 클로드는 이러한 경계를 넘을 수도 있습니다. 제 경험상 이렇게 하면 클로드가 주의를 기울일 확률이 높아지지만, 완전히 보장되지는 않습니다.
주의해서 사용하세요. 모든 항목에 '중요'라고 표시되어 있다면, 아무것도 중요해지지 않습니다.
시간이 지남에 따라 CLAUDE.md를 개선하는 방법
가장 가치 있는 업데이트는 대개 코드 리뷰에서 나옵니다.
PR에서 문서화되지 않은 규칙이 드러나거나 리뷰어가 패턴 위반을 발견하면, 그것은 신호입니다. 해당 내용을 CLAUDE.md 에 추가하세요. 그러면 같은 실수가 반복되지 않을 것입니다.
Claude Code GitHub 액션( /install-github-action 로 설치)을 사용하고 있다면, PR 댓글에 @_claude를 직접 태그하여 이러한 업데이트를 요청할 수 있습니다. 예를 들어 "@_claude CLAUDE.md에 다음 내용을 추가해 주세요: enum은 절대 사용하지 말고, 항상 문자열 리터럴 유니온을 선호하세요."와 같이 작성하면 됩니다. 클로드는 파일을 업데이트하고 PR의 일부로 변경 사항을 커밋합니다. Boris Cherny가 이 워크플로를 공유해 주었고 , 저는 이 워크플로를 CLAUDE.md 유지 관리 방식의 일부로 활용하고 있습니다.
이렇게 하면 피드백 루프가 생성됩니다. 실제 문제를 바탕으로 지침을 개선하고, 이를 통해 향후 문제를 예방할 수 있습니다. CLAUDE.md 파일은 팀이 축적한 지식을 담아내는 살아있는 문서가 됩니다.
저는 CLAUDE.md를 코드베이스 자체와 같다고 생각합니다. 처음부터 완벽한 코드를 작성할 수는 없잖아요. 리팩토링을 하고, 개선해 나가야죠. CLAUDE.md도 마찬가지입니다.
CLAUDE.md 모범 사례
- 프로젝트가 무엇인지 한 줄로 설명하는 것으로 시작하세요.
- 코드 스타일 선호 사항을 구체적이고 실행 가능하게 만드세요.
- 주요 명령어(테스트, 빌드, 린트, 배포)를 포함하세요.
- 실수를 방지할 수 있도록 주의 사항을 충분히 자세히 알려주세요.
- 300줄 이하로 유지하거나, 모든 줄이 그 자리에 있을 만한 가치가 있도록 하세요.
- 자세한 안내를 @import한 파일로 옮기세요.
- 오래되었거나 최신 지침과 충돌하는 내용은 모두 제거하십시오.
- 정말 중요한 규칙만 강조 표시하세요.
- 작업 시작 전에만 지침을 추가하지 말고, 작업하면서 동시에 지침을 추가하세요.
- PR 리뷰에서 규칙(컨벤션)이 발견되면 업데이트하세요.
- 오래되었거나 상충되는 규칙이 있는지 정기적으로 검토하십시오.
규모가 큰 프로젝트의 경우:
- 서로 다른 규칙을 가진 하위 디렉터리에는 별도의
CLAUDE.md이 필요할 수 있습니다. - 규칙을
.claude/rules/파일로 분리하면 팀 간 소유권을 더 명확하게 할 수 있습니다.
오늘 시작하세요
아직 CLAUDE.md 파일이 없다면 지금 바로 /init을 실행하세요. 생성된 내용을 검토하고, 해당되지 않는 부분은 삭제하세요. 그리고 원하는 코드 스타일을 추가하세요.
이미 파일이 있다면, 클로드에게 다음에 수정하고 싶은 가정이 있을 때 파일을 업데이트하라고 알려주세요. 실제 사용량을 통해 파일이 자연스럽게 커지는 것을 지켜보세요.
단 하나의 파일. 몇 분의 설정만으로. 장기적으로 몇 시간을 절약할 수 있습니다.
🚀 한국어로 된 프런트엔드 아티클을 빠르게 받아보고 싶다면 Korean FE Article을 구독해주세요!
