본문으로 건너뛰기

"Claude Code" + "bkit" 로 나만의 아이디어를 실현 가능하도록 기획하기

은빈

2026.03.22

"Claude Code" + "bkit" 로 나만의 아이디어를 실현 가능하도록 기획하기 본문 이미지

소개

  • 21기 바이브코딩 스터디 (아이디어만 가져오세요. 4주. 서비스 4개) 를 시작하면서 Claude Code과 bkit 를 설치하고 실제 사이트를 제작하면서 사용력을 높이는 중.

: Claude Code 위에서 동작하는 AI 개발 Tool Kit 인데요, PDCA (Plan-Design-Check-Action) 사이클 기반으로 아이디어를 구체화하여 문서로 정리하고 개발을 도와주는 바이브코딩 키트 (Claude Code 에서 ```/bkit``` 을 치면 bkit 으로 할 수 있는 기능들 요약해서 설명해줍니다)

진행 방법

  1. Claude Code 에서 ```/pdca {아이디어}``` 를 작성

  2. 몇 가지 질문을 통해 아이디어를 구체화 함

  3. 저는 현재 5월에 일본 여행을 계획하고 있는데 지도 상에서 가고 싶은 곳 여러곳을 태그하고 싶고, 그 중에 일정으로 확정하는 곳도 같이 보이고 일정들은 DAY별로 동선까지 한 눈에 보이도록 구성을 하고 싶었습니다.

  4. 하지만,,, 이전 대화 기록이 사라져서😢 .. Claude Code 에서 bkit/pdca 기능을 사용해 아이디어가 AI개발하기 좋게 기획을 끌어올리고 여러 기능을 파악한 Plan 문서(markdown) 를 작성하는지 다른 간단한 아이디어로 예시로 보여드릴께요!

    1. 아이디어를 자연어로 작성 "이미지를 캡쳐하거나 업로드 했을 때 url 링크로 만드는 사이트를 만들고 싶어"

    2. Claude Code 에서 프로젝트 방향성을 잡기 위한 질문을 던짐

    3. 1. 프로젝트 레벨 : 프로젝트 수준을 어떻게 하시겠어요?

    4. 2. 핵심기능 : 어떤 핵심 기능이 필요한가요?

      한국어 텍스트가 적힌 컴퓨터 화면
    5. 인증 : 로그인/회원가입 기능이 필요한가요?

    6. 원하는 답변을 선택(tab) -> submit

    7. 프로젝트 수준에 따라 Plan 문서를 작성해줌

      한국어 프로그램 스크린샷

결과와 배운 점

  • local 파일 내 Plan 문서 자동 생성

  • 결과물

# Image Hosting 서비스 Planning Document

> **Summary**: 이미지를 업로드하거나 클립보드에서 붙여넣으면 공유 가능한 URL 링크를 즉시 생성하는 웹 서비스
>
> **Project**: image-hosting
> **Version**: 0.1.0
> **Author**: hjsu1
> **Date**: 2026-03-22
> **Status**: Draft

---

## Executive Summary

| Perspective | Content |
|-------------|---------|
| **Problem** | 이미지를 빠르게 공유하려면 복잡한 클라우드 스토리지 설정이 필요하고, 캡쳐 이미지를 URL로 변환하는 간편한 도구가 부족함 |
| **Solution** | 드래그앤드롭/클립보드 붙여넣기로 이미지를 업로드하고 즉시 공유 URL을 생성하는 웹 서비스 (bkend.ai BaaS 기반) |
| **Function/UX Effect** | 3초 이내 업로드 → URL 복사 완료. 로그인 없이도 사용 가능하며, 로그인 시 갤러리 관리 제공 |
| **Core Value** | "캡쳐하고 붙여넣으면 끝" — 가장 빠른 이미지 공유 경험 |

---

## 1. Overview

### 1.1 Purpose

이미지를 캡쳐하거나 파일로 업로드했을 때, 즉시 공유 가능한 URL 링크를 생성하는 웹 서비스를 제공한다. Imgur와 유사하지만 더 간결하고 빠른 UX를 목표로 한다.

### 1.2 Background

- 개발자, 디자이너, 일반 사용자가 스크린샷이나 이미지를 빠르게 공유해야 하는 상황이 빈번함
- 기존 서비스(Imgur, Gyazo 등)는 기능이 과도하거나 광고가 많음
- 심플하고 빠른 이미지 공유 도구에 대한 수요 존재

### 1.3 Related Documents

- Design: `docs/02-design/features/image-hosting.design.md` (작성 예정)

---

## 2. Scope

### 2.1 In Scope

- [ ] 이미지 파일 드래그앤드롭 업로드
- [ ] 클립보드 이미지 붙여넣기 (Ctrl+V)
- [ ] 업로드 즉시 공유 URL 생성 및 클립보드 복사
- [ ] 이미지 미리보기
- [ ] 선택적 회원가입/로그인 (Google 소셜 로그인)
- [ ] 로그인 사용자 전용 갤러리 (업로드 이력 관리)
- [ ] 이미지 삭제 기능 (업로더 본인)
- [ ] 반응형 디자인 (모바일/데스크톱)

### 2.2 Out of Scope

- 이미지 편집 기능 (크롭, 필터 등)
- 동영상 업로드
- 유료 결제/프리미엄 플랜
- 커스텀 도메인 연결
- API 키 발급 (외부 연동)

---

## 3. Requirements

### 3.1 Functional Requirements

| ID | Requirement | Priority | Status |
|----|-------------|----------|--------|
| FR-01 | 이미지 파일 업로드 (드래그앤드롭, 파일 선택) | High | Pending |
| FR-02 | 클립보드 이미지 붙여넣기 (Ctrl+V) | High | Pending |
| FR-03 | 업로드 완료 시 공유 URL 자동 생성 | High | Pending |
| FR-04 | URL 원클릭 클립보드 복사 | High | Pending |
| FR-05 | 이미지 미리보기 표시 | High | Pending |
| FR-06 | 선택적 회원가입/로그인 (Google OAuth) | Medium | Pending |
| FR-07 | 로그인 사용자 갤러리 (업로드 이력) | Medium | Pending |
| FR-08 | 이미지 삭제 (본인 업로드만) | Medium | Pending |
| FR-09 | 다중 이미지 동시 업로드 | Low | Pending |
| FR-10 | 이미지 만료일 설정 (선택) | Low | Pending |

### 3.2 Non-Functional Requirements

| Category | Criteria | Measurement Method |
|----------|----------|-------------------|
| Performance | 이미지 업로드 완료 3초 이내 (10MB 기준) | Lighthouse, 실측 |
| Performance | 페이지 초기 로드 1.5초 이내 | Lighthouse |
| Security | 업로드 파일 타입 검증 (이미지만 허용) | 서버 사이드 검증 |
| Security | 파일 크기 제한 (최대 20MB) | 클라이언트 + 서버 검증 |
| Usability | 모바일 반응형 지원 | 실기기 테스트 |
| Availability | 99.5% 이상 가동률 | bkend.ai SLA |

---

## 4. Success Criteria

### 4.1 Definition of Done

- [ ] 모든 FR-01 ~ FR-08 기능 구현 완료
- [ ] 이미지 업로드 → URL 생성 플로우 정상 동작
- [ ] 클립보드 붙여넣기 동작 확인 (Chrome, Firefox, Safari)
- [ ] 로그인/비로그인 모두 업로드 가능 확인
- [ ] 갤러리 CRUD 동작 확인
- [ ] 반응형 레이아웃 확인

### 4.2 Quality Criteria

- [ ] Zero lint errors
- [ ] Build succeeds (Next.js production build)
- [ ] Core Web Vitals 통과 (LCP < 2.5s, FID < 100ms, CLS < 0.1)

---

## 5. Risks and Mitigation

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| 대용량 이미지 업로드 시 타임아웃 | High | Medium | Presigned URL 직접 업로드 방식 (bkend.ai storage) |
| 악성 파일 업로드 | High | Medium | MIME 타입 검증 + 확장자 화이트리스트 |
| 무제한 익명 업로드로 스토리지 남용 | Medium | High | 비로그인 사용자 일일 업로드 제한 (10건) + 자동 만료 (30일) |
| 클립보드 API 브라우저 호환성 | Low | Medium | Clipboard API + fallback (input file) |

---

## 6. Architecture Considerations

### 6.1 Project Level Selection

| Level | Characteristics | Recommended For | Selected |
|-------|-----------------|-----------------|:--------:|
| **Starter** | Simple structure | Static sites, portfolios | ☐ |
| **Dynamic** | Feature-based modules, BaaS integration | Web apps with backend, SaaS MVPs | ☑ |
| **Enterprise** | Strict layer separation, microservices | High-traffic systems | ☐ |

### 6.2 Key Architectural Decisions

| Decision | Options | Selected | Rationale |
|----------|---------|----------|-----------|
| Framework | Next.js / React / Vue | **Next.js (App Router)** | SSR + 파일 기반 라우팅, 이미지 최적화 내장 |
| State Management | Context / Zustand / Redux | **Zustand** | 경량, 간결한 API, 갤러리 상태 관리에 적합 |
| API Client | fetch / axios / react-query | **TanStack Query + fetch** | 캐싱, 로딩 상태 자동 관리 |
| Styling | Tailwind / CSS Modules | **Tailwind CSS** | 빠른 프로토타이핑, 반응형 유틸리티 |
| Backend | BaaS / Custom Server | **bkend.ai** | 파일 스토리지 + DB + 인증 통합 제공 |
| File Upload | Direct / Presigned URL | **Presigned URL** | 대용량 파일 직접 업로드, 서버 부하 없음 |

### 6.3 Clean Architecture Approach

```
Selected Level: Dynamic

Folder Structure Preview:
┌─────────────────────────────────────────────────────┐
│ image-hosting/                                       │
│ ├── src/                                             │
│ │   ├── app/                  # Next.js App Router   │
│ │   │   ├── page.tsx          # 메인 업로드 페이지    │
│ │   │   ├── gallery/page.tsx  # 갤러리 페이지         │
│ │   │   ├── i/[id]/page.tsx   # 이미지 뷰어 페이지   │
│ │   │   └── layout.tsx        # 공통 레이아웃         │
│ │   ├── components/           # UI 컴포넌트           │
│ │   │   ├── UploadZone.tsx    # 드래그앤드롭 영역     │
│ │   │   ├── ClipboardPaste.tsx# 클립보드 붙여넣기     │
│ │   │   ├── ImagePreview.tsx  # 미리보기              │
│ │   │   ├── UrlDisplay.tsx    # URL 표시/복사         │
│ │   │   └── GalleryGrid.tsx   # 갤러리 그리드         │
│ │   ├── features/             # 기능 모듈             │
│ │   │   ├── upload/           # 업로드 로직           │
│ │   │   ├── gallery/          # 갤러리 로직           │
│ │   │   └── auth/             # 인증 로직             │
│ │   ├── services/             # 외부 서비스 연동       │
│ │   │   └── bkend.ts          # bkend.ai 클라이언트   │
│ │   ├── lib/                  # 유틸리티              │
│ │   └── types/                # 타입 정의             │
│ ├── public/                   # 정적 파일             │
│ ├── .mcp.json                 # bkend MCP 설정        │
│ └── package.json                                     │
└─────────────────────────────────────────────────────┘
```

---

## 7. Convention Prerequisites

### 7.1 Existing Project Conventions

- [ ] `CLAUDE.md` — 작성 예정
- [ ] ESLint configuration — Next.js 기본 설정 사용
- [ ] Prettier configuration — 프로젝트 생성 시 추가
- [ ] TypeScript configuration — Next.js 기본 설정

### 7.2 Conventions to Define/Verify

| Category | Current State | To Define | Priority |
|----------|---------------|-----------|:--------:|
| **Naming** | missing | 컴포넌트: PascalCase, 함수: camelCase, 파일: kebab-case | High |
| **Folder structure** | missing | Dynamic 레벨 구조 (features/, services/) | High |
| **Import order** | missing | react → next → external → internal → types | Medium |
| **Environment variables** | missing | NEXT_PUBLIC_ 접두사 규칙 | Medium |
| **Error handling** | missing | try-catch + toast 알림 | Medium |

### 7.3 Environment Variables Needed

| Variable | Purpose | Scope | To Be Created |
|----------|---------|-------|:-------------:|
| `NEXT_PUBLIC_BKEND_URL` | bkend.ai API 엔드포인트 | Client | ☑ |
| `NEXT_PUBLIC_BKEND_PROJECT_ID` | bkend 프로젝트 ID | Client | ☑ |
| `BKEND_SECRET_KEY` | bkend 서버 사이드 키 | Server | ☑ |

### 7.4 Pipeline Integration

| Phase | Status | Document Location | Command |
|-------|:------:|-------------------|---------|
| Phase 1 (Schema) | ☐ | `docs/01-plan/schema.md` | `/phase-1-schema` |
| Phase 2 (Convention) | ☐ | `docs/01-plan/conventions.md` | `/phase-2-convention` |

---

## 8. Next Steps

1. [ ] Design 문서 작성 (`/pdca design image-hosting`)
2. [ ] bkend.ai 프로젝트 생성 및 MCP 연결
3. [ ] Next.js 프로젝트 초기화
4. [ ] 구현 시작

---

## Version History

| Version | Date | Changes | Author |
|---------|------|---------|--------|
| 0.1 | 2026-03-22 | Initial draft |  |

제가 실행하려고 한(3번) 여행 계획 및 다이어리 웹을 구현하고 있는데,

처음 프로젝트를 실행하다보니 bkit pdca 중 plan부분으로

기획서 문서 기반으로 웹 사이트 구현 -> 웹 실행 시 수정사항 확인 -> claude code 에 수정 사하 요청하는 과정으로 원래 진행한 바이브 코딩 방법으로 웹 기능 개선을 진행했습니다.

이렇게 하다보니 token을 금방 쓰더라구요.. 초기 기획을 확실하게 잡고 웹 구현하는게 중요한데 기능들을 계속 쓰면서 익혀나가야될 것 같습니다.

다음 글에는 여행 계획 및 다이어리 웹 구현 시 google API 사용하여 지도 연동하는 부분, 백엔드 연결하여 운영 버전으로 확장하는 부분 등 하나씩 작성하도록 하겠습니다.

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

아루나 프로필 이미지
아루나2026.03.22

Bkit을 활용해서 pdca로 잘 작업을 진행하셨군요! 체계적으로 진행하면서 문서가 정리되서 쌓이니 다음에 이어서 작업을 진행할땐, 문서를 참조해서 더 잘 작업하실수 있을거예요.

황인준 프로필 이미지
황인준2026.03.25

다음 글에는 여행 계획 및 다이어리 웹 구현 시 google API 사용하여 지도 연동하는 부분, 백엔드 연결하여 운영 버전으로 확장하는 부분 등 하나씩 작성하도록 하겠습니다.

-> 지금 개발하신 내용 이상으로 위의 내용들을 구현하시는게 더 재밌으실거라고 확신합니다! 실제로 내가 원하는 기능들이 하나씩 구현되는 과정이 정말 뿌듯하고 자신감도 많이 생깁니다!

실제로 저도 비슷한 사례 만들고 있는데, 공유 드리고 싶네요!!

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기