Claude Code 가이드

Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드

프로젝트 루트에 놓는 CLAUDE.md 파일의 역할, 작성법, 실전 예시를 정리한다. 규칙 수·구조·갱신 주기별 베스트 프랙티스와 디렉토리별 분산 전략까지 포함한 완벽 가이드.

2026-01-20

한 줄 요약: CLAUDE.md는 Claude Code가 프로젝트를 이해하는 설정 파일로, 기술 스택, 코딩 컨벤션, 금지 패턴을 명시하면 AI 응답 품질이 극적으로 향상된다.

CLAUDE.md는 Claude Code 세션 시작 시 자동으로 읽히는 프로젝트 가이드라인 파일이다. 잘 작성된 CLAUDE.md는 매번 같은 맥락을 반복 설명할 필요를 없애고, 일관된 코드 품질을 보장한다. 이 가이드는 CLAUDE.md 작성법을 상세히 정리한다.

왜 CLAUDE.md가 필요한가?

Claude Code는 매 세션마다 새로 시작합니다. 이전 대화 내용을 기억하지 못합니다. CLAUDE.md는 이 문제를 해결합니다.

프로젝트 컨텍스트 유지: 기술 스택, 아키텍처, 컨벤션을 매번 설명할 필요 없음
일관된 코드 품질: 코딩 스타일, 네이밍 규칙이 매 세션 동일하게 적용
실수 방지: 금지사항, 주의사항을 명시하여 반복 실수 차단

왜 CLAUDE.md가 필요한가? — CLI 실행 화면과 출력 결과 — Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드 — CLI 실행 화면과 출력 결과 (출처: 공식 문서 및 벤치마크 데이터 기반)

CLAUDE.md의 위치와 범위: 프로젝트 루트의 CLAUDE.md가 해당 프로젝트의 기본 설정이 된다. ~/.claude/CLAUDE.md에 전역 설정을 넣으면 모든 프로젝트에 적용된다. 서브디렉토리에도 CLAUDE.md를 둘 수 있어 모노레포에서 패키지별 설정이 가능하다.

CLAUDE.md 기본 구조
# CLAUDE.md

## 프로젝트 개요
Next.js 15 + TypeScript + Tailwind CSS 기반 SaaS

## 기술 스택
- Runtime: Node.js 20
- ORM: Prisma + PostgreSQL
- Auth: NextAuth.js v5
- UI: shadcn/ui

## 코딩 컨벤션
- 서버 컴포넌트 우선
- 에러 처리: Result 패턴
- 파일명: kebab-case

## 금지 패턴
- any 타입 사용 금지
- console.log 커밋 금지
- 인라인 스타일 금지

좋은 CLAUDE.md의 특징: 1) 기술 스택과 버전을 명시 — AI가 정확한 API를 사용한다. 2) 파일 구조를 설명 — 어떤 디렉토리에 무엇이 있는지. 3) 금지 패턴을 명시 — '하지 말아야 할 것'이 '해야 할 것'보다 중요하다. 4) 배포/테스트 명령어 포함 — AI가 직접 빌드와 테스트를 실행할 수 있다.

CLAUDE.md 기본 구조

CLAUDE.md 템플릿
# CLAUDE.md

## 프로젝트 정의
이 프로젝트는 [설명].

## 기술 스택
- Next.js 14 (Pages Router)
- React 18
- Vercel 배포

## 코딩 규칙
1. TypeScript strict 모드
2. 함수형 컴포넌트만 사용
3. CSS-in-JS 대신 Tailwind

## 금지 사항
- any 타입 사용 금지
- console.log 커밋 금지

## 파일 구조
pages/ → 라우팅
components/ → 재사용 컴포넌트
data/ → 정적 데이터

효과적인 CLAUDE.md 작성 팁

구체적으로 작성: "좋은 코드를 작성해" 대신 "함수는 30줄 이내, 단일 책임 원칙 준수"
예시 포함: 올바른 패턴과 잘못된 패턴을 모두 보여주기
계층 구조: 프로젝트 루트 + 하위 디렉토리에도 CLAUDE.md 가능 (하위가 우선)
정기 업데이트: 프로젝트가 변하면 CLAUDE.md도 업데이트

CLAUDE.md 기본 구조 — 설정 구조와 워크플로우 다이어그램 — Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드 — 설정 구조와 워크플로우 다이어그램 (출처: 공식 문서 및 벤치마크 데이터 기반)

💡 실전 팁: CLAUDE.md에 "매 답변 후 커밋 메시지 제안"을 넣으면, Claude Code가 작업 후 자동으로 커밋 메시지를 제안합니다.

다음 편 예고

다음 편에서는 CLI 명령어 총정리를 다룹니다. /plan, /copy, /loop 등 생산성을 높이는 슬래시 명령어를 알아봅니다.

효과적인 CLAUDE.md 작성 팁 — 에러 해결 프로세스 흐름도 — Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드 — 에러 해결 프로세스 흐름도 (출처: 공식 문서 및 벤치마크 데이터 기반)

📘 Claude Code 공식 문서 보기

고급 CLAUDE.md 패턴

환경별 분리: 루트 CLAUDE.md에 공통 설정, packages/frontend/CLAUDE.md에 프론트엔드 전용 설정. 외부 참조: '자세한 API 스펙은 docs/api.md를 참조하라'처럼 다른 문서를 가리킨다. 검증 명령: 커밋 전 반드시 실행해야 할 명령을 포함하면 AI가 자동으로 검증한다.

팁: CLAUDE.md는 커밋해서 팀원과 공유하라. .cursorrules(Cursor)와 함께 두면, 어떤 AI 도구를 사용하든 일관된 맥락을 제공할 수 있다.

claude-code클로드 코드claude-md프로젝트설정워크플로우

← 이전
Claude Code 가이드 #1 — 개요와 설치 다음 →
Claude Code 가이드 #3 — CLI 명령어 총정리