🎓 유데미 강의 추천
Claude Code 실전 강의 — AI 코딩을 지금 시작하세요
설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
강의 보러가기 →
Claude Code 가이드 #2 — CLAUDE.md 완벽 가이드
한 줄 요약: CLAUDE.md는 Claude Code가 프로젝트를 이해하는 설정 파일로, 기술 스택, 코딩 컨벤션, 금지 패턴을 명시하면 AI 응답 품질이 극적으로 향상된다. CLAUDE.md는 Claude Code 세션 시작 시 자동으로 읽히는 프로젝트 가이드라인 파일이다. 🎓 유데미 강의 추천 Claude Code 실전 강의 — AI 코딩을 지금 시작하세요 설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
by Lee
한 줄 요약: CLAUDE.md는 Claude Code가 프로젝트를 이해하는 설정 파일로, 기술 스택, 코딩 컨벤션, 금지 패턴을 명시하면 AI 응답 품질이 극적으로 향상된다.
CLAUDE.md는 Claude Code 세션 시작 시 자동으로 읽히는 프로젝트 가이드라인 파일이다. 잘 작성된 CLAUDE.md는 매번 같은 맥락을 반복 설명할 필요를 없애고, 일관된 코드 품질을 보장한다. 이 가이드는 CLAUDE.md 작성법을 상세히 정리한다.
강의 보러가기 →
왜 CLAUDE.md가 필요한가?
Claude Code는 매 세션마다 새로 시작합니다. 이전 대화 내용을 기억하지 못합니다. CLAUDE.md는 이 문제를 해결합니다.
- 프로젝트 컨텍스트 유지: 기술 스택, 아키텍처, 컨벤션을 매번 설명할 필요 없음
- 일관된 코드 품질: 코딩 스타일, 네이밍 규칙이 매 세션 동일하게 적용
- 실수 방지: 금지사항, 주의사항을 명시하여 반복 실수 차단
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가 작업 후 자동으로 커밋 메시지를 제안합니다.
다음 편 예고
다음 편에서는 CLI 명령어 총정리를 다룹니다. /plan, /copy, /loop 등 생산성을 높이는 슬래시 명령어를 알아봅니다.
고급 CLAUDE.md 패턴
환경별 분리: 루트 CLAUDE.md에 공통 설정, packages/frontend/CLAUDE.md에 프론트엔드 전용 설정. 외부 참조: '자세한 API 스펙은 docs/api.md를 참조하라'처럼 다른 문서를 가리킨다. 검증 명령: 커밋 전 반드시 실행해야 할 명령을 포함하면 AI가 자동으로 검증한다.
팁: CLAUDE.md는 커밋해서 팀원과 공유하라. .cursorrules(Cursor)와 함께 두면, 어떤 AI 도구를 사용하든 일관된 맥락을 제공할 수 있다.
자주 묻는 질문
CLAUDE.md는 얼마나 길게 작성해야 하나요?
500줄 이하를 권장합니다. 너무 길면 Claude Code가 핵심 규칙을 놓칠 수 있습니다. 핵심 규칙에 IMPORTANT: 접두어를 붙이고, 자세한 내용은 외부 문서로 분리하세요.
CLAUDE.md를 팀원과 공유해도 되나요?
네, 권장합니다. git에 커밋해서 공유하면 팀 전체가 동일한 AI 컨텍스트에서 작업할 수 있습니다. 단, API 키나 민감한 정보는 절대 포함하지 마세요.
CLAUDE.md에 넣으면 안 되는 내용이 있나요?
API 키, 비밀번호, 개인정보, 기밀 비즈니스 로직은 절대 포함하지 마세요. 위험한 명령어나 자동 실행되면 안 되는 작업도 포함하지 않는 것이 좋습니다.
여러 디렉토리에 CLAUDE.md를 둘 수 있나요?
네. 프로젝트 루트뿐만 아니라 하위 디렉토리에도 CLAUDE.md를 둘 수 있습니다. 하위 디렉토리의 CLAUDE.md가 우선 적용되므로, 서브패키지별로 다른 규칙을 설정할 수 있습니다.
CLAUDE.md를 작성했는데 Claude Code가 규칙을 따르지 않습니다.
파일이 너무 길거나 규칙이 모호하게 작성된 경우가 많습니다. 규칙을 구체적이고 명확하게 작성하고, 중요 규칙에 IMPORTANT: 접두어를 추가하세요.
🎓 관련 강의
Claude Code 완전 정복 — 유데미 강의
이 글에서 다룬 내용을 더 체계적으로 배우고 싶다면 강의를 확인해보세요. 실전 예제 중심으로 구성되어 있습니다.
강의 살펴보기 →
claude-code클로드 코드claude-md프로젝트설정워크플로우
