개인 지식 대시보드
100분 안에 만드는 바이브코딩 사이클

Session 5 · 개인 지식 대시보드 · 바이브코딩 사이클

FastAPI + Postgres + React · Anthropic API · CLAUDE.md · subagent 3 · pytest · Playwright · Docker Compose

강사 박수현 · 🚀 젠아이랩스(GenAI Labs)

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background — laptop screen showing a personal knowledge dashboard mockup. Three cards on screen with headings 'RSS Feeds', 'GitHub Stars', 'Notes'. Stack badges above: React, FastAPI, Postgres (each appearing EXACTLY ONCE). Clean editorial style, 16:9. English ONLY, no duplicate labels."

PART 1

왜 이 실습 — todo 가 아닌 이유·요구사항·스택

세션 목표 · todo-app 이 최악의 예제인 이유 · 요구사항 6개와 3축 매핑 · FastAPI + Postgres + React + Anthropic 스택 선택 근거.

세션 목표 — 동작하는 대시보드가 뜬다

이 세션이 끝나면 참여자 노트북에 동작하는 개인 지식 대시보드 가 뜬다. RSS 피드를 긁고, 노트를 인덱싱하고, Anthropic API 로 요약·태깅한 결과를 React UI 에서 확인할 수 있다.

🎯 진짜 목표

완성물이 아니라 바이브코딩 사이클 이다.

스펙 → 아키텍처 프롬프트 → CLAUDE.md 규약 → subagent 분업 → 반복 리팩토링 → 회귀 방지 테스트 → 배포

이 사이클을 100분 안에 한 번 완주하는 게 목표.

todo-app 이 아닌 이유 — 바이브코딩 관점에서 최악의 예제

많은 AI 코딩 튜토리얼이 todo-app 을 쓴다. CRUD 4개로 프레임워크 개념이 다 나오기 때문이다. 그런데 바이브코딩 관점에서 todo-app 은 최악의 예제 다.

요구사항 6개 · 3축의 실전 발생 지점

GOALS.md 의 여섯 개 기능 요구를 3축 (프롬프트·컨텍스트·하네스) 과 매핑한다.

스택 개요 — FastAPI · Postgres · React · Anthropic

스택 선택 자체가 이 실습의 첫 아키텍처 결정이다.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background showing a three-layer vertical stack on the left: 'React' at top, 'FastAPI' in the middle, 'Postgres' at bottom, connected by arrows. On the right, three external service icons labeled 'RSS', 'GitHub', 'Anthropic' with arrows pointing to the FastAPI layer. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

PART 2

요구사항 설계 · CLAUDE.md · subagent

프롬프트 카드 A (스펙→아키텍처) · 파일 트리 확정 · CLAUDE.md 세팅 · subagent 3 (backend-dev · frontend-dev · db-migrator) 분업.

프롬프트 카드 A — 스펙 → 아키텍처

빈 폴더에서 시작. 참여자는 강사가 만든 뼈대 리포 vibecoding-dashboard-skel 을 clone 한다. 안에는 README.md 와 SPEC.md 두 개뿐이다. 여기서 첫 프롬프트를 던진다.

@SPEC.md

이 요구사항을 FastAPI + PostgreSQL + React(Vite) 로 구현할 계획을 세워줘.
다음 순서로 답변해줘.

1. 파일 트리 (backend/, frontend/, docker/, tests/)
2. 데이터 모델 (SQLAlchemy 클래스명·컬럼만, 코드 X)
3. API 엔드포인트 목록 (path · method · 요청/응답 요약만, 코드 X)
4. 3개의 잠재적 위험 (스코프 · 성능 · 보안)

코드는 이번 턴에 쓰지 마. 다음 턴에 파일 트리부터 만들자.

파일 트리 확정 — 표준 뼈대

프롬프트 A 응답을 검토해 파일 트리를 확정한다. 강사가 사전에 준비한 표준 트리는 아래와 같다.

vibecoding-dashboard/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI 앱 진입
│   │   ├── config.py            # 설정 (환경변수 로드)
│   │   ├── db.py                # SQLAlchemy 엔진·세션
│   │   ├── models.py            # ORM 모델
│   │   ├── schemas.py           # Pydantic 스키마
│   │   ├── routes/              # feeds · github · notes · digest
│   │   └── services/            # rss · github_sync · summarizer · tagger
│   ├── tests/                   # pytest · conftest.py
│   ├── pyproject.toml
│   └── alembic/                 # DB 마이그레이션
├── frontend/
│   ├── src/                     # App · api.ts · components/
│   ├── package.json
│   └── vite.config.ts
├── docker/                      # docker-compose.yml + Dockerfile 2종
├── CLAUDE.md
├── SPEC.md
└── README.md

뼈대 생성 — acceptEdits 로 넘어가는 지점

파일 트리가 확정되면 뼈대 파일을 한 번에 만든다.

확정된 파일 트리를 만들어줘. 각 파일은 빈 셸(주석 한 줄 + 최소 import) 로 두고,
pyproject.toml·package.json·docker-compose.yml 은 실제로 동작하는 최소 구성으로 채워줘.

CLAUDE.md — 프로젝트 규약 (전반부)

뼈대가 만들어졌어도 구현 프롬프트를 바로 이어가지 않는다. 먼저 CLAUDE.md 를 채운다. 이걸 채우지 않으면 Claude 는 매 세션 스타일·테스트·라우트 규약을 다시 물어본다.

# Vibecoding Dashboard — 프로젝트 규약

## 스택
- Backend: FastAPI 0.136+, SQLAlchemy 2.x, Alembic, Pydantic v2
- Frontend: React 18, Vite, TypeScript
- DB: PostgreSQL 16 (Docker)
- LLM: Anthropic Python SDK (`anthropic`)

## 스타일
- Python: black + ruff (line-length 100). `poetry run lint` 로 검증.
- TypeScript: prettier + eslint. `pnpm lint` 로 검증.
- 모든 함수는 타입 힌트 필수. `mypy --strict` 통과 목표.
- 커밋 메시지: `feat(feeds): add RSS ingest route` 형식.

## 테스트
- 백엔드: pytest, `poetry run pytest -x` 가 통과해야 커밋 가능.
- 프론트: Vitest + Playwright. `pnpm test` 로 통합.
- 새 라우트 추가 시 라우트별 테스트 1개는 필수.

CLAUDE.md — 프로젝트 규약 (후반부)

## API 규약
- 모든 라우트는 `/api/v1/` prefix.
- 응답은 항상 `{"data": ..., "error": null}` 또는 `{"data": null, "error": {...}}` 봉투.
- 200/201 외 상태 코드는 `HTTPException` 으로만 발생.
- 시간은 UTC ISO 8601, DB 컬럼은 `TIMESTAMPTZ`.

## 시크릿
- `.env` 는 절대 커밋 금지. `.env.example` 만 유지.
- Anthropic API 키는 `ANTHROPIC_API_KEY` 환경변수로만.

## Claude 지시
- 새 파일 만들기 전에 항상 파일 트리와 대조.
- 모델은 Sonnet 4.6 기본, 어려운 리팩토링만 Opus 4.7.
- 대량 변경은 항상 커밋을 나눠서 (한 커밋 = 한 관심사).

subagent 분업 — backend-dev 정의

프로젝트가 크면 한 세션에서 백엔드·프론트·DB 를 모두 다루기 어렵다. Claude Code 의 subagent 를 세 개 정의해 역할을 나눈다. 세 subagent 는 리포의 .claude/agents/ 안에 마크다운으로 정의한다.

.claude/agents/backend-dev.md

---
name: backend-dev
description: FastAPI 백엔드 라우트·서비스·모델 담당. DB 마이그레이션·프론트 변경은 금지.
tools: [Read, Edit, Write, Bash]
---

너는 이 리포의 FastAPI 백엔드 개발자다.
다음 원칙을 지킨다.

- `backend/` 디렉토리 안에서만 편집. `frontend/` · `alembic/` 은 만지지 않는다.
- 모든 라우트는 CLAUDE.md 의 API 규약을 따른다.
- 새 라우트에는 pytest 케이스 최소 1개.
- 의심스러운 스키마 변경은 db-migrator 에게 위임한다고 답한다.

• name = subagent 식별자 (/agent backend-dev 로 호출).
• description = 언제 이 subagent 로 넘길지 판단하는 근거.
• tools = subagent 가 쓸 수 있는 도구 목록 (여기서 벗어난 도구는 호출 불가).

subagent 3종 — 역할·금지·호출

호출 방법.

> Task(subagent_type="backend-dev", prompt="feeds 라우트에 GET /api/v1/feeds/{id}/refresh 추가")

PART 3

반복 개발 사이클 — FastAPI·DB·RSS·LLM·React

FastAPI 뼈대 · DB 모델 2 슬라이드 · RSS 수집기 · Anthropic 요약·태깅 · React 대시보드 · CLAUDE.md 갱신·hook.

FastAPI 뼈대 ① — config.py

첫 실제 코드는 FastAPI 진입 · DB 세션 · 헬스체크. 강사가 이 코드를 한 번에 만드는 프롬프트를 던진다.

backend/app/main.py · db.py · config.py 를 채워줘. 조건.
- FastAPI 앱은 CORS · lifespan 훅으로 DB 엔진 초기화.
- SQLAlchemy 2.x 비동기 세션.
- 환경변수는 pydantic-settings 로.
- GET /api/v1/health 헬스체크 라우트 하나.
- 코드만. 설명은 필요 없음.

backend/app/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    database_url: str = "postgresql+asyncpg://dash:dash@db:5432/dash"
    anthropic_api_key: str = ""
    cors_origins: list[str] = ["http://localhost:5173"]
    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")


settings = Settings()

FastAPI 뼈대 ② — db.py · 비동기 세션

backend/app/db.py

from sqlalchemy.ext.asyncio import (
    AsyncSession,
    async_sessionmaker,
    create_async_engine,
)

from .config import settings

engine = create_async_engine(settings.database_url, echo=False, pool_pre_ping=True)
SessionLocal = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)


async def get_session() -> AsyncSession:
    async with SessionLocal() as session:
        yield session

FastAPI 뼈대 ③ — main.py · 헬스체크

backend/app/main.py

from contextlib import asynccontextmanager
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from .config import settings
from .db import engine

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    await engine.dispose()  # shutdown: 커넥션 풀 정리

app = FastAPI(title="Vibecoding Dashboard", lifespan=lifespan)
app.add_middleware(
    CORSMiddleware, allow_origins=settings.cors_origins,
    allow_credentials=True, allow_methods=["*"], allow_headers=["*"],
)

@app.get("/api/v1/health")
async def health():
    return {"data": {"status": "ok"}, "error": None}

• lifespan — yield 앞 = startup(엔진은 import 시점에 이미 만들어져 비움), 뒤 = shutdown(engine.dispose()).
• allow_credentials=True — 쿠키·Authorization 을 크로스오리진에 허용. 이 조합엔 ["*"] 가 금지라 settings.cors_origins 화이트리스트 명시.

데이터 모델 ① — FeedSource · db-migrator 위임

헬스체크가 뜨면 데이터 모델을 얹는다. db-migrator subagent 에게 위임.

Task(subagent_type="db-migrator", prompt="""
SPEC.md 의 4개 엔티티(FeedSource · FeedItem · Note · GithubEvent) 를 SQLAlchemy 모델 + alembic 초기 마이그레이션으로. 조건.
- 모든 테이블 공통: id(uuid) · created_at · updated_at (TIMESTAMPTZ).
- FeedItem 은 summary · tags(jsonb) 컬럼, title+summary 에 GIN 인덱스.
""")

backend/app/models.py — FeedSource

import uuid
from datetime import datetime
from sqlalchemy import String, func
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship


class Base(DeclarativeBase):
    pass


class FeedSource(Base):
    __tablename__ = "feed_sources"
    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    url: Mapped[str] = mapped_column(String(500), unique=True)
    title: Mapped[str] = mapped_column(String(200))
    created_at: Mapped[datetime] = mapped_column(server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(server_default=func.now(), onupdate=func.now())
    items: Mapped[list["FeedItem"]] = relationship(back_populates="source")

데이터 모델 ② — FeedItem · 요약·태그 컬럼

backend/app/models.py — FeedItem

from sqlalchemy import JSON, ForeignKey, String, Text, func


class FeedItem(Base):
    __tablename__ = "feed_items"
    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    source_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("feed_sources.id"))
    title: Mapped[str] = mapped_column(String(300))
    url: Mapped[str] = mapped_column(String(500))
    raw_content: Mapped[str] = mapped_column(Text)
    summary: Mapped[str | None] = mapped_column(Text)
    tags: Mapped[dict] = mapped_column(JSON, default=dict)
    published_at: Mapped[datetime] = mapped_column()
    created_at: Mapped[datetime] = mapped_column(server_default=func.now())
    updated_at: Mapped[datetime] = mapped_column(server_default=func.now(), onupdate=func.now())
    source: Mapped[FeedSource] = relationship(back_populates="items")

마이그레이션 실행.

docker compose exec backend alembic upgrade head

RSS 수집기 — feedparser · async 래퍼

데이터 모델이 준비되면 RSS 수집기부터 붙인다. backend-dev 호출.

Task(subagent_type="backend-dev", prompt="""
services/rss.py: async fetch_feed(url)->list[dict] (feedparser).
routes/feeds.py: POST /feeds(등록) · POST /feeds/{id}/refresh(fetch→FeedItem) · pytest 1개.
""")

backend/app/services/rss.py — 핵심부

import asyncio, feedparser

async def fetch_feed(url: str) -> list[dict]:
    loop = asyncio.get_running_loop()
    parsed = await loop.run_in_executor(None, feedparser.parse, url)  # sync 파서를 스레드로
    return [
        {"title": e.get("title", "")[:300], "url": e.get("link", ""),
         "raw_content": e.get("summary", ""), "published_at": _published_at(e)}
        for e in parsed.entries
    ]

📎 _published_at() (published_parsed·updated_parsed → UTC datetime, 없으면 now) 전체 구현은 뼈대 리포 backend/app/services/rss.py 참고.

RSS 라우트 ① — 등록 엔드포인트

backend/app/routes/feeds.py — imports · router · POST /api/v1/feeds

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from ..db import get_session
from ..models import FeedItem, FeedSource
from ..schemas import FeedSourceIn, FeedSourceOut
from ..services.rss import fetch_feed

router = APIRouter(prefix="/api/v1/feeds", tags=["feeds"])


@router.post("", response_model=FeedSourceOut, status_code=201)
async def register(payload: FeedSourceIn, session: AsyncSession = Depends(get_session)):
    src = FeedSource(url=str(payload.url), title=payload.title)
    session.add(src)
    await session.commit()
    await session.refresh(src)
    return {"data": src, "error": None}

RSS 라우트 ② — refresh 엔드포인트

backend/app/routes/feeds.py (이어서) — POST /api/v1/feeds/{id}/refresh

@router.post("/{source_id}/refresh")
async def refresh(source_id: str, session: AsyncSession = Depends(get_session)):
    src = await session.get(FeedSource, source_id)
    if not src:
        raise HTTPException(status_code=404, detail="feed not found")
    fetched = await fetch_feed(src.url)
    for item in fetched:
        session.add(FeedItem(source_id=src.id, **item))
    await session.commit()
    return {"data": {"ingested": len(fetched)}, "error": None}

Anthropic API 요약·태깅 ① — SDK·프롬프트 상수

LLM 호출이 처음 들어오는 지점. anthropic SDK 를 쓴다. 프롬프트 자체가 모듈 상수로 코드에 박힌다.

backend/app/services/summarizer.py — imports · client · SUMMARY_PROMPT

import asyncio
import json
import logging

from anthropic import AsyncAnthropic, APIError

from ..config import settings

logger = logging.getLogger(__name__)

client = AsyncAnthropic(api_key=settings.anthropic_api_key)

SUMMARY_PROMPT = """너는 개인 지식 큐레이터다.
주어진 글의 제목과 본문을 읽고 다음 JSON 을 반환한다.

{
  "summary": "3문장 이내 한국어 요약",
  "tags": ["소문자 영어 슬러그", "최대 5개"]
}

JSON 외 어떤 텍스트도 반환하지 마."""

Anthropic API 요약·태깅 ② — 호출·재시도·실패 처리

backend/app/services/summarizer.py (이어서) — summarize_and_tag

async def summarize_and_tag(title: str, body: str) -> dict:
    user_msg = f"제목: {title}\n\n본문:\n{body[:4000]}"

    for attempt in range(3):
        try:
            resp = await client.messages.create(
                model="claude-haiku-4-5",
                max_tokens=512,
                system=SUMMARY_PROMPT,
                messages=[{"role": "user", "content": user_msg}],
            )
            text = resp.content[0].text.strip()
            return json.loads(text)
        except (APIError, json.JSONDecodeError) as exc:
            logger.warning("summarize attempt %d failed: %s", attempt + 1, exc)
            await asyncio.sleep(2**attempt)

    return {"summary": "", "tags": []}

요약·태깅 — pytest 케이스

backend/tests/test_summarizer.py

import pytest

from app.services.summarizer import summarize_and_tag


@pytest.mark.asyncio
@pytest.mark.integration
async def test_summarize_and_tag_shape():
    result = await summarize_and_tag(
        title="Anthropic releases Claude Opus 4.7",
        body="Anthropic announced ...",
    )
    assert isinstance(result, dict)
    assert "summary" in result
    assert "tags" in result and isinstance(result["tags"], list)

React 대시보드 ① — api.ts · fetch 래퍼

백엔드가 요약을 반환할 수 있게 되면 프론트를 붙인다. frontend-dev 호출.

Task(subagent_type="frontend-dev", prompt="""
frontend/src 컴포넌트.
- App.tsx: 상단 SearchBar + 하단 DigestList
- DigestList.tsx: /api/v1/digest/today 를 카드 그리드로
- SearchBar.tsx: debounced 300ms 로 /api/v1/digest/search?q=... 호출
- api.ts: fetch 래퍼 (base = .env VITE_API_BASE)
스타일 최소, Tailwind 대신 모듈 CSS.
""")

frontend/src/api.ts

const BASE = import.meta.env.VITE_API_BASE ?? "http://localhost:8000";

export type DigestItem = {
  id: string; title: string; url: string;
  summary: string; tags: string[]; published_at: string;
};

async function get<T>(path: string): Promise<T> {
  const res = await fetch(`${BASE}${path}`);
  if (!res.ok) throw new Error(`${res.status}`);
  return (await res.json()).data as T;
}

export const api = {
  today: () => get<DigestItem[]>("/api/v1/digest/today"),
  search: (q: string) => get<DigestItem[]>(`/api/v1/digest/search?q=${encodeURIComponent(q)}`),
};

React 대시보드 ② — DigestList (props·state·hooks)

frontend/src/components/DigestList.tsx — imports · props · state · effect

import { useEffect, useState } from "react";
import { api, DigestItem } from "../api";
import styles from "./DigestList.module.css";

export function DigestList({ query }: { query: string }) {
  const [items, setItems] = useState<DigestItem[]>([]);

  useEffect(() => {
    const load = query ? api.search(query) : api.today();
    load.then(setItems).catch(() => setItems([]));
  }, [query]);

  // return ( ... ) — 이어짐
}

React 대시보드 ③ — DigestList (JSX 렌더)

frontend/src/components/DigestList.tsx (이어서) — return JSX 와 렌더 결과 대조

  return (
    <div className={styles.grid}>
      {items.map((item) => (
        <article key={item.id} className={styles.card}>
          <h3>
            <a href={item.url} target="_blank" rel="noreferrer">
              {item.title}
            </a>
          </h3>
          <p>{item.summary}</p>
          <div className={styles.tags}>
            {item.tags.map((t) => (
              <span key={t}>{t}</span>
            ))}
          </div>
        </article>
      ))}
    </div>
  );
}

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background — a dashboard UI mockup. Left sidebar with three menu items 'Feeds', 'Digests', 'Settings'. Main area: 3x2 grid of six digest cards. Each card has a title area shown as 2 thin abstract horizontal lines (NO letters, NO English words in the title — just abstract lines suggesting text), and below the lines three colored tag chips. The tag chips use ONLY these real English tech words: 'FastAPI', 'React', 'MCP', 'RAG', 'CI', 'Docker' (mix and match, 3 chips per card). CRITICAL: NO garbled English text, NO hex color codes, NO fake latin/gibberish words. Clean editorial style, 16:9. English ONLY."

CLAUDE.md 갱신 — 실습 진행 중 특이사항

지금까지 만든 것이 세 번의 반복을 거쳤다. FastAPI 뼈대 → RSS 라우트 → 요약 서비스 → React 대시보드. 매 반복마다 결정이 CLAUDE.md 에 추가돼야 한다.

CLAUDE.md 에 추가할 세 줄.

## 이 리포 특이사항 (실습 진행 중 갱신)

- 요약 프롬프트는 `backend/app/services/summarizer.py` 의 SUMMARY_PROMPT 상수만 편집.
  프롬프트 변경은 별도 커밋으로.
- RSS refresh 는 동기. 다음 라운드에 background task 로 옮길 예정.
- 프론트 컴포넌트는 함수형만. class 컴포넌트 금지.

hook 3개 — .claude/settings.local.json

hook 은 리포 .claude/settings.local.json 에 얹는다. 규약을 문서에서 코드로 옮기는 지점.

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write|Edit", "hooks": [
        { "type": "command", "command": "test ! -f .env || echo 'WARNING: .env exists'" }
      ]}
    ],
    "PostToolUse": [
      { "matcher": "Edit", "hooks": [
        { "type": "command", "command": "cd backend && poetry run ruff check --fix . 2>&1 | tail -20" }
      ]}
    ]
  }
}

PART 4

회귀 방지 · 리팩토링 — 프롬프트 카드 B·C

pytest 첫 초록불 · 프롬프트 카드 B (회귀 방지) · 프롬프트 카드 C (반복 리팩토링) · Playwright E2E · Docker Compose 배포.

pytest 도입 — 초록불 만들기

코드가 쌓였다. 리팩토링에 들어가려면 테스트가 초록불 이어야 한다.

backend/pyproject.toml — pytest 설정

[tool.pytest.ini_options]
asyncio_mode = "auto"
markers = ["integration: 외부 API 호출 필요 (기본 skip)"]
addopts = "-x -ra --strict-markers"

backend/tests/conftest.py — 인메모리 DB fixture (핵심)

import pytest_asyncio
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker
from app.models import Base

@pytest_asyncio.fixture
async def db_session() -> AsyncSession:
    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    async with async_sessionmaker(engine, expire_on_commit=False)() as session:
        yield session
    await engine.dispose()

• sqlite+aiosqlite:///:memory: — 인메모리 async SQLite. fixture 마다 새로 만들고 폐기해 케이스 간 오염 차단.
• client fixture 는 httpx ASGITransport(app=app) 로 uvicorn 없이 ASGI 앱을 직접 호출 — 포트 충돌·기동 대기 없음.

프롬프트 카드 B — 회귀 방지

초록불이 잡히면 회귀 방지 카드 를 던진다. 이 카드는 리팩토링 프롬프트 앞에 항상 붙는다.

지금부터 리팩토링을 진행할 텐데, 다음 원칙을 지킨다.

1. 변경 전 `poetry run pytest -x` 결과를 먼저 실행해 초록불 확인.
2. 변경 후 같은 명령을 실행해 여전히 초록불인지 확인.
3. 만약 실패한다면, 실패한 테스트 이름 · 실패 원인 · 수정 diff 를 표로 보고.
4. 이 원칙은 이 세션 내 모든 리팩토링에 적용.

프롬프트 카드 C — 반복 리팩토링

이제 실제 리팩토링을 시작한다. 첫 표적은 응답 봉투 반복 코드. {"data": ..., "error": None} 을 라우트마다 손으로 쓰는 게 냄새다.

backend/app/routes/feeds.py 의 응답 봉투(`{"data": ..., "error": None}`) 가
라우트마다 반복된다. 이 반복을 제거하는 3가지 접근을 표로 비교해줘.

각 접근에 다음 열.
- 접근명
- 구현 위치 (미들웨어 · 의존성 · 유틸 함수)
- 장점 2줄
- 단점 2줄
- 이 리포에 적합한 정도 (상/중/하)

표만 먼저. 코드는 다음 턴에.

프롬프트 카드 C — 응답 표와 선택

강사가 이 표를 읽고 적합=상 인 3번 접근을 고른다. 다음 턴에 코드를 요청.

3번 접근으로 구현해줘. 다음 파일 편집.
- backend/app/envelope.py (새 파일)
- backend/app/routes/feeds.py (기존 라우트 수정)

변경 후 pytest -x 결과 확인 (카드 B 원칙 적용).

Playwright — 프론트 회귀 시나리오 하나

백엔드는 pytest 로 회귀를 막았다. 프론트는 Playwright 로 한 개 만 붙인다. 검색 → 결과 표시.

frontend/tests/e2e/search.spec.ts

import { test, expect } from "@playwright/test";

test("search shows digest items", async ({ page }) => {
  await page.goto("http://localhost:5173");

  await page.getByPlaceholder("검색").fill("anthropic");

  await expect(page.locator("article")).toHaveCount(1, { timeout: 3000 });
  await expect(page.locator("article h3")).toContainText(/./);
});

실행.

pnpm exec playwright test

Docker Compose ① — services.db

회귀 방지가 갖춰졌으면 마지막 조각은 한 명령으로 뜨는 배포. Docker Compose 로 백엔드·DB·프론트를 한꺼번에.

docker/docker-compose.yml — db 블록

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: dash
      POSTGRES_PASSWORD: dash
      POSTGRES_DB: dash
    volumes:
      - db-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dash"]
      interval: 5s
      retries: 10

Docker Compose ② — services.backend

docker/docker-compose.yml — backend 블록

  backend:
    build:
      context: ..
      dockerfile: docker/Dockerfile.backend
    environment:
      DATABASE_URL: postgresql+asyncpg://dash:dash@db:5432/dash
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      CORS_ORIGINS: '["http://localhost:5173"]'
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8000:8000"
    command: >
      sh -c "alembic upgrade head &&
             uvicorn app.main:app --host 0.0.0.0 --port 8000"

📎 docker/Dockerfile.backend (python:3.12-slim + poetry --only main 설치, uvicorn CMD — compose command 가 오버라이드) 전체는 뼈대 리포 참고.

• CORS_ORIGINS: '["http://localhost:5173"]' — list[str] 필드라 pydantic-settings 가 JSON 파싱. 리스트는 JSON 배열 문자열로 넣어야 한다.
• ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY} — Compose 가 호스트 셸 환경변수를 물려받음. 시크릿이 이미지·git 에 안 남고, 없으면 빈 문자열로 확장.

Docker Compose ③ — services.frontend

docker/docker-compose.yml — frontend 블록

  frontend:
    build:
      context: ..
      dockerfile: docker/Dockerfile.frontend
    environment:
      VITE_API_BASE: http://localhost:8000
    ports:
      - "5173:5173"
    depends_on:
      - backend

volumes:
  db-data:

한 명령 배포.

docker compose -f docker/docker-compose.yml up --build

PART 5

정리 · 확장 — 한 문장·확장 아이디어 5

확장 아이디어 5개 (Slack · 모바일 · 오디오 · 백업 · 벡터 검색) · 마무리 한 문장.

확장 아이디어 5개 — 하나만 골라 가져간다

이 대시보드는 초안이다. 각자 자기 리포로 가져가 확장할 다섯 방향을 짧게 짚는다.

마무리 — 사이클을 한 번 완주했다

100분의 실습이 끝났다. 스펙 → 아키텍처 프롬프트 → CLAUDE.md → subagent → 반복 → 회귀 방지 → Docker Compose 까지 한 사이클을 통과했다.

🎨 이미지 프롬프트: "Editorial illustration on dark navy #0f1722 background of a circular diagram at the center: a laptop with a dashboard screen, and radiating outward to five smaller icons labeled 'Slack', 'Mobile', 'Audio', 'Backup', 'Vector'. Warm orange gradient background accent similar to the cover slide. Clean editorial illustration style, teal #00b894 and purple #6c5ce7 accents, 16:9. CRITICAL: All visible text MUST be in English ONLY (no Korean characters). Each label appears EXACTLY ONCE — no duplicates. No mirrored or reversed text."

마무리 — 사이클을 한 번 완주했다