Claude CLI 가이드

소개

Claude CLI (Claude Code)는 Anthropic이 공식 제공하는 커맨드라인 인터페이스로, 터미널에서 직접 Claude와 대화하며 코드를 생성하고 프로젝트를 관리할 수 있습니다.

왜 Claude CLI인가?

설치

방법 1: 공식 설치 스크립트 (권장)

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

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# 설치 확인
claude --version

공식 설치 스크립트는 자동 업데이트를 지원합니다.

방법 2: 패키지 매니저

# Homebrew (macOS/Linux)
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm (공식 지원, 네이티브 바이너리 래핑)
npm install -g @anthropic-ai/claude-code

시스템 요구사항

• OS: macOS 13.0+, Ubuntu 20.04+, Windows 10 1809+
• RAM: 4GB 이상
• Windows: Git for Windows 필수
• 셸: Bash, Zsh, PowerShell, CMD 지원

인증 설정

Claude Code는 두 가지 인증 방식을 지원합니다.

방법 1: 대화형 로그인 (권장)

# 브라우저 기반 로그인 — Anthropic/Google/GitHub 계정 사용
claude auth login

# 로그아웃
claude auth logout

# 로그인 상태 확인
claude auth status

Pro/Max/Team/Enterprise 플랜 사용자는 이 방법으로 바로 시작할 수 있습니다.

방법 2: API 키

# macOS/Linux
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxx"

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxxxx"

# 영구 설정 (~/.bashrc 또는 ~/.zshrc에 추가)
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxx"' >> ~/.zshrc
source ~/.zshrc

API 키는 빠른 시작 가이드를 참고하여 발급받으세요.

기본 사용법

CLI 시작

# Claude CLI 시작
claude

# 특정 디렉토리에서 시작
cd my-project
claude

CLI가 시작되면 대화형 인터페이스가 표시됩니다:

╭────────────────────────────────────────╮
│  Welcome to Claude Code CLI            │
│  Model: sonnet               │
│  Type 'help' for commands              │
╰────────────────────────────────────────╯

💬 You: _

기본 명령어

파일 생성 요청

💬 You: "Python으로 간단한 웹 서버 만들어줘. Flask 사용해서."

🤖 Claude: "Flask 웹 서버를 생성하겠습니다."

# 파일 생성
Created: app.py
Created: requirements.txt
Created: templates/index.html

🤖 Claude: "3개 파일을 생성했습니다.
app.py - Flask 애플리케이션
requirements.txt - 의존성 목록
templates/index.html - 메인 페이지

설치 및 실행:
```
pip install -r requirements.txt
python app.py
```
http://localhost:5000 에서 확인하세요!"

파일 수정 요청

💬 You: "app.py에 /api/hello 엔드포인트 추가해줘. JSON으로 인사말 반환."

🤖 Claude: "app.py를 수정하겠습니다."

# 파일 수정
Modified: app.py

🤖 Claude: "/api/hello 엔드포인트를 추가했습니다:

@app.route('/api/hello')
def hello_api():
    return jsonify({'message': 'Hello from Claude!'})

curl로 테스트:
curl http://localhost:5000/api/hello"

여러 파일 동시 편집

💬 You: "데이터베이스 연동 추가해줘. SQLite 사용하고,
User 모델 만들고, app.py에서 사용하게."

🤖 Claude: "데이터베이스 기능을 추가하겠습니다."

# 여러 파일 생성/수정
Created: models.py
Created: database.py
Modified: app.py
Modified: requirements.txt

🤖 Claude: "SQLite 연동을 완료했습니다:
- models.py: User 모델 정의
- database.py: DB 초기화 및 연결
- app.py: User CRUD 엔드포인트 추가
- requirements.txt: SQLAlchemy 추가"

슬래시 명령어

대화형 세션에서 /로 시작하는 명령어를 사용할 수 있습니다.

키보드 단축키

멀티라인 입력

• Option+Enter — macOS 기본 터미널
• Shift+Enter — iTerm2, WezTerm, Ghostty, Kitty (/terminal-setup 설정 후)
• \+Enter — 모든 터미널에서 사용 가능

대화 히스토리

Claude CLI는 현재 세션의 대화 히스토리를 유지합니다. 이전 대화를 참조하여 연속적인 작업이 가능합니다.

💬 You: "React 컴포넌트 만들어줘. Button 컴포넌트."
🤖 Claude: "Button.jsx를 생성했습니다."

💬 You: "이 버튼에 hover 효과 추가해줘."
🤖 Claude: "Button.jsx에 CSS-in-JS로 hover 효과를 추가했습니다."
# "이 버튼"이 Button.jsx를 가리킨다는 것을 컨텍스트로 이해

💬 You: "테스트 코드도 작성해줘."
🤖 Claude: "Button.test.jsx를 생성했습니다."
# Button 컴포넌트에 대한 테스트라는 것을 컨텍스트로 이해

고급 기능

프로젝트 컨텍스트 (CLAUDE.md)

CLAUDE.md는 프로젝트의 영구 지침 파일입니다. Claude Code는 매 세션 시작 시 이 파일을 자동으로 읽어 프로젝트 규칙, 코드 스타일, 아키텍처 등을 이해합니다.

CLAUDE.md 자동 생성

# 프로젝트 루트에서 자동 생성
claude /init

# 또는 수동으로 생성
cat > CLAUDE.md << 'EOF'
# 프로젝트 지시사항

## 코드 스타일
- TypeScript 사용
- ESLint + Prettier 준수
- 함수형 컴포넌트 (React Hooks)

## 네이밍 규칙
- 컴포넌트: PascalCase (예: UserProfile)
- 함수: camelCase (예: getUserData)
- 상수: UPPER_SNAKE_CASE (예: API_BASE_URL)

## 테스트
- Jest + React Testing Library 사용
- 최소 80% 커버리지 유지

## 빌드 & 실행
- `npm run dev` — 개발 서버
- `npm test` — 테스트 실행
EOF

CLAUDE.md 우선순위 계층

Rules 디렉토리

.claude/rules/에 주제별로 규칙 파일을 분리할 수 있습니다. YAML frontmatter로 특정 경로에만 적용되도록 제한할 수도 있습니다.

# .claude/rules/frontend.md
---
paths: ["src/components/**/*.tsx", "src/hooks/**/*.ts"]
---

- React 함수형 컴포넌트만 사용
- styled-components 대신 Tailwind CSS 사용
- 모든 props에 TypeScript 인터페이스 정의

설정 파일 (settings.json)

settings.json으로 도구 권한, 모델, 환경 변수 등을 설정할 수 있습니다.

// .claude/settings.json (프로젝트 — Git 커밋)
// .claude/settings.local.json (로컬 — gitignored)
// ~/.claude/settings.json (사용자 전역)
{
  "model": "sonnet",
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm test)", "Read"],
    "deny": ["Bash(rm -rf *)"]
  }
}

Auto Memory

Claude Code는 대화에서 배운 내용(빌드 명령, 선호도, 버그 원인 등)을 자동으로 ~/.claude/projects/<project>/memory/에 저장합니다. /memory 명령으로 관리할 수 있습니다.

멀티파일 편집

Claude CLI는 한 번의 요청으로 여러 파일을 동시에 생성하거나 수정할 수 있습니다.

💬 You: "사용자 인증 시스템 만들어줘.
- 회원가입, 로그인, 로그아웃 API
- JWT 토큰 사용
- bcrypt로 비밀번호 해싱
- Express + MongoDB

필요한 모든 파일 생성해줘."

🤖 Claude: "인증 시스템을 생성하겠습니다."

# 여러 파일 동시 생성
Created: src/models/User.js
Created: src/routes/auth.js
Created: src/middleware/auth.js
Created: src/utils/jwt.js
Created: src/config/database.js
Modified: src/app.js
Modified: package.json

🤖 Claude: "인증 시스템을 완성했습니다:
- User 모델 (MongoDB 스키마)
- 인증 라우트 (회원가입/로그인/로그아웃)
- JWT 미들웨어 (토큰 검증)
- 비밀번호 해싱 (bcrypt)
- 데이터베이스 연결 설정

환경 변수 설정 (.env):
```
MONGO_URI=mongodb://localhost:27017/myapp
JWT_SECRET=your-secret-key
```

테스트:
```
npm install
npm run dev
```"

스트리밍 응답

Claude CLI는 기본적으로 스트리밍 모드로 작동하여, 응답이 생성되는 즉시 표시됩니다. 긴 응답도 기다리지 않고 실시간으로 확인할 수 있습니다.

MCP 통합

Model Context Protocol (MCP) 서버를 연동하여 Claude에게 외부 도구 접근 권한을 부여할 수 있습니다. 설정 파일은 스코프별로 위치가 다릅니다.

// .mcp.json — MCP 서버 설정
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "http://localhost:3000"
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-slack"],
      "env": {
        "SLACK_TOKEN": "${SLACK_TOKEN}"
      }
    }
  }
}

CLI 플래그로 직접 MCP 설정 파일을 지정할 수도 있습니다:

claude --mcp-config ./my-mcp.json

MCP 가이드 →

CLI 플래그 레퍼런스

Claude Code CLI는 다양한 플래그로 동작을 제어할 수 있습니다.

기본 실행

claude                          # 대화형 세션 시작
claude "task description"        # 초기 프롬프트와 함께 시작
claude -p "query"               # 비대화형 모드 (print, 즉시 종료)
claude -c                       # 최근 대화 재개 (continue)
claude -r "session-name"        # 특정 세션 재개 (resume)

모델 및 추론

claude --model opus             # Opus 4.7 사용
claude --model sonnet           # Sonnet 4.6 사용
claude --model haiku            # Haiku 사용
claude --model opus[1m]         # Opus with 1M context window
claude --effort high            # 추론 노력 수준 (low/medium/high/max)

권한 및 보안

claude --permission-mode plan         # Plan Mode 시작
claude --permission-mode acceptEdits  # 파일 편집 자동 승인
claude --permission-mode auto         # Auto Mode (분류기 기반)
claude --permission-mode bypassPermissions  # 모든 권한 무시 (주의!)

도구 및 자동화

claude --allowedTools "Bash(git *)"  # 도구 사전 승인
claude --disallowedTools "Bash"     # 도구 비활성화
claude --mcp-config ./mcp.json       # MCP 서버 로드
claude --max-turns 5                # 최대 에이전트 턴 제한
claude --max-budget-usd 5.00        # 최대 비용 한도
claude --output-format json          # JSON 출력 (자동화용)
claude --output-format stream-json   # 스트리밍 JSON 출력

워크트리 및 추가 디렉토리

claude -w feature-auth          # Git worktree 생성 후 시작
claude --worktree               # 자동 이름으로 worktree 생성
claude --add-dir ../shared-lib  # 추가 작업 디렉토리 지정

권한 모드

Claude Code는 도구 실행 시 권한을 관리하는 여러 모드를 제공합니다.

# 실행 시 모드 지정
claude --permission-mode plan

# 세션 중 Shift+Tab으로 모드 순환

# settings.json에서 기본값 설정
# "defaultMode": "acceptEdits"

Hooks 시스템

Hooks는 특정 이벤트 발생 시 셸 명령을 자동 실행하는 기능입니다. 코드 포매팅, 린팅, 알림 등을 자동화할 수 있습니다.

주요 Hook 이벤트

Hook 설정 예시

// settings.json — 파일 편집 후 자동 포매팅
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test --silent 2>&1 | tail -5"
          }
        ]
      }
    ]
  }
}

모델 선택

# 세션 중 모델 변경
/model opus

# CLI 플래그로 지정
claude --model sonnet

# 환경 변수로 기본값 설정
export ANTHROPIC_MODEL=opus

# 추론 노력 수준 조정
/effort low    # 최소 추론 (빠름, 저비용)
/effort high   # 깊은 추론
/effort max    # 최대 추론 (Opus 전용)

Plan Mode

Plan Mode는 코드를 수정하기 전에 분석과 계획을 먼저 수립하는 모드입니다. 파일 읽기와 명령 실행(읽기 전용)만 가능하며, 실제 수정은 승인 후 진행됩니다.

# Plan Mode 시작
/plan
# 또는
claude --permission-mode plan

# 프로세스:
# 1) Claude가 코드를 읽고 분석
# 2) 수정 계획을 제시
# 3) 승인 후 실행 모드 선택:
#    - Auto Mode로 실행
#    - Accept Edits로 실행
#    - 수동 검토 모드로 실행

Fast Mode

Fast Mode는 동일한 Opus 4.7 모델을 약 2.5배 빠르게 실행합니다. 토큰당 비용이 높지만 빠른 반복이 필요할 때 유용합니다.

# Fast Mode 토글
/fast
# 또는 단축키
# Option+O (Mac) / Alt+O (Win/Linux)

사용 가능한 플랫폼

Claude Code는 CLI 외에도 다양한 환경에서 사용할 수 있습니다.

실전 워크플로우

새 프로젝트 시작

# 1. 디렉토리 생성
mkdir my-new-project
cd my-new-project

# 2. Git 초기화
git init

# 3. 프로젝트 지시사항 작성
mkdir .claude
cat > .claude/instructions.md << 'EOF'
# Next.js 프로젝트

- TypeScript 사용
- Tailwind CSS 스타일링
- App Router (Next.js 13+)
- ESLint + Prettier
EOF

# 4. Claude CLI 시작
claude

# 5. 초기 구조 요청
💬 You: "Next.js 13 프로젝트 초기 구조 만들어줘.
TypeScript, Tailwind, App Router 사용.
홈페이지에 Hero 섹션과 Feature 섹션 포함."

기존 프로젝트 리팩토링

# 프로젝트 디렉토리로 이동
cd existing-project

# Claude CLI 시작
claude

💬 You: "src/utils/helpers.js를 읽어봐.
이 코드를 TypeScript로 변환하고,
함수들을 더 작은 단위로 분리해줘.
테스트 코드도 작성해줘."

🤖 Claude: "helpers.js를 분석했습니다."

# 파일 읽기 → 분석 → 리팩토링
Created: src/utils/helpers.ts
Created: src/utils/helpers.test.ts
Deleted: src/utils/helpers.js

🤖 Claude: "TypeScript로 변환하고 다음과 같이 리팩토링했습니다:
- formatDate → dateUtils.ts
- validateEmail → validators.ts
- debounce → performanceUtils.ts
각 유틸리티별 테스트 코드도 작성했습니다."

버그 디버깅

💬 You: "npm test 실행했는데 에러 나. 로그 첨부할게:

TypeError: Cannot read property 'map' of undefined
  at UserList.render (UserList.jsx:15:18)

UserList.jsx 파일 확인하고 수정해줘."

🤖 Claude: "UserList.jsx를 확인했습니다. 문제를 발견했습니다."

Modified: src/components/UserList.jsx

🤖 Claude: "버그를 수정했습니다.
문제: users prop이 undefined일 때 map()을 호출
해결: Optional chaining과 기본값 추가

수정 전:
```jsx
{users.map(user => ...)}
```

수정 후:
```jsx
{(users || []).map(user => ...)}
```

또는:
```jsx
{users?.map(user => ...) || 
No users
}
```"

테스트 주도 개발 (TDD)

💬 You: "calculateDiscount 함수 만들려고 해.
먼저 테스트 코드부터 작성해줘.

요구사항:
- 10% 기본 할인
- 100달러 이상이면 15% 할인
- VIP 회원이면 추가 5% 할인"

🤖 Claude: "테스트 코드를 먼저 작성하겠습니다."

Created: src/utils/discount.test.ts

🤖 Claude: "테스트 케이스를 작성했습니다. 지금 실행하면 모두 실패할 것입니다."

💬 You: "좋아. 이제 함수 구현해줘."

Created: src/utils/discount.ts

🤖 Claude: "calculateDiscount 함수를 구현했습니다.
`npm test`로 테스트를 실행하면 모두 통과할 것입니다."

Ollama 병행 워크플로우

Claude CLI와 Ollama를 상황에 따라 병행하면 클라우드 추론 품질과 로컬 무제한·프라이버시를 동시에 활용할 수 있습니다.

언제 Ollama를 병행하는가?

오프라인 개발 워크플로우

네트워크가 없는 환경(비행기, 보안 시설 등)에서도 Ollama로 AI 코딩을 유지하는 패턴입니다.

# 📶 온라인 단계: Claude CLI로 핵심 작업 완료
# 아키텍처 설계, 핵심 알고리즘, 복잡한 로직 처리
claude "프로젝트 아키텍처를 설계하고 핵심 모듈 구조를 잡아줘"
claude "인증 모듈의 토큰 갱신 로직을 구현해줘"

# ✈️ 오프라인 전환: Ollama + Aider로 구현 작업 계속
ollama serve &   # 로컬 서버 시작

# 환경 변수 설정
export OLLAMA_API_BASE="http://localhost:11434"

# Aider + Ollama로 코딩 계속
aider --model ollama_chat/llama3.2 \
      --no-auto-commits \
      src/auth/*.ts

# 📶 다시 온라인: Claude CLI로 리뷰
claude "오프라인에서 작성한 auth 모듈 변경사항을 리뷰해줘"

작업 분할 패턴

Claude CLI와 Aider(Ollama)를 조합하여 작업을 효율적으로 분배하는 스크립트입니다.

#!/bin/bash
# dual-workflow.sh — Claude CLI + Aider(Ollama) 듀얼 워크플로우

# 1단계: Claude CLI로 설계 문서 생성
echo "📐 Claude CLI로 설계 중..."
claude "다음 요구사항으로 설계 문서를 작성해줘: $1" \
  --output design.md

# 2단계: Aider + Ollama로 코드 구현
echo "🔨 Aider + Ollama로 구현 중..."
aider --model ollama_chat/qwen2.5-coder:7b \
      --message "design.md를 기반으로 구현해줘" \
      --no-auto-commits \
      src/**/*.ts

# 3단계: Claude CLI로 코드 리뷰
echo "🔍 Claude CLI로 리뷰 중..."
claude "방금 구현된 코드를 리뷰하고 개선점을 알려줘"

echo "✅ 워크플로우 완료"

Aider + Ollama 보완 사용

Claude CLI의 강점(고품질 추론)과 Aider+Ollama의 강점(무제한 로컬 실행)을 워크플로우 단계별로 조합합니다.

┌─────────────────────────────────────────────────────────┐
│                    설계 → 구현 → 리뷰 워크플로우            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1️⃣ 설계 (Claude CLI)                                   │
│     $ claude "API 엔드포인트 설계해줘"                     │
│     → 아키텍처, 스키마, 인터페이스 정의                      │
│                                                         │
│  2️⃣ 구현 (Aider + Ollama)                                │
│     $ aider --model ollama_chat/qwen2.5-coder:7b        │
│     → 설계를 기반으로 코드 작성, 테스트 생성                │
│                                                         │
│  3️⃣ 리뷰 (Claude CLI)                                   │
│     $ claude "변경사항 리뷰해줘"                           │
│     → 코드 품질, 보안, 성능 검토                           │
│                                                         │
│  4️⃣ 수정 (Aider + Ollama)                                │
│     → 리뷰 피드백 반영, 반복 수정                          │
│                                                         │
└─────────────────────────────────────────────────────────┘

Local LLM 게이트웨이 연동

앞서 살펴본 Ollama 병행 워크플로우는 Claude CLI와 Ollama를 별도 도구로 사용하는 방식입니다. 여기서는 한 단계 더 나아가, Claude Code CLI 자체의 API 엔드포인트를 로컬 LLM으로 리다이렉트하여 동일한 CLI 인터페이스로 로컬 모델을 사용하는 방법을 다룹니다.

동작 원리

Claude Code CLI는 내부적으로 Anthropic Messages API(/v1/messages) 포맷을 사용합니다. 환경 변수 ANTHROPIC_BASE_URL을 설정하면 API 요청을 다른 서버로 보낼 수 있습니다. 단, 로컬 LLM은 Anthropic API 포맷을 직접 지원하지 않으므로, 중간에 API 변환 게이트웨이(프록시)가 필요합니다.

공식 지원 백엔드 비교

Claude Code CLI가 공식적으로 지원하는 API 백엔드와 로컬 게이트웨이를 비교합니다.

환경 변수 레퍼런스

LiteLLM 프록시 설정 가이드

LiteLLM은 Anthropic Messages API 포맷을 다양한 LLM 백엔드로 변환해주는 유일한 프록시입니다. 아래 단계를 따라 설정합니다.

Step 1: Ollama 모델 준비

# Ollama 실행 (이미 실행 중이면 생략)
ollama serve

# 코딩에 적합한 모델 다운로드
ollama pull qwen2.5-coder:14b

# 모델 동작 확인
ollama run qwen2.5-coder:14b "Hello, world!"

Step 2: LiteLLM 설치 및 설정 파일 작성

# LiteLLM 설치
pip install litellm[proxy]

# 설정 파일 생성
mkdir -p ~/.litellm

# Claude Code CLI가 요청하는 모델명을 로컬 모델로 매핑
model_list:
  - model_name: sonnet
    litellm_params:
      model: ollama/qwen2.5-coder:14b
      api_base: http://localhost:11434

  - model_name: haiku
    litellm_params:
      model: ollama/qwen2.5-coder:7b
      api_base: http://localhost:11434

  - model_name: opus
    litellm_params:
      model: ollama/qwen2.5-coder:32b
      api_base: http://localhost:11434

litellm_settings:
  # Anthropic Messages API 포맷 변환 활성화
  drop_params: true
  # 지원하지 않는 파라미터 자동 제거

Step 3: LiteLLM 프록시 시작

# 프록시 서버 시작 (기본 포트 4000)
litellm --config ~/.litellm/litellm_config.yaml --port 4000

# 백그라운드 실행
nohup litellm --config ~/.litellm/litellm_config.yaml --port 4000 &

Step 4: Claude Code CLI 연결

방법 A: 환경 변수 (일시적)

# 환경 변수 설정
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-any-string"  # 프록시 인증 불필요 시 아무 값

# Claude Code CLI 실행 — 로컬 모델 사용
claude

# 또는 한 줄로 실행
ANTHROPIC_BASE_URL="http://localhost:4000" \
ANTHROPIC_API_KEY="sk-any-string" \
claude "이 프로젝트 구조를 분석해줘"

방법 B: settings.json (영구 설정)

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_API_KEY": "sk-any-string"
  }
}

아키텍처 다이어그램

제약 사항 및 주의점

• API 포맷 필수: Claude Code CLI는 Anthropic Messages API (/v1/messages) 포맷만 사용합니다. OpenAI 호환 API (/v1/chat/completions)로는 동작하지 않으며, LiteLLM 같은 변환 프록시가 반드시 필요합니다.
• Claude 고유 기능 제한: Extended thinking, Computer use, Tool use 등 Claude 전용 기능은 로컬 모델에서 작동하지 않거나 품질이 크게 저하됩니다.
• 에이전트 루프 성능: Claude Code의 핵심인 파일 읽기/쓰기, 명령 실행 등 에이전트 기능은 모델의 도구 사용 능력에 크게 의존합니다. 소형 로컬 모델은 복잡한 에이전트 루프를 안정적으로 수행하기 어렵습니다.
• 모델 매핑 주의: litellm_config.yaml에서 Claude 모델 alias를 로컬 모델로 매핑해야 합니다. CLI가 요청하는 alias(예: sonnet, haiku, opus)를 설정하지 않으면 오류가 발생합니다.
• 스트리밍 호환성: 일부 로컬 LLM 백엔드의 SSE 스트리밍 구현이 불완전할 수 있으며, 응답이 끊기거나 지연될 수 있습니다.

모범 사례

효과적인 프롬프트

❌ 나쁜 예

💬 You: "앱 만들어줘."

문제: 너무 모호함. 어떤 앱인지, 어떤 기능인지 불명확.

✅ 좋은 예

💬 You: "React로 날씨 앱 만들어줘.

기능:
- 현재 위치 기반 날씨 표시
- 도시 검색 기능
- 5일 예보
- 날씨 아이콘

기술:
- React 18 + TypeScript
- OpenWeather API
- Tailwind CSS
- React Query for data fetching

파일 구조:
- src/components/ (컴포넌트)
- src/hooks/ (커스텀 훅)
- src/services/ (API 호출)"

장점: 명확한 요구사항, 기술 스택, 구조까지 지정.

컨텍스트 관리

1. .claude/instructions.md 활용

프로젝트 전체에 적용될 규칙을 작성하여 매번 반복하지 않기

2. .claudeignore 설정

불필요한 파일 제외로 토큰 절약 및 응답 속도 향상

3. 대화 초기화

주제가 바뀌면 /clear로 히스토리 초기화

Git 통합

Claude Code는 Git과 깊이 통합되어 있습니다. 커밋, 브랜치, PR 생성을 자연어로 요청할 수 있습니다.

# Claude에게 직접 커밋 요청
💬 You: "변경사항 커밋해줘"
# → Claude가 git diff 분석 → 커밋 메시지 작성 → 커밋

# PR 생성 요청
💬 You: "이 브랜치로 PR 만들어줘"
# → gh pr create 실행

# 수동으로 하려면
git add .
git commit -m "feat: Add user authentication system

- JWT token-based auth
- bcrypt password hashing
- Login/signup endpoints"

비용 최적화

비용 모니터링 및 최적화 →

운영 플레이북

Claude CLI는 터미널 중심 도구라서 \"프롬프트 작성\"보다 \"작업 절차 표준화\"가 더 중요합니다. 세션 규칙과 비용 규칙을 팀 공통으로 맞추면 결과 품질 편차를 크게 줄일 수 있습니다.

세션 운영 템플릿

# Claude CLI 세션 시작 체크리스트
1) git status 확인 (작업 디렉토리 상태 점검)
2) 작업 목표 1~2문장으로 고정
3) 산출물 형식 지정 (파일/테스트/문서)
4) 성공 조건 정의 (테스트 통과, 빌드 통과 등)
5) 실패 시 재시도 전략 지정 (모델 상향 여부 포함)

# 세션 종료 체크리스트
1) git diff 검토
2) 테스트 로그 확인
3) 변경 요약 작성
4) 다음 작업 TODO 정리

모델 티어 전략

비용 관리 템플릿

# 비용 운영 기준 (예시)
- 개인 일일 소프트 한도: 3 USD
- 개인 월 하드 한도: 60 USD
- 팀 월 한도: 700 USD
- 재시도 횟수 제한: 동일 작업 최대 2회
- 긴 컨텍스트 요청: 리뷰어 승인 후 실행

# 모니터링 지표
- 요청 수 / 성공 수 / 재시도 수
- 평균 입력 토큰 / 평균 출력 토큰
- 고비용 모델 사용 비율

트러블슈팅

일반적인 문제

❌ "API key not found" 또는 인증 실패

해결:

# 방법 1: 대화형 로그인
claude auth login

# 방법 2: API 키 설정
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"

# 환경 진단
claude doctor

❌ "Rate limit exceeded"

원인: 사용량 한도 초과

해결: 1분 대기 후 재시도. /cost로 현재 사용량 확인. /effort low로 토큰 절약.

❌ 파일이 생성되지 않음

해결:

• 현재 디렉토리 쓰기 권한 확인
• 권한 모드 확인 (Shift+Tab으로 전환)
• 더 구체적인 요청으로 재시도 (파일 경로 명시)

❌ 응답이 중간에 끊김 / 컨텍스트 초과

해결:

# 대화 컨텍스트 압축
/compact

# 또는 새 대화로 시작
/clear

Claude Code는 컨텍스트 한계에 도달하면 자동으로 이전 대화를 압축(compaction)합니다.

디버깅 팁

# 환경 진단 (설치, 인증, 설정 모두 확인)
claude doctor

# 디버그 모드로 실행
claude --debug

# 세션 비용 확인
/cost

# 세션 상태 확인
/status

성능 최적화

• /compact — 컨텍스트 압축으로 토큰 절약
• /effort low — 간단한 작업에서 추론 노력 최소화
• Haiku 모델 — 단순 작업에 /model haiku로 전환
• subagent 활용 — 탐색과 구현을 분리하여 컨텍스트 보존
• --max-turns — 에이전트 루프 횟수 제한으로 비용 관리
• --max-budget-usd — 세션 비용 한도 설정

핵심 정리

• 설치: curl -fsSL https://claude.ai/install.sh | bash로 설치, claude auth login 또는 API 키로 인증
• 프로젝트 설정: CLAUDE.md에 프로젝트 규칙 작성, .claude/settings.json으로 권한 및 도구 관리
• 모델 선택: 일반 작업은 Sonnet, 복잡한 추론은 Opus, 빠른 작업은 Haiku. /model로 전환
• 권한 관리: Plan Mode로 분석 → 승인 후 실행. Shift+Tab으로 모드 순환
• 자동화: Hooks로 포매팅/테스트 자동 실행, MCP로 외부 서비스 연동
• 비용 최적화: /effort로 추론 수준 조절, /compact로 컨텍스트 압축, --max-budget-usd로 한도 설정
• 플랫폼: CLI 외에 VS Code, JetBrains, Desktop App, Web 등 다양한 표면에서 이어서 사용할 수 있습니다.