Claude Code 시작하기: 한국 개발자 30분 완성 가이드 (2026)

Q: 월 비용이 얼마나 들어요?

개인 사이드 프로젝트 수준(주 5~10시간)이면 월 $20~$50. 본업으로 매일 4시간 이상 쓴다면 $150~$400. 80/15/5 라우팅과 prompt caching을 적용하면 같은 작업량에서 60~70% 절감이 가능합니다.

Claude Code는 Anthropic이 공식 제공하는 터미널 기반 코딩 에이전트 CLI입니다. npm install -g @anthropic-ai/claude-code 또는 Homebrew로 설치하고, console.anthropic.com에서 API 키를 발급받은 뒤 claude 명령 한 줄로 바로 시작할 수 있습니다. 30분이면 설치, 인증, 첫 프로젝트 자동화까지 끝납니다. 한국어 출력은 프로젝트 루트의 CLAUDE.md에 "모든 응답은 한국어로 작성"이라고 명시하면 강제됩니다. macOS와 Linux는 네이티브 지원이고, Windows는 WSL2를 권장합니다. 이 글은 한국 개발자가 가장 자주 막히는 지점(API 결제, 한국어 강제, 비용 통제)에 초점을 맞춘 실전 입문서입니다.

왜 Claude Code인가?

Cursor, GitHub Copilot, Cline 같은 경쟁 도구가 이미 많은데 왜 또 Claude Code일까요? 핵심 차이점은 세 가지입니다.

터미널 네이티브: IDE에 종속되지 않습니다. Vim, Emacs, VS Code, JetBrains 어떤 환경이든 터미널만 있으면 동일하게 동작합니다. SSH로 원격 서버에서도 그대로 씁니다.
멀티 파일 편집: Cursor가 한 파일 컨텍스트에 강하다면, Claude Code는 수십 개 파일을 동시에 열어 일관된 리팩터링을 수행합니다. "이 프로젝트의 모든 fetch를 axios로 바꿔줘" 같은 명령이 한 번에 끝납니다.
에이전트 루프: 단순 자동완성이 아니라, 실패한 테스트를 보고 → 코드 수정 → 다시 실행 → 통과까지 자율적으로 반복합니다. Bash, 파일 편집, 웹 검색, MCP 도구를 스스로 조합합니다.

요약하면 Cursor는 "스마트한 자동완성"이고 Claude Code는 "자율 주니어 개발자"에 가깝습니다. 둘은 경쟁이라기보다 보완 관계라, 실제로 둘 다 쓰는 분도 많습니다. 더 자세한 비교는 Claude Code 완전 가이드를 참고하세요.

설치 (3가지 방법)

운영체제와 패키지 매니저에 따라 가장 편한 방법을 고르세요. 셋 다 동일한 바이너리를 설치합니다.

# 1. npm (모든 플랫폼, 가장 일반적)
npm install -g @anthropic-ai/claude-code

# 2. bun (속도 최우선, macOS/Linux 권장)
bun add -g @anthropic-ai/claude-code

# 3. Homebrew (macOS 전용, 자동 업데이트 편리)
brew install anthropic/claude-code/claude-code

Windows 사용자는 PowerShell에서 npm을 써도 되지만, 한국어 인코딩과 경로 문제로 종종 어색하게 동작합니다. WSL2(Ubuntu 24.04 권장)에 Node.js를 설치하고 거기서 npm으로 깔면 macOS와 거의 동일한 경험을 얻을 수 있습니다.

설치가 끝나면 버전을 확인합니다.

claude --version
# Claude Code v2.1.x

API 키 발급 walkthrough

Claude Code는 Claude API를 호출하므로 별도 결제 계정이 필요합니다. ChatGPT Plus 같은 월 정액제가 아니라, 사용한 토큰만큼 후불로 청구되는 종량제입니다.

console.anthropic.com 접속 — 구글 계정 또는 이메일로 가입합니다.
Billing → Add payment method — 신용카드(Visa/Master) 등록. 한국 발행 카드도 정상 동작하지만, 일부 체크카드는 인증이 거부될 수 있어 신용카드 권장입니다.
선불 크레딧 충전 — 최소 $5부터. 처음에는 $10 정도로 시작해서 사용 패턴을 보며 늘리면 됩니다.
API Keys → Create Key — 키 이름은 자유롭게(예: claude-code-laptop). 생성 직후에만 전체 키가 보이므로 비밀번호 매니저에 즉시 저장하세요.
Usage limit 설정 — Settings → Usage limits에서 일일/월간 한도를 반드시 걸어두세요. 무한 루프 사고 시 청구서 폭탄을 막아줍니다. 처음에는 일 $5, 월 $50 정도가 안전합니다.

결제가 막히거나 환불이 필요한 경우는 Claude API 결제·환불 한국어 가이드를 따로 보시면 됩니다.

첫 실행 + 인증

키를 발급받았다면, 작업할 프로젝트 디렉토리로 이동해 claude를 실행합니다.

cd ~/projects/my-app
claude

처음 실행하면 인증 방법을 묻습니다. Anthropic API → 발급한 키 붙여넣기. 키는 ~/.claude/settings.json에 암호화되어 저장됩니다(절대 git에 올리지 마세요).

인증이 끝나면 프롬프트가 뜹니다.

> 안녕하세요, 무엇을 도와드릴까요?

여기서 자유 문장으로 질문하거나 / 슬래시 명령을 사용합니다.

첫 5개 명령 (실전 워크플로)

설치만 하고 끝내면 의미가 없습니다. 처음 30분 동안 이 다섯 가지를 직접 해보세요. 모든 입력은 한국어로 자연스럽게 적어도 됩니다.

1. /init — 프로젝트 CLAUDE.md 생성

프로젝트 구조를 분석해 자동으로 CLAUDE.md(이 프로젝트만의 컨텍스트 문서)를 만들어줍니다. Claude Code가 매 세션마다 읽는 "프로젝트 매뉴얼"입니다.

2. 자유형 — README 한국어 번역

이 프로젝트의 README.md를 한국어로 번역해서 README.ko.md로 저장해줘. 코드 블록은 그대로 두고.

영어 OSS 프로젝트를 한국어 사이드 문서로 미러링할 때 매우 유용합니다.

3. /cost — 토큰 사용량 + 비용 확인

현재 세션의 입력/출력 토큰, 캐시 적중률, 누적 비용을 USD로 보여줍니다. 30분 일하면 보통 $0.50~$2 정도입니다.

4. 파일 자동 생성 — backup.sh

scripts/ 폴더에 매일 자정 ./data 폴더를 ~/backups로 압축 백업하는 backup.sh를 만들어줘. 권한도 chmod +x 해주고.

Claude Code는 파일 생성, chmod, 디렉토리 확인까지 한 번에 처리합니다.

5. 디버깅 — 테스트 실패 분석

npm test가 실패하는데 이유 분석하고 고쳐줘. 단, 테스트 코드는 수정하지 말고 구현만 고쳐.

"테스트 코드는 수정하지 말고"처럼 제약을 명시하면 LLM이 손쉬운 우회를 막을 수 있습니다.

한국어 출력 강제하기

기본 모델은 영어로 답하는 경향이 강합니다. 한국어를 항상 받으려면 프로젝트 루트의 CLAUDE.md에 명시적으로 적습니다.

# Project: my-app

## 응답 언어
- 모든 응답은 한국어 존댓말로 작성합니다.
- 영문 기술 용어(API, function, deploy 등)는 번역하지 않고 그대로 둡니다.
- 코드 주석은 한국어로 작성합니다.
- 커밋 메시지는 영어 conventional commits 형식을 유지합니다.

## 코딩 스타일
- TypeScript strict mode
- ESM 모듈만 사용
- 들여쓰기 2칸

이 패턴이 가장 견고합니다. 시스템 프롬프트에 지시문을 분산하지 말고 CLAUDE.md 한 곳에 모으면 충돌이 적고 캐시 적중률도 높아집니다. 자세한 패턴은 Claude Code 한국어 가이드에 정리되어 있습니다.

모델 선택: 80/15/5 규칙

Claude Code는 Haiku, Sonnet, Opus 세 모델을 사용할 수 있고 가격이 10배씩 차이 납니다. 무작정 Opus만 쓰면 한 달 청구서가 수백 달러로 폭주합니다. 권장 비율은 다음과 같습니다.

Haiku 80% — 콘텐츠 초안, 단순 수정, 반복 작업, 파일 이름 짓기, 짧은 번역
Sonnet 15% — 코드 디버깅, 복합 분석, 중간 난이도 추론
Opus 5% — 아키텍처 설계, 보안 심사, 복잡한 리팩터링 전략

세션 안에서 모델을 바꾸려면 /model haiku, /model sonnet, /model opus를 입력합니다. 기본값은 opusplan(계획은 Opus, 실행은 Sonnet)이 가성비가 가장 좋습니다.

비용 통제 (CTA)

잠깐 — 비용 추적 안 하면 첫 달에 깜짝 청구서 받습니다.

무료 도구 claudecosts.app을 깔면 매일 사용량을 자동 추적하고 한도 초과 시 알림을 보냅니다. 더 깊이 파고들고 싶다면 저희 Cost Optimization Masterclass ($59)에서 80/15/5 라우팅을 자동화하는 7가지 패턴을 다룹니다. 첫 달 청구서를 60~70% 줄인 한국 개발자 사례 4건을 케이스 스터디로 포함했습니다.

추가 절감 팁은 Claude API 비용 절감 한국어 가이드에 정리되어 있습니다.

주요 함정 5가지

처음 한 달 안에 한국 개발자들이 가장 자주 만나는 사고들입니다.

API 키 노출 — ~/.claude/settings.json은 물론, 프로젝트의 .claude/settings.local.json도 절대 git에 올리지 마세요. .gitignore에 .claude/settings.local.json을 미리 추가하세요. 노출 시 즉시 콘솔에서 키를 폐기(revoke)하고 새로 발급합니다.
무한 루프 — 에이전트가 동일한 실패를 반복하며 토큰을 태우는 경우가 있습니다. 터미널에서 Ctrl+C로 즉시 중단하고, /clear로 컨텍스트를 비운 뒤 더 좁은 작업으로 다시 시도하세요.
Windows 네이티브 어색 — PowerShell에서 한글 경로, 줄바꿈(CRLF), 권한 문제로 빈번히 멈춥니다. WSL2 Ubuntu에서 실행하는 것을 강력히 권장합니다.
한국어가 영어로 섞이는 경우 — CLAUDE.md에 추가로 "이전 답변에서 영어가 섞였다면 다시 한국어로 작성"이라는 한 줄을 넣으면 회복률이 높아집니다. Sonnet/Opus가 Haiku보다 한국어 안정성이 더 좋습니다.
비용 폭주 — 콘솔의 monthly limit + claudecosts.app 일일 알림을 이중으로 걸어두세요. 한 번의 무한 루프가 $50을 태우는 데 5분이면 충분합니다.

자주 묻는 질문

Cursor와 무엇이 다른가요?

Cursor는 IDE 기반 자동완성에 강하고, Claude Code는 터미널 기반 에이전트 루프에 강합니다. Cursor에서 한 파일을 정밀 편집하고, 큰 리팩터링이나 멀티 파일 작업은 Claude Code로 돌리는 식의 병행 사용이 현실적입니다. 둘 다 Claude 모델을 호출하므로 모델 품질 차이는 거의 없습니다.

한국어 출력이 안 정확해요. 어떻게 하나요?

세 가지를 순서대로 시도하세요. (1) CLAUDE.md에 언어 지시를 명시적으로 작성, (2) Haiku 대신 Sonnet 또는 Opus로 모델 변경, (3) 시스템 프롬프트에 한국어 예시 2~3개를 few-shot으로 포함. 대부분 (1)+(2)에서 해결됩니다.

API 키를 안전하게 보관하려면?

1Password, Bitwarden 같은 비밀번호 매니저에 저장하고, 머신마다 별도 키를 발급해 사고 시 한 키만 폐기하면 되도록 격리하세요. .env 파일에 평문으로 두는 건 단기적으로는 괜찮지만 mode 600 권한과 .gitignore 등록은 필수입니다. 클라우드 환경에서는 AWS Secrets Manager, GCP Secret Manager를 사용합니다.

월 비용이 얼마나 들어요?

개인 사이드 프로젝트 수준(주 5~~10시간)이면 월 $20~~$50. 본업으로 매일 4시간 이상 쓴다면 $150~$400. 80/15/5 라우팅과 prompt caching을 적용하면 같은 작업량에서 60~70% 절감이 가능합니다.

팀에서 같이 쓸 수 있나요?

가능합니다. 콘솔에서 Workspace를 만들고 멤버를 초대하면 결제는 통합되고 사용량은 멤버별로 추적됩니다. 팀 단위 CLAUDE.md는 git으로 공유하고, 개인 설정은 .claude/settings.local.json(gitignore)에 분리하는 것이 표준 패턴입니다.

마무리

Claude Code는 "터미널에서 동작하는 자율 주니어 개발자"입니다. 30분 투자로 설치, 인증, 첫 자동화까지 끝낼 수 있고, 처음 한 달은 비용 통제와 한국어 강제 두 가지에만 집중하면 사고 없이 정착합니다. 더 깊이 들어가고 싶다면 Claude Code 완전 가이드와 Claude Code 한국어 가이드로 이어가세요. 결제가 막히거나 환불이 필요한 경우는 Claude API 결제·환불 한국어 가이드, 비용 절감 심화는 Claude API 비용 절감 한국어에서 다룹니다.

오늘 안에 첫 명령을 실행해 보세요. 가장 빠른 학습은 결국 본인의 실제 프로젝트에서 한 번 돌려보는 것입니다.