Claude Code 환경 설정: CLAUDE.md로 10분 투자해서 수 시간 절약하기

MoreLean 2026. 1. 21. 00:12

2026. 1. 21. 00:12

Claude Code 환경 설정에서 제일 먼저 해야 할 건 CLAUDE.md 파일 만들기입니다.

이 파일은 프로젝트 루트에 두는 일종의 설명서입니다. "이 프로젝트는 뭐고, 어떤 규칙으로 코딩하고, 파일 구조는 어떻고" 다 적어두는 거예요. Claude Code가 작업 시작할 때마다 이 파일을 먼저 읽습니다. 그러면 매번 같은 설명 안 해도 됩니다.

처음 세팅하는 데 10분 걸리지만, 이후에 몇 시간씩 절약됩니다.

TL;DR

CLAUDE.md는 Claude Code의 **"헌법"**이자 영구 기억 장치입니다
매 세션 시작 시 자동으로 로드됩니다
300줄 미만, 짧을수록 좋습니다
포함할 것: 프로젝트 개요, 기술 스택, 코딩 컨벤션, 주요 명령어, 금지 사항
/init 명령으로 시작하고, 점진적으로 다듬어가세요

CLAUDE.md란?

"The single most important file in your codebase for using Claude Code effectively is the root CLAUDE.md. This file is the agent's 'constitution,' its primary source of truth for how your specific repository works." — Shrivu Shankar

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 특별한 파일입니다. 프로젝트에 대한 모든 컨텍스트를 여기에 적어두면, 매번 같은 설명을 반복할 필요가 없습니다.

왜 필요한가?

"Coding agents know absolutely nothing about your codebase at the beginning of each session. The agent must be told anything that's important to know about your codebase each time you start a session. CLAUDE.md is the preferred way of doing this." — HumanLayer Blog

Claude Code는 상태가 없는(stateless) 도구입니다. 매 세션마다 당신의 코드베이스에 대해 아무것도 모릅니다. CLAUDE.md가 없으면:

매번 "이 프로젝트는 React + TypeScript야" 설명해야 함
코딩 컨벤션을 반복해서 알려줘야 함
테스트 명령어를 매번 가르쳐야 함
실수로 건드리면 안 되는 파일을 건드림

CLAUDE.md 위치와 계층 구조

Claude Code는 여러 위치의 CLAUDE.md를 계층적으로 읽습니다:

우선순위 (높음 → 낮음)
─────────────────────────────────────────────────
1. .claude/CLAUDE.md      ← 프로젝트 (.claude 폴더 내)
2. ./CLAUDE.md            ← 프로젝트 루트
3. ~/.claude/CLAUDE.md    ← 사용자 (모든 프로젝트에 적용)
4. 하위 디렉토리 CLAUDE.md ← 해당 디렉토리 작업 시만 로드
─────────────────────────────────────────────────

"Claude Code reads information from CLAUDE.md files in a hierarchical order: first from your home directory (~/.claude/CLAUDE.md), then from your project root, and finally from individual directories." — Dinanjana Gunaratne

각 위치의 용도

위치 용도 Git 커밋

~/.claude/CLAUDE.md	개인 환경설정 (모든 프로젝트)	❌
./CLAUDE.md	팀 공유 프로젝트 설정	✅
.claude/CLAUDE.md	팀 공유 (폴더 정리 선호 시)	✅
./CLAUDE.local.md	개인 설정 (Git 제외)	❌
src/api/CLAUDE.md	특정 디렉토리 전용 규칙	✅

추가 규칙 파일

.claude/rules/ 폴더에 여러 마크다운 파일을 넣으면 자동으로 로드됩니다:

.claude/
├── rules/
│   ├── code-style.md      ← 프론트엔드 팀 관리
│   ├── security.md        ← 보안 팀 관리
│   └── testing.md         ← QA 팀 관리
└── CLAUDE.md              ← 핵심 설정

"All markdown files in .claude/rules/ are automatically loaded with the same priority as your main CLAUDE.md. No imports needed." — Builder.io

CLAUDE.md에 넣어야 할 것

WHAT, WHY, HOW 프레임워크

"At a high level, CLAUDE.md should cover:

WHAT: Tell Claude about the tech, your stack, the project structure

WHY: Tell Claude the purpose of the project

HOW: Tell Claude how it should work on the project" — HumanLayer Blog

필수 포함 항목

프로젝트 개요: 한 줄로 프로젝트 설명
기술 스택: 프레임워크, 언어, 주요 라이브러리
디렉토리 구조: 핵심 폴더와 역할
주요 명령어: 빌드, 테스트, 린트, 배포
코딩 컨벤션: 스타일 가이드, 네이밍 규칙
금지 사항: 절대 건드리면 안 되는 것들

예시: Next.js 프로젝트

# Project: ShopFront

Next.js 14 e-commerce application with App Router, Stripe payments, and Prisma ORM.

## Tech Stack
- **Framework**: Next.js 14 (App Router)
- **Language**: TypeScript (strict mode)
- **Database**: PostgreSQL + Prisma
- **Auth**: NextAuth.js
- **Payments**: Stripe
- **Styling**: Tailwind CSS

## Directory Structure
- `app/` - Next.js App Router pages and layouts
- `components/` - Reusable React components
- `lib/` - Utility functions and shared logic
- `prisma/` - Database schema and migrations
- `public/` - Static assets

## Commands
- `pnpm dev` - Start development server
- `pnpm build` - Production build
- `pnpm test` - Run tests (Jest)
- `pnpm lint` - ESLint check
- `pnpm db:migrate` - Run Prisma migrations
- `pnpm db:studio` - Open Prisma Studio

## Code Style
- Use ES modules (import/export)
- 2-space indentation
- Single quotes for strings
- No semicolons (Prettier handles it)
- Prefer interfaces over types
- No `any` - use `unknown` instead

## IMPORTANT RULES
- NEVER leave console.log in production code
- NEVER commit .env files
- NEVER modify files in `generated/` directory
- Always run `pnpm lint` before committing
- All API routes must have error handling

## Testing
- Unit tests: `__tests__/` folders next to source
- E2E tests: `e2e/` folder with Playwright
- Minimum 80% coverage for new code

/init으로 시작하기

처음부터 직접 작성할 필요 없습니다. /init 명령으로 자동 생성할 수 있습니다:

cd your-project
claude
> /init

Claude가 프로젝트를 분석해서 기본 CLAUDE.md를 생성합니다.

"Run it in your project directory and Claude generates a starter CLAUDE.md based on your project structure and detected tech stack. I use /init as a starting point and delete what I don't need. Deleting is easier than creating from scratch." — Builder.io

/init 후 해야 할 것

불필요한 내용 삭제: 뻔한 것들 제거
누락된 내용 추가: 팀 컨벤션, 워크플로우
금지 사항 명시: "절대 하지 마" 규칙들
Git 커밋: 팀과 공유

"The generated file often includes obvious things you don't need spelled out, or filler that doesn't add value. Because context is precious. Every line in your CLAUDE.md competes for attention with the actual work you're asking Claude to do." — Builder.io

짧게 유지하기: Less is More

300줄 미만 권장

"While Anthropic does not have an official recommendation on how long your CLAUDE.md file should be, general consensus is that < 300 lines is best, and shorter is even better. At HumanLayer, our root CLAUDE.md file is less than sixty lines." — HumanLayer Blog

왜 짧아야 하나?

컨텍스트 경쟁: CLAUDE.md도 컨텍스트 윈도우를 차지함
주의력 분산: 내용이 많으면 중요한 것을 놓침
무시 가능성: 관련 없는 내용이 많으면 Claude가 무시함

"The more information you have in the file that's not universally applicable to the tasks you have it working on, the more likely it is that Claude will ignore your instructions in the file." — HumanLayer Blog

Progressive Disclosure 원칙

모든 걸 CLAUDE.md에 넣지 마세요. 필요할 때 찾아보게 하세요:

## Database Migrations
For complex migration patterns, see `docs/migrations.md`.
Run `pnpm db:migrate --help` for available options.

## API Documentation
Full API spec at `docs/api/openapi.yaml`.
Use Swagger UI: `pnpm docs:api`

"Don't tell Claude all the information you could possibly want it to know. Rather, tell it how to find important information so that it can find and use it, but only when it needs to." — HumanLayer Blog

규칙 강조하기

중요한 규칙은 강조해야 Claude가 잘 따릅니다:

## CRITICAL RULES (DO NOT IGNORE)

⛔ **NEVER** leave console.log in production code
⛔ **NEVER** commit API keys or secrets
⛔ **NEVER** modify files in `generated/` directory
⛔ **NEVER** skip error handling in API routes

✅ **ALWAYS** run tests before committing
✅ **ALWAYS** use TypeScript strict mode
✅ **ALWAYS** handle loading and error states in components

"Add emphasis (e.g., 'IMPORTANT,' 'YOU MUST') to improve Claude's adherence to critical instructions." — Steve Kinney

실제 효과

저는 CLAUDE.md에 "절대 console.log 남기지 마" 같은 규칙을 박아뒀어요. 그랬더니 Claude Code가 알아서 지켜주더라고요. 디버깅용 로그를 넣었다가도 마지막에 자동으로 제거합니다.

# 키로 빠르게 추가하기

세션 중에 규칙을 추가하고 싶다면 **#**으로 시작하면 됩니다:

# Never use deprecated lodash methods
# Prefer native array methods over lodash when possible

이렇게 입력하면 CLAUDE.md에 자동으로 추가됩니다.

"The fastest way to add a memory during a session is by starting your input with the # character." — Steve Kinney

실전 CLAUDE.md 예시

최소 버전 (스타트업 프로젝트)

# Ttokseo (똑서) - 어린이 디지털 독서 플랫폼

React Native + Kotlin/Spring Boot 기반 구독형 교육 서비스.

## Commands
- Mobile: `cd mobile && pnpm start`
- Backend: `cd backend && ./gradlew bootRun`
- Tests: `pnpm test` / `./gradlew test`

## Key Rules
- Korean comments for business logic
- All API responses must include `success`, `data`, `error` fields
- UTC timestamps in DB, KST conversion in frontend
- Never commit .env files

상세 버전 (팀 프로젝트)

# Project: Enterprise Dashboard

Internal analytics dashboard for sales team.
React 18 + TypeScript + GraphQL + PostgreSQL.

## Quick Start
1. `pnpm install`
2. `cp .env.example .env.local`
3. `pnpm db:migrate`
4. `pnpm dev`

## Architecture
- `src/features/` - Feature-based modules (sales, users, reports)
- `src/shared/` - Shared components, hooks, utilities
- `src/graphql/` - GraphQL schema and resolvers
- `prisma/` - Database schema

## Code Standards
- Feature-first folder structure
- Colocation: tests, styles, types next to components
- No barrel exports (index.ts re-exports)
- Prefer server components, client only when needed

## GraphQL Conventions
- Queries: `use{Resource}Query` (e.g., `useSalesQuery`)
- Mutations: `use{Action}{Resource}Mutation` (e.g., `useCreateOrderMutation`)
- Always handle loading, error, data states

## Testing
- Unit: Jest + React Testing Library
- E2E: Playwright
- Run `pnpm test:coverage` before PR

## IMPORTANT
- This dashboard contains sensitive sales data
- Never log PII (names, emails, phone numbers)
- All API calls must go through auth middleware
- Check `docs/security.md` before adding new endpoints

CLAUDE.md vs CLAUDE.local.md

구분 CLAUDE.md CLAUDE.local.md

용도	팀 공유 설정	개인 환경설정
Git	✅ 커밋	❌ gitignore
내용	프로젝트 규칙, 컨벤션	개인 선호, 실험

# CLAUDE.local.md (개인용)

## My Preferences
- I prefer verbose explanations
- Always show full file paths in responses
- Use Korean for comments

## Current Focus
Working on payment integration this week.
Key files: `src/features/payment/`

## Experiments
Testing new caching strategy - see `docs/cache-experiment.md`

CLAUDE.md 유지보수

CLAUDE.md는 살아있는 문서입니다. 프로젝트와 함께 진화해야 합니다.

업데이트 시점

새로운 주요 의존성 추가 시
아키텍처 패턴 변경 시
디렉토리 구조 변경 시
새로운 환경 변수 추가 시
Claude가 반복적으로 실수하는 패턴 발견 시

"Treat customization as an ongoing practice rather than a one-time setup task. Projects change, teams learn better patterns, and new tools enter your workflow. A well-maintained CLAUDE.md evolves with your codebase." — Claude Blog

안티패턴

❌ 모든 명령어 나열: 필요한 것만 ❌ 모든 파일 경로 나열: 핵심 디렉토리만 ❌ 일반적인 조언: 프로젝트 특화된 것만 ❌ 한 번 만들고 방치: 지속적 업데이트 필요

"Don't try to stuff every command Claude could possibly need to run in your CLAUDE.md file - you will get sub-optimal results." — HumanLayer Blog

체크리스트

초기 설정

[ ] /init으로 기본 파일 생성
[ ] 불필요한 내용 삭제
[ ] 프로젝트 개요 추가
[ ] 핵심 명령어 추가
[ ] 금지 사항 명시 (IMPORTANT 강조)
[ ] Git 커밋

지속적 관리

[ ] Claude가 반복 실수하면 규칙 추가
[ ] 새 패턴/도구 도입 시 업데이트
[ ] 300줄 미만 유지
[ ] 팀원과 주기적 리뷰

고급 설정

[ ] ~/.claude/CLAUDE.md로 개인 전역 설정
[ ] .claude/rules/로 모듈화 (대규모 팀)
[ ] CLAUDE.local.md로 개인 실험

마무리

CLAUDE.md는 Claude Code의 가장 높은 레버리지 포인트입니다.

기억하세요:

10분 투자로 수 시간 절약
짧게 유지 (300줄 미만, 짧을수록 좋음)
핵심만 포함 (WHAT, WHY, HOW)
금지 사항은 강하게 강조
지속적으로 업데이트

"The more thought put into Claude.md files, the better Claude Code performs." — Anthropic: How Anthropic teams use Claude Code

프로젝트에 처음 Claude Code를 도입한다면, 오늘 바로 CLAUDE.md를 만드세요. 10분이면 됩니다. 그 10분이 앞으로 수십 시간을 절약해줄 겁니다.

참고 자료

Anthropic 공식

Using CLAUDE.md Files — Claude Blog
Claude Code Best Practices — Anthropic Engineering
Claude Code Settings — Official Docs

커뮤니티

Writing a Good CLAUDE.md — HumanLayer Blog
The Complete Guide to CLAUDE.md — Builder.io
How I Use Every Claude Code Feature — Shrivu Shankar
CLAUDE.md Guide — Steve Kinney

'Programmer > AI' 카테고리의 다른 글

Claude Code Skills & Agents: 전문가 팀을 내 손안에 (0)	2026.01.21
Claude Code Hooks: 자동화로 실수를 원천 차단하기 (0)	2026.01.21
Claude Code 컨텍스트 관리: 채워질수록 썩는 작업 기억 (1)	2026.01.20
Claude Code의 게임체인저: Plan Mode vs YOLO Mode (1)	2026.01.20
Claude Code는 시니어가 아니라 "똑똑한 주니어"다 (0)	2026.01.20

MoreLean