Claude Code로 웹앱 만들기 실전: 아이디어에서 배포까지

Claude Code로 웹앱 만들기 실전: 아이디어에서 배포까지

"할 일 관리 앱을 만들어줘"라고 말하면 Claude Code가 프로젝트 스캐폴딩부터 데이터베이스 설계, 컴포넌트 구현, 테스트, 배포 설정까지 전체 풀스택을 자율적으로 구현합니다. 이 글에서는 Claude Code로 실제 웹 애플리케이션을 만드는 실전 워크플로우를 처음부터 끝까지 정리합니다.

Claude Code로 웹앱 만들기 실전

---

1. 웹앱 개발의 전체 흐름

5단계 개발 프로세스

Claude Code로 웹앱을 만드는 전체 흐름은 5단계로 진행됩니다.

1단계: 기획 (Plan 모드)
  └── 기술 스택, 구조, DB 설계 계획
       ↓
2단계: 스캐폴딩
  └── 프로젝트 생성, 의존성 설치, 디렉토리 구조
       ↓
3단계: 기능 구현
  └── 다중 파일 동시 수정 (컴포넌트, API, DB)
       ↓
4단계: 테스트와 검증
  └── 단위/통합/E2E 테스트, 버그 수정
       ↓
5단계: 배포
  └── Docker, Vercel, GitHub Actions

Claude Code가 웹앱에 강한 이유

강점	설명
다중 파일 조율	컴포넌트, API, DB를 동시에 수정
전체 구조 이해	package.json부터 설정까지 파악
에이전트 루프	구현→테스트→수정 자동 반복
CLAUDE.md	프로젝트 규칙 일관 적용
Git 네이티브	기능별 브랜치, 커밋, PR 자동화

파일 하나씩 편집하는 것이 아니라, "좋아요 기능 추가해줘"라고 말하면 DB 스키마, API, 컴포넌트, 테스트를 한 번에 만듭니다.

 

웹앱 개발의 전체 흐름

---

2. 1단계: Plan 모드로 기획하기

코드를 쓰기 전에 설계부터

# Plan 모드로 시작
claude --permission-mode plan

Plan 모드에서는 Claude가 파일을 읽기만 하고 수정하지 않습니다. 안전하게 설계를 검토할 수 있습니다.

기획 프롬프트 예시

할 일 관리 웹앱을 만들려고 합니다.

요구사항:
- 사용자 인증 (이메일/비밀번호)
- 할 일 생성/수정/삭제
- 카테고리별 분류
- 우선순위 설정 (높음/중간/낮음)
- 완료 상태 토글
- 모바일 반응형 UI

기술 스택, 파일 구조, DB 스키마, API 엔드포인트를
포함한 상세한 구현 계획을 세워줘.

Claude가 만드는 계획

기술 스택:
  - 프레임워크: Next.js 14 (App Router)
  - 언어: TypeScript
  - ORM: Prisma (SQLite → PostgreSQL)
  - 스타일: Tailwind CSS
  - 인증: NextAuth.js
  - 테스트: Vitest + Playwright

파일 구조:
  app/
  ├── (auth)/login/page.tsx
  ├── (auth)/signup/page.tsx
  ├── dashboard/page.tsx
  ├── api/todos/route.ts
  ├── api/todos/[id]/route.ts
  ├── layout.tsx
  components/
  ├── TodoList.tsx
  ├── TodoItem.tsx
  ├── TodoForm.tsx
  ├── CategoryFilter.tsx
  lib/
  ├── prisma.ts
  ├── auth.ts
  ├── validators.ts
  prisma/
  └── schema.prisma

DB 스키마:
  User: id, email, password, name
  Todo: id, title, description, priority,
        completed, categoryId, userId
  Category: id, name, color, userId

API 엔드포인트:
  POST   /api/auth/signup
  POST   /api/auth/login
  GET    /api/todos
  POST   /api/todos
  PATCH  /api/todos/[id]
  DELETE /api/todos/[id]
  GET    /api/categories
  POST   /api/categories

계획을 검토한 후 Shift+Tab으로 일반 모드로 전환하여 구현을 시작합니다.

Plan 모드로 기획하기

---

3. 2단계: 프로젝트 스캐폴딩

한 번에 프로젝트 구조 생성

이 계획대로 프로젝트를 생성해줘.
package.json, 설정 파일, 디렉토리 구조를 만들고
의존성을 설치해.

Claude가 자동으로 생성하는 것들:

package.json

{
  "name": "todo-app",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "test": "vitest",
    "test:e2e": "playwright test",
    "lint": "next lint",
    "db:push": "prisma db push",
    "db:studio": "prisma studio"
  },
  "dependencies": {
    "next": "^14.0.0",
    "react": "^18.0.0",
    "@prisma/client": "^5.0.0",
    "next-auth": "^5.0.0",
    "bcryptjs": "^2.4.3",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "tailwindcss": "^3.4.0",
    "prisma": "^5.0.0",
    "vitest": "^1.0.0",
    "@playwright/test": "^1.40.0"
  }
}

Prisma 스키마

model User {
  id         String     @id @default(cuid())
  email      String     @unique
  password   String
  name       String
  todos      Todo[]
  categories Category[]
  createdAt  DateTime   @default(now())
}

model Todo {
  id          String   @id @default(cuid())
  title       String
  description String?
  priority    String   @default("medium")
  completed   Boolean  @default(false)
  category    Category? @relation(fields: [categoryId], references: [id])
  categoryId  String?
  user        User     @relation(fields: [userId], references: [id])
  userId      String
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model Category {
  id     String @id @default(cuid())
  name   String
  color  String @default("#3B82F6")
  todos  Todo[]
  user   User   @relation(fields: [userId], references: [id])
  userId String
}

/init로 CLAUDE.md 자동 생성

claude /init

프로젝트를 분석해서 빌드 명령어, 코딩 규칙, 프로젝트 구조를 담은 CLAUDE.md를 자동 생성합니다.

프로젝트 스캐폴딩

---

4. 3단계: 기능 구현

다중 파일 동시 구현의 위력

"좋아요 기능을 추가해줘"라고 하면, Claude가 관련 파일을 모두 찾아서 동시에 수정합니다.

실전 예시: 인증 기능 구현

인증 기능을 구현해줘:
1. 회원가입/로그인 페이지
2. 비밀번호 해싱
3. 세션 관리
4. 보호된 라우트 미들웨어
5. 로그아웃 기능

Claude가 한 번의 요청으로 수정하는 파일들:

✏️ lib/auth.ts          → 비밀번호 해싱, 세션 유틸
✏️ app/api/auth/route.ts → 로그인/회원가입 API
✏️ app/(auth)/login/page.tsx → 로그인 폼
✏️ app/(auth)/signup/page.tsx → 회원가입 폼
✏️ components/AuthForm.tsx → 공통 폼 컴포넌트
✏️ middleware.ts         → 보호 라우트 미들웨어
✏️ lib/validators.ts    → Zod 유효성 검증

프론트엔드 컴포넌트

할 일 목록 UI를 구현해줘:
- 할 일 목록 (필터링, 정렬)
- 할 일 추가 폼
- 할 일 카드 (완료 토글, 삭제)
- 카테고리 필터
- 우선순위 배지

Claude가 만드는 컴포넌트 구조:

components/
├── TodoList.tsx        → 목록 + 필터/정렬
├── TodoItem.tsx        → 개별 카드 (토글/삭제)
├── TodoForm.tsx        → 추가/수정 폼
├── CategoryFilter.tsx  → 카테고리 필터 바
├── PriorityBadge.tsx   → 우선순위 배지
└── EmptyState.tsx      → 빈 목록 안내

백엔드 API

할 일 CRUD API를 만들어줘:
- GET /api/todos → 목록 (필터/정렬 지원)
- POST /api/todos → 생성
- PATCH /api/todos/[id] → 수정
- DELETE /api/todos/[id] → 삭제
- 모든 엔드포인트에 인증 확인
- Zod로 입력 검증

반복 개발 패턴

첫 번째 요청: "기본 CRUD를 구현해줘"
  → 핵심 기능 완성

두 번째 요청: "검색 기능을 추가해줘"
  → 검색 API + 검색 UI 추가

세 번째 요청: "드래그앤드롭 정렬을 추가해줘"
  → DnD 라이브러리 + 순서 저장 로직

네 번째 요청: "다크 모드를 추가해줘"
  → 테마 프로바이더 + 토글 + 스타일 수정

각 요청마다 Claude가 관련된 모든 파일을 자동으로 찾아 수정합니다.

기능 구현

---

5. 스타일링과 UI

Tailwind CSS (기본 접근)

Claude가 생성하는 컴포넌트 스타일:

// TodoItem.tsx
export function TodoItem({ todo, onToggle, onDelete }) {
  return (
    <div className={`
      flex items-center gap-3 p-4 rounded-lg border
      ${todo.completed
        ? 'bg-gray-50 border-gray-200'
        : 'bg-white border-gray-300'}
      hover:shadow-sm transition-all
    `}>
      <input
        type="checkbox"
        checked={todo.completed}
        onChange={() => onToggle(todo.id)}
        className="w-5 h-5 rounded accent-blue-600"
      />
      <div className="flex-1">
        <h3 className={`font-medium ${
          todo.completed ? 'line-through text-gray-400' : ''
        }`}>
          {todo.title}
        </h3>
      </div>
      <PriorityBadge priority={todo.priority} />
      <button onClick={() => onDelete(todo.id)}
        className="text-red-400 hover:text-red-600">
        삭제
      </button>
    </div>
  );
}

반응형 디자인

모바일 반응형으로 만들어줘:
- 모바일: 단일 컬럼 레이아웃
- 태블릿: 사이드바 + 메인
- 데스크탑: 넓은 레이아웃

Claude가 Tailwind 반응형 클래스를 적용:

<div className="flex flex-col md:flex-row gap-4">
  <aside className="w-full md:w-64 shrink-0">
    <CategoryFilter />
  </aside>
  <main className="flex-1">
    <TodoList />
  </main>
</div>

다크 모드

다크 모드를 추가해줘.
localStorage에 설정 저장하고
시스템 설정도 따르게 해줘.

Claude가 테마 프로바이더, 토글 버튼, Tailwind dark: 클래스를 모두 추가합니다.

스타일링과 UI

---

6. 4단계: 테스트와 검증

단위 테스트 (Vitest)

인증 서비스의 단위 테스트를 작성해줘.

Claude가 생성하는 테스트:

// lib/auth.test.ts
describe('인증 서비스', () => {
  it('비밀번호를 해싱한다', async () => {
    const hash = await hashPassword('password123');
    expect(hash).not.toBe('password123');
  });

  it('올바른 비밀번호를 검증한다', async () => {
    const hash = await hashPassword('password123');
    const isValid = await verifyPassword('password123', hash);
    expect(isValid).toBe(true);
  });

  it('잘못된 비밀번호를 거부한다', async () => {
    const hash = await hashPassword('password123');
    const isValid = await verifyPassword('wrong', hash);
    expect(isValid).toBe(false);
  });
});

E2E 테스트 (Playwright)

로그인부터 할 일 생성까지 E2E 테스트를 작성해줘.

// tests/e2e/todo.spec.ts
test('할 일 생성 플로우', async ({ page }) => {
  // 로그인
  await page.goto('/login');
  await page.fill('input[name="email"]', 'test@test.com');
  await page.fill('input[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  // 대시보드 확인
  await expect(page).toHaveURL('/dashboard');

  // 할 일 생성
  await page.fill('input[name="title"]', '첫 번째 할 일');
  await page.click('button:has-text("추가")');

  // 목록에 표시 확인
  await expect(page.locator('.todo-item')).toContainText('첫 번째 할 일');
});

테스트 실행과 자동 수정

테스트를 실행하고 실패하는 것들을 수정해줘.

Claude가 자동으로:

1. npm test 실행
2. 실패 원인 분석
3. 코드 수정
4. 재실행 → 통과 확인

테스트와 검증

---

7. 5단계: 배포

Vercel 배포 (Next.js 최적)

Vercel에 배포할 수 있게 설정해줘.
환경 변수와 빌드 설정을 포함해.

Claude가 생성하는 파일:

// vercel.json
{
  "buildCommand": "npm run build",
  "env": {
    "DATABASE_URL": "@database_url",
    "NEXTAUTH_SECRET": "@nextauth_secret"
  }
}

# 배포 명령
vercel deploy --prod

Docker 컨테이너화

Docker로 패키징해줘.
개발용 docker-compose와 프로덕션 Dockerfile을 만들어.

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./
EXPOSE 3000
CMD ["npm", "start"]

GitHub Actions CI/CD

GitHub Actions로 자동 배포 파이프라인을 만들어줘:
- PR마다 테스트 실행
- main 머지 시 자동 배포

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm test
      - run: npm run build

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

배포

---

8. 실전 프롬프트 전략

전략 1: 복잡한 기능은 분해해서 요청

❌ 나쁜 예:
"결제 시스템을 만들어줘"

✅ 좋은 예:
"Stripe 연동을 다음 순서로 구현해줘:
1. Stripe API 설정 (lib/stripe.ts)
2. 결제 API 엔드포인트 (POST /api/checkout)
3. 결제 폼 컴포넌트 (Stripe Elements)
4. 웹훅으로 결제 확인 처리
5. 주문 상태 DB 업데이트
6. 테스트 작성"

전략 2: CLAUDE.md로 일관성 유지

# CLAUDE.md
## 컴포넌트 패턴
- 서버 컴포넌트가 기본, 'use client'는 필요할 때만
- Zod로 모든 입력 검증
- 절대 경로 import: @/components/Button

## 스타일링
- Tailwind CSS만 사용 (CSS 파일 금지)
- 반응형: mobile-first (sm: → md: → lg:)

전략 3: 검증 기준 명시

다크 모드를 추가해줘:
1. 테마 프로바이더 래퍼 추가
2. useTheme 훅 생성
3. 내비게이션에 토글 버튼 추가
4. localStorage에 설정 저장
5. 라이트/다크 모드 모두에서 모든 페이지 확인
6. 테스트 작성 후 실행

전략 4: 프론트/백엔드 분리 요청

첫 번째: "DB 스키마와 API 엔드포인트를 만들어줘"
  → 백엔드 완성

두 번째: "방금 만든 API를 사용하는 UI를 만들어줘"
  → 프론트엔드 완성

컨텍스트를 깔끔하게 유지하면서 모듈별로 구현합니다.

전략 5: MCP로 외부 도구 활용

# 개발 중 DB 직접 조회
claude mcp add postgres -- npx @bytebase/dbhub \
  --dsn "postgresql://localhost:5432/todoapp"

"users 테이블에 데이터가 제대로 들어가 있는지 확인해줘"

 

실전 프롬프트 전략

---

9. 실전 예제: 할 일 앱에서 SaaS까지

예제 1: 블로그 플랫폼

블로그 플랫폼을 만들어줘:
- 최근 글 목록 홈페이지
- 개별 글 페이지
- 관리자 패널 (글 작성/수정/삭제)
- 댓글 기능
- 태그 기반 필터링
- 마크다운 에디터

예제 2: 실시간 기능 추가

실시간 알림을 추가해줘:
- 누가 좋아요 누르면 작성자에게 알림
- 댓글 달리면 관련자에게 알림
- Socket.IO 사용
- 네비게이션에 알림 배지

예제 3: 멀티 테넌트 SaaS

SaaS 앱으로 확장해줘:
- 워크스페이스 생성/전환
- 팀원 초대 기능
- 역할 기반 권한 (관리자/편집자/뷰어)
- 워크스페이스별 데이터 격리

예제 4: 기존 앱 리팩토링

이 노트북을 Streamlit 대시보드로 변환해줘.
분석 로직은 data.py, 시각화는 viz.py로 추출하고
Streamlit 앱 (app.py)을 만들어.

반복 개발의 흐름

세션 1: 기본 CRUD 완성
  → git commit

세션 2: "검색과 필터 추가해줘"
  → claude --continue
  → git commit

세션 3: "성능 최적화해줘"
  → 가상 스크롤, 이미지 최적화, 캐싱
  → git commit

세션 4: "배포해줘"
  → Docker + GitHub Actions
  → git push → 자동 배포

 

할 일 앱에서 SaaS까지

---

10. 자주 묻는 질문 (FAQ)

Q: Claude Code가 어떤 프레임워크를 가장 잘 다루나요?
A: Next.js(React), Vue 3, SvelteKit 모두 잘 다루지만, Next.js에 가장 최적화되어 있습니다. App Router, 서버 컴포넌트, 서버 액션 등 최신 기능도 완벽히 지원합니다.

Q: 기존 프로젝트에도 사용할 수 있나요?
A: 네. Claude Code가 기존 프로젝트의 구조, 의존성, 코딩 패턴을 분석한 후 기존 스타일에 맞게 코드를 생성합니다. /init으로 CLAUDE.md를 먼저 만들면 더 정확합니다.

Q: 데이터베이스는 어떤 걸 추천하나요?
A: 개발 단계에서는 SQLite(Prisma), 프로덕션에서는 PostgreSQL을 추천합니다. Claude Code는 Prisma, Drizzle, 직접 SQL 모두 지원합니다.

Q: 프론트엔드 디자인도 해주나요?
A: 기본적인 Tailwind CSS 스타일링은 잘 합니다. 디자인 시안이 있으면 스크린샷을 보여주고 "이 디자인대로 만들어줘"라고 하면 비전 분석으로 구현합니다.

Q: 테스트를 직접 실행할 수 있나요?
A: 네. Claude Code가 npm test, npx playwright test 등을 직접 실행하고, 실패하면 자동으로 수정 후 재실행합니다.

Q: 배포까지 자동화할 수 있나요?
A: GitHub Actions CI/CD 설정을 만들어주고, Vercel이나 Docker 배포 설정도 생성합니다. 헤드리스 모드로 CI 파이프라인에서 직접 Claude Code를 실행할 수도 있습니다.

Q: 실시간 기능(WebSocket)도 구현할 수 있나요?
A: 네. Socket.IO, Pusher, Server-Sent Events 등을 활용한 실시간 기능을 구현할 수 있습니다.

---

 

면책 조항: 이 글은 정보 제공 목적으로 작성되었습니다. Claude Code의 기능과 요금은 Anthropic의 정책에 따라 변경될 수 있으며, 최신 정보는 공식 문서를 확인해 주세요.