[클로드코드를 이용한 러닝 코스 공유 서비스] 1. 프로젝트 설계

1. 프로젝트 초기화

프롬프트

> 런닝코스 공유 서비스 초기화해줘
- Frontend : React (Vite 기반), TailwindCSS, React Query 포함
- Backend : Spring Boot (Java, Gradle)
- Database : SQLite (개발용)
- 인증 : JWT (Spring Security)
- 이미지 업로드 : 로컬 저장 + S3 전환 고려

결과

런닝코스 공유 서비스가 초기화되었습니다.

  프로젝트 구조:
  running_share_service/
  ├── frontend/          # React + Vite + TailwindCSS + React Query
  └── backend/           # Spring Boot + Gradle + SQLite + JWT

  주요 기능:
  - ✅ Frontend: React (Vite), TailwindCSS, React Query, React Router, Axios
  - ✅ Backend: Spring Boot 3.2.0, Java 17, Gradle 8.5
  - ✅ Database: SQLite (자동 설정)
  - ✅ 인증: JWT + Spring Security
  - ✅ 파일 업로드: 로컬 저장 (S3 전환 준비 완료)

  실행 방법:

  Frontend:
  cd frontend
  npm run dev

  Backend:
  cd backend
  ./gradlew bootRun

---

2. 기능 명세 작성

프롬프트

> 위 서비스의 MVP 기능 명세서를 작성해줘
- 사용자 스토리 형식
- 우선순위 표시(p0,p1,p2)
- 예상 구현 시간 포함

결과

MVP 기능 명세서를 작성했습니다. (MVP_SPEC.md)

  주요 내용:

  📋 5개 카테고리, 21개 사용자 스토리
  1. 사용자 인증 및 관리 (3개)
  2. 런닝 코스 관리 (6개)
  3. 소셜 기능 (4개)
  4. 마이페이지 (2개)
  5. UI/UX (3개)

  ⏱️ 예상 구현 시간:
  - P0 (필수): 38시간 - 최소 기능 출시
  - P1 (중요): 28시간 - 완성도 있는 MVP
  - P2 (추가): 7시간 - 부가 기능
  - 총 MVP: 66시간 (약 2주, 1인 개발 기준)

  🎯 각 스토리 포함 사항:
  - 사용자 관점의 스토리
  - 구체적인 인수 조건
  - 세부 구현 시간 (Backend/Frontend 분리)

---

3. 아키텍처

프롬프트

> 아키텍처 다이어그램을 mermaid chart를 포함해서 작성해줘

결과

아키텍처 다이어그램을 작성했습니다. (ARCHITECTURE.md)

  주요 내용:

  📊 13개의 Mermaid 다이어그램 포함

  1. 시스템 아키텍처 개요 - 전체 레이어 구조
  2. 프론트엔드 아키텍처 - React 계층 구조 + 폴더 구조
  3. 백엔드 아키텍처 - Spring Boot 계층 구조 + 폴더 구조
  4. 데이터베이스 스키마 - ERD (7개 테이블)
  5. API 아키텍처 - 시퀀스 다이어그램 + 엔드포인트 구조
  6. 인증 플로우 - 회원가입/로그인/인증 요청 플로우
  7. 파일 업로드 아키텍처 - Local/S3 저장 전략
  8. 상태 관리 - React Query 캐싱 전략
  9. 보안 아키텍처 - 다층 보안 체계
  10. 배포 아키텍처 - AWS 기반 프로덕션 환경
  11. 성능 최적화 - Frontend/Backend/Network 최적화
  12. 확장성 - 마이크로서비스 전환 가능
  13. 모니터링 및 로깅 - Sentry, CloudWatch 통합

  각 다이어그램은 Markdown에서 바로 렌더링되며, GitHub/GitLab에서도 확인 가능합니다.

1. 시스템 아키텍처

graph TB
    subgraph "Client Layer"
        A[Web Browser]
        B[Mobile Browser]
    end

    subgraph "Frontend - React + Vite"
        C[React Router]
        D[React Query]
        E[Axios HTTP Client]
        F[TailwindCSS]
        G[Map API SDK]
    end

    subgraph "Backend - Spring Boot"
        H[Spring Security + JWT Filter]
        I[REST Controllers]
        J[Service Layer]
        K[Repository Layer]
        L[JPA/Hibernate]
    end

    subgraph "External Services"
        M[Kakao/Google Map API]
        N[AWS S3<br/>Optional]
    end

    subgraph "Data Storage"
        O[(SQLite DB)]
        P[Local File System]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    E --> H
    H --> I
    I --> J
    J --> K
    K --> L
    L --> O
    J --> P
    J -.-> N
    G --> M

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#fff4e1
    style D fill:#fff4e1
    style E fill:#fff4e1
    style H fill:#e1ffe1
    style I fill:#e1ffe1
    style J fill:#e1ffe1
    style O fill:#ffe1f5
    style P fill:#ffe1f5

2. 프론트엔드 아키텍처

graph LR
    subgraph "Presentation Layer"
        A[Pages]
        B[Components]
        C[Layouts]
    end

    subgraph "Business Logic Layer"
        D[Custom Hooks]
        E[React Query Hooks]
        F[Context/State]
    end

    subgraph "Data Access Layer"
        G[API Service]
        H[Axios Instance]
    end

    subgraph "Utilities"
        I[Auth Utils]
        J[Format Utils]
        K[Validation Utils]
    end

    A --> D
    B --> D
    D --> E
    E --> G
    G --> H
    D --> F
    D --> I
    D --> J
    D --> K

    style A fill:#ffebee
    style B fill:#ffebee
    style D fill:#e3f2fd
    style E fill:#e3f2fd
    style G fill:#e8f5e9
    style H fill:#e8f5e9

3. 백엔드 아키텍처

graph TB
    subgraph "Presentation Layer"
        A[Auth Controller]
        B[Course Controller]
        C[Comment Controller]
        D[User Controller]
        E[File Controller]
    end

    subgraph "Security Layer"
        F[JWT Filter]
        G[Security Config]
    end

    subgraph "Service Layer"
        H[Auth Service]
        I[Course Service]
        J[Comment Service]
        K[User Service]
        L[File Storage Service]
    end

    subgraph "Repository Layer"
        M[User Repository]
        N[Course Repository]
        O[Comment Repository]
        P[Like Repository]
        Q[Bookmark Repository]
    end

    subgraph "Domain Layer"
        R[User Entity]
        S[Course Entity]
        T[Comment Entity]
        U[Like Entity]
        V[Bookmark Entity]
    end

    F --> A
    F --> B
    F --> C
    F --> D

    A --> H
    B --> I
    C --> J
    D --> K
    E --> L

    H --> M
    I --> N
    I --> P
    I --> Q
    J --> O
    K --> M

    M --> R
    N --> S
    O --> T
    P --> U
    Q --> V

    style A fill:#ffcdd2
    style B fill:#ffcdd2
    style C fill:#ffcdd2
    style F fill:#fff9c4
    style H fill:#c5e1a5
    style I fill:#c5e1a5
    style M fill:#b3e5fc
    style N fill:#b3e5fc

4. 데이터베이스 스키마

erDiagram
    USERS ||--o{ COURSES : creates
    USERS ||--o{ COMMENTS : writes
    USERS ||--o{ LIKES : gives
    USERS ||--o{ BOOKMARKS : saves
    COURSES ||--o{ COMMENTS : has
    COURSES ||--o{ LIKES : receives
    COURSES ||--o{ BOOKMARKS : saved_in
    COURSES ||--o{ COURSE_IMAGES : contains
    COURSES ||--o{ ROUTE_POINTS : has

    USERS {
        bigint id PK
        varchar username UK
        varchar email UK
        varchar password
        varchar nickname
        varchar profile_image
        timestamp created_at
        timestamp updated_at
    }

    COURSES {
        bigint id PK
        bigint user_id FK
        varchar title
        text description
        decimal distance
        varchar difficulty
        text start_point
        text end_point
        int view_count
        int like_count
        int comment_count
        timestamp created_at
        timestamp updated_at
    }

    ROUTE_POINTS {
        bigint id PK
        bigint course_id FK
        decimal latitude
        decimal longitude
        int sequence
    }

    COURSE_IMAGES {
        bigint id PK
        bigint course_id FK
        varchar image_url
        boolean is_thumbnail
        int sequence
    }

    COMMENTS {
        bigint id PK
        bigint course_id FK
        bigint user_id FK
        text content
        timestamp created_at
        timestamp updated_at
    }

    LIKES {
        bigint id PK
        bigint course_id FK
        bigint user_id FK
        timestamp created_at
    }

    BOOKMARKS {
        bigint id PK
        bigint course_id FK
        bigint user_id FK
        timestamp created_at
    }

5. API 아키텍처

sequenceDiagram
    participant C as Client
    participant F as JWT Filter
    participant Ctrl as Controller
    participant Svc as Service
    participant Repo as Repository
    participant DB as Database

    C->>F: HTTP Request + JWT Token
    F->>F: Validate Token
    F->>Ctrl: Authenticated Request
    Ctrl->>Ctrl: Validate Input
    Ctrl->>Svc: Business Logic Call
    Svc->>Repo: Data Access
    Repo->>DB: SQL Query
    DB-->>Repo: Result
    Repo-->>Svc: Entity
    Svc-->>Ctrl: DTO
    Ctrl-->>C: JSON Response

6. 인증 플로우

sequenceDiagram
    participant U as User
    participant FE as Frontend
    participant BE as Backend
    participant DB as Database

    rect rgb(200, 220, 250)
    Note over U,DB: 회원가입 플로우
    U->>FE: 회원가입 정보 입력
    FE->>BE: POST /api/auth/register
    BE->>BE: 비밀번호 암호화 (BCrypt)
    BE->>DB: 사용자 저장
    DB-->>BE: 저장 완료
    BE-->>FE: JWT Token
    FE->>FE: Token 저장 (localStorage)
    FE-->>U: 회원가입 완료 + 자동 로그인
    end

    rect rgb(220, 250, 220)
    Note over U,DB: 로그인 플로우
    U->>FE: 로그인 정보 입력
    FE->>BE: POST /api/auth/login
    BE->>DB: 사용자 조회
    DB-->>BE: 사용자 정보
    BE->>BE: 비밀번호 검증
    BE->>BE: JWT Token 생성
    BE-->>FE: JWT Token + User Info
    FE->>FE: Token 저장
    FE-->>U: 로그인 완료
    end

    rect rgb(250, 220, 220)
    Note over U,DB: 인증된 요청 플로우
    U->>FE: 코스 등록 요청
    FE->>BE: POST /api/courses + Authorization Header
    BE->>BE: JWT Token 검증
    BE->>DB: 데이터 저장
    DB-->>BE: 저장 완료
    BE-->>FE: 성공 응답
    FE-->>U: 등록 완료 메시지
    end

7. 파일 업로드 아키텍처

graph TB
    subgraph "Client"
        A[File Selection]
        B[Image Preview]
        C[Upload Request]
    end

    subgraph "Frontend Validation"
        D{File Type Check}
        E{File Size Check}
        F[Compress Image]
    end

    subgraph "Backend Processing"
        G[Receive MultipartFile]
        H[Validate File]
        I{Storage Type?}
    end

    subgraph "Storage Options"
        J[Local File System]
        K[AWS S3]
    end

    L[Return File URL]
    M[Update Database]

    A --> B
    B --> C
    C --> D
    D -->|Valid| E
    D -->|Invalid| N[Error: Invalid Type]
    E -->|Valid| F
    E -->|Invalid| O[Error: Too Large]
    F --> G
    G --> H
    H --> I
    I -->|Local| J
    I -->|S3| K
    J --> L
    K --> L
    L --> M

    style J fill:#b3e5fc
    style K fill:#ffccbc
    style N fill:#ffcdd2
    style O fill:#ffcdd2

8. 상태 관리 아키텍처

graph TB
    subgraph "Global State"
        A[Auth Context]
        B[Toast Context]
    end

    subgraph "Server State - React Query"
        C[Courses Query]
        D[Course Detail Query]
        E[Comments Query]
        F[User Query]
    end

    subgraph "Local State"
        G[Form State]
        H[UI State]
        I[Filter State]
    end

    subgraph "Components"
        J[Pages]
        K[Containers]
        L[Presentational]
    end

    J --> A
    J --> B
    J --> C
    J --> D
    K --> C
    K --> E
    K --> G
    L --> H

    C -.Cache.-> M[(Query Cache)]
    D -.Cache.-> M
    E -.Cache.-> M
    F -.Cache.-> M

    style A fill:#ffe0b2
    style B fill:#ffe0b2
    style C fill:#c8e6c9
    style M fill:#b2dfdb

9. 보안 아키텍처

graph TB
    subgraph "Frontend Security"
        A[XSS Prevention]
        B[CSRF Token]
        C[Input Sanitization]
        D[Secure Token Storage]
    end

    subgraph "Network Security"
        E[HTTPS Only]
        F[CORS Configuration]
        G[Rate Limiting]
    end

    subgraph "Backend Security"
        H[JWT Validation]
        I[Password Encryption]
        J[SQL Injection Prevention]
        K[File Upload Validation]
    end

    subgraph "Data Security"
        L[Sensitive Data Encryption]
        M[Secure Database Access]
    end

    A --> E
    B --> F
    C --> H
    D --> H
    H --> I
    H --> J
    K --> M
    I --> L

    style A fill:#ffccbc
    style H fill:#c5cae9
    style L fill:#b2dfdb

---

4. WBS

프롬프트

> 위 서비스의 MVP 개발을 위한 WBS 를 작성해줘
- Markdown 테이블 형식으로 작성해줘
- 팀 구성 : 백엔드 개발자 1명 , 프론트는 AI

결과

 WBS를 작성했습니다. (WBS.md)

  주요 내용:

  📅 전체 일정: 17일 (3주), 총 167시간

  Phase 구성:
  1. Phase 1-4: 백엔드 기반 작업 (5일)
    - 프로젝트 초기 설정, 인증, 코스 관리, 파일 업로드
  2. Phase 5: 프론트엔드 메인 개발 (3일, AI 활용)
    - 공통 컴포넌트, 레이아웃, 코스 관리 UI
  3. Phase 6-7: 추가 기능 (3일)
    - 소셜 기능, 마이페이지
  4. Phase 8-11: 마무리 (4일)
    - 통합, 테스트, 배포, 문서화

  🎯 주요 특징:
  - 백엔드 개발자 1명 중심으로 일정 계획
  - AI(Claude Code)를 활용한 프론트엔드 빠른 개발
  - 우선순위 기반 작업 배분 (P0/P1/P2)
  - 리스크 관리 및 일일 체크리스트 포함
  - 명확한 성공 기준 (DoD) 정의

---

5. 리스크 확인

프롬프트

> 실제 결과물을 보고 리스크 분석을 해줘

결과

실제 결과물 기반 리스크 분석을 완료했습니다. (RISK_ANALYSIS.md)

  🔴 핵심 발견 사항

  현재 진행률: 전체 MVP 대비 약 5% (167시간 중 7.5시간)

  심각한 문제 3가지 (즉시 해결 필요):
  1. ⚠️ TailwindCSS 빌드 실패 - 프론트엔드 개발 불가
  2. ⚠️ Gradle Wrapper JAR 누락 - 백엔드 빌드 불가
  3. ⚠️ Java 환경 미설정 - 백엔드 실행 불가

  21개 리스크 식별:
  - 🔥 Critical: 5개
  - 🔶 High: 4개
  - 🟢 Medium: 7개
  - 🟢 Low: 5개

  주요 리스크:
  - 핵심 비즈니스 로직 미구현 (Controller, DTO, API 전체 없음)
  - 백엔드 개발자 1인 부담 (167시간 작업)
  - JWT Secret Key 보안 취약점
  - AI 생성 코드 품질 불확실성

  권장 조치:
  1. 즉시: 개발 환경 3대 문제 해결 (1.5시간)
  2. 우선순위 조정: P0만 집중 (17일 → 12일)
  3. 성공 확률: 30% → 70% (리스크 완화 시)

---