Claude Code 완벽 셋팅 가이드: 설치부터 실전 활용까지

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트다. 단순한 코드 자동완성이 아니라, 프로젝트를 이해하고, 파일을 읽고 수정하고, 명령어를 실행하며, Git 워크플로우까지 자동화할 수 있는 강력한 도구다. 이 글에서는 설치부터 실전 활용까지 상세히 다룬다.

설치

Native Installer (권장)

가장 권장되는 방법이다. Node.js 없이 독립 바이너리로 설치되며, 자동 업데이트를 지원한다.

macOS / Linux:

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

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

바이너리는 ~/.claude/bin/claude에 설치되고, PATH에 자동 등록된다.

Homebrew (macOS)

brew install claude-code

Homebrew 설치는 자동 업데이트가 되지 않으므로 주기적으로 brew upgrade claude-code를 실행해야 한다.

npm (레거시)

npm install -g @anthropic-ai/claude-code

Node.js 18 이상이 필요하다. 공식적으로 deprecated 상태이므로 가능하면 Native Installer를 사용하자. 절대 sudo와 함께 사용하지 말 것.

설치 확인

claude doctor

설치 타입, 버전, 일반적인 문제를 진단해준다.

흔한 설치 문제

command not found: claude: 새 터미널을 열어야 한다. 설치 스크립트가 쉘 프로필(.zshrc, .bashrc)을 수정하지만 기존 터미널에는 반영되지 않는다.
권한 오류: sudo를 절대 사용하지 말 것. Native Installer는 ~/.claude/bin/에 설치하므로 관리자 권한이 불필요하다.
Windows: Git Bash 또는 WSL 환경에서 실행한다.

인증 설정

Pro/Max 구독 사용자

별도의 API 키 없이 OAuth 로그인으로 인증한다.

claude
# 브라우저가 열리면 Anthropic 계정으로 로그인

API 키 사용 (종량제)

Anthropic Console에서 키를 발급받아 환경변수로 설정한다.

export ANTHROPIC_API_KEY="sk-ant-..."
claude

.bashrc 또는 .zshrc에 추가해두면 매번 입력할 필요가 없다.

echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.zshrc
source ~/.zshrc

인증 상태 확인

claude auth status

핵심 설정: CLAUDE.md

CLAUDE.md는 Claude Code의 두뇌라고 할 수 있다. 프로젝트의 구조, 코딩 컨벤션, 빌드/테스트 명령어 등을 기록하면 Claude가 매 세션마다 이 파일을 읽고 프로젝트를 이해한다.

계층 구조

범위	위치	용도
전역	`~/.claude/CLAUDE.md`	모든 프로젝트에 적용
프로젝트 (공유)	`<프로젝트>/CLAUDE.md`	Git에 커밋, 팀 공유
프로젝트 (개인)	`<프로젝트>/.claude/CLAUDE.md`	개인 설정, 커밋 안함

상위 계층이 하위를 오버라이드한다.

초기 생성

/init

Claude Code 세션에서 /init 명령을 실행하면 프로젝트를 분석해 기본 CLAUDE.md를 자동 생성한다.

실전 CLAUDE.md 예시

# My Project

## 프로젝트 개요
React 18 + TypeScript 기반 SaaS 대시보드.
백엔드는 FastAPI, DB는 PostgreSQL.

## 빌드 & 테스트
- 프론트: `npm run build`, `npm test`
- 백엔드: `poetry run pytest`
- 린트: `npm run lint && poetry run ruff check .`

## 코딩 컨벤션
- 컴포넌트는 함수형 + hooks 패턴
- API 응답은 Zod 스키마로 검증
- 커밋 메시지는 Conventional Commits 형식

## 디렉토리 구조
- `src/components/` - React 컴포넌트
- `src/hooks/` - Custom hooks
- `src/api/` - API 클라이언트
- `backend/app/` - FastAPI 앱
- `backend/tests/` - 백엔드 테스트

## 주의사항
- .env 파일은 절대 커밋하지 말 것
- DB 마이그레이션은 반드시 리뷰 후 적용

권한(Permissions) 설정

Claude Code는 파일 읽기, 수정, 명령어 실행 등에 대한 세밀한 권한 관리를 지원한다.

설정 파일 위치

범위	파일
프로젝트 (팀 공유)	`.claude/settings.json`
프로젝트 (개인)	`.claude/settings.local.json`
사용자 전역	`~/.claude/settings.json`

권한 설정 예시

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ],
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(npm run build)",
      "Read",
      "Glob",
      "Grep"
    ],
    "ask": [
      "Bash",
      "Edit",
      "Write"
    ]
  }
}

deny: 무조건 차단 (다른 레벨에서 allow해도 deny가 우선)
allow: 묻지 않고 자동 실행
ask: 실행 전 사용자에게 확인

팁: 처음에는 대부분을 ask로 두고, 안전하다고 판단되는 명령을 점진적으로 allow에 추가하는 전략이 좋다. Claude가 허락을 물을 때 "Yes, and don't ask again"을 선택하면 자동으로 allow 목록에 추가된다.

Hooks: 자동화 파이프라인

Hooks는 Claude Code의 라이프사이클 이벤트에 연결되는 셸 명령어다. 자동 포맷팅, 보안 검사, CI 연동 등에 활용할 수 있다.

Hook 이벤트 종류

이벤트	실행 시점
`PreToolUse`	도구 실행 직전 (exit code 2로 차단 가능)
`PostToolUse`	도구 실행 완료 후
`Stop`	Claude 응답 완료 시
`SessionStart`	세션 시작 시
`UserPromptSubmit`	사용자 프롬프트 제출 시
`Notification`	알림 발송 시

예시 1: TypeScript 파일 자동 포맷팅

파일을 수정할 때마다 Prettier를 자동 실행한다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read f; echo \"$f\" | grep -q '\\.ts$' && npx prettier --write \"$f\"; }"
          }
        ]
      }
    ]
  }
}

예시 2: 민감 파일 수정 차단

.env나 package-lock.json 수정을 사전에 차단한다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json,sys; d=json.load(sys.stdin); p=d.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(x in p for x in ['.env','package-lock.json']) else 0)\""
          }
        ]
      }
    ]
  }
}

PreToolUse hook에서 exit code 2를 반환하면 해당 도구 실행이 차단된다.

MCP 서버: 기능 확장

MCP(Model Context Protocol) 서버를 통해 Claude Code에 외부 도구를 연결할 수 있다.

MCP 서버 추가

# GitHub 연동
claude mcp add github --scope user

# HTTP 원격 서버
claude mcp add my-server --transport http --url https://my-server.example.com

# 설정된 서버 확인
claude mcp list

설정 파일

전역: ~/.mcp.json
프로젝트: .mcp.json (프로젝트 루트)

Claude Code를 MCP 서버로 사용

claude mcp serve

이렇게 하면 다른 MCP 클라이언트에서 Claude Code의 도구를 사용할 수 있다.

IDE 연동

VS Code

Extensions에서 “Claude Code”를 검색해 설치한다.

주요 기능:

사이드바 채팅 패널
@파일명으로 파일 참조
체크포인트 기반 되돌리기 (메시지에 hover하면 Rewind 가능)
병렬 대화 탭
권한 모드: Normal / Plan / Auto-accept

단축키: Cmd+Esc (Mac)으로 현재 파일 컨텍스트와 함께 Claude를 열 수 있다.

외부 터미널과 연결: Claude Code 세션에서 /ide 명령을 실행하면 VS Code와 연결된다.

JetBrains (Beta)

Settings > Plugins > Marketplace에서 “Claude Code [Beta]”를 검색해 설치한다. IntelliJ, PyCharm, WebStorm 등 전체 JetBrains 제품군을 지원한다. Claude Code CLI가 별도로 설치되어 있어야 한다.

실전 활용 케이스

케이스 1: 코드베이스 탐색

새 프로젝트에 합류했을 때 구조를 빠르게 파악할 수 있다.

> 이 프로젝트의 전체 아키텍처를 설명해줘
> API 엔드포인트 목록과 각각의 역할을 정리해줘
> 인증 흐름이 어떻게 구현되어 있는지 분석해줘

케이스 2: 버그 수정

에러 메시지를 그대로 붙여넣으면 원인을 추적하고 수정까지 해준다.

> src/utils/parser.ts에서 TypeError가 발생하는데 수정해줘
> 세션 만료 시 로그인이 실패하는 버그를 디버깅해줘

케이스 3: 리팩토링

> UserService 클래스를 DI(Dependency Injection) 패턴으로 리팩토링해줘
> getCwd 함수를 getCurrentWorkingDirectory로 프로젝트 전체에서 리네이밍해줘

케이스 4: 테스트 작성

> PaymentProcessor 클래스의 유닛 테스트를 작성해줘
> REST API 엔드포인트의 통합 테스트를 추가해줘

케이스 5: Git 워크플로우

> 변경사항을 리뷰하고 커밋 메시지를 작성해서 커밋해줘
> 이 브랜치의 변경사항을 정리해서 PR을 만들어줘

실제로 /commit 명령만 입력하면 staged 변경사항을 분석해 적절한 커밋 메시지를 생성하고 커밋까지 처리한다.

케이스 6: 비대화형 모드 (스크립팅)

CI/CD 파이프라인이나 셸 스크립트에서 활용할 수 있다.

# TODO 코멘트 추출
claude -p "이 프로젝트의 모든 TODO 코멘트를 정리해줘" --output-format json

# JSON에서 TypeScript 인터페이스 생성
claude -p "이 JSON으로 TypeScript 인터페이스를 만들어줘" < data.json

# 코드 리뷰 자동화
git diff --staged | claude -p "이 변경사항을 코드 리뷰해줘. 버그, 보안 이슈, 개선점을 지적해줘"

케이스 7: 커스텀 슬래시 커맨드

.claude/commands/ 디렉토리에 마크다운 파일을 만들면 커스텀 명령을 정의할 수 있다.

.claude/commands/review.md:

---
model: sonnet
---
다음 파일을 코드 리뷰해줘: $ARGUMENTS

리뷰 기준:
1. 버그 가능성
2. 보안 취약점
3. 성능 이슈
4. 코드 스타일 컨벤션 준수 여부

사용법:

/review src/components/Dashboard.tsx

.claude/commands/test-gen.md:

---
model: sonnet
---
$ARGUMENTS 파일에 대한 유닛 테스트를 작성해줘.
기존 테스트 패턴을 분석해서 동일한 스타일로 작성할 것.

케이스 8: 세션 이어가기

작업 중이던 대화를 이어갈 수 있다.

# 마지막 세션 이어가기
claude -c

# 특정 세션 선택해서 이어가기
claude --resume

주요 슬래시 커맨드 정리

커맨드	설명
`/help`	사용 가능한 명령 목록
`/init`	CLAUDE.md 자동 생성
`/clear`	대화 기록 초기화
`/compact`	대화 요약 (컨텍스트 절약)
`/model`	모델 전환
`/cost`	토큰 사용량 확인
`/permissions`	권한 관리
`/config`	설정 토글
`/export`	대화 내보내기
`/mcp`	MCP 서버 관리
`/doctor`	설치 진단
`/vim`	Vim 모드 진입

입력 단축키

단축키	기능
`@파일명`	파일/디렉토리 참조
`!명령어`	셸 명령 실행
`Ctrl+B`	현재 작업 백그라운드 전환
`Ctrl+G`	외부 에디터 열기
`Ctrl+R`	명령 히스토리 검색
`Shift+Tab`	권한 모드 순환

모델 선택 가이드

모델	특성	적합한 작업
Opus 4.6	최고 수준의 추론 능력	복잡한 아키텍처 설계, 대규모 리팩토링
Sonnet 4.5	속도와 성능의 균형	일반적인 코딩 작업
Haiku	빠르고 저렴	단순 작업, 커스텀 슬래시 커맨드

세션 중에 /model 명령으로 모델을 전환할 수 있다.

요금제

Claude Code는 무료로 설치할 수 있으며, AI 사용량에 따라 과금된다.

플랜	월 요금	특징
Pro	$20	기본 사용량, 대부분의 개발자에게 충분
Max 5x	$100	Pro의 5배 사용량
Max 20x	$200	Pro의 20배 사용량, 하루 4시간 이상 집중 사용 시
API (종량제)	토큰당 과금	구독 없이 사용, 기업/자동화 용도

사용량 제한은 5시간마다 갱신된다.

실전 팁

1. CLAUDE.md에 투자하라. 잘 작성된 CLAUDE.md 하나가 매 세션마다 수십 줄의 설명을 대체한다.

2. /clear를 자주 사용하라. 새 작업을 시작할 때 이전 대화 기록은 토큰만 소비한다.

3. 프로젝트 루트에서 실행하라. 항상 리포지토리 루트에서 claude를 실행해야 전체 프로젝트 컨텍스트를 활용할 수 있다.

4. 점진적으로 권한을 열어라. 처음엔 ask로 시작하고, 안전한 명령어를 하나씩 allow에 추가한다.

5. Hook으로 가드레일을 만들어라. PreToolUse로 위험한 작업을 차단하고, PostToolUse로 포맷팅이나 린트를 자동화한다.

6. 환경변수를 활용하라.

# 추론 깊이 조절
export CLAUDE_CODE_EFFORT_LEVEL=high

# Bash 명령 타임아웃 연장
export BASH_DEFAULT_TIMEOUT_MS=300000

마무리

Claude Code는 단순한 AI 코드 어시스턴트를 넘어 터미널에서 동작하는 페어 프로그래머에 가깝다. CLAUDE.md로 프로젝트 맥락을 전달하고, 권한과 Hook으로 안전장치를 설정하고, MCP 서버로 기능을 확장하면 매우 강력한 개발 환경을 구축할 수 있다.

처음에는 간단한 코드 질문이나 버그 수정부터 시작하고, 점차 리팩토링, 테스트 작성, Git 워크플로우 자동화 등으로 활용 범위를 넓혀가는 것을 추천한다.

설치