Claude Code로 사이드프로젝트 처음부터 끝까지 만들기

출시 9개월 만에 연간 반복 매출 25억 달러를 찍었습니다. Claude Code 얘기입니다. 개발자 도구 역사상 이 속도로 성장한 제품이 없었다는 게 Anthropic이 직접 밝힌 숫자입니다. 왜 이렇게 빠르게 퍼졌는지, 실제로 URL 단축기 사이드프로젝트를 처음부터 배포까지 만들어보면서 확인해봤습니다.

---

핵심 요약

Claude Code는 터미널에서 직접 실행하는 에이전트형 코딩 도구로, 브라우저 챗봇이나 IDE 플러그인과 근본적으로 다릅니다. 프로젝트 전체를 인덱싱하고 파일 간 관계를 이해한 채로 파일을 읽고, 수정하고, 터미널 명령을 직접 실행합니다.

2026년 초 기준으로 개발자 선호도 조사에서 46%가 가장 선호하는 AI 코딩 도구로 Claude Code를 꼽았고, Cursor(19%)와 GitHub Copilot(9%)을 크게 앞섰습니다. 핵심 이유는 단순합니다. 복잡한 문제 해결에서 다른 도구들보다 한 수 위라는 게 현장에서 검증됐기 때문입니다.

기능 면에서는 Plan Mode가 가장 중요합니다. /plan을 치면 코드를 짜기 전에 먼저 어떤 파일을 어떤 순서로 건드릴지 계획을 세우고 보여줍니다. 승인하기 전까지 아무것도 건드리지 않아서 실수를 사전에 막을 수 있습니다. 여기에 CLAUDE.md 파일로 프로젝트 규칙을 한 번 정의해두면 매 세션마다 같은 설명을 반복할 필요가 없습니다.

모델 선택도 이제 세분화됐는데, 일상적인 코드 작업은 Sonnet 4.6, 아키텍처 결정이나 복잡한 디버깅은 Opus 4.7을 씁니다. Max 플랜($100/월) 이상에서 Opus가 기본 모델로 들어오고, Pro 플랜($20/월)은 Sonnet이 기본입니다. /cost로 현재 세션 토큰 사용량을 수시로 확인하는 습관이 비용 관리에 도움됩니다.

---

실전 0: 설치

Claude Code는 Node.js가 설치된 환경에서 npm 한 줄로 설치합니다. 2026년 기준 공식 권장 방식은 네이티브 CLI 설치로, 별도 의존성 없이 백그라운드 자동 업데이트까지 됩니다. Homebrew로 설치하면 수동 업데이트가 필요하므로 권장하지 않습니다.

# 네이티브 설치 (권장)
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

# 프로젝트 폴더로 이동 후 실행
mkdir url-shortener
cd url-shortener
claude

첫 실행 시 브라우저로 Anthropic 계정 로그인 창이 열립니다. 로그인은 한 번만 하면 되고 이후엔 자격증명이 시스템에 저장됩니다. Pro 플랜 이상이 필요하고, 무료 플랜에서는 Claude Code를 쓸 수 없습니다.

---

실전 1: CLAUDE.md로 프로젝트 규칙 세팅

CLAUDE.md는 Claude Code가 세션을 시작할 때마다 가장 먼저 읽는 파일입니다. 여기에 기술 스택, 코딩 규칙, 금지 사항을 한 번 써두면 매번 같은 말을 반복할 필요가 없습니다. 팀 프로젝트라면 이 파일 하나가 온보딩 문서 역할도 합니다.

아래는 FastAPI + SQLite 기반 URL 단축기 프로젝트의 CLAUDE.md 예시입니다. 기술 선택 이유와 코딩 규칙을 같이 적어두면 Claude가 일관성 있는 코드를 씁니다.

# URL Shortener Project

## 기술 스택
- Backend: FastAPI + SQLite (sqlalchemy)
- Python 3.11+
- 테스트: pytest

## 코딩 규칙
- 타입 힌트 필수
- 함수마다 docstring 작성
- 에러 핸들링은 HTTPException으로 통일
- 변수명은 snake_case, 클래스명은 PascalCase

## 금지 사항
- print() 사용 금지 (logging 모듈 사용)
- 하드코딩된 시크릿 금지 (.env 파일 사용)
- 테스트 없는 새 기능 추가 금지

## 프로젝트 구조
app/
  main.py      # FastAPI 앱 진입점
  models.py    # SQLAlchemy 모델
  schemas.py   # Pydantic 스키마
  crud.py      # DB 조작 함수
  database.py  # DB 연결 설정
tests/
  test_api.py

CLAUDE.md가 없으면 Claude가 알아서 합리적인 추측을 하지만, 있으면 첫 프롬프트부터 팀 표준을 정확히 따릅니다. 프로젝트가 커질수록 이 파일의 가치가 확실하게 드러납니다.

---

실전 2: Plan Mode로 설계하기

복잡한 기능을 바로 구현하라고 시키면 Claude가 한 번에 너무 많은 파일을 건드리다 방향을 잃을 수 있습니다. Plan Mode를 먼저 쓰면 Claude가 무엇을 어떤 순서로 만들지 계획을 세우고 승인을 기다립니다. 특히 처음 프로젝트 뼈대를 잡을 때 필수입니다.

Claude Code 세션에서 아래처럼 입력하면 됩니다. 계획이 마음에 들면 yes로 승인하고, 수정이 필요하면 자연어로 피드백을 주면 됩니다.

/plan

FastAPI와 SQLite로 URL 단축기를 만들어줘.
기능:
1. POST /shorten - 긴 URL을 받아서 8자리 단축 코드 생성
2. GET /{code} - 단축 코드로 원본 URL로 리다이렉트
3. GET /stats/{code} - 클릭 횟수 조회

CRUD 함수, 스키마, 모델을 분리해서 만들고
pytest로 테스트 파일도 같이 생성해줘.

Plan Mode가 출력하는 계획은 어떤 파일을 어떤 순서로 생성하고, 각 파일에 뭘 넣을지 단계별로 설명합니다. 계획을 보고 순서나 방향이 마음에 안 들면 승인 전에 자연어로 수정을 요청하면 됩니다.

---

실전 3: 코드 생성

Plan Mode 승인 후 Claude가 실제 코드를 씁니다. 이 프로젝트의 경우 database.py, models.py, schemas.py, crud.py, main.py, test_api.py 순서로 생성합니다. 아래는 Claude가 생성한 핵심 파일들입니다.

FastAPI 앱의 진입점인 main.py는 라우터를 정의하고 URL 단축 로직을 담습니다. 단축 코드는 UUID를 8자리로 잘라서 쓰는 방식입니다.

# app/main.py
from fastapi import FastAPI, HTTPException, Depends
from fastapi.responses import RedirectResponse
from sqlalchemy.orm import Session
import logging

from . import crud, schemas
from .database import get_db, engine, Base

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

Base.metadata.create_all(bind=engine)
app = FastAPI(title="URL Shortener", version="1.0.0")

@app.post("/shorten", response_model=schemas.URLResponse)
def shorten_url(url_data: schemas.URLCreate, db: Session = Depends(get_db)):
    """긴 URL을 받아서 8자리 단축 코드를 반환합니다."""
    db_url = crud.create_short_url(db, url_data.original_url)
    logger.info(f"URL 단축 완료: {url_data.original_url} -> {db_url.short_code}")
    return db_url

@app.get("/stats/{code}", response_model=schemas.URLStats)
def get_stats(code: str, db: Session = Depends(get_db)):
    """단축 코드의 클릭 통계를 반환합니다."""
    db_url = crud.get_url_by_code(db, code)
    if not db_url:
        raise HTTPException(status_code=404, detail="존재하지 않는 단축 코드입니다.")
    return db_url

@app.get("/{code}")
def redirect_url(code: str, db: Session = Depends(get_db)):
    """단축 코드로 원본 URL로 리다이렉트합니다."""
    db_url = crud.get_url_by_code(db, code)
    if not db_url:
        raise HTTPException(status_code=404, detail="존재하지 않는 단축 코드입니다.")
    crud.increment_click_count(db, code)
    return RedirectResponse(url=db_url.original_url)

코드 생성이 완료되면 바로 실행해서 동작을 확인합니다. 에러가 나면 그 메시지를 그대로 Claude에 붙여넣으면 됩니다.

---

실전 4: 버그 디버깅

실행 중 에러가 나면 에러 메시지를 그대로 Claude에 주는 게 가장 빠릅니다. 컨텍스트를 설명하거나 에러를 해석할 필요 없이 터미널 출력을 붙여넣으면 됩니다. 아래처럼 구체적인 상황을 같이 넣으면 정확도가 올라갑니다.

GET /abc123 을 호출했을 때 아래 에러가 납니다:

sqlalchemy.exc.OperationalError: (sqlite3.OperationalError)
no such table: urls

전체 스택트레이스:
File "app/crud.py", line 15, in get_url_by_code
  return db.query(models.URL).filter(models.URL.short_code == code).first()

왜 이 에러가 나는지 찾고 고쳐줘.

이 경우는 Base.metadata.create_all(bind=engine)이 앱 시작 전에 호출되지 않아서 테이블이 생성되지 않은 문제입니다. Claude가 main.py의 앱 초기화 순서를 확인하고 수정합니다. "버그 수정"보다 이렇게 구체적으로 요청할수록 한 번에 정확한 원인을 찾아줍니다.

---

실전 5: Hooks로 자동화

Hooks는 특정 이벤트가 발생했을 때 셸 명령을 자동 실행하는 기능입니다. Claude가 Python 파일을 수정할 때마다 자동으로 포매터와 린터를 돌리면 코드 품질을 일정하게 유지할 수 있습니다. .claude/settings.json에 정의합니다.

아래는 Python 파일 수정 후 black 포매터와 pytest를 자동 실행하는 Hook 설정입니다. Claude가 파일을 저장할 때마다 검사를 자동으로 돌려줘서 일일이 실행할 필요가 없습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_TOOL_INPUT' | python3 -c \"import sys,json; d=json.load(sys.stdin); exit(0 if d.get('file_path','').endswith('.py') else 1)\" 2>/dev/null; then black ${CLAUDE_TOOL_INPUT_FILE_PATH} && echo 'Black 포매팅 완료'; fi"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd /path/to/project && python -m pytest tests/ -q --tb=short 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

Stop Hook은 Claude가 작업을 마칠 때마다 테스트를 자동으로 돌립니다. 테스트가 실패하면 결과를 Claude가 보고 바로 수정에 들어가는 루프를 만들 수 있습니다.

---

실전 6: 배포까지

코드가 완성됐으면 배포를 Claude에 맡겨봅니다. 인프라 설정 파일도 Claude가 만들어줍니다.

이 FastAPI 앱을 Railway에 배포할 수 있게 설정해줘.
Procfile, railway.toml, requirements.txt가 필요할 것 같아.
환경변수는 DATABASE_URL 하나만 쓰도록 해줘.

Claude가 Procfile, railway.toml, requirements.txt를 생성하고 database.py에서 환경변수를 읽도록 수정합니다. 이후 Railway CLI로 배포하거나 GitHub 연동으로 자동 배포를 걸면 됩니다.

# Railway CLI 배포
npm install -g @railway/cli
railway login
railway init
railway up

Railway 대신 Fly.io나 Render를 쓴다면 그렇게 말하면 됩니다. Claude가 해당 플랫폼에 맞는 설정 파일로 바꿔줍니다.

---

마무리

Claude Code가 $2.5B ARR를 9개월 만에 찍은 이유는 써보면 납득됩니다. 단순히 코드를 생성하는 게 아니라 프로젝트 전체 맥락을 이해하고 파일을 직접 건드리면서 작업을 완료해줍니다. Plan Mode로 설계를 먼저 검토하고, CLAUDE.md로 규칙을 정의하고, Hooks로 반복 작업을 자동화하면 혼자 하는 사이드프로젝트의 속도가 눈에 띄게 달라집니다. 코드를 짜는 시간보다 뭘 만들지 결정하는 시간이 더 많아지는 느낌인데, 그게 이 도구의 진짜 포인트입니다.