Claude Code 종합 설정 가이드

01 CLAUDE.md 계층 구조

왜 설정 파일이 필요한가?

Claude Code는 설정 없이도 작동합니다. 하지만 CLAUDE.md를 추가하면 프로젝트의 기술 스택과 컨벤션을 알고 코드를 작성합니다. 예를 들어 "Next.js App Router 사용, Server Components 기본"이라고 적어두면, 구식 Pages Router 패턴 대신 올바른 코드가 나옵니다.

4단계 계층

Claude Code는 여러 레벨의 설정 파일을 자동으로 읽어들입니다. 더 구체적인 파일이 우선합니다.

02 CLAUDE.md 작성 가이드

핵심 원칙: WHY-WHAT-HOW 프레임워크로 구조화하고, 60~80줄 이하로 유지합니다.

길이 제한 & 토큰 효율성

권장 섹션 구성

효율성 자가 진단

직접 만들어보기

아래 템플릿을 프로젝트 루트에 CLAUDE.md로 저장하고, 주석 부분을 자신의 프로젝트에 맞게 채워보세요:

# [프로젝트 이름]

## Overview
[한 줄로 프로젝트 설명]

## Tech Stack
- [언어/프레임워크]
- [DB/ORM]
- [기타 핵심 도구]

## Commands
- [빌드 명령어]
- [테스트 명령어]
- [린트 명령어]

## Conventions
- [팀 코딩 컨벤션 1~3개]

## Important
- [절대 수정 금지 파일이나 주의사항]

작성 후 Claude Code를 실행하여 "CLAUDE.md 내용을 요약해줘"라고 입력하면 정상 인식 여부를 확인할 수 있습니다.

03 포함할 것 / 제외할 것

CLAUDE.md의 모든 줄은 토큰을 소비합니다. 반드시 필요한 것만 포함하세요.

Progressive Disclosure 패턴

모든 정보를 CLAUDE.md에 넣지 말고, 중요한 정보를 찾는 방법을 알려주세요.

상세 API 가이드는 @docs/api-guide.md 참조
(매 세션마다 전체 파일 임베드됨)

복잡한 API 사용법은 docs/api-guide.md 참조
인증 구현 패턴: src/auth/jwt.ts:15-65

04 7가지 안티패턴

Boris Cherny(Claude Code 창시자) 등 커뮤니티에서 발견된 대표적인 실수들입니다.

05 실전 CLAUDE.md 예시

커뮤니티에서 검증된 실제 CLAUDE.md 구조를 소개합니다.

글로벌 CLAUDE.md (~/.claude/CLAUDE.md)

markdown# 개인 개발 선호도

## 핵심 원칙
- Clean Architecture 우선
- 가독성 > 복잡한 솔루션
- 변경 전 코드베이스 탐색, 복잡한 작업은 계획 후 구현
- 변경 후 테스트 실행

## 코딩 표준
- 모든 함수에 타입 힌트/타입 정의
- 작은 diff 선호 (요청하지 않은 리팩토링 금지)
- 로직 변경 시 테스트 필수
- 접근성: 레이블, 키보드 네비게이션

## 도구 선호도
- 패키지 매니저: bun (npm 대신)
- 린터: Biome (ESLint + Prettier 대체)
- 커밋: Conventional Commits
- 민감 데이터 커밋 금지

## 커뮤니케이션
- 아키텍처 결정 전 명확히 질문
- 비자명한 선택에 이유 문서화
- 코드 주석: 영어 / 문서: 한국어

프로젝트 CLAUDE.md (./CLAUDE.md)

markdown# E-Commerce Platform

## Overview
Next.js 14 기반 전자상거래 플랫폼. App Router 사용.

## Tech Stack
- Next.js 14 (App Router) + TypeScript (strict)
- Prisma + PostgreSQL, Tailwind CSS, Zod

## Architecture
- /app - Pages, layouts, API routes
- /components - 재사용 컴포넌트
- /lib - 유틸리티 및 DB 클라이언트
- /prisma - DB 스키마

## Commands
- npm run dev        # localhost:3000
- npm test           # Jest + RTL
- npm run db:push    # Prisma 스키마 푸시
- npm run lint       # ESLint + Prettier

## Conventions
- Server Components 기본, 인터랙션 필요 시만 'use client'
- DB 쿼리는 /lib/queries에 분리
- Zod 스키마로 모든 입력 검증

## Important
- 결제 코드는 /lib/payments 에서만 수정
- 환경 변수는 .env.example 참고

자기 개선 루프

06 모듈화 (.claude/rules/)

v2.0.64+에서 지원. CLAUDE.md 하나로 부족할 때 도메인별로 규칙을 나눌 수 있습니다.

경로 기반 규칙 예시

yaml + markdown---
paths:
  - "src/backend/**/*.py"
  - "tests/backend/**/*.py"
---

# Backend Python 규칙
- FastAPI 라우트 핸들러 패턴 준수
- Pydantic 모델로 요청/응답 정의
- 비동기 함수 우선 사용

07 settings.json 설정 관리

Claude Code의 핵심 설정 파일. 권한, 플러그인, 환경변수, hooks를 구조화합니다.

설정 우선순위 (5단계)

권한 체인

우선순위: deny > allow > ask > default

json{
  "permissions": {
    "allow": [
      "Read(**/*.{js,ts,tsx,json,md})",
      "Bash(npm *)",
      "Bash(git status)",
      "Bash(git diff*)"
    ],
    "deny": [
      "Read(.env*)",
      "Write(node_modules/**)",
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ],
    "ask": [
      "Bash(git push*)",
      "Bash(git commit*)",
      "Write(package.json)"
    ]
  }
}

08 MCP 서버 관리

MCP(Model Context Protocol)는 Claude Code에 외부 도구를 연결하는 표준 방식입니다. 기본 상태에서는 코드 편집과 터미널 명령만 가능한데, MCP 서버를 연결하면 GitHub PR 관리, 웹 검색, 데이터베이스 조회도 할 수 있습니다.

필수 MCP 서버 Top 5

MCP 설정 파일 (.mcp.json)

json{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
    }
  }
}

09 스킬 관리

스킬(Skill)은 반복적인 워크플로우를 재사용 가능한 명령어로 패키징한 것입니다. 예를 들어 "코드 리뷰" 과정을 스킬로 만들면, 매번 같은 지시를 반복하지 않아도 됩니다. 토큰 절약을 위해 3단계(Tier)로 나눠서 필요한 만큼만 로드합니다.

3-Tier 로딩 시스템

SKILL.md 구조

markdown---
name: code-review
description: 코드 리뷰 수행 시 사용. PR, 코드 변경, 품질 검토 요청 시 자동 활성화.
---

# 코드 리뷰 지침

## 검토 영역
1. **가독성**: 변수명, 함수명, 주석
2. **보안**: SQL 인젝션, XSS, 인증/인가
3. **성능**: 알고리즘 복잡도, 메모리 사용
4. **테스트**: 테스트 커버리지, 엣지 케이스

## 출력 형식
- 긍정적 측면 먼저 언급
- 개선 사항은 구체적 제안과 함께
- 우선순위: Critical / High / Medium / Low

10 Hooks 자동화

Hooks는 Claude Code가 특정 동작을 할 때 자동으로 셸 명령어를 실행하는 기능입니다. 예를 들어 "파일을 저장할 때마다 자동으로 코드 포맷팅 실행" 같은 자동화를 설정할 수 있습니다. Claude의 판단에 의존하지 않고 항상 확실하게 실행됩니다(결정론적 동작).

라이프사이클 이벤트

실전 Hooks 예시

json{
  "hooks": {
    "PostToolUse": [
      {
        "match": "Write(**.py)",
        "command": "black ${file} && isort ${file}",
        "description": "Python 자동 포맷팅"
      },
      {
        "match": "Write(**.{js,ts,tsx})",
        "command": "prettier --write ${file}",
        "description": "JS/TS 포맷팅"
      }
    ],
    "PreToolUse": [
      {
        "match": "Write(config/production.*)",
        "command": "echo 'Production protected'; exit 1",
        "description": "프로덕션 설정 보호"
      },
      {
        "match": "Write(**)",
        "command": "if grep -q 'API_KEY\\|SECRET' ${file}; then exit 1; fi",
        "description": "민감 데이터 검출"
      }
    ],
    "Stop": [
      {
        "command": "notify-send 'Claude Code' 'Task completed'",
        "description": "Linux 데스크톱 알림"
      }
    ]
  }
}

11 Dotfiles & 크로스 환경 동기화

여러 머신에서 일관된 Claude Code 환경을 유지하는 방법입니다.

권장 Dotfiles 구조

심볼릭 링크 설치

bash#!/bin/bash
# install.sh

# 기존 설정 백업
[ -d ~/.claude ] && mv ~/.claude ~/.claude.bak.$(date +%Y%m%d)

# 심볼릭 링크 생성
ln -sf ~/dotfiles/claude/.claude ~/.claude

# 또는 GNU Stow 사용 (권장)
cd ~/dotfiles && stow claude

.gitignore 필수 항목

gitignore# 절대 커밋 금지
.credentials.json
*.local.json
*.local.md
.env*

# 대화 히스토리 (프라이버시)
projects/

# 캐시
*.log
statsig/

커뮤니티 도구

12 비용 최적화

전략적 모델 선택과 캐싱을 조합하면 50~90% 비용 절감이 가능합니다.

모델별 역할 분담

최적화 전략 4가지

13 커뮤니티 사례 & 팁

실제 개발자들의 검증된 워크플로우와 생산성 팁을 모았습니다.

Boris Cherny (Claude Code 창시자) 워크플로우

YK Dojo 45가지 팁 핵심

엔터프라이즈 성공 사례

생산성 핵심 팁

14 참고 리소스

커뮤니티 리소스에서 엄선한 링크 모음입니다.

공식 문서

• Best Practices for Claude Code — 공식 베스트 프랙티스
• Using CLAUDE.MD files — CLAUDE.md 사용법
• Claude Code Settings — 설정 가이드
• Connect to tools via MCP — MCP 연결
• Automate workflows with hooks — Hooks 가이드
• Manage costs effectively — 비용 관리

커뮤니티 가이드

• Writing a good CLAUDE.md — HumanLayer (60줄 벤치마크 출처)
• The Complete Guide to CLAUDE.md — Builder.io 완전 가이드
• Creating the Perfect CLAUDE.md — Dometrain 멀티 언어 예시
• ClaudeLog — 종합 가이드, 튜토리얼, 모범 사례

GitHub 레포지토리

한국어 리소스

• revfactory/claude-code-guide — 한국어 바이브코딩 가이드
• revfactory/claude-code-mastering — 한국어 마스터 가이드북
• PyTorch 한국 커뮤니티 — 30가지 활용 팁

도구 & 유틸리티

• MCPcat.io — MCP 서버 가이드 & 디렉토리
• claude-code-hooks-mastery — Hook 마스터 가이드
• claudekit — 27개 명령어, 7개 모드, 34개 스킬
• awesome-claude-code-subagents — 100+ 전문 서브에이전트

15 FAQ & 트러블슈팅

자주 묻는 질문과 흔한 문제 해결 방법을 모았습니다.

CLAUDE.md 관련

세션 관련

MCP 관련

# 1. 서버 목록 및 상태 확인
claude mcp list

# 2. 특정 서버 로그 확인
claude mcp logs [서버이름]

# 3. 환경변수 확인 (API 키가 설정되어 있는지)
echo $GITHUB_TOKEN
echo $BRAVE_API_KEY

비용 관련

Hooks 관련

기타