Claude CLI 5분 시작

Claude CLI란?

Claude Code (Claude CLI)는 Anthropic이 공식 제공하는 에이전틱 코딩 도구입니다. 터미널에서 Claude와 대화하며 코드를 읽고, 파일을 수정하고, 명령어를 실행하고, 프로젝트 전체를 관리할 수 있습니다. 단순한 코드 생성을 넘어, 파일 시스템·터미널·Git·웹 검색에 직접 접근하여 "수집 → 행동 → 검증"의 에이전틱 루프를 자동으로 반복합니다. 터미널 CLI 외에도 VS Code, JetBrains, 데스크톱 앱, 웹(claude.ai/code), Slack 등 다양한 플랫폼에서 사용할 수 있습니다.

왜 Claude Code인가?

• 에이전틱 코딩: 단순 자동완성이 아니라, 코드베이스를 이해하고 여러 파일에 걸쳐 자율적으로 작업합니다.
• 도구 접근: 파일 읽기/쓰기, 셸 명령 실행, Git 조작, 웹 검색 등을 직접 수행합니다.
• 멀티 플랫폼: 터미널, VS Code, JetBrains, 데스크톱 앱, 웹에서 동일한 엔진을 사용합니다.
• 확장 가능: MCP 서버로 외부 도구를 연결하고, Skills와 Hooks로 워크플로우를 커스터마이징할 수 있습니다.
• 안전한 실행: Permission Modes와 Checkpoints로 안전하게 작업을 검증하고 되돌릴 수 있습니다.

Claude CLI 워크플로우

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

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

Claude Code를 사용하려면 인증이 필요합니다. 두 가지 방법이 있으며, 로그인 방식(권장)이 더 간단합니다.

1-1. 로그인 방식 (권장)

Claude Pro, Max, Team 또는 Enterprise 구독이 있다면 가장 간단합니다:

# Claude Code 실행 — 브라우저에서 자동 로그인 안내
claude

# 세션 내에서 계정 전환 시
/login

브라우저에서 Anthropic 계정으로 로그인하면 인증이 완료됩니다. 로그인 자격 증명은 시스템에 저장되므로 다시 로그인할 필요가 없습니다.

1-2. API 키 방식

Anthropic Console에서 API 키를 발급받아 환경 변수로 설정할 수도 있습니다:

# 1. Anthropic Console에서 API 키 발급
#    https://console.anthropic.com/settings/keys

# 2. 환경 변수에 설정

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

# macOS/Linux 현재 세션만
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxx"

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

# 설정 확인
echo $ANTHROPIC_API_KEY

1-3. 클라우드 제공자 방식

기업 환경에서는 Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry를 통해서도 사용할 수 있습니다. 각 제공자의 설정 방법은 공식 문서를 참고하세요.

Step 2: Claude Code 설치 및 실행

2-1. 작업 폴더 준비

# 작업 폴더 생성 및 이동
mkdir my-project && cd my-project

2-2. 설치 방법

Claude Code는 여러 방법으로 설치할 수 있습니다. 네이티브 설치(권장)는 자동 업데이트가 포함되어 가장 편리합니다.

# ✅ 네이티브 설치 (권장) — 자동 업데이트 포함

# macOS / Linux / WSL
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

# 📦 패키지 매니저 설치

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

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# apt (Debian/Ubuntu)
# dnf (Fedora/RHEL)
# apk (Alpine) — 공식 문서 참고

2-3. 설치 확인 및 진단

# 설치 확인
claude --version
# 예시 출력: 2.1.211 (Claude Code)

# 설치 상태 종합 진단
claude doctor

claude doctor는 설치 건강성, 설정 파일 유효성, 업데이트 상태 등을 진단하고 수정 방법을 제안합니다. 문제가 있을 때 먼저 실행해보세요.

2-4. Claude Code 실행

# 프로젝트 디렉토리에서 실행
claude

실행하면 모델 이름, 현재 모델, 작업 디렉토리가 표시됩니다. /help로 사용 가능한 명령어를 확인하고, /resume으로 이전 대화를 이어갈 수 있습니다.

2-5. 필수 명령어

알아두면 유용한 CLI 플래그와 세션 명령어입니다:

2-6. 키보드 단축키

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 Code를 효과적으로 사용하기 위해 알아두면 좋은 핵심 개념입니다.

권한 모드 (Permission Modes)

Claude Code는 파일 수정이나 명령 실행 전에 사용자 허락을 구합니다. Shift+Tab으로 모드를 전환하여 허용 수준을 조절할 수 있습니다.

CLAUDE.md — 프로젝트 지침 파일

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 마크다운 파일입니다. 프로젝트의 코딩 규칙, 아키텍처 결정, 빌드 명령어 등을 여기에 적으면 Claude가 매번 동일한 맥락으로 작업합니다.

# CLAUDE.md (프로젝트 루트에 생성)

# 코딩 스타일
- ES 모듈(import/export) 사용, CommonJS(require) 금지
- 함수명은 camelCase, 컴포넌트명은 PascalCase

# 빌드 및 테스트
- 빌드: npm run build
- 테스트: npm test (단일 테스트는 npm test -- --testPathPattern=이름)
- 타입 체크: npx tsc --noEmit

# 워크플로우
- 코드 변경 후 반드시 테스트 실행
- 커밋 메시지는 Conventional Commits 형식

/init 명령어로 현재 프로젝트를 분석하여 CLAUDE.md 초안을 자동 생성할 수 있습니다.

Checkpoints — 되돌리기

Claude가 파일을 수정하기 전에 자동으로 스냅샷을 생성합니다. 실수가 있었다면 Esc를 두 번 눌러 이전 상태로 되돌릴 수 있습니다. Git과 별개로 동작하며, 세션을 복원해도 스냅샷이 유지됩니다.

다음 단계

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 Code는 에이전틱 코딩 도구로, 코드 읽기/수정/명령 실행을 자율적으로 수행합니다.
• 설치: 네이티브 설치(curl | bash)가 가장 간편하고 자동 업데이트가 포함됩니다.
• 인증: Claude 구독 계정 로그인이 기본, API 키가 보조 경로입니다.
• 에이전틱 루프: 컨텍스트 수집 → 행동 → 검증을 반복하여 작업을 완성합니다.
• CLAUDE.md에 프로젝트 규칙을 적으면 매 세션 자동으로 적용됩니다.
• 권한 모드를 조절하여 안전성과 속도의 균형을 맞출 수 있습니다.
• claude doctor로 설치 상태를 진단하고, /help로 명령어를 확인하세요.