클로드 코드(Claude Code)로 사이드 프로젝트 빠르게 만들기 — 실전 워크플로

클로드 코드(Claude Code) 실전 워크플로. AI에게 "그냥 시키는" 것과 "제대로 시키는" 것은 결과가 다르다. 사이드 프로젝트를 빠르게, 그러나 망가지지 않게 만드는 Claude Code 활용법을 CLAUDE.md·계획 우선·서브에이전트 중심으로 정리한다.

---

들어가며

지난 글에서 바이브 코딩의 한계를 봤다. 도구는 70%까지 데려다주지만, 나머지 30%는 결국 사람이 채워야 한다고. 그렇다면 질문이 바뀐다. 개발 지식이 있는 사람은 AI 코딩 도구를 어떻게 써야 그 30%까지 끌고 갈 수 있을까?

핵심은 도구 선택이 아니라 일하는 방식이다. 같은 Claude Code를 써도, "그냥 시키는" 사람과 "구조를 잡고 시키는" 사람의 결과물은 완전히 다르다.

한 통계가 인상적이다. AI가 개별 결정을 80% 확률로 맞힌다고 해도, 기능 하나에 결정 지점이 20개면 전부 맞을 확률은 0.8의 20제곱, 약 1%다. 계획이 이 문제를 푼다.

이 글에서는 사이드 프로젝트를 빠르면서도 망가지지 않게 만드는 Claude Code 실전 워크플로를 정리한다.

---

왜 "그냥 시키기"는 실패하는가

Claude Code에 "할 일 관리 앱 만들어줘"라고 던지면, 처음 몇 분은 마법 같다. 그러다 점점 어긋난다. 변수명이 들쭉날쭉해지고, 앞에서 만든 패턴을 잊고, 엉뚱한 방향으로 간다. 바이브 코딩에서 봤던 그 30%의 벽이다.

원인은 위에서 말한 확률 누적이다. 기능 하나는 수십 개의 작은 결정으로 이뤄진다. "DB는 뭘 쓸지, 폴더 구조는 어떻게 할지, 에러는 어떻게 처리할지..." 각 결정에서 AI가 조금씩 어긋나면, 그게 쌓여 전체가 무너진다.

Anthropic 내부 테스트에서도 아무 가이드 없이 시킨 작업의 성공률은 약 33%였다. 뒤집으면, 나머지는 구조를 잡아줘야 성공한다는 뜻이다. 고출력 개발자와 그렇지 않은 사람의 차이는 프롬프트 솜씨가 아니라, 실행 전에 만들어두는 구조에 있다.

그 구조를 만드는 세 가지 도구가 CLAUDE.md, 계획 우선, 서브에이전트다.

---

1. CLAUDE.md — 프로젝트의 규칙을 고정한다

가장 먼저 할 일은 프로젝트 루트에 CLAUDE.md 파일을 두는 것이다. Claude Code가 매번 자동으로 읽는 파일로, 프로젝트의 작업 규칙을 한곳에 고정한다. 사람이 매번 설명하지 않아도, AI가 일관된 기준으로 일하게 만드는 장치다.

# CLAUDE.md

## 기술 스택
- Backend: FastAPI (Python 3.12)
- DB: PostgreSQL + SQLAlchemy
- 패키지 관리: uv

## 코딩 규칙
- 모든 함수에 타입 힌트를 붙인다
- API 응답은 Pydantic 모델로 검증한다
- 예외는 도메인별 커스텀 예외로 처리한다 (빈 except 금지)

## 폴더 구조
- app/routers/  : API 엔드포인트
- app/services/ : 비즈니스 로직
- app/models/   : DB 모델

## 하지 말 것
- 비밀키를 코드에 하드코딩하지 않는다 (.env 사용)
- 테스트 없이 기능을 완료로 표시하지 않는다

이렇게 규칙을 박아두면, AI가 매번 다른 스타일로 코드를 짜는 일이 줄어든다. 바이브 코딩에서 "프로젝트가 커지면 일관성이 깨진다"고 했던 문제를, CLAUDE.md가 상당 부분 잡아준다. 프로젝트가 커질수록 이 파일의 가치가 올라간다.

---

2. 계획 우선 — 코드보다 설계를 먼저

가장 중요한 원칙이다. 바로 코딩시키지 말고, 계획부터 세우게 한다. 위에서 본 "20개 결정의 1% 함정"을 푸는 직접적인 방법이다.

계획 단계에서 모호한 결정들을 미리 확정해두면, 각 결정의 성공률이 100%에 가까워진다. 그래서 구현 전에 이렇게 시작한다.

나: 할 일 관리 앱을 만들 거야. 바로 코딩하지 말고,
    먼저 구현 계획을 세워줘.
    - 필요한 API 엔드포인트 목록
    - DB 스키마
    - 폴더 구조
    각 항목에 대해 선택지가 있으면 이유와 함께 제안해줘.

Claude Code의 계획 모드(Plan Mode) 를 쓰면 코드를 건드리지 않고 설계만 먼저 받을 수 있다. 이 계획을 사람이 검토하고 수정한 뒤에 구현에 들어간다. "어떤 결정을 내릴지"를 사람이 먼저 확정하는 것이다.

핵심은 이거다. 계획은 20개의 모호한 결정을, 사람이 검토한 명세로 바꾼다. 각 결정이 이미 내려져 있으니 AI는 헤매지 않는다.

이 단계를 건너뛰면 빠른 것 같지만, 결국 어긋난 코드를 고치느라 더 느려진다. 급할수록 계획부터.

---

3. 작은 단위로 끊어서, 검증하며

계획이 섰으면 한 번에 다 시키지 않는다. 기능을 작은 단위로 쪼개고, 각 단계를 검증하며 진행한다.

1단계: DB 모델과 마이그레이션만 만들어줘. (검토)
2단계: 할 일 CRUD API를 만들어줘. 테스트도 함께. (검토 + 테스트 실행)
3단계: 인증을 붙여줘. (검토)

각 단계마다 코드를 읽고, 테스트를 돌려본다. 여기서 바이브 코딩 글에서 강조한 "결국 코드를 읽어야 한다"가 적용된다. AI가 만든 걸 검증 없이 쌓으면, 30%의 벽에서 그대로 무너진다.

특히 중요한 건 증거를 요구하는 것이다. "됐어"라는 말 대신, 실제 테스트 출력이나 실행 결과를 보여달라고 한다.

나: 방금 만든 API, 실제로 동작하는지 테스트를 실행해서
    그 결과를 보여줘. 통과했다고 말만 하지 말고.

AI가 "성공했다"고 주장하는 것과, 실제로 통과한 테스트 출력을 보는 것은 다르다. 검증 가능한 증거를 요구하는 습관이 품질을 지킨다.

---

4. 서브에이전트 — 컨텍스트를 깨끗하게

조금 더 깊이 들어가면, 서브에이전트(Subagent) 가 강력한 도구다. 메인 작업과 별개로, 특정 작업을 독립된 컨텍스트에서 처리하게 하는 기능이다.

왜 필요할까? AI의 컨텍스트 윈도우는 무한하지 않다. 코드베이스를 탐색하거나 리뷰하는 작업으로 메인 대화를 채우면, 정작 중요한 구현 맥락이 밀려난다. 서브에이전트는 그 탐색을 별도 창에서 하고 요약만 가져온다. 메인 대화는 깨끗하게 유지된다.

대표적인 활용은 코드 리뷰 전용 에이전트다. .claude/agents/ 에 정의해둔다.

---
name: code-reviewer
description: 기능 구현 후 코드 품질·보안을 리뷰한다
tools: Read, Glob, Grep
---
당신은 시니어 코드 리뷰어입니다. 다음을 중점적으로 봅니다.
- 인젝션 취약점 (SQL, XSS)
- 인증·인가 결함
- 코드에 노출된 비밀키
- 빈 예외 처리, 검증 누락
구체적인 라인 번호와 수정 방안을 제시하세요.

이렇게 하면 "작업한 AI"가 아니라 "다른 AI"가 검토하게 된다. 만든 사람이 자기 일을 채점하지 않게 하는 것이다. 실무에서 3~5개 정도의 병렬 서브에이전트가 적정선이고, 그 이상은 비용만 늘고 효과는 줄어든다.

서브에이전트는 결국 N+1 글이나 보안 글에서 다룬 "검증"을 자동화하는 장치다. AI에게 맡기되, 다른 AI가 점검하게 하는 구조다.

---

실전 예제 — 할 일 API를 워크플로대로 만들어보기

말로만 하면 와닿지 않으니, 위 워크플로를 그대로 따라 할 일 관리 API를 만들어보자. CLAUDE.md는 앞에서 만든 그대로 두고 시작한다.

1단계: 계획부터 받는다

나: 할 일(Todo) CRUD API를 만들 거야. 바로 코딩하지 말고
    계획부터 세워줘. 엔드포인트 목록과 DB 스키마를 제안해줘.

Claude Code가 계획 모드에서 이런 설계를 돌려준다.

Claude Code Plan

여기서 사람이 검토한다. "완료일(completed_at)은 빼고, 우선순위(priority)를 추가해줘" 같은 수정을 계획 단계에서 끝낸다. 코드를 고치는 것보다 계획을 고치는 게 훨씬 싸다.

2단계: 작은 단위로 구현시킨다

계획이 확정되면 첫 단위만 시킨다.

나: 계획대로 1단계만 진행해. Todo 모델과 스키마만 만들어줘.

Claude Code가 CLAUDE.md의 규칙(타입 힌트, Pydantic 검증, 폴더 구조)을 따라 코드를 만든다.

# app/models/todo.py — Claude Code가 생성한 코드
from datetime import datetime
from sqlalchemy.orm import Mapped, mapped_column
from app.models.base import Base


class Todo(Base):
    __tablename__ = "todos"

    id: Mapped[int] = mapped_column(primary_key=True)
    title: Mapped[str] = mapped_column(nullable=False)
    priority: Mapped[int] = mapped_column(default=2)  # 1=높음 2=보통 3=낮음
    done: Mapped[bool] = mapped_column(default=False)
    created_at: Mapped[datetime] = mapped_column(default=datetime.utcnow)

# app/routers/todos.py — CRUD 엔드포인트 (일부)
from fastapi import APIRouter, HTTPException, status
from app.schemas.todo import TodoCreate, TodoResponse
from app.services.todo_service import TodoService

router = APIRouter(prefix="/todos", tags=["todos"])


@router.post("/", response_model=TodoResponse,
             status_code=status.HTTP_201_CREATED)
async def create_todo(body: TodoCreate) -> TodoResponse:
    return await TodoService.create(body)


@router.get("/{todo_id}", response_model=TodoResponse)
async def get_todo(todo_id: int) -> TodoResponse:
    todo = await TodoService.get(todo_id)
    if todo is None:
        raise HTTPException(status_code=404, detail="할 일을 찾을 수 없습니다")
    return todo

눈여겨볼 점: CLAUDE.md에 적어둔 규칙대로 타입 힌트가 전부 붙어 있고, 응답이 Pydantic 모델로 검증되고, 폴더 구조(routers/services/models)를 지킨다. 규칙을 박아둔 효과가 코드에 그대로 드러난다.

3단계: 증거를 요구한다

"만들었어"라는 말로 끝내지 않는다. 테스트를 실행시키고 출력을 확인한다.

나: pytest 실행해서 결과를 그대로 보여줘.

$ pytest tests/test_todos.py -v

tests/test_todos.py::test_create_todo PASSED              [ 20%]
tests/test_todos.py::test_get_todo PASSED                 [ 40%]
tests/test_todos.py::test_get_todo_not_found PASSED       [ 60%]
tests/test_todos.py::test_update_todo PASSED              [ 80%]
tests/test_todos.py::test_delete_todo PASSED              [100%]

======================== 5 passed in 0.42s ========================

5개 테스트가 실제로 통과한 출력을 확인했다. 특히 test_get_todo_not_found 같은 실패 경로 테스트가 있는지 본다. 바이브 코딩이 놓치는 엣지 케이스가 바로 이런 부분이다.

4단계: 동작 화면으로 확인한다

서버를 띄우고 실제 응답을 확인한다. FastAPI는 Swagger 문서가 자동 생성되니 눈으로 바로 검증할 수 있다.

자동 생성된 Swagger 문서

$ curl -X POST http://localhost:8000/todos/ \
    -H "Content-Type: application/json" \
    -d '{"title": "블로그 글 쓰기", "priority": 1}'

{"id":1,"title":"블로그 글 쓰기","priority":1,"done":false,
 "created_at":"2026-06-10T09:12:33"}

여기까지 걸린 시간은 직접 짜는 것보다 훨씬 짧다. 하지만 계획 검토 → 단계 구현 → 테스트 증거 → 동작 확인이라는 관문을 거쳤기 때문에, 빠르면서도 "그럴싸한 껍데기"가 아니라 검증된 결과물이 나온다.

5단계: 서브에이전트 리뷰로 마무리

마지막으로 앞에서 정의한 code-reviewer 서브에이전트에게 점검을 맡긴다.

나: code-reviewer 서브에이전트로 방금 만든 코드를 리뷰해줘.

[code-reviewer 결과 요약]
✔ 타입 힌트, Pydantic 검증 규칙 준수
✔ 404 처리 등 실패 경로 존재
⚠ app/routers/todos.py:21 — todo_id에 음수 검증 없음
  → Path(gt=0) 추가 권장
⚠ 페이지네이션 없음 — 목록 API에 limit/offset 추가 권장

작업한 AI가 아닌 별도 컨텍스트의 AI가 빈틈을 잡아준다. 음수 ID 검증, 페이지네이션처럼 사람도 놓치기 쉬운 부분이 리뷰에서 걸린다. 이 지적을 다음 단계 작업으로 넘기면 루프가 완성된다.

---

실전 워크플로 정리

지금까지를 하나의 흐름으로 묶으면 이렇다.

1. CLAUDE.md 작성        프로젝트 규칙을 고정
2. 계획 모드로 설계       코딩 전에 결정을 확정
3. 작은 단위로 구현       한 번에 다 시키지 않기
4. 단계마다 검증          테스트 출력 등 증거 요구
5. 서브에이전트로 리뷰     별도 AI가 보안·품질 점검
6. 사람이 최종 확인        배포 전 직접 읽기

바이브 코딩이 "70%의 마법"이라면, 이 워크플로는 나머지 30%를 끌어올리는 구조다. 도구는 같지만, 구조를 잡고 쓰면 결과가 달라진다.

---

마치며

AI 코딩 도구를 둘러싼 흔한 오해는 "좋은 프롬프트가 실력"이라는 것이다. 하지만 진짜 차이는 프롬프트가 아니라 실행 전에 만들어두는 구조에서 나온다. CLAUDE.md로 규칙을 고정하고, 계획으로 결정을 미리 확정하고, 작은 단위로 검증하며, 서브에이전트로 점검하는 것. 화려하지 않지만, 이 평범한 규율이 1%를 100%에 가깝게 만든다.

결국 바이브 코딩 글과 이 글은 같은 이야기를 한다. AI가 70%를 해주기 때문에, 나머지 30%를 다룰 줄 아는 사람의 가치가 오른다. 도구를 잘 쓴다는 건, 도구에 끌려가지 않고 구조로 끌고 간다는 뜻이다.

다음 글에서는 한 발 물러서서, 이런 AI 코딩 시대에 개발자가 무엇을 준비해야 하는지를 이야기해보겠다.

---

참고 출처

• Claude Code 공식 문서: Best practices — https://code.claude.com/docs/en/best-practices
• Claude Code: CLAUDE.md 및 서브에이전트 가이드 — https://code.claude.com/docs/en/best-practices
• Anthropic Engineering: Claude Code best practices — https://www.anthropic.com/engineering/claude-code-best-practices