Claude CLI 가이드

소개

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

왜 Claude CLI인가?

설치

방법 1: npx (권장 - 설치 불필요)

# 설치 없이 바로 실행
npx claude

# 처음 실행 시 패키지 다운로드
Need to install the following packages:
  @anthropic-ai/claude-cli
Ok to proceed? (y)

방법 2: 전역 설치

# npm으로 전역 설치
npm install -g @anthropic-ai/claude-cli

# 설치 확인
claude --version

# 이제 짧은 명령어로 실행
claude

API 키 설정

Claude CLI는 Anthropic API를 사용하므로 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

기본 사용법

CLI 시작

# Claude CLI 시작
npx claude

# 또는 전역 설치 후
claude

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

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

╭────────────────────────────────────────╮
│  Welcome to Claude Code CLI            │
│  Model: claude-     │
│  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 추가"

CLI 내장 명령어

대화 히스토리

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/)

.claude/ 디렉토리를 사용하여 프로젝트별 설정을 관리할 수 있습니다.

.claude/instructions.md

프로젝트 전체에 적용될 지시사항을 작성합니다. Claude는 매 요청마다 이 내용을 참조합니다.

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

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

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

## 테스트
- 모든 컴포넌트에 테스트 코드 작성
- Jest + React Testing Library 사용
- 최소 80% 커버리지 유지

## 파일 구조
```
src/
  components/
    Button/
      Button.tsx
      Button.test.tsx
      Button.stories.tsx
  hooks/
  utils/
```
EOF

이제 Claude는 모든 코드를 TypeScript로 생성하고, 지정된 네이밍 규칙을 따릅니다.

.claudeignore

특정 파일/디렉토리를 Claude의 컨텍스트에서 제외합니다 (.gitignore와 유사).

# .claudeignore
node_modules/
.git/
dist/
build/
*.log
.env
package-lock.json
yarn.lock

멀티파일 편집

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에게 외부 도구 접근 권한을 부여할 수 있습니다.

# .claude/mcp.json
{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

이제 Claude가 파일 시스템 접근, GitHub 조작 등을 할 수 있습니다.

MCP 가이드 →

실전 워크플로우

새 프로젝트 시작

# 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 시작
npx 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: claude-sonnet-4-20250514
    litellm_params:
      model: ollama/qwen2.5-coder:14b
      api_base: http://localhost:11434

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

  - model_name: claude-opus-4-20250514
    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 모델명을 로컬 모델로 매핑해야 합니다. CLI가 요청하는 정확한 모델명(예: claude-sonnet-4-20250514)을 설정하지 않으면 오류가 발생합니다.
• 스트리밍 호환성: 일부 로컬 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가 파일 변경 후
git status
git diff

# 변경사항 확인 후 커밋
git add .
git commit -m "feat: Add user authentication system

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

Co-Authored-By: Claude Sonnet (균형) "

비용 최적화

비용 모니터링 및 최적화 →

운영 플레이북

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"

원인: 환경 변수 미설정

해결:

echo $ANTHROPIC_API_KEY  # 확인
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"  # 설정

❌ "Rate limit exceeded"

원인: 너무 많은 요청

해결: 1분 대기 후 재시도. 또는 요청 간격 늘리기

❌ 파일이 생성되지 않음

원인: 디렉토리 권한 또는 모호한 요청

해결:

• 현재 디렉토리 쓰기 권한 확인
• 더 구체적인 요청으로 재시도
• 파일 경로를 명시적으로 지정

❌ 응답이 중간에 끊김

원인: 네트워크 문제 또는 토큰 제한

해결:

💬 You: "계속해줘" 또는 "이어서 작성해줘"

디버깅 팁

# 상세 로그 보기 (디버그 모드)
export DEBUG=claude:*
claude

# 현재 컨텍스트 확인
💬 You: "/context"

# 파일 목록 확인
💬 You: "/files"

성능 최적화

• .claudeignore 철저히 설정 (node_modules, .git 등)
• 대화 주기적 초기화 (/clear로 메모리 정리)
• 큰 파일 제외 (이미지, 비디오, 빌드 결과물)
• Haiku 모델 사용 (간단한 작업에 충분)

핵심 정리

• Claude CLI 가이드의 핵심 개념과 흐름을 정리합니다.
• 소개를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.