# Claude Code 완벽 가이드 (한글 요약본)

박성수·2025년 12월 5일
AIClaudeClaude 활용법ai devclaude codeclaude code 사용법

AI 알고쓰자

목록 보기
1/2

원문: Cooking with Claude Code: The Complete Guide
작성: Siddharth Bharath | 2025년 7월 8일 (11월 25일 업데이트)

목차

  1. Claude Code란?
  2. 초기 설정
  3. 세 가지 채팅 모드
  4. 프로젝트 메모리 - CLAUDE.md
  5. 컨텍스트 관리
  6. 서브에이전트 활용
  7. Git 워크플로우
  8. 커스텀 슬래시 명령
  9. MCP 서버
  10. Hooks 자동화
  11. 테스트 전략
  12. CI/CD 파이프라인
  13. 성능 최적화
  14. 웹/모바일/데스크톱 인터페이스

개발 시 유용한 슬래시 커맨드

🔥 자주 쓰는 핵심 커맨드

커맨드용도
/compact대화 압축 (토큰 절약하면서 맥락 유지)
/context토큰 사용량 시각화
/cost비용 확인
/modelAI 모델 전환 (예: Opus ↔ Sonnet)
/review코드 리뷰 요청

📝 대화 관리

커맨드용도
/clear대화 기록 완전 삭제
/compact대화 압축 (맥락은 유지) ← clear 대신 추천
/rewind이전 상태로 되돌리기
/resume이전 세션 이어서 작업

🛠 프로젝트 관리

커맨드용도
/initCLAUDE.md 생성
/memory영구 메모 편집
/todos작업 목록 표시

🔍 문제 해결

커맨드용도
/doctor설치 상태 검진
/status버전, 모델, 계정 상태 확인
/mcpMCP 서버 연결 상태

💡 팁: /clear vs /compact

/clear → 완전 초기화 (맥락 전부 삭제)
/compact → 대화 압축 (핵심 맥락은 유지, 토큰만 절약)

챕터별 요약

1. Claude Code란?

Claude Code는 Anthropic의 CLI 기반 AI 코딩 에이전트입니다.

핵심 특징:

  • Sonnet 4.5, Opus 4.5 등 최신 모델 사용
  • 뛰어난 컨텍스트 관리 및 툴 호출 능력
  • 작업 계획 수립 후 순차적 실행
  • Todo 리스트 자동 관리
  • 프로액티브한 문제 해결 (한 파일의 문제를 다른 파일에서도 자동 수정)

2. 초기 설정

# 설치
curl -fsSL https://claude.ai/install.sh | bash

# 프로젝트 시작
mkdir my-project
cd my-project
claude

인증 방식:

  • API 키 사용
  • 기존 Claude 계정 연동 (월 $20부터)

3. 세 가지 채팅 모드

모드특징사용 시점
Default요청 → 제안 → 승인 → 실행신중한 작업, 학습 시
Auto승인 없이 자동 실행반복 작업, 신뢰할 수 있는 작업
Plan확장 사고로 전략 수립복잡한 기능, 새 프로젝트 시작

Plan Mode 분석 깊이 조절:

  • think - 기본 분석
  • think hard - 심층 분석
  • ultrathink - 최대 깊이 분석

4. 프로젝트 메모리 - CLAUDE.md

프로젝트의 규약, 결정사항, 컨텍스트를 저장하여 세션 간 유지합니다.

# 초기화
/init

계층 구조:

~/.claude/CLAUDE.md          # 전역 설정
├── 프로젝트/CLAUDE.md       # 프로젝트 표준
│   ├── backend/CLAUDE.md    # 백엔드 규칙
│   ├── frontend/CLAUDE.md   # 프론트엔드 규칙
│   └── docs/CLAUDE.md       # 문서화 규칙

5. 컨텍스트 관리

핵심 전략:
1. 한 프로젝트/기능당 하나의 채팅 유지
2. 완료 후 /clear 명령으로 초기화
3. /resume으로 이전 세션 복귀
4. 대규모 프로젝트는 plan.md로 분할

컨텍스트 압축:

/compact Focus on preserving authentication and database schema

6. 서브에이전트 활용

메인 Claude (조율자)
├── 코드 리뷰어
├── 테스트 엔지니어
└── 문서 작성자
/agents

각 서브에이전트는 독립적 컨텍스트를 유지하여 메인 채팅 과부하 방지

7. Git 워크플로우

기본 흐름:
1. 새 기능 → 새 브랜치
2. 개발 완료 → 테스트
3. 성공 → 문서 업데이트 및 커밋
4. 완료 → 메인에 머지

Git Worktrees (병렬 개발):

git worktree add ../project-feature-a -b feature/feature-a
git worktree add ../project-feature-b -b feature/feature-b
git worktree list

체크포인트:

/rewind

8. 커스텀 슬래시 명령

mkdir -p .claude/commands

예시 - .claude/commands/review.md:

포괄적 코드 리뷰 수행:
1. 코딩 규칙 준수 확인
2. 에러 처리 및 로딩 상태 검증
3. 접근성 표준 확인
4. 테스트 커버리지 검토
5. 보안 취약점 확인
6. 성능 영향 평가

팀원이 저장소 클론하면 자동 공유됨

9. MCP 서버

외부 도구/데이터소스 연결 (Jira, GitHub, 웹 검색 등)

# 추가
claude mcp add brave-search -s project -- npx @modelcontextprotocol/server-brave-search

# 확인
/mcp

10. Hooks 자동화

실행 시점:

  • PreToolUse - 도구 실행 전
  • PostToolUse - 도구 완료 후
  • Notification - 알림 발송 시
  • Stop - 작업 완료 시
/hooks

11. 테스트 전략

├── 단위 테스트 (유틸리티 함수)
├── 컴포넌트 테스트 (React Testing Library)
├── 통합 테스트 (API 엔드포인트)
├── E2E 테스트 (중요 워크플로우)
└── 성능 테스트

Claude Code가 비즈니스 로직을 이해하고 엣지 케이스 포함 테스트 자동 생성

12. CI/CD 파이프라인

PR 체크: 테스트 → TypeScript 컴파일 → 포맷팅 → 린트 → 빌드 → 보안 검사

Main 머지: 위 검사 + 스테이징 배포 → 스모크 테스트 → Slack 알림

릴리즈: 무중단 배포 → 상태 확인 → 모니터링

13. 성능 최적화

성능 감사 → 병목 식별 → 최고 영향도 우선 최적화

분석 대상: 번들 크기, DB 쿼리, 프론트엔드 렌더링

14. 웹/모바일/데스크톱 인터페이스

claude.ai의 </> 아이콘으로 접근:

  • GitHub 연동
  • 가상 샌드박스에서 코드 실행
  • Pull Request 자동 생성

핵심 포인트 상세 정리

1. CLAUDE.md - 프로젝트의 두뇌

CLAUDE.md는 단순한 설정 파일이 아닌 프로젝트의 살아있는 문서입니다.

왜 중요한가?

Claude Code는 매 세션마다 컨텍스트가 초기화됩니다. CLAUDE.md가 없으면:

  • 매번 프로젝트 구조를 설명해야 함
  • 코딩 컨벤션이 일관되지 않음
  • 이전 결정사항을 기억하지 못함

효과적인 CLAUDE.md 작성법

# 프로젝트명

## 아키텍처
- 프론트엔드: React + TypeScript
- 백엔드: Spring Boot + Kotlin
- 데이터베이스: MongoDB

## 코딩 규칙
- 함수명은 camelCase
- 컴포넌트는 PascalCase
- 테스트 파일은 *.test.ts

## 디렉토리 구조
@docs/architecture.md 참조

## 중요 결정사항
- 2024-01: REST 대신 gRPC 채택 (성능 이유)
- 2024-03: 모노레포 구조로 전환

## 현재 작업 컨텍스트
- 진행 중: 사용자 인증 기능
- 다음 작업: 결제 시스템 연동

계층적 CLAUDE.md 활용

~/.claude/CLAUDE.md
├── 내 모든 프로젝트에 적용되는 개인 스타일
│
프로젝트/CLAUDE.md
├── 이 프로젝트의 전체 규칙
│
프로젝트/backend/CLAUDE.md
├── 백엔드만의 특수 규칙 (Kotlin 스타일 등)
│
프로젝트/frontend/CLAUDE.md
└── 프론트엔드만의 특수 규칙 (React 패턴 등)

규칙: 더 구체적인 파일이 일반적인 파일을 덮어씁니다.

2. 컨텍스트 관리 - 성능의 핵심

컨텍스트 윈도우는 Claude가 한 번에 "기억"할 수 있는 정보량입니다.

컨텍스트가 가득 차면?

  • 응답 품질 저하
  • 이전 대화 내용 망각
  • 비용 증가 (토큰 사용량 ↑)

실전 관리 전략

1. 기능 단위로 채팅 분리

❌ 하나의 채팅에서 모든 기능 개발
✅ 기능 A 채팅 → /clear → 기능 B 채팅

2. 완료된 작업은 즉시 정리

# 기능 완료 후
/clear

3. 필요시 이전 세션 복귀

/resume

4. 대규모 작업은 계획 파일로 분할

# plan.md
## Phase 1: 데이터베이스 설계
- [ ] 스키마 정의
- [ ] 마이그레이션 작성

## Phase 2: API 개발
- [ ] 엔드포인트 구현
- [ ] 테스트 작성

5. 선택적 컨텍스트 압축

/compact Focus on preserving authentication flow and API schemas

3. Plan Mode - 복잡한 작업의 시작점

Plan Mode는 Claude의 "확장 사고(Extended Thinking)" 기능을 활용합니다.

언제 사용하나?

  • 새로운 기능 시작
  • 복잡한 리팩토링
  • 아키텍처 결정
  • 버그의 근본 원인 분석

분석 깊이 조절

키워드분석 수준사용 시점
think기본간단한 계획
think hard심층복잡한 로직
ultrathink최대아키텍처 결정, 중요한 설계

실전 예시

사용자 인증 시스템을 구현하려고 해.
JWT와 세션 기반 중 어떤 것이 좋을지 ultrathink해서 분석하고,
선택한 방식의 구현 계획을 단계별로 세워줘.

Claude의 응답:
1. 요구사항 확인 질문
2. 각 방식의 장단점 분석
3. 추천 방식과 근거
4. 단계별 구현 계획
5. 예상 파일 구조
6. 테스트 전략

4. Git Worktrees - 병렬 개발의 혁신

여러 기능을 동시에 개발할 때 브랜치 전환 없이 작업할 수 있습니다.

기존 방식의 문제

# 기능 A 작업 중...
git stash
git checkout feature-b
# 기능 B 작업...
git checkout feature-a
git stash pop
# 컨텍스트 스위칭 비용 발생!

Worktree 방식

# 메인 프로젝트
~/project/
├── (main 브랜치)

# Worktree 생성
git worktree add ../project-auth -b feature/auth
git worktree add ../project-payment -b feature/payment

# 결과
~/project/           # main 브랜치
~/project-auth/      # feature/auth 브랜치
~/project-payment/   # feature/payment 브랜치

Claude Code와 함께 사용

# 터미널 1: 인증 기능
cd ~/project-auth
claude
> 로그인 기능 구현해줘

# 터미널 2: 결제 기능 (동시 진행)
cd ~/project-payment
claude
> 결제 API 연동해줘

# 각 Claude 인스턴스는 독립적으로 작동

정리

# Worktree 목록 확인
git worktree list

# 작업 완료 후 제거
git worktree remove ../project-auth

5. 커스텀 슬래시 명령 - 팀 생산성 향상

반복되는 작업을 명령어로 자동화합니다.

디렉토리 구조

.claude/
└── commands/
    ├── review.md      # /review
    ├── test.md        # /test
    ├── deploy.md      # /deploy
    └── debug.md       # /debug

실전 예시들

코드 리뷰 (/review)

# .claude/commands/review.md

다음 항목을 기준으로 코드 리뷰를 수행해줘:

## 코드 품질
- [ ] 함수가 단일 책임 원칙을 따르는가?
- [ ] 변수명이 명확한가?
- [ ] 중복 코드가 없는가?

## 에러 처리
- [ ] 예외 상황이 적절히 처리되는가?
- [ ] 사용자에게 명확한 에러 메시지를 제공하는가?

## 보안
- [ ] SQL 인젝션 위험이 없는가?
- [ ] XSS 취약점이 없는가?
- [ ] 민감한 정보가 노출되지 않는가?

## 성능
- [ ] N+1 쿼리 문제가 없는가?
- [ ] 불필요한 연산이 없는가?

발견된 문제점과 개선 제안을 목록으로 정리해줘.

테스트 생성 (/test)

# .claude/commands/test.md

현재 파일에 대한 테스트를 작성해줘:

1. 정상 케이스 테스트
2. 엣지 케이스 테스트 (빈 값, null, 경계값)
3. 에러 케이스 테스트
4. 모킹이 필요한 경우 적절히 처리

테스트 파일은 `*.test.ts` 형식으로 생성해줘.

디버깅 (/debug)

# .claude/commands/debug.md

다음 단계로 디버깅을 진행해줘:

1. 에러 메시지 분석
2. 관련 코드 추적
3. 가능한 원인 3가지 나열
4. 각 원인에 대한 검증 방법 제안
5. 가장 유력한 원인에 대한 수정 코드 제시

팀 공유

.claude/commands/를 Git에 커밋하면 팀 전체가 동일한 명령어 사용 가능

6. MCP 서버 - 외부 도구 연동

Model Context Protocol을 통해 Claude를 외부 서비스와 연결합니다.

주요 MCP 서버

서버용도
brave-search웹 검색
githubGitHub 이슈, PR 관리
jiraJira 티켓 연동
postgres데이터베이스 직접 쿼리
slackSlack 메시지 전송

설정 방법

# 프로젝트 단위로 추가
claude mcp add github -s project -- npx @modelcontextprotocol/server-github

# 전역으로 추가
claude mcp add brave-search -s user -- npx @modelcontextprotocol/server-brave-search

프로젝트 설정 파일 (.mcp.json)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

활용 예시

GitHub에서 이번 주에 올라온 이슈들 중
버그 라벨이 붙은 것들을 우선순위별로 정리해줘.

체크리스트: Claude Code 마스터하기

시작 전

  • CLAUDE.md 파일 생성 (/init)
  • 프로젝트 구조와 규칙 문서화
  • 필요한 MCP 서버 연결

작업 중

  • Plan Mode로 복잡한 작업 시작
  • 기능 단위로 채팅 분리
  • 정기적으로 /clear로 컨텍스트 정리
  • Git Worktree로 병렬 작업

작업 후

  • 커스텀 명령으로 코드 리뷰
  • 테스트 자동 생성
  • 문서 업데이트 요청
  • CLAUDE.md에 결정사항 기록

팀 협업

  • .claude/commands/ Git 커밋
  • .mcp.json 공유
  • CLAUDE.md 팀 규칙 통일

결론

Claude Code는 단순한 코드 생성 도구가 아닌 개발 파트너입니다.

"Sonnet과 Opus는 이미 코딩 분야 최고 성능 모델이고, Claude Code가 이를 에이전트화하여 중급 소프트웨어 엔지니어 수준의 역량을 제공합니다."

핵심은 컨텍스트 관리와 구조화된 워크플로우입니다. CLAUDE.md를 잘 관리하고, Plan Mode를 활용하며, 커스텀 명령으로 반복 작업을 자동화하세요.

이 문서는 원문을 한글로 번역하고 핵심 내용을 요약한 것입니다.

profile
박성수
Kotlin, Java 백엔드 개발자입니다. 제가 생각하는 개발자로서 가져야하는 업무적인 기본 소양과 실무에서 가지는 고민들을 같이 공유하고 소통하려고 합니다.
다음 포스트

Claude Code 커스텀 명령어 가이드: Git 워크플로우 자동화

0개의 댓글