Claude Code 시작하기: 설치부터 첫 번째 프로젝트까지 완벽 가이드

Claude Code란 무엇인가?

Claude Code는 Anthropic에서 개발한 AI 코딩 어시스턴트로, CLI(Command Line Interface) 환경에서 직접 코드 작성, 디버깅, 리팩토링 등을 수행할 수 있는 강력한 도구입니다. GitHub Copilot이나 Cursor와 달리 터미널에서 직접 동작하며, 파일 읽기/쓰기, Bash 명령 실행, 웹 검색 등 다양한 툴을 활용해 실제 개발 워크플로우에 통합됩니다.

Claude Code의 핵심 특징

• 자율적 실행: 단순 코드 제안을 넘어 파일 수정, 테스트 실행, Git 커밋까지 자동 처리
• 컨텍스트 인식: 프로젝트 전체 구조를 파악하고 관련 파일을 자동으로 읽어 최적의 솔루션 제공
• 도구 통합: Bash, Grep, Read, Edit, Write 등 20여 개의 도구를 조합해 복잡한 작업 수행
• 대화형 인터페이스: 자연어로 요청하면 Claude가 계획을 세우고 실행 후 결과 보고

설치 및 초기 설정

1. Node.js 설치 확인

Claude Code는 Node.js 기반으로 동작합니다. 먼저 Node.js 18 이상이 설치되어 있는지 확인하세요.

node --version
# v18.0.0 이상이어야 함

2. Claude Code CLI 설치

npm을 통해 전역으로 설치합니다.

npm install -g @anthropic-ai/claude-code

설치 후 버전 확인:

claude --version

3. 인증 설정

Claude Code를 사용하려면 Anthropic 계정이 필요합니다. 두 가지 인증 방식이 있습니다.

방법 1: OAuth 인증 (권장)

claude auth login

브라우저가 자동으로 열리며 Claude.ai 계정으로 로그인합니다. Max Plan 구독자는 무제한 사용 가능합니다.

방법 2: API 키 인증

export ANTHROPIC_API_KEY="sk-ant-..."

API 키는 Anthropic Console에서 발급받을 수 있습니다.

첫 번째 프로젝트: Todo 앱 만들기

프로젝트 시작하기

새 디렉토리를 만들고 Claude Code를 실행합니다.

mkdir my-todo-app
cd my-todo-app
claude

Claude Code 인터랙티브 셸이 시작됩니다.

자연어로 요청하기

> Python으로 간단한 CLI Todo 앱을 만들어줘. JSON 파일로 데이터를 저장하고,
  add, list, done, delete 명령어를 지원해야 해.

Claude는 다음과 같이 동작합니다:

1. 계획 수립: 필요한 파일 구조와 기능을 분석
2. 파일 생성: todo.py, requirements.txt 등 생성
3. 코드 작성: 각 기능을 구현한 Python 코드 작성
4. 테스트 제안: 기본적인 사용 예시 제공

생성된 코드 예시

import json
import sys
from pathlib import Path

TODO_FILE = Path.home() / ".todos.json"

def load_todos():
    if not TODO_FILE.exists():
        return []
    with open(TODO_FILE, 'r') as f:
        return json.load(f)

def save_todos(todos):
    with open(TODO_FILE, 'w') as f:
        json.dump(todos, f, indent=2)

def add_todo(text):
    todos = load_todos()
    todos.append({"id": len(todos) + 1, "text": text, "done": False})
    save_todos(todos)
    print(f"Added: {text}")

# ... 나머지 함수들

수정 요청하기

> 각 todo에 우선순위(high, medium, low)를 추가하고,
  우선순위별로 정렬해서 보여줘.

Claude는 기존 코드를 읽고, 필요한 부분만 수정합니다. Edit 도구를 사용해 정확한 위치에 코드를 추가/변경합니다.

주요 명령어와 옵션

모델 선택

claude --model sonnet    # Claude 3.5 Sonnet (기본값, 빠르고 정확)
claude --model opus      # Claude 3 Opus (복잡한 작업에 적합)
claude --model haiku     # Claude 3 Haiku (간단한 작업, 저비용)

프롬프트 직접 실행

claude -p "이 디렉토리의 모든 Python 파일에서 print 문을 logging으로 바꿔줘"

프로젝트 컨텍스트 제공

claude --context "이 프로젝트는 FastAPI로 만든 REST API야. PostgreSQL을 사용해."

실전 활용 시나리오

시나리오 1: 버그 수정

> tests/test_user.py가 실패하는데, 원인을 찾아서 고쳐줘.

Claude는:
1. 테스트 파일 읽기
2. pytest tests/test_user.py 실행
3. 에러 로그 분석
4. 관련 소스 코드 파일 읽기
5. 버그 수정
6. 테스트 재실행으로 검증

시나리오 2: 코드 리뷰

> src/api/auth.py를 보안 관점에서 리뷰하고, 문제점이 있으면 수정해줘.

Claude는 SQL Injection, XSS, CSRF 등 일반적인 보안 취약점을 자동으로 체크하고 개선안을 제시합니다.

시나리오 3: 문서화

> 모든 public 함수에 docstring을 추가하고, README.md도 업데이트해줘.

주의사항과 팁

효율적인 프롬프트 작성법

좋은 예시:

Python FastAPI 프로젝트에 JWT 인증을 추가해줘. /auth/login 엔드포인트를 만들고, Bearer 토큰으로 보호되는 /users/me 엔드포인트도 추가해. 토큰 만료는 24시간으로 설정.

나쁜 예시:

인증 좀 추가해줘.

마무리

Claude Code는 단순한 코드 자동완성 도구를 넘어 실제 개발 워크플로우에 통합될 수 있는 강력한 AI 파트너입니다. 설치부터 첫 프로젝트 생성까지 기본기를 익혔다면, 이제 본격적으로 디버깅, 리팩토링, 테스트 자동화 등 실전 활용법을 배울 차례입니다.

다음 편 “Claude Code 실전 활용법: 디버깅, 리팩토링, 테스트 자동화 마스터하기”에서는 실제 프로젝트에서 마주치는 복잡한 문제들을 Claude Code로 해결하는 방법을 상세히 다룰 예정입니다. 레거시 코드 개선, 성능 최적화, CI/CD 파이프라인 구축 등 실무에서 바로 적용 가능한 테크닉을 소개하겠습니다.