CLAUDE.md 베스트 프랙티스: 실무 프로젝트를 위한 설정 템플릿

CLAUDE.md는 매 세션마다 프로젝트 구조와 규칙을 다시 설명하지 않기 위한 팀의 작업 설명서입니다. 하지만 긴 문서를 무조건 넣으면 컨텍스트가 커지고 지시 준수율이 떨어집니다.

팀 규칙은 짧고 검증 가능하게 쓰고, 개인 메모는 local memory에 두며, 강제해야 하는 보안 규칙은 permissions와 hooks로 처리합니다. 이 글은 CLAUDE.md에 무엇을 두고 무엇을 밖으로 빼야 하는지, 초보자도 바로 적용할 수 있는 방식으로 설명합니다.

목표는 복사해서 시작할 수 있는 템플릿을 제공하고, 팀이 나중에 리뷰하면서 규칙을 계속 유지할 수 있게 만드는 것입니다.

Core idea: CLAUDE.md is guidance, not enforcement

팀 규칙은 짧고 검증 가능하게 쓰고, 개인 메모는 local memory에 두며, 강제해야 하는 보안 규칙은 permissions와 hooks로 처리합니다. 공식 문서 기준으로 CLAUDE.md는 안내 문맥이고, Auto memory는 로컬 학습 기록이며, settings는 클라이언트 동작을 설정하고, hooks는 정해진 이벤트에서 명령을 실행합니다.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to place CLAUDE.md files

Claude Code는 작업 디렉터리에서 상위 방향으로 CLAUDE.md와 CLAUDE.local.md를 읽습니다. 루트 규칙은 세션 시작부터 들어오고, 중첩 규칙은 관련 파일을 읽을 때 들어옵니다. 공유 규칙은 루트에, 개인 메모는 local 파일에 둡니다.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What to keep in always-loaded memory

항상 로드되는 메모리에는 빌드 명령, 테스트 명령, 아키텍처 경계, 네이밍 규칙, 금지 패턴, 리뷰 게이트를 둡니다. secrets, 긴 로그, 회의 기록, 일회성 계획, 전체 리서치 노트는 제외합니다.

Keep build, test, lint, type-check, and release verification commands.
Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
Do not paste entire official docs. Keep the URL and the decision rule.

Copy-paste CLAUDE.md template

아래 템플릿은 컨텍스트를 무겁게 만들지 않도록 짧게 유지했습니다. 프로젝트에 맞게 바꾸되, 각 규칙은 검증 가능하게 적으세요.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use imports and .claude/rules carefully

@path import는 정리에 유용하지만 token 절약 수단은 아닙니다. import된 내용도 컨텍스트에 들어갑니다. 큰 프로젝트에서는 오래된 내용을 지우고, path별 규칙은 .claude/rules/로 옮깁니다.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three practical use cases

실무에서는 온보딩, 버그 수정, 콘텐츠 제작 세 가지 장면에서 가장 효과가 큽니다. 온보딩에서는 프로젝트 지도와 검증 명령을 먼저 적습니다.
버그 수정에서는 재현 명령, 로그 위치, 최소 테스트 명령을 적어 불필요한 탐색을 줄입니다.
콘텐츠 workflow에서는 tone, 내부 링크, 품질 게이트를 CLAUDE.md에 두고 긴 노트는 Obsidian이나 docs에 둡니다.

Failure cases and pitfalls

대표 실패는 README 전체 import, 모호한 규칙, 보안 정책을 CLAUDE.md에만 쓰는 것입니다. 해결책은 항상 필요한 규칙만 남기고 세부 문서는 필요할 때 읽게 하는 것입니다.
“좋게 정리” 같은 모호한 지시 대신 실행할 명령과 파일 경계를 정확히 씁니다.
보안 강제에는 permissions와 PreToolUse hooks가 필요합니다. CLAUDE.md만으로는 충분하지 않습니다.

Team maintenance rule

CLAUDE.md는 같은 실수가 두 번 반복되거나, 리뷰 코멘트가 반복되거나, 명령과 아키텍처 경계가 바뀌었을 때만 업데이트합니다.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

Next step and monetization path

지식 워크플로는 Obsidian 연동 글과 함께 읽고, 팀 도입은 상담 페이지로 연결하는 것이 좋습니다. 전체 workflow는 Obsidian 연동, token optimization, 상담 페이지와 연결하면 좋습니다. Related articles: Obsidian workflow, productivity tips, permissions guide, and consultation page.

What was verified

이번 업데이트는 공식 memory, context window, settings, commands 문서를 기준으로 modern Claude Code 동작에 맞췄습니다. Official references: memory, context window, settings, and commands.