CLAUDE.md 완전 가이드 — Claude 코드를 프로젝트 맞춤형 AI로 전환

Source: Dev.to

Claude Code의 출력이 일반적이라고 느껴진다면, 해결 방법은 간단합니다: CLAUDE.md 파일을 작성하세요.
CLAUDE.md는 프로젝트 루트에 두는 설정 파일입니다. Claude Code는 매 상호작용 시 자동으로 이를 읽어, 추측하는 대신 프로젝트별 규칙을 따릅니다.

CLAUDE.md가 중요한 이유

Without CLAUDE.md, Claude Code makes assumptions about:

• 귀하의 코딩 규칙(탭 vs. 스페이스, 명명 스타일)
• 귀하의 아키텍처(새 파일을 어디에 넣을지)
• 귀하의 테스트 전략(무엇을 테스트하고, 어떻게 테스트할지)
• 귀하의 빌드 명령(실행, 린트, 배포 방법)

With CLAUDE.md, you explicitly define all of this. The difference is dramatic:

4‑섹션 구조

효과적인 모든 CLAUDE.md는 다음 섹션을 포함합니다:

# CLAUDE.md

빠른 참고

[팀이 매일 실행하는 명령]

아키텍처

[디렉터리 구조 및 디자인 패턴]

Rules

[코딩 규칙, 테스트 요구사항]

제약조건

[하지 말아야 할 것]

템플릿 1: 파이썬 백엔드 (FastAPI)

# CLAUDE.md

빠른 참고

Run: make dev | Test: make test | Lint: make lint
DB: make db-migrate | Docker: docker compose up -d

Architecture

• app/routers/ — 얇은 API 엔드포인트
• app/services/ — 비즈니스 로직
• app/models/ — SQLAlchemy ORM
• app/core/ — 설정, 인증, 미들웨어

규칙

• 라우터는 요청을 파싱하고 → 서비스를 호출하고 → 응답을 반환합니다 (비즈니스 로직 없음)
• 새로운 엔드포인트는 반드시 인증 테스트를 포함해야 합니다: 401, 403, 404, 422
• 비밀은 os.environ.get("KEY", "") 로 가져오며 — 기본값을 하드코딩하지 마세요
• 라우터당 최대 300줄, 서비스 파일당 최대 400줄

템플릿 2: React/Next.js 프론트엔드

# CLAUDE.md

빠른 참고

Dev: npm run dev | Build: npm run build | Test: npm test

아키텍처

• src/components/ — 재사용 가능한 UI 컴포넌트
• src/features/ — 기능 모듈
• src/hooks/ — 커스텀 훅
• src/lib/ — 유틸리티, API 클라이언트

규칙

• 함수형 컴포넌트 + TypeScript만
• 상태: React Query(서버), useState/useReducer(로컬)
• 스타일링: Tailwind CSS만 — 인라인 스타일 금지
• import 순서: React → 라이브러리 → 내부 → 타입
• 접근성: 버튼에 aria-label, 이미지에 alt

템플릿 3: 데이터 과학 / 머신러닝

# CLAUDE.md

빠른 참고

Jupyter: jupyter lab | 테스트: pytest tests/

아키텍처

• notebooks/ — 탐색 (번호 매김: 01_, 02_)
• src/data/ — 데이터 가져오기, 전처리
• src/models/ — 모델 정의, 학습
• src/evaluation/ — 메트릭, 시각화

Rules

• 탐색용 노트북만 사용 — 프로덕션 코드는 src/에 둡니다
• config.yaml에서 데이터 경로를 가져옵니다 (절대 하드코딩 금지)
• 무작위 시드 MUST 고정 (재현성 확보)
• 큰 데이터 파일은 .gitignore에 포함합니다

3 안티‑패턴 피하기

1. 모호한 규칙

# ❌ Bad
- Write clean code
- Write tests

# ✅ Good
- Functions max 50 lines. Split if longer
- Every new API endpoint needs auth tests (401/403)

구체적인 숫자와 조건을 제시하면 AI가 규칙을 정확히 따릅니다.

2. 너무 길게

1,000줄짜리 CLAUDE.md는 도움이 되기보다 오히려 해롭습니다—컨텍스트 창을 많이 차지하니까요. 50‑150줄 정도로 유지하세요. 규모가 큰 프로젝트라면 .claude/rules/ 디렉터리로 나눕니다:

.claude/
  rules/
    development.md
    architecture.md
    testing.md

Claude Code는 .claude/rules/에 있는 파일을 자동으로 로드합니다.

3. 명령어 누락

Quick Reference 섹션이 없으면 AI가 어떤 명령을 실행해야 할지 추측하게 됩니다. 항상 다음과 같이 포함하세요:

빠른 참고

개발: npm run dev | 테스트: npm test | 린트: npm run lint

오늘 시작하세요

위 템플릿을 복사하고 프로젝트에 맞게 커스터마이즈한 뒤, 프로젝트 루트에 CLAUDE.md 로 저장하세요. 약 15 분 정도 걸리며 Claude Code가 코드베이스와 작동하는 방식을 근본적으로 바꿉니다.

AI와 함께 전문 개발 환경을 설정하고 싶으신가요? DigitalOcean에서 $200 무료 크레딧을 제공하니—개발 서버, CI/CD 파이프라인, 스테이징 환경 운영에 안성맞춤입니다.

Claude Code로 빌드하고 계신가요? 댓글에 CLAUDE.md 설정을 공유해주세요 — 다른 사람들이 프로젝트를 어떻게 구성하는지 보고 싶습니다.