소개
21기 바이브코딩 스터디 (아이디어만 가져오세요. 4주. 서비스 4개) 를 시작하면서 Claude Code과 bkit 를 설치하고 실제 사이트를 제작하면서 사용력을 높이는 중.
bkit (https://www.bkit.ai/)
: Claude Code 위에서 동작하는 AI 개발 Tool Kit 인데요, PDCA (Plan-Design-Check-Action) 사이클 기반으로 아이디어를 구체화하여 문서로 정리하고 개발을 도와주는 바이브코딩 키트 (Claude Code 에서 ```/bkit``` 을 치면 bkit 으로 할 수 있는 기능들 요약해서 설명해줍니다)
진행 방법
Claude Code 에서 ```/pdca {아이디어}``` 를 작성
몇 가지 질문을 통해 아이디어를 구체화 함
저는 현재 5월에 일본 여행을 계획하고 있는데 지도 상에서 가고 싶은 곳 여러곳을 태그하고 싶고, 그 중에 일정으로 확정하는 곳도 같이 보이고 일정들은 DAY별로 동선까지 한 눈에 보이도록 구성을 하고 싶었습니다.
하지만,,, 이전 대화 기록이 사라져서😢 .. Claude Code 에서 bkit/pdca 기능을 사용해 아이디어가 AI개발하기 좋게 기획을 끌어올리고 여러 기능을 파악한 Plan 문서(markdown) 를 작성하는지 다른 간단한 아이디어로 예시로 보여드릴께요!
아이디어를 자연어로 작성 "이미지를 캡쳐하거나 업로드 했을 때 url 링크로 만드는 사이트를 만들고 싶어"
Claude Code 에서 프로젝트 방향성을 잡기 위한 질문을 던짐
1. 프로젝트 레벨 : 프로젝트 수준을 어떻게 하시겠어요?
2. 핵심기능 : 어떤 핵심 기능이 필요한가요?
인증 : 로그인/회원가입 기능이 필요한가요?
원하는 답변을 선택(tab) -> submit
프로젝트 수준에 따라 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 사용하여 지도 연동하는 부분, 백엔드 연결하여 운영 버전으로 확장하는 부분 등 하나씩 작성하도록 하겠습니다.
