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`로 테스트를 실행하면 모두 통과할 것입니다."

모범 사례

효과적인 프롬프트

❌ 나쁜 예

💬 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 (균형) "

비용 최적화

비용 모니터링 및 최적화 →

트러블슈팅

일반적인 문제

❌ "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 가이드의 핵심 개념과 흐름을 정리합니다.
• 소개를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.