CLAUDE.md 파일을 활용하여 프로젝트의 기술 스택, 코딩 컨벤션, 아키텍처 정보를 Claude Code에 효과적으로 전달하는 방법을 알아봅니다.
CLAUDE.md는 Claude Code의 영구 메모리입니다. 세션이 시작될 때 자동으로 로드되어 Claude가 프로젝트를 이해하는 기초 컨텍스트가 됩니다. 잘 작성된 CLAUDE.md는 매 세션마다 같은 설명을 반복할 필요 없이, Claude가 프로젝트의 기술 스택, 코딩 규칙, 디렉토리 구조를 즉시 파악하도록 합니다.
CLAUDE.md가 없으면 Claude Code는 파일을 직접 읽어가며 프로젝트를 파악해야 하므로, 초기 탐색에 시간과 토큰이 소비됩니다. CLAUDE.md가 있으면 이 과정을 건너뛰고 바로 핵심 작업에 집중할 수 있습니다.
CLAUDE.md는 하나만 사용하는 것이 아닙니다. Claude Code는 여러 위치의 CLAUDE.md를 계층적으로 로드하며, 각 위치마다 역할이 다릅니다.
| 위치 | 용도 | Git 포함 여부 |
|---|---|---|
~/.claude/CLAUDE.md | 전역 개인 설정 (선호 언어, 스타일) | 해당 없음 |
프로젝트 루트/CLAUDE.md | 프로젝트 공통 컨텍스트 | 포함 권장 |
하위 디렉토리/CLAUDE.md | 특정 모듈/패키지 규칙 | 포함 권장 |
Claude Code는 현재 작업 디렉토리를 기준으로 상위 경로의 모든 CLAUDE.md를 수집합니다. 더 구체적인(하위 디렉토리) 파일이 더 일반적인(상위) 파일보다 우선합니다.
효과적인 CLAUDE.md를 작성하기 위한 핵심 원칙이 있습니다.
CLAUDE.md는 Claude에게 보내는 지시서입니다. 산문체보다는 구조화된 형식이 효과적입니다.
이 프로젝트는 Next.js를 사용하는 블로그입니다.
TypeScript를 사용하고 있으며 strict 모드입니다.
Tailwind CSS로 스타일링하고 있습니다.## 기술 스택
- **Framework**: Next.js 15 (App Router, TypeScript strict)
- **Styling**: Tailwind CSS v4
- **Content**: MDX + Velite단순한 사실 나열보다 Claude가 따라야 할 행동 규칙을 구체적으로 명시합니다.
## 코딩 컨벤션
- 컴포넌트는 함수 선언(`function Component()`) 사용, 화살표 함수 금지
- import 순서: React/Next > 외부 라이브러리 > 내부 모듈 > 스타일
- 파일명: 컴포넌트는 PascalCase, 유틸리티는 kebab-case
- CSS: Tailwind 유틸리티 클래스 우선, 커스텀 CSS 최소화Claude가 빌드, 테스트, 린트 등을 실행할 수 있도록 명령어를 명시합니다.
## 개발 명령어
pnpm dev # 개발 서버 (포트 3000)
pnpm build # 프로덕션 빌드
pnpm lint # ESLint 검사
pnpm test # 테스트 실행
pnpm test:e2e # E2E 테스트Claude가 피해야 할 패턴을 명확히 알려주는 것이 중요합니다.
## 금지 사항
- `any` 타입 사용 금지
- `console.log` 프로덕션 코드에 남기지 않기
- 문서 파일(*.md, README) 임의 생성 금지
- `.env` 파일 수정 또는 커밋 금지프로젝트 유형별로 활용할 수 있는 CLAUDE.md 템플릿을 제시합니다.
# 프로젝트명
## 개요
설명 한 줄
## 기술 스택
- **Framework**: Next.js 15 (App Router, TypeScript strict)
- **Styling**: Tailwind CSS v4
- **DB**: PostgreSQL + Drizzle ORM
- **Auth**: NextAuth.js v5
- **Deploy**: Vercel
## 프로젝트 구조
app/ # App Router 페이지
(auth)/ # 인증 관련 라우트 그룹
api/ # API 라우트
components/ # 공유 컴포넌트
ui/ # 기본 UI 프리미티브
forms/ # 폼 컴포넌트
lib/ # 유틸리티, 헬퍼
db/ # 데이터베이스 스키마, 쿼리
auth/ # 인증 설정
## 개발 명령어
pnpm dev # 개발 서버
pnpm build # 빌드
pnpm db:push # 스키마 반영
pnpm db:studio # DB GUI
## 코딩 컨벤션
- 서버 컴포넌트 기본, 클라이언트는 'use client' 명시
- 데이터 fetch는 서버 컴포넌트에서 직접 수행
- 폼 처리는 Server Actions 사용
- 에러 처리: try-catch + error.tsx 바운더리
## 커밋 규칙
- Conventional Commits 형식: feat, fix, refactor, docs, chore
- 한글 커밋 메시지 사용# API 서버명
## 기술 스택
- **Runtime**: Node.js 20 + TypeScript strict
- **Framework**: Fastify 5
- **DB**: PostgreSQL + Kysely
- **Test**: Vitest + Supertest
- **Deploy**: Docker + ECS
## 구조
src/
routes/ # API 라우트 (자동 로드)
services/ # 비즈니스 로직
repositories/ # DB 쿼리 레이어
middleware/ # 인증, 로깅, 에러 처리
types/ # 공유 타입 정의
## 개발 명령어
pnpm dev # 개발 서버 (watch)
pnpm build # 빌드
pnpm test # 단위 테스트
pnpm test:int # 통합 테스트 (DB 필요)
pnpm migrate # DB 마이그레이션
## 규칙
- 모든 라우트에 Zod 스키마 유효성 검사 적용
- 에러는 커스텀 AppError 클래스 사용
- 로깅은 Pino (console.log 금지)
- 모든 서비스 함수에 단위 테스트 작성CLAUDE.md에는 정적 텍스트만 넣을 수 있습니다. 동적으로 변하는 정보를 주입하려면 훅(Hooks)이나 스킬의 context 필드를 활용합니다. 이에 대해서는 5장(훅)과 6장(스킬)에서 자세히 다룹니다.
하지만 CLAUDE.md 자체에서도 몇 가지 실용적인 패턴을 활용할 수 있습니다.
프로젝트의 현재 상태나 진행 중인 작업을 CLAUDE.md에 기록해 두면, 새 세션을 시작할 때 이전 컨텍스트를 빠르게 복원할 수 있습니다.
## 현재 진행 중인 작업
- [ ] 사용자 프로필 페이지 리디자인 (app/profile/)
- [ ] API 응답 캐싱 레이어 추가 (lib/cache/)
- [x] 다크 모드 전환 버그 수정모노레포나 복잡한 프로젝트에서는 하위 디렉토리에 별도의 CLAUDE.md를 둘 수 있습니다.
# API 패키지
이 디렉토리는 백엔드 API 서버 코드입니다.
## 이 패키지의 규칙
- 모든 엔드포인트는 OpenAPI 스키마 정의 필수
- 응답 형식: { data, error, meta } 래퍼 사용
- 인증 미들웨어는 반드시 적용 (공개 API 제외)CLAUDE.md가 수백 줄이 되면 컨텍스트 윈도우를 불필요하게 소비합니다. 핵심 정보만 담고, 세부사항은 필요할 때 파일을 직접 읽도록 합니다.
CLAUDE.md는 매 세션 시작 시 전체가 컨텍스트에 로드됩니다. 불필요하게 긴 내용은 토큰 비용을 높이고 핵심 지시를 희석시킵니다. 200줄 이내를 권장합니다.
"좋은 코드를 작성해 주세요"와 같은 모호한 지시는 효과가 없습니다. "TypeScript strict mode, no-any, 함수 선언식 사용"처럼 구체적으로 작성합니다.
프로젝트가 발전하면 CLAUDE.md도 함께 업데이트해야 합니다. 더 이상 사용하지 않는 기술이나 변경된 규칙이 남아 있으면 Claude가 잘못된 판단을 내릴 수 있습니다.
CLAUDE.md를 Git에 포함하면 팀원 전체가 Claude Code를 사용할 때 동일한 컨텍스트를 공유합니다. 이는 코딩 컨벤션 준수, 일관된 코드 품질 유지에 효과적입니다.
팀에서 CLAUDE.md를 관리할 때 고려할 점은 다음과 같습니다.
~/.claude/CLAUDE.md에 작성합니다CLAUDE.md는 Claude Code와 효과적으로 협업하기 위한 핵심 도구입니다.
다음 장에서는 CLAUDE.md로 설정한 컨텍스트를 바탕으로, Claude Code의 핵심 워크플로우인 코드 작성, 리뷰, 리팩터링을 실습합니다.
이 글이 도움이 되셨나요?
Claude Code로 코드를 작성하고, 리뷰하고, 리팩터링하는 핵심 워크플로우를 실전 예제와 함께 익힙니다.
Claude Code를 설치하고 기본 설정을 완료한 뒤, 첫 번째 대화형 세션을 실행하는 과정을 단계별로 안내합니다.
Claude Code 훅 시스템의 개념과 라이프사이클을 이해하고, 코드 품질 게이트와 자동화 파이프라인을 구축하는 방법을 다룹니다.