Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드
프로젝트 루트에 놓는 CLAUDE.md 파일의 역할, 작성법, 실전 예시. 코딩 표준, 아키텍처 결정, 라이브러리 설정까지.
CLAUDE.md는 프로젝트 루트에 놓는 마크다운 파일로, Claude Code가 모든 세션 시작 시 읽습니다. 코딩 표준, 아키텍처 결정, 선호 라이브러리, 리뷰 체크리스트를 설정할 수 있습니다.
CLAUDE.md를 잘 작성하면 Claude Code의 출력 품질이 극적으로 향상됩니다.
왜 CLAUDE.md가 필요한가?
Claude Code는 매 세션마다 새로 시작합니다. 이전 대화 내용을 기억하지 못합니다. CLAUDE.md는 이 문제를 해결합니다.
- 프로젝트 컨텍스트 유지: 기술 스택, 아키텍처, 컨벤션을 매번 설명할 필요 없음
- 일관된 코드 품질: 코딩 스타일, 네이밍 규칙이 매 세션 동일하게 적용
- 실수 방지: 금지사항, 주의사항을 명시하여 반복 실수 차단
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가 작업 후 자동으로 커밋 메시지를 제안합니다.
다음 편 예고
다음 편에서는 CLI 명령어 총정리를 다룹니다. /plan, /copy, /loop 등 생산성을 높이는 슬래시 명령어를 알아봅니다.
claude-codeclaude-md프로젝트설정워크플로우