Claude Code 설치 — AI 코딩 어시스턴트 시작하기

들어가며

Claude Code는 Anthropic의 Claude AI를 터미널에서 직접 사용할 수 있는 강력한 CLI 도구입니다. 코드 작성, 파일 편집, 디버깅, 프로젝트 분석 등을 대화형으로 수행할 수 있으며, IDE와 통합하여 효율적인 개발 워크플로우를 구축할 수 있습니다.

이 가이드는 Claude Code의 설치부터 초기 설정, 주요 기능, 그리고 기본적인 사용법까지 다룹니다.

 

 

목차

1. Claude Code란 무엇인가?
2. 시스템 요구사항
3. 설치 방법
4. 초기 설정 및 인증
5. 기본 사용법

 

 

Claude Code란 무엇인가?

핵심 기능

Claude Code는 다음과 같은 강력한 기능을 제공합니다:

기능	설명
코드 생성	자연어 지시로 코드 작성
파일 편집	기존 파일을 읽고 수정
프로젝트 분석	코드베이스 전체 탐색 및 이해
버그 수정	오류 진단 및 해결책 제시
리팩토링	코드 개선 및 최적화
테스트 작성	자동 테스트 코드 생성
문서화	README, 주석, API 문서 작성
터미널 명령	Git, npm, Docker 등 실행

Claude Code vs 다른 AI 코딩 도구

도구	장점	단점
Claude Code	강력한 추론 능력, 긴 컨텍스트, 파일 편집	CLI 기반 (UI 없음)
GitHub Copilot	IDE 통합 우수	짧은 컨텍스트, 단순 자동완성 중심
Cursor	전용 IDE, 시각적	유료 구독, 에디터 제한
ChatGPT	웹 기반, 접근 쉬움	파일 직접 편집 불가

시스템 요구사항

최소 요구사항

• 운영체제:
  • macOS 10.15 (Catalina) 이상
  • Linux (Ubuntu 18.04+, Debian 10+, Fedora 30+)
  • Windows 10/11 (WSL2 권장)
• Node.js: 18.0 이상 (20.x 권장)
• 메모리: 최소 4GB RAM
• 디스크: 500MB 여유 공간
• 네트워크: 인터넷 연결 (API 호출용)

권장 환경

• 터미널: iTerm2 (macOS), Windows Terminal, Alacritty
• 셸: Bash, Zsh, Fish
• 에디터: VS Code, Neovim, Vim

 

 

설치 방법

방법 1: npm으로 설치 (권장)

npm을 통한 설치가 가장 간단하고 안정적입니다.

# 1. Node.js 버전 확인
node --version
# v20.x.x 이상이어야 함

# 2. Claude Code 전역 설치
npm install -g @anthropic-ai/claude-code

# 3. 설치 확인
claude --version
# 출력: claude-code v1.x.x

설치 중 권한 오류 발생 시:

# macOS/Linux: sudo 사용
sudo npm install -g @anthropic-ai/claude-code

# 또는 nvm 사용 (권장)
# nvm으로 설치한 Node.js는 권한 문제 없음

방법 2: npx로 임시 실행

설치 없이 바로 사용하고 싶다면:

# 설치 없이 실행
npx @anthropic-ai/claude-code

# 매번 최신 버전 사용
npx @anthropic-ai/claude-code@latest

장점:

• 설치 불필요
• 항상 최신 버전 사용

단점:

• 실행할 때마다 다운로드 (느림)
• 로컬 설정 유지 어려움

방법 3: 소스에서 빌드

개발자이거나 최신 개발 버전을 사용하려면:

# 1. 레포지토리 클론
git clone https://github.com/anthropics/claude-code.git
cd claude-code

# 2. 의존성 설치
npm install

# 3. 빌드
npm run build

# 4. 전역 링크
npm link

# 5. 실행 확인
claude --version

Windows 설치 (WSL2)

Windows에서는 WSL2 사용을 강력히 권장합니다:

# PowerShell에서 WSL2 설치
wsl --install

# Ubuntu 재시작 후 WSL 터미널에서
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

네이티브 Windows (실험적):

# Node.js 설치 (https://nodejs.org/)
# PowerShell에서
npm install -g @anthropic-ai/claude-code

# 경로 확인
where claude

 

 

 

초기 설정 및 인증

API 키 발급

1. Anthropic Console 접속
   • https://console.anthropic.com/ 방문
   • Google 또는 이메일로 로그인
2. API 키 생성
   • 키 이름 입력 (예: "claude-code-dev")
   • 생성된 키 복사 (한 번만 표시됨!)
3. Settings → API Keys → Create Key
4. 크레딧 확인
   • 신규 가입 시 $5 무료 크레딧 제공
   • 사용량 확인: Settings → Billing

인증 설정

방법 1: 대화형 설정 (권장)

# Claude Code 실행
claude

# 처음 실행 시 API 키 입력 프롬프트
# API key를 입력하면 ~/.claude/config.json에 자동 저장

방법 2: 환경변수

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

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

# 테스트
claude chat "Hello"

방법 3: 설정 파일 직접 편집

# 설정 디렉토리 생성
mkdir -p ~/.claude

# 설정 파일 생성
cat > ~/.claude/config.json << 'EOF'
{
  "apiKey": "sk-ant-api03-xxxxx...",
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 8192
}
EOF

# 권한 설정 (보안)
chmod 600 ~/.claude/config.json

초기 설정 확인

# 설정 파일 위치 확인
claude config show

# API 연결 테스트
claude chat "Hello, Claude!"

# 출력 예시:
# Claude: Hello! How can I help you today?

 

 

 

기본 사용법

1. 대화형 모드 (Chat)

# 기본 실행
claude

# 프롬프트가 나타나면 질문 입력
You: Python으로 피보나치 수열을 구현해줘

Claude: 물론입니다. 재귀와 반복 두 가지 방식으로 구현해드리겠습니다.

[코드 생성...]

You: /exit  # 종료

특수 명령어:

명령어	기능
/help	도움말 표시
/exit	종료
/clear	대화 기록 초기화
/save <file>	대화 내용 저장
/load <file>	대화 내용 불러오기

2. 단발성 질의

# 한 줄 명령
claude chat "Explain Git in one sentence"

# 파이프 활용
echo "Translate to Korean: Hello World" | claude chat

# 파일에서 프롬프트 읽기
claude chat < prompt.txt

# 결과를 파일로 저장
claude chat "Write a README for a Todo app" > README.md

3. 파일 편집

# 프로젝트 디렉토리에서 실행
cd my-project

# Claude에게 파일 수정 요청
claude edit "Fix the bug in src/app.js where the user login fails"

# 특정 파일 지정
claude edit --file src/utils.js "Add error handling to all functions"

# 여러 파일 동시 수정
claude edit "Refactor the authentication system"

동작 방식:

1. Claude가 관련 파일 자동 탐색
2. 코드 분석 후 수정안 제시
3. 사용자 승인 시 파일 직접 편집
4. Git diff 형식으로 변경사항 표시

4. 프로젝트 분석

# 전체 코드베이스 이해
claude analyze

# 특정 질문
claude analyze "Where is the user authentication implemented?"

# 아키텍처 다이어그램 요청
claude analyze "Draw the system architecture"

5. Git 통합

# 커밋 메시지 자동 생성
claude commit

# Pull Request 설명 작성
claude pr

# 코드 리뷰
claude review