Claude CLI 5분 시작

Claude CLI란?

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

왜 Claude CLI인가?

• 공식 도구: Anthropic이 직접 개발 및 유지보수
• 최신 모델: Claude 4.6 Sonnet/Opus 및 Haiku 별칭 지원
• 최고 품질: 코드 생성 품질이 다른 도구들보다 우수
• 간단한 사용: 공식 네이티브 설치 후 claude 명령으로 시작
• MCP 지원: Model Context Protocol 네이티브 통합

Claude CLI 워크플로우

아래 다이어그램은 Claude CLI의 에이전트 개발 사이클을 보여줍니다.

Step 1: 로그인 또는 API 키 준비

Claude Code는 두 가지 방식으로 시작할 수 있습니다. 가장 간단한 방법은 Anthropic 계정 로그인이고, 팀 정책상 API 키를 써야 한다면 ANTHROPIC_API_KEY를 설정하면 됩니다.

1-1. 어떤 인증 방식을 쓸까?

1-2. 로그인 방식

1. claude auth login 실행
2. 브라우저에서 Anthropic 계정 인증
3. 터미널로 돌아와 claude 실행

# 로그인 시작
claude auth login

# 로그인 상태 확인
claude auth status

# 시작
claude

1-3. API 키 방식

Anthropic Console에서 키를 발급받아 환경 변수로 저장합니다.

1. console.anthropic.com 접속
2. API Keys에서 새 키 생성
3. 키를 복사해 환경 변수로 저장

# API 키 예시 (실제로는 더 깁니다)
sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxx...

환경 변수 설정

API 키를 환경 변수로 설정하면 매번 입력할 필요가 없습니다.

macOS / Linux (bash/zsh)

# ~/.bashrc 또는 ~/.zshrc에 추가
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxx"

# 즉시 적용
source ~/.bashrc  # 또는 source ~/.zshrc

Windows (PowerShell)

# 현재 세션만
$env:ANTHROPIC_API_KEY = "sk-ant-api03-xxxxxxx"

# 영구 설정 (시스템 환경 변수)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-xxxxxxx", "User")

Windows (CMD)

# 현재 세션만
set ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxx

1-4. API 키 확인

# 설정 확인 (macOS/Linux)
echo $ANTHROPIC_API_KEY

# Windows (PowerShell)
echo $env:ANTHROPIC_API_KEY

키가 출력되면 성공입니다. 이후 claude 명령으로 시작하세요.

Step 2: Claude CLI 실행

Claude CLI는 공식 네이티브 설치를 권장합니다. 설치 후 프로젝트 폴더에서 claude로 실행합니다.

2-0. 작업 폴더 준비

파일이 섞이지 않도록 새 폴더를 만들고 그 안에서 진행하세요:

# 작업 폴더 생성 및 이동
mkdir claude-quickstart
cd claude-quickstart

2-1. 사전 요구사항 확인

네이티브 설치 경로는 Node.js가 필요 없습니다. npm 호환 설치를 선택할 때만 Node.js 18 이상이 필요합니다:

# Node.js 버전 확인
node --version

# npm 버전 확인
npm --version

# 예상 출력
v18.17.0  # 18 이상이면 OK

2-2. Claude CLI 실행

# macOS / Linux / WSL 네이티브 설치
curl -fsSL https://claude.ai/install.sh | bash

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

# 설치 확인
claude --version

# 실행
claude

잠시 후 Claude CLI가 시작됩니다:

╭────────────────────────────────────────╮
│  Welcome to Claude Code CLI            │
│  Type your request or 'help' for info │
╰────────────────────────────────────────╯

💬 You: _

# npm 호환 설치
npm install -g @anthropic-ai/claude-code

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

2-3. 첫 번째 명령어

Claude에게 간단한 요청을 해봅시다:

💬 You: "안녕, Claude! 간단한 인사말을 출력하는 Python 스크립트 만들어줘."

🤖 Claude: "안녕하세요! Python 인사말 스크립트를 만들겠습니다."

# 파일 생성됨
Created: hello.py

# 내용 확인
def main():
    print("안녕하세요! Claude CLI에 오신 것을 환영합니다.")
    print("Vibe Coding의 세계를 즐겨보세요!")

if __name__ == "__main__":
    main()

🤖 Claude: "hello.py 파일을 생성했습니다. `python hello.py`로 실행해보세요!"

파일이 생성되었습니다! 실행해봅시다:

# 새 터미널 창 열기 (또는 Claude CLI 종료 후)
python hello.py

# 출력
안녕하세요! Claude CLI에 오신 것을 환영합니다.
Vibe Coding의 세계를 즐겨보세요!

Step 3: 첫 번째 실전 프로젝트

실용적인 TODO 웹 앱을 만들어봅시다. HTML + CSS + JavaScript로 구성됩니다.

3-1. 프로젝트 디렉토리 생성

# 작업 디렉토리 생성
mkdir todo-app
cd todo-app

# Claude CLI 시작
claude

3-2. 프로젝트 요청

Claude에게 구체적인 요구사항을 전달합니다:

💬 You:
"HTML, CSS, JavaScript로 TODO 웹 앱을 만들어줘.

요구사항:
1. 할 일 입력 필드 (Enter로 추가)
2. 할 일 목록 (체크박스 + 텍스트 + 삭제 버튼)
3. 완료된 항목은 취소선 표시
4. localStorage에 저장 (새로고침해도 유지)
5. 남은 할 일 개수 표시
6. 깔끔한 UI (파스텔 톤 색상)
7. 반응형 디자인 (모바일 지원)

파일 3개로 나눠줘:
- index.html
- style.css
- script.js"

3-3. AI 응답 확인

🤖 Claude: "TODO 웹 앱을 생성하겠습니다!"

# 파일 생성 중...
index.html 생성 중...
style.css 생성 중...
script.js 생성 중...

🤖 Claude: "3개 파일을 생성했습니다.

📄 index.html
- 시맨틱 HTML5 구조
- 입력 필드와 할 일 목록 컨테이너
- 남은 할 일 카운터

🎨 style.css
- 파스텔 톤 색상 (#e3f2fd, #fff9c4 등)
- Flexbox 레이아웃
- 반응형 미디어 쿼리
- 부드러운 트랜지션 애니메이션

⚙️ script.js
- 할 일 추가/삭제/완료 토글
- localStorage 영구 저장
- 카운터 자동 업데이트
- Enter 키 이벤트

브라우저에서 index.html을 열어 테스트해보세요!"

3-4. 앱 테스트

# 간단한 HTTP 서버 실행
# Python 3 사용
python3 -m http.server 8000

# 또는 Node.js
npx serve

# 브라우저에서 열기
open http://localhost:8000

3-5. 앱 개선하기

Claude와 대화하며 기능을 추가해봅시다:

💬 You: "좋아! 이제 다음 기능들 추가해줘:
1. 다크모드 토글 버튼
2. 완료된 항목을 아래로 이동
3. '모두 삭제' 버튼
4. 할 일에 우선순위 표시 (High/Medium/Low)"

🤖 Claude: "모든 기능을 추가했습니다!

✨ 변경사항:
1. index.html - 다크모드 토글, 모두 삭제 버튼, 우선순위 select 추가
2. style.css - 다크모드 스타일, 우선순위별 색상 (빨강/노랑/초록)
3. script.js - 자동 정렬 로직, 다크모드 전환, 일괄 삭제 기능

localStorage에 다크모드 설정도 저장됩니다."

페이지를 새로고침하면 새로운 기능들이 적용됩니다!

3-6. 코드 이해하기

생성된 코드가 이해되지 않는다면 Claude에게 물어보세요:

💬 You: "script.js에서 localStorage.setItem은 어떻게 작동해?"

🤖 Claude: "localStorage.setItem은 브라우저의 로컬 스토리지에 데이터를 저장하는 함수입니다.

문법:
```javascript
localStorage.setItem(key, value)
```

우리 앱에서는:
```javascript
localStorage.setItem('todos', JSON.stringify(todosArray));
```

- 'todos': 저장할 데이터의 키 (이름)
- JSON.stringify(): JavaScript 객체를 문자열로 변환
  (localStorage는 문자열만 저장 가능)

데이터 읽기:
```javascript
const saved = localStorage.getItem('todos');
const todos = JSON.parse(saved); // 문자열을 객체로 변환
```

이렇게 하면 브라우저를 닫았다 열어도 데이터가 유지됩니다!"

다음 단계

Claude CLI 기본을 마스터했습니다! 이제 더 고급 기능을 배워봅시다:

고급 기능

연습 프로젝트

추가 학습 자료

• Claude CLI 가이드 - 모든 기능 상세 설명
• 코딩용 프롬프트 - 효과적인 요청 방법
• CLI 모범 사례 - 실전 노하우
• API 키 관리 - 보안 설정

문제 해결

일반적인 문제

❌ "API key not found" 오류

원인: 환경 변수가 설정되지 않음

해결:

# 환경 변수 확인
echo $ANTHROPIC_API_KEY

# 비어있다면 다시 설정
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxx"

❌ "npx: command not found"

원인: Node.js가 설치되지 않음

해결: Node.js 설치

❌ "Rate limit exceeded"

원인: 너무 많은 요청을 빠르게 보냄

해결: 잠시 기다렸다가 재시도 (보통 1분)

❌ 파일이 생성되지 않음

원인: 디렉토리 권한 문제 또는 요청이 불명확

해결:

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

❌ "Permission denied" 또는 접근 권한 오류

원인: 시스템 보호 디렉토리에서 작업 중

해결: 홈 디렉토리 아래 새 폴더를 만들고 그 안에서 실행

mkdir claude-quickstart
cd claude-quickstart

❌ "Port 8000 is already in use"

원인: 이미 다른 프로그램이 8000 포트 사용 중

해결: 다른 포트로 서버 실행

python3 -m http.server 8080
# 브라우저: http://localhost:8080

❌ "Insufficient credits"

원인: 로그인 플랜 한도 초과, API 예산 부족, 또는 결제 설정 문제

해결:

• 로그인 기반 사용자는 현재 플랜 한도와 계정 상태 확인
• API 키 기반 사용자는 Billing 페이지에서 결제 수단과 사용량 한도 확인
• 또는 Ollama로 전환 (무료)

핵심 정리

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