Claude Code 완전 가이드: 설치부터 고급 워크플로우까지 (2026)

Claude Code는 Anthropic이 만든 AI 코딩 CLI 도구로, 터미널에서 직접 실행하며 파일을 읽고 쓰고, 명령어를 실행하고, 멀티스텝 작업을 자율적으로 수행한다. 에디터 플러그인이 아니라 에이전트다 — Claude가 코드베이스 전체를 파악하고, 버그를 찾고, 테스트를 돌리고, PR을 준비하는 작업을 실제로 실행한다. 설치부터 고급 패턴까지, 한국 개발자를 위해 처음부터 다시 썼다.

설치 방법 (5분 완료)

Node.js 18 이상이 필요하다. 없으면 nodejs.org에서 먼저 설치한다.

# 전역 설치
npm install -g @anthropic-ai/claude-code

# 버전 확인
claude --version

인증 설정

# 브라우저 기반 로그인 (권장)
claude auth login

# 또는 API 키를 환경변수로 직접 설정
export ANTHROPIC_API_KEY="sk-ant-..."

# 동작 확인
claude "안녕하세요, 동작하나요?"

Anthropic API 요금제를 사용한다. 별도 Claude Code 구독은 없고 API 토큰 사용량만큼 과금된다. 일반적인 일상 개발 사용이라면 월 $10~30 수준이다.

주요 명령어 레퍼런스

기본 사용법

# 대화형 세션 시작
claude

# 단발성 작업 (비대화형)
claude "src/api/users.ts에 에러 핸들링 추가해줘"

# 파일 컨텍스트 지정
claude "@src/components/Button.tsx Tailwind로 리팩터링해줘"

# 여러 파일 동시 지정
claude "@src/lib/auth.ts @src/api/login.ts 인증 흐름에서 토큰 갱신 버그 찾아줘"

유용한 플래그

# 권한 확인 건너뜀 (CI 환경, 신뢰된 환경에서만)
claude --dangerously-skip-permissions "전체 테스트 실행하고 실패한 것 고쳐줘"

# 모델 지정
claude --model claude-opus-4-5 "시스템 아키텍처 설계해줘"
claude --model claude-haiku-4-5 "변수명 바꿔줘"

# 이전 대화 이어서
claude -c "아까 말한 함수를 async로 바꿔줘"

# 출력만 받기 (파이프라인용)
claude -p "마지막 커밋에서 뭐가 바뀌었는지 요약해줘"

# 도구 호출 상세 출력
claude --verbose "이 테스트가 왜 실패하는지 디버깅해줘"

세션 관리

# 최근 세션 목록
claude sessions

# 특정 세션 재개
claude -r SESSION_ID

# 세션 히스토리 초기화
claude clear

CLAUDE.md 설정 — Claude에게 프로젝트를 가르치는 방법

CLAUDE.md는 Claude Code의 핵심 커스터마이징 수단이다. 세션이 시작될 때마다 자동으로 읽히고, 프로젝트의 규칙과 컨텍스트를 Claude에게 전달한다.

파일 계층 구조 (모두 병합됨):

~/.claude/CLAUDE.md          → 전역 설정 (모든 프로젝트에 적용)
프로젝트루트/CLAUDE.md       → 프로젝트 전체 설정 (git에 커밋)
프로젝트루트/src/CLAUDE.md   → 서브디렉토리 오버라이드

실제 CLAUDE.md 예시

# MyApp 프로젝트

## 기술 스택
- Next.js 15, TypeScript strict 모드
- Prisma + PostgreSQL
- 패키지 매니저: bun (npm/yarn 사용 금지)

## 코딩 규칙
- `any` 타입 사용 금지
- 코드 수정 후 반드시 `bun run typecheck` 실행
- 커밋 메시지: Conventional Commits 형식
- 컴포넌트 파일명: PascalCase
- API 라우트: REST 원칙 준수

## 금지 사항
- console.log 프로덕션 코드에 남기기
- 하드코딩된 시크릿 값

## 주요 명령어
- 빌드: `bun run build`
- 테스트: `bun test`
- 타입 체크: `bun run typecheck`
- 린트: `bun run lint`

CLAUDE.md에 넣으면 좋은 것: 기술 스택, 코딩 컨벤션, 금지 패턴, 핵심 파일 경로, 빌드/테스트 명령어.

CLAUDE.md에 넣으면 안 되는 것: API 키/시크릿, 자주 바뀌는 임시 메모, 현재 작업 태스크.

Slash Commands — 세션 내 단축 명령어

Claude Code 세션 안에서 /로 시작하는 빌트인 명령어들이다.

명령어	설명
`/help`	사용 가능한 명령어 목록
`/clear`	대화 컨텍스트 초기화
`/compact`	컨텍스트 압축 (토큰 절약)
`/model claude-sonnet-4-5`	세션 도중 모델 변경
`/cost`	현재 세션 토큰 비용 확인
`/status`	세션 정보 확인

커스텀 슬래시 명령어 (Skills)

.claude/skills/[이름]/SKILL.md 파일을 만들면 재사용 가능한 워크플로우를 슬래시 명령어로 등록할 수 있다.

# /deploy 커스텀 스킬 생성
mkdir -p .claude/skills/deploy

# .claude/skills/deploy/SKILL.md 작성 예시:
# 1. bun run build 실행
# 2. 빌드 성공하면 vercel --prod --yes 실행
# 3. 배포 URL 확인

이후 세션에서 /deploy만 입력하면 전체 배포 프로세스가 실행된다. 반복적인 작업을 팀 전체에 표준화할 때 특히 유용하다.

MCP 서버 연동

Model Context Protocol(MCP)을 통해 Claude Code에 외부 서비스를 연결할 수 있다. GitHub, Slack, 데이터베이스 등을 직접 연동하면 Claude가 해당 데이터에 접근하며 작업할 수 있다.

// ~/.claude/claude.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://localhost:5432/mydb" }
    }
  }
}

MCP 서버 설정 후 Claude Code 세션을 재시작하면 바로 사용할 수 있다. claude "GitHub에서 열린 PR 목록 가져와줘"처럼 자연어로 연동 서비스를 사용할 수 있다.

Hooks — 자동화 트리거

Hooks는 Claude Code의 특정 시점에 셸 명령어를 자동으로 실행하는 기능이다. 파일 수정 전후 타입 체크, 포맷터 실행, 커스텀 알림 등을 자동화할 수 있다.

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "echo '파일 수정 시작: $TOOL_INPUT_PATH'"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{
          "type": "command",
          "command": "bun run typecheck 2>&1 | head -30"
        }]
      }
    ],
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "terminal-notifier -title 'Claude Code' -message '작업 완료'"
        }]
      }
    ]
  }
}

위 설정은 파일이 수정될 때마다 자동으로 TypeScript 타입 체크를 실행하고, 세션이 종료되면 macOS 알림을 띄운다. 타입 에러를 즉시 피드백으로 받아 Claude가 바로 수정할 수 있게 된다.

→ Hooks 상세 설정과 실전 패턴은 Claude Code Hooks 완전 가이드 (한국어) 참고.

실전 워크플로우

1. Plan Mode — 실행 전 계획 검토

큰 리팩터링이나 위험한 작업 전에 Plan Mode를 사용하면 Claude가 먼저 계획을 제시하고, 승인 후에만 실행한다.

# 세션 내에서
/plan "REST API를 GraphQL로 전환해줘"
# → Claude가 단계별 계획 제시
# → 검토 후 승인하면 실행

→ 상세 사용법은 Claude Code Plan Mode 한국어 가이드 참고.

2. Worktree 격리 — 안전한 대규모 변경

Git worktree를 활용하면 메인 브랜치를 건드리지 않고 Claude에게 위험한 변경을 맡길 수 있다.

# 격리된 worktree 생성
git worktree add ../feature-auth main
cd ../feature-auth
claude "인증 모듈 전체를 JWT에서 세션 기반으로 마이그레이션해줘"

3. 병렬 서브에이전트 — 동시 조사

Claude에게 여러 작업을 동시에 수행시킬 수 있다.

claude "서브에이전트 3개를 병렬로 실행해줘:
1. 현재 인증 시스템 구조 분석
2. 모든 API 엔드포인트 목록 정리
3. 테스트 커버리지 현황 파악

완료 후 결과를 통합해서 보고해줘."

4. 비대화형 모드 — CI/CD 파이프라인 연동

# GitHub Actions 예시
- name: Claude Code 코드 리뷰
  run: |
    claude --dangerously-skip-permissions -p \
      "변경된 파일을 분석하고 잠재적 버그와 보안 이슈를 리포트해줘" \
      > review-output.txt

5. 모델 선택 전략

작업 유형	권장 모델	이유
아키텍처 설계, 복잡한 리팩터링	claude-opus-4-5	최고 추론 능력
일반 코딩, 버그 수정	claude-sonnet-4-5	비용 대비 최고 성능
변수명 변경, 포맷팅, 간단한 수정	claude-haiku-4-5	빠르고 저렴

CLAUDE.md에 기본 모델을 명시해두면 매번 지정할 필요가 없다:

## 모델 설정
기본: claude-sonnet-4-5
복잡한 아키텍처 결정 시에만: claude-opus-4-5
단순 수정 작업: claude-haiku-4-5

Claude Code Power Prompts 300 — 실전 프롬프트 모음

Claude Code를 처음 쓸 때 가장 시간이 걸리는 건 "어떻게 지시해야 잘 작동하는지" 파악하는 것이다. 300개의 검증된 프롬프트 모음에는 디버깅, 리팩터링, 테스트 생성, 보안 스캔, 아키텍처 설계에 바로 복사해 쓸 수 있는 프롬프트가 담겨 있다. 5가지 프로젝트 타입별 CLAUDE.md 템플릿과 팀용 슬래시 커맨드 라이브러리도 포함.

Power Prompts 300 받기 ($29) →

30일 환불 보장. 즉시 다운로드.

Frequently Asked Questions

Claude Code는 무료인가요?

Claude Code 자체는 무료로 설치할 수 있지만, 실행 시 Anthropic API 요금이 발생한다. 별도 구독 없이 API 토큰 사용량만큼 과금된다. 일반적인 개인 개발 용도로는 월 $10~30 수준이고, 헤비 유저는 $50 이상도 가능하다.

Claude Code와 GitHub Copilot의 차이는?

GitHub Copilot은 에디터 내 코드 자동완성 도구다. Claude Code는 터미널에서 실행되는 에이전트로, 파일 시스템 접근권한을 갖고 멀티스텝 작업을 자율적으로 실행한다. "이 기능 전체를 만들어줘"처럼 큰 작업을 맡길 수 있는 것이 핵심 차이다.

VS Code나 JetBrains에서도 사용할 수 있나요?

네. Claude Code는 IDE 통합을 지원한다. VS Code Extension이나 JetBrains 플러그인 형태로 설치하거나, 터미널에서 직접 실행해도 된다. 터미널 실행이 가장 기능이 풍부하다.

코드가 Anthropic 서버로 전송되나요?

Claude Code 사용 시 지정한 파일과 컨텍스트는 추론을 위해 Anthropic API로 전송된다. Anthropic의 API 이용약관이 적용된다. 기업 환경에서 개인정보 보호 요건이 있다면 Anthropic Enterprise 옵션을 검토하면 된다.

CLAUDE.md 없이도 잘 작동하나요?

작동은 하지만, CLAUDE.md 없이 쓰는 것은 팀 컨텍스트 없이 일하는 것과 같다. 기술 스택, 코딩 컨벤션, 금지 패턴을 CLAUDE.md에 명시할수록 Claude의 출력 품질이 눈에 띄게 높아진다. 10분 투자로 세션 품질이 크게 달라진다.

인터넷 연결이 없으면 사용할 수 없나요?

네. Claude Code는 모든 추론을 Anthropic API에 의존하기 때문에 인터넷 연결이 필수다. 오프라인 환경에서는 사용할 수 없다.

더 읽을거리

Claude Code Hooks 완전 가이드 (한국어) — 자동화 트리거 상세 설정
Claude Code Plan Mode 한국어 가이드 — 실행 전 계획 검토 워크플로우
MCP 서버 가이드 (한국어) — GitHub, DB 연동 실전 예시
커스텀 스킬 만들기 — 팀용 슬래시 커맨드 제작