Claude.md로 더욱 스마트하게 claude를 써보자 !

개발 프로젝트를 시작할 때마다 동일한 패턴과 규칙을 Claude에게 반복 설명하는 것에 지치지 않나요? Claude Code와 claude.md 파일을 활용하면 이런 번거로움을 완전히 해결할 수 있습니다. 이 글에서는 claude.md를 통해 AI 페어 프로그래밍의 효율성을 극대화하는 방법을 실전 예시와 함께 자세히 알아보겠습니다.

Claude Code는 단순한 AI 코딩 도구가 아닙니다. 프로젝트의 맥락을 이해하고, 팀의 개발 규칙을 학습하며, 일관된 코딩 스타일을 유지할 수 있는 강력한 페어 프로그래밍 파트너입니다. 그리고 이 모든 것의 핵심에 claude.md 파일이 있습니다.

Claude.md란 무엇인가요?

Claude.md는 Claude Code가 자동으로 읽어들이는 마크다운 파일입니다. 새로운 개발자가 팀에 합류했을 때 받는 온보딩 문서와 비슷한 역할을 하죠. 프로젝트의 기술 스택, 개발 규칙, 워크플로우, 그리고 암묵적인 컨벤션들을 Claude에게 알려주는 '프로젝트 설명서’라고 생각하시면 됩니다.

Claude Code는 프로젝트를 열 때마다 이 파일을 자동으로 읽고, 그 안에 담긴 정보를 바탕으로 프로젝트에 최적화된 코드를 작성합니다. 한 번 작성해두면 Claude는 이 정보를 영구적으로 기억하며, 새로운 세션이나 다른 브랜치에서도 동일한 컨텍스트를 유지합니다.

Claude.md 사용법: 프로젝트 맥락 구축하기

Claude.md의 가장 큰 장점은 프로젝트의 "암묵적 룰"을 문서화할 수 있다는 점입니다. 예를 들어, 팀에서 ES 모듈을 사용하기로 했지만 이를 명시적으로 문서화하지 않은 경우, Claude는 CommonJS 방식으로 코드를 작성할 수 있습니다. 하지만 claude.md에 이런 규칙을 명시해두면:

# 개발 규칙
- ES 모듈 사용 (import/export 구문 사용)
- API 호출은 반드시 try-catch로 감싸기
- TypeScript에서 'any' 타입 사용 금지

이렇게 작성해두면 Claude는 항상 이 규칙들을 준수하면서 코드를 작성하게 됩니다.

또한 디렉토리 구조와 각 폴더의 역할도 명확히 정의할 수 있습니다:

# 프로젝트 구조
- `src/components`: 재사용 가능한 UI 컴포넌트
- `src/lib`: 핵심 비즈니스 로직
- `src/utils`: 헬퍼 함수들
- `scripts/`: 빌드 및 배포 스크립트

Claude.md 베스트 프랙티스

기술 스택과 버전 명시

버전 정보는 매우 중요합니다. Next.js 13과 15는 완전히 다른 접근 방식을 요구하기 때문이죠:

# 기술 스택
- Framework: Next.js 14
- Language: TypeScript 5.2
- Styling: Tailwind CSS 3.4
- Database: Prisma 5.x + PostgreSQL
- State Management: Zustand 4.x

개발 규칙 세부 명시

Claude가 따라야 할 구체적인 규칙들을 명시할 수 있습니다 !:

# 개발 규칙
- 모든 API 호출은 try-catch로 래핑
- 컴포넌트는 함수형으로 작성 (React hooks 사용)
- CSS-in-JS 대신 Tailwind 클래스 사용
- 상태 관리는 Zustand store 패턴 준수
- 에러 처리는 toast 알림 사용

워크플로우 문서화

개발 워크플로우도 중요한 정보입니다:

# 워크플로우
- 브랜치명: feature/TICKET-123-description
- 커밋 메시지: conventional commits 규칙 준수
- PR 전 반드시 lint 및 type check 통과
- 테스트 커버리지 80% 이상 유지

Claude 전용 지시사항

Claude가 특별히 주의해야 할 사항들을 추가할 수 있습니다:

# Claude 지시사항
- 레거시 코드 리팩토링 시 주의 (동작하는 코드는 건드리지 말 것)
- 접근성 검사 생략하지 말 것
- 설정 파일 수정 시 반드시 확인 요청
- 중요한 변경사항은 TODO 코멘트로 표시

컨텍스트 스위처로서의 Claude.md

Claude.md는 단순한 규칙 파일이 아닙니다. 프로젝트의 다양한 부분에서 서로 다른 규칙을 적용할 수 있는 ‘컨텍스트 스위처’ 역할을 합니다.

Claude Code는 여러 위치에서 CLAUDE.md 파일을 찾아 결합합니다:

1. 홈 디렉토리 (~/.claude/CLAUDE.md): 모든 Claude Code 세션에 전역적으로 적용
2. 프로젝트 루트 (your-repo/CLAUDE.md): 가장 일반적인 위치로 버전 관리에 포함
3. 서브 디렉토리 (your-repo/feature/CLAUDE.md): 특정 기능 작업 시 적용
4. 로컬 오버라이드 (CLAUDE.local.md): 개인 설정용 (gitignore에 추가)

예를 들어, 엔티티 디렉토리에서 작업할 때만 적용되는 규칙을 만들 수 있습니다:

# src/entities/CLAUDE.md
- 모든 엔티티는 Zod 스키마 검증 필수
- 데이터베이스 관련 로직만 포함
- 비즈니스 로직은 services 레이어로 분리

이렇게 하면 엔티티 디렉토리에서 작업할 때 Claude가 자동으로 이 규칙들을 적용합니다.

프로젝트 성장에 따른 진화

Claude.md는 프로젝트와 함께 관리되어야 합니다. 새로운 기능이 추가되거나 개발 방식이 변경될 때마다 업데이트해볼 수도 있어요 ! Claude에게 이전 커밋들을 검토하게 하고 claude.md 업데이트를 제안하도록 할 수도 있습니다:

claude -p "최근 10개 커밋을 검토하고 CLAUDE.md에 추가해야 할 새로운 패턴이나 규칙이 있는지 확인해줘"

Claude Code 설정하기

Claude Code를 시작하는 것은 매우 간단합니다.

설치 과정

# Claude Code CLI 설치
npm install -g @anthropic-ai/claude-code

# 버전 확인
claude --version

# 프로젝트 디렉토리로 이동
cd your-project

# Claude Code 실행
claude

예를 들어서 어떻게 작성할 수 있을까?

다음은 Next.js 프로젝트를 위한 완전한 claude.md 예시입니다:

# 프로젝트: E-commerce Dashboard

## 기술 스택
- Framework: Next.js 14.0 (App Router)
- Language: TypeScript 5.2
- Styling: Tailwind CSS 3.4
- Database: Prisma 5.x + PostgreSQL
- Authentication: NextAuth.js 4.x
- State Management: Zustand 4.x
- UI Components: Radix UI + Shadcn/ui

## 프로젝트 구조
- `app/`: Next.js 13+ App Router 구조
- `components/ui/`: Shadcn/ui 기반 재사용 컴포넌트
- `components/`: 비즈니스 로직 컴포넌트
- `lib/`: 유틸리티 및 설정
- `stores/`: Zustand 상태 관리
- `types/`: TypeScript 타입 정의

## 개발 규칙
- 모든 컴포넌트는 TypeScript로 작성
- 서버 컴포넌트 우선 사용, 필요시에만 클라이언트 컴포넌트
- API 경로는 `/app/api/` 디렉토리 사용
- 데이터베이스 접근은 Prisma Client를 통해서만
- 상태 관리는 Zustand store 패턴 준수
- 스타일링은 Tailwind CSS 클래스만 사용

## 명령어
- `npm run dev`: 개발 서버 실행
- `npm run build`: 프로덕션 빌드
- `npm run lint`: ESLint 실행
- `npm run type-check`: TypeScript 검사
- `npx prisma studio`: 데이터베이스 GUI

## 코딩 컨벤션
- 컴포넌트명: PascalCase
- 파일명: kebab-case
- 변수명: camelCase
- 상수: UPPER_SNAKE_CASE
- 인터페이스: `I` 접두사 사용 안함

## 브랜치 및 커밋
- 브랜치명: `feature/TASK-123-short-description`
- 커밋 메시지: Conventional Commits 규칙
- PR 전 반드시 `npm run lint && npm run type-check` 통과

## Claude 지시사항
- 'any' 타입 사용 절대 금지
- 컴포넌트 작성 시 접근성 고려 필수
- 에러 핸들링은 toast 알림 사용
- 로딩 상태는 Suspense 경계 활용
- 중요한 비즈니스 로직 변경 시 TODO 코멘트로 표시

Claude와 Claude.md가 개발을 혁신하는 방법

Claude.md를 제대로 활용하면 개발 경험이 완전히 바뀝니다. 더 이상 같은 설명을 반복할 필요가 없고, Claude는 프로젝트의 맥락을 완벽하게 이해한 상태로 코드를 작성합니다. 팀 전체가 일관된 코딩 스타일을 유지할 수 있고, 새로운 팀원도 빠르게 프로젝트에 적응할 수 있어요.

특히 복잡한 엔터프라이즈 프로젝트에서는 claude.md가 없으면 Claude가 프로젝트의 복잡성을 이해하기 어려울 수 있습니다. 하지만 잘 작성된 claude.md 하나로 Claude를 프로젝트의 완벽한 페어 프로그래밍 파트너로 만들 수도 있겠죠 !