포스트

Claude Code 바이브 코딩 실전 워크플로우

게시 업데이트
By BLUEBUG
45 분읽는 시간
Claude Code 바이브 코딩 실전 워크플로우

Cursor 스타일 개발 프로세스와 Claude Code의 통합

들어가며

현대 AI 기반 개발에서 가장 중요한 것은 단순히 ‘코드를 빨리 생성하는 것’이 아닙니다. 체계적인 프로세스를 통해 올바른 것을 올바르게 만드는 것입니다. 이 가이드는 Cursor 사용자들이 선호하는 체계적인 워크플로우를 Claude Code에 적용하는 방법을 다룹니다.

Part 1: 바이브 코딩의 진화

1세대 바이브 코딩: 즉흥적 개발

초기 바이브 코딩은 대부분 이런 식이었습니다:

1
2
3
4
5
6

개발자: "TODO 앱 만들어줘"
AI: [코드 생성]
개발자: "여기에 날짜 필터 추가해줘"
AI: [코드 수정]
개발자: "이거 왜 안돼? 고쳐줘"
AI: [코드 수정]

문제점:

  • 체계 없는 즉흥적 개발
  • 일관성 없는 결과물
  • 나중에 유지보수 어려움
  • 팀 협업 불가능

2세대 바이브 코딩: 체계적 프로세스

현재 고급 개발자들은 이렇게 접근합니다:

1
2
3
4
5

1. 명확한 요구사항 정의
2. 단계별 계획 수립
3. AI로 구현하되 각 단계 검증
4. 체계적인 리뷰와 테스트
5. 문서화와 커밋

장점:

  • 일관된 품질
  • 팀 협업 가능
  • 유지보수 용이
  • 확장 가능한 구조

Part 2: 6단계 워크플로우 상세 가이드

🎯 Phase 1: Plan (계획 수립)

목적

무엇을 만들 것인지 명확히 정의하고, 어떻게 만들 것인지 계획을 수립합니다.

Claude Code와 함께하는 Plan 작성

Step 1: 기능 요구사항 정의

Claude Code에게 이렇게 요청하세요:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

다음 기능에 대한 상세한 요구사항을 정리해줘:

[사용자 관점]
- 사용자가 주식 종목을 검색할 수 있어야 함
- 실시간으로 가격 변동을 확인할 수 있어야 함
- 관심 종목을 저장하고 관리할 수 있어야 함

[기술 제약사항]
- Spring Boot 3.2, React 18 사용
- PostgreSQL 데이터베이스
- REST API 설계

위 내용을 바탕으로 PRD(Product Requirement Document) 초안을 작성해줘.
각 기능별로 user story 형식으로 정리하고,
우선순위와 예상 개발 시간도 함께 제시해줘.

Claude Code의 응답 예시:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Product Requirement Document (PRD)
## 주식 관심종목 관리 시스템

### 1. 핵심 기능

#### Feature 1: 종목 검색
**User Story:** 
사용자로서, 종목명이나 코드로 주식을 검색하여 
빠르게 원하는 종목 정보를 찾을 수 있기를 원한다.

**Acceptance Criteria:**
- 종목명 또는 종목코드로 검색 가능
- 자동완성 기능 제공
- 검색 결과는 0.5초 이내 응답
- 부분 일치 검색 지원

**우선순위:** P0 (필수)
**예상 시간:** 4시간

...

Step 2: 기술 요구사항 정의

1
2
3
4
5
6
7
8
9
10
11

위 PRD를 바탕으로 TRD(Technical Requirement Document)를 작성해줘.

포함할 내용:
1. 시스템 아키텍처 (3-tier 구조)
2. API 엔드포인트 목록 (RESTful 설계)
3. 데이터베이스 스키마 설계
4. 기술 스택과 주요 라이브러리
5. 성능 요구사항
6. 보안 요구사항

각 항목은 구현 가능한 수준으로 구체적으로 작성해줘.

Step 3: Use Case 시나리오 작성

1
2
3
4
5
6
7
8
9
10
11
12

주요 사용자 시나리오를 use case별로 작성해줘:

1. 신규 사용자의 첫 방문 시나리오
2. 기존 사용자의 관심종목 확인 시나리오
3. 종목 검색 및 추가 시나리오
4. 에러 상황 처리 시나리오

각 시나리오는 다음 형식으로:
- 사전 조건
- 단계별 흐름
- 예상 결과
- 예외 상황

산출물 체크리스트

Plan 단계에서 만들어야 할 문서들:

  • PRD: 제품 요구사항 문서
  • TRD: 기술 요구사항 문서
  • Use Cases: 주요 사용자 시나리오
  • API Specification: API 명세서 초안
  • Database Schema: ERD 또는 스키마 정의

🔍 Phase 2: Validation (검증 및 개선)

목적

작성한 계획을 다른 관점에서 검토하고 개선점을 찾습니다.

다중 AI 모델 활용 전략

왜 여러 AI를 사용하나요?

  • 각 AI는 다른 강점을 가짐
  • 서로 다른 관점에서 검증
  • 편향을 줄이고 품질 향상

Claude Code에서의 구현:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

[새로운 대화 세션 시작]

다음은 내가 작성한 주식 관심종목 시스템의 계획서야:

[PRD 내용 붙여넣기]
[TRD 내용 붙여넣기]

이 계획서를 다음 관점에서 검토해줘:

1. 보안 관점: 
   - 잠재적 보안 취약점은 없는가?
   - 인증/인가는 적절한가?
   - 민감 데이터 보호는 충분한가?

2. 성능 관점:
   - 병목 지점은 없는가?
   - 확장성을 고려했는가?
   - 캐싱 전략은 적절한가?

3. 사용자 경험 관점:
   - 사용자 흐름이 자연스러운가?
   - 에러 처리가 친절한가?
   - 접근성을 고려했는가?

4. 개발/운영 관점:
   - 테스트하기 쉬운 구조인가?
   - 모니터링은 가능한가?
   - 배포는 어떻게 할 것인가?

각 관점에서 발견된 문제와 개선 제안을 구체적으로 제시해줘.

개선 사항 통합

Claude Code가 제시한 개선사항을 검토하고:

1
2
3
4
5
6
7
8
9
10
11

위에서 제시한 개선사항 중 다음 항목들을 계획서에 반영해줘:

[선택한 개선사항 나열]

1. API에 rate limiting 추가
2. 데이터베이스 쿼리 최적화를 위한 인덱스 추가
3. 프론트엔드에 에러 바운더리 구현
4. 로깅 및 모니터링 전략 추가

기존 PRD와 TRD를 업데이트하고, 
변경사항을 changelog 형식으로 요약해줘.

🏗️ Phase 3: Build (구현)

목적

검증된 계획을 바탕으로 실제 코드를 생성합니다.

점진적 구현 전략

한 번에 모든 것을 만들지 마세요!

단계별로 구현하고 각 단계마다 테스트합니다:

Step 1: 프로젝트 골격 생성

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

다음 요구사항으로 프로젝트 초기 구조를 생성해줘:

기술 스택:
- Backend: Spring Boot 3.2 + MyBatis + PostgreSQL
- Frontend: React 18 + TypeScript + Vite
- 빌드: Maven (backend), npm (frontend)

생성할 것:
1. 프로젝트 디렉토리 구조
2. 기본 설정 파일 (application.yml, vite.config.ts 등)
3. 의존성 설정 (pom.xml, package.json)
4. README.md 초안
5. .gitignore

단, 실제 비즈니스 로직은 아직 포함하지 말고,
빈 프로젝트가 정상적으로 실행되는 것까지만 구현해줘.

Step 2: 데이터베이스 레이어

1
2
3
4
5
6
7
8
9
10
11

이제 데이터베이스 레이어를 구현해줘:

1. PostgreSQL 스키마 생성 SQL
2. MyBatis Mapper 인터페이스
3. Mapper XML 파일
4. 도메인 모델 클래스

앞서 작성한 TRD의 데이터베이스 스키마를 참고하고,
각 테이블에 대한 기본 CRUD 쿼리를 포함해줘.

샘플 데이터 INSERT 문도 함께 만들어줘.

Step 3: 백엔드 API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

백엔드 REST API를 구현해줘:

참고 문서: [TRD의 API 명세 부분]

구현할 API:
1. GET /api/stocks - 주식 목록 조회
2. GET /api/stocks/{code} - 특정 주식 조회
3. GET /api/stocks/search?q={query} - 주식 검색
4. POST /api/watchlist - 관심종목 추가
5. GET /api/watchlist - 내 관심종목 조회
6. DELETE /api/watchlist/{id} - 관심종목 삭제

각 API는:
- Controller 레이어
- Service 레이어
- 적절한 예외 처리
- DTO 클래스
- 로깅

포함해서 구현해줘. 아직 인증은 제외하고 진행.

Step 4: 프론트엔드 UI

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

React 프론트엔드를 구현해줘:

구현할 컴포넌트:
1. StockSearchBar - 종목 검색 바
2. StockList - 종목 목록 표시
3. StockCard - 개별 종목 카드
4. WatchlistPanel - 관심종목 패널
5. App - 메인 애플리케이션

각 컴포넌트는:
- TypeScript로 작성
- Props 타입 정의
- 기본 스타일링 (CSS-in-JS 또는 모듈 CSS)
- 로딩 상태 처리
- 에러 바운더리

백엔드 API와 연동하는 Axios 클라이언트도 포함해줘.

빌드 단계 체크포인트

각 단계마다 확인할 것:

  • 코드가 컴파일되는가?
  • 기본 실행이 되는가?
  • 콘솔에 에러가 없는가?
  • 의도한 대로 동작하는가?

🔬 Phase 4: Review (검토)

목적

구현된 코드를 체계적으로 검토하고 품질을 검증합니다.

자동화된 코드 리뷰

Step 1: 코드 품질 검토

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

다음 파일들을 검토해줘:

backend/src/main/java/com/stock/controller/StockController.java
backend/src/main/java/com/stock/service/StockService.java
frontend/src/components/StockList.tsx

검토 항목:
1. 코드 스타일과 컨벤션
   - 네이밍이 명확한가?
   - 일관된 포맷팅인가?
   
2. 로직 정확성
   - 비즈니스 요구사항을 만족하는가?
   - edge case 처리가 되어있는가?
   
3. 보안
   - SQL 인젝션 취약점은 없는가?
   - XSS 취약점은 없는가?
   - 민감 정보 노출은 없는가?
   
4. 성능
   - N+1 쿼리 문제는 없는가?
   - 불필요한 재렌더링은 없는가?
   
5. 테스트 가능성
   - 의존성 주입이 잘 되어있는가?
   - 테스트하기 쉬운 구조인가?

각 파일별로 발견된 이슈를 severity(High/Medium/Low)와 
함께 리포트해줘. 개선 코드도 함께 제시해줘.

Step 2: 아키텍처 리뷰

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

전체 프로젝트 구조를 리뷰해줘:

1. 레이어 분리가 적절한가?
   - Controller, Service, Repository 계층이 명확한가?
   - 각 레이어의 책임이 분명한가?
   
2. 의존성 방향이 올바른가?
   - 상위 레이어가 하위 레이어에만 의존하는가?
   - 순환 참조는 없는가?
   
3. 확장성을 고려했는가?
   - 새로운 기능 추가가 쉬운가?
   - 기존 코드 수정 없이 확장 가능한가?
   
4. 재사용성이 있는가?
   - 공통 로직이 잘 추출되었는가?
   - 유틸리티 클래스가 적절한가?

프로젝트 구조 다이어그램을 mermaid 형식으로 그려주고,
개선이 필요한 부분을 구체적으로 제안해줘.

Step 3: 문서화 검토

1
2
3
4
5
6
7
8
9
10
11
12
13
14

다음 문서들이 코드와 일치하는지 확인해줘:

1. API 명세서
2. 데이터베이스 스키마 문서
3. 컴포넌트 문서

불일치하는 부분을 찾아서:
- 현재 코드 기준으로 문서를 업데이트하거나
- 문서 기준으로 코드를 수정하도록 제안해줘

또한 누락된 문서가 있다면 생성해줘:
- 주요 함수/메서드의 JSDoc/JavaDoc
- 복잡한 로직에 대한 주석
- 환경 설정 가이드

🔧 Phase 5: Debug (디버깅)

목적

실행 중 발생하는 문제를 빠르게 파악하고 해결합니다.

Claude Code 디버깅 전략

시나리오 1: 런타임 에러

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

다음 에러가 발생했어:

[에러 로그 전체 붙여넣기]

현재 상황:
- 종목 검색 API를 호출할 때 발생
- 특정 검색어("삼성전자")에서만 발생
- 다른 검색어는 정상 동작

분석해줘:
1. 에러 스택 트레이스 해석
2. 발생 원인 추정
3. 관련 코드 부분 확인
4. 해결 방법 제시 (여러 옵션)
5. 재발 방지 방법

시나리오 2: 로직 버그

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

예상과 다른 동작이 발생해:

예상: 관심종목 추가 시 목록에 즉시 표시
실제: 페이지 새로고침 해야 표시됨

관련 코드:
- frontend/src/components/WatchlistPanel.tsx
- frontend/src/hooks/useWatchlist.ts
- backend/src/main/java/com/stock/controller/WatchlistController.java

문제를 진단하고:
1. 데이터 흐름 추적
2. 상태 관리 확인
3. API 응답 검증
4. 원인 파악
5. 수정 코드 제시

시나리오 3: 성능 문제

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

주식 목록 페이지가 너무 느려:

증상:
- 초기 로딩 시 5초 이상 소요
- 스크롤 시 버벅임
- 크롬 DevTools Performance 프로파일 첨부

분석 요청:
1. 병목 지점 식별
2. 데이터베이스 쿼리 분석
3. 프론트엔드 렌더링 최적화
4. 네트워크 요청 최적화
5. 구체적인 개선 방안

성능 개선 전후 비교 가능한 코드로 수정해줘.

디버깅 베스트 프랙티스

1. 재현 가능한 환경 만들기

1
2
3
4
5
6
7
8

이 버그를 재현할 수 있는 최소한의 환경을 만들어줘:

버그: 특정 날짜 범위 조회 시 빈 결과 반환

필요한 것:
1. 샘플 데이터 SQL (버그가 재현되는 최소 데이터)
2. API 호출 예제 (curl 또는 JavaScript)
3. 예상 결과 vs 실제 결과

2. 단계별 디버깅

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

다음 순서로 디버깅을 도와줘:

1단계: 데이터베이스 레벨
   - 쿼리가 올바른 결과를 반환하는가?
   
2단계: 서비스 레벨
   - 데이터 변환이 올바른가?
   - 비즈니스 로직이 정확한가?
   
3단계: API 레벨
   - 응답 포맷이 올바른가?
   - HTTP 상태 코드가 적절한가?
   
4단계: 프론트엔드 레벨
   - API 응답을 올바르게 파싱하는가?
   - UI에 제대로 반영되는가?

각 단계별로 검증할 수 있는 코드를 작성해줘.

📦 Phase 6: Commit (커밋 및 배포)

목적

완성된 코드를 버전 관리 시스템에 저장하고 배포 준비를 합니다.

의미 있는 커밋 메시지 작성

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

다음 변경사항에 대한 커밋 메시지를 작성해줘:

변경 내용:
1. 주식 검색 API 추가
2. 검색 자동완성 기능 구현
3. 검색어 하이라이팅
4. 검색 히스토리 저장

컨벤션:
- Conventional Commits 스타일
- type(scope): subject 형식
- body에 상세 설명
- footer에 이슈 번호 또는 Breaking Changes

여러 개의 논리적 커밋으로 나누어 제시해줘.

Claude Code 응답 예시:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

feat(api): add stock search endpoint

- Add GET /api/stocks/search endpoint
- Support both stock name and code search
- Implement fuzzy matching with 70% threshold
- Add pagination support (default 20 items)

Related: #123

---

feat(frontend): implement search autocomplete

- Add SearchBar component with autocomplete
- Integrate with stock search API
- Show search results as dropdown
- Highlight matching text in results

Related: #123

---

feat(frontend): add search history

- Store recent searches in localStorage
- Display recent searches in dropdown
- Add clear history button
- Limit to 10 most recent searches

Related: #123

Pre-commit 체크리스트

커밋 전에 Claude Code로 최종 확인:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

커밋 전 최종 점검을 해줘:

1. 코드 품질
   - [ ] ESLint/SonarLint 경고 없음
   - [ ] 불필요한 console.log 제거됨
   - [ ] 주석 처리된 코드 제거됨
   
2. 테스트
   - [ ] 모든 단위 테스트 통과
   - [ ] 새로운 기능에 테스트 추가됨
   - [ ] 커버리지 80% 이상
   
3. 문서화
   - [ ] README 업데이트됨
   - [ ] API 문서 업데이트됨
   - [ ] CHANGELOG 작성됨
   
4. 보안
   - [ ] 환경 변수가 .env.example에 문서화됨
   - [ ] 민감 정보가 커밋에 포함되지 않음
   - [ ] 의존성 취약점 없음

각 항목을 검사하고 문제가 있으면 수정 방법을 제시해줘.

Pull Request 준비

1
2
3
4
5
6
7
8
9
10
11
12
13
14

다음 변경사항에 대한 Pull Request 설명을 작성해줘:

기능: 주식 검색 및 자동완성
커밋: [커밋 해시 또는 범위]

포함할 내용:
1. ## What (무엇을 변경했는가)
2. ## Why (왜 변경했는가)
3. ## How (어떻게 구현했는가)
4. ## Testing (어떻게 테스트했는가)
5. ## Screenshots (UI 변경사항 캡처)
6. ## Checklist (리뷰어 체크리스트)

GitHub PR 템플릿 형식으로 작성해줘.

Part 3: 통합 워크플로우 실전 예제

실전 예제: 주식 포트폴리오 관리 기능 추가

이제 6단계 워크플로우를 실제 기능 개발에 적용해봅시다.

🎯 Phase 1: Plan

첫 번째 프롬프트:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

주식 관심종목 시스템에 포트폴리오 관리 기능을 추가하려고 해.

사용자 요구사항:
- 사용자가 보유한 주식을 기록할 수 있어야 함
- 매수 날짜, 수량, 매수가를 입력
- 현재가 기준으로 수익률 자동 계산
- 포트폴리오 전체 평가액 표시
- 종목별 비중 표시

이 기능에 대한 PRD를 작성해줘:
1. User Stories (우선순위 포함)
2. Functional Requirements
3. Non-Functional Requirements
4. UI/UX 고려사항
5. 데이터 모델링

두 번째 프롬프트:

1
2
3
4
5
6
7
8

위 PRD를 바탕으로 TRD를 작성해줘:

포함할 내용:
1. 데이터베이스 스키마 (ERD)
2. API 엔드포인트 설계
3. 프론트엔드 컴포넌트 구조
4. 주요 알고리즘 (수익률 계산)
5. 기술적 제약사항 및 해결방안

🔍 Phase 2: Validation

검증 프롬프트:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

[새 대화]

다음은 포트폴리오 관리 기능의 계획서야:

[PRD 붙여넣기]
[TRD 붙여넣기]

다음 관점에서 검토하고 개선사항을 제시해줘:

1. 데이터 정합성
   - 매수/매도 기록이 정확히 추적되는가?
   - 주식 분할/배당 이벤트 처리는?
   
2. 성능
   - 수익률 계산을 매번 할 필요가 있는가?
   - 캐싱 전략은 없는가?
   
3. 사용자 경험
   - 입력 폼이 직관적인가?
   - 에러 메시지가 도움이 되는가?
   
4. 확장성
   - 다중 포트폴리오 지원 가능한가?
   - 다른 자산(채권, 펀드) 추가 가능한가?

🏗️ Phase 3: Build

단계별 구현:

1
2
3
4
5
6
7
8
9
10
11

1단계: 데이터베이스 먼저 구현해줘

CREATE TABLE portfolio (
  ...
)

위 스키마를 바탕으로:
- MyBatis Mapper 인터페이스
- Mapper XML
- DTO 클래스
생성해줘

1
2
3
4
5
6
7
8
9
10

2단계: 백엔드 API 구현

포트폴리오 CRUD API:
POST   /api/portfolio/stocks      - 종목 추가
GET    /api/portfolio/stocks      - 내 포트폴리오 조회
PUT    /api/portfolio/stocks/{id} - 보유 수량 수정
DELETE /api/portfolio/stocks/{id} - 종목 삭제
GET    /api/portfolio/summary     - 포트폴리오 요약

각 API의 Controller, Service, Repository 구현해줘

1
2
3
4
5
6
7
8
9

3단계: 프론트엔드 UI

다음 컴포넌트 구현:
1. PortfolioTable - 보유 종목 테이블
2. AddStockForm - 종목 추가 폼
3. PortfolioSummary - 포트폴리오 요약 카드
4. ProfitChart - 수익률 차트 (Recharts)

TypeScript + React Hooks로 작성해줘

🔬 Phase 4: Review

1
2
3
4
5
6
7
8
9
10
11
12
13

구현된 코드를 리뷰해줘:

특히 다음 파일들을 집중적으로:
- PortfolioService.java (수익률 계산 로직)
- PortfolioTable.tsx (테이블 렌더링 성능)
- portfolio.mapper.xml (복잡한 조인 쿼리)

리뷰 기준:
1. 버그 가능성
2. 성능 이슈
3. 보안 취약점
4. 코드 가독성
5. 테스트 가능성

🔧 Phase 5: Debug

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

테스트 중 다음 문제 발견:

문제: 수익률이 음수로 표시되어야 하는데 양수로 나옴
예시:
- 매수가: 50,000원
- 현재가: 45,000원
- 예상: -10%
- 실제: +10%

관련 코드:
PortfolioService.calculateProfitRate()

디버깅해줘:
1. 계산 로직 검증
2. 테스트 케이스 작성
3. 수정된 코드 제공

📦 Phase 6: Commit

1
2
3
4
5
6
7
8
9
10
11

포트폴리오 기능 구현 완료.

변경된 파일:
- backend: 10개 파일
- frontend: 8개 파일
- database: 2개 마이그레이션 파일

의미 있는 단위로 커밋을 나누고
각 커밋 메시지를 작성해줘.

그리고 PR description도 작성해줘.

Part 4: 고급 팁과 베스트 프랙티스

팁 1: 컨텍스트 유지하기

문제: Claude Code는 대화가 길어지면 초기 컨텍스트를 잃을 수 있습니다.

해결책:

1
2
3
4
5
6
7
8
9

현재 작업 중인 기능에 대한 context를 요약해줘:

1. 목표: 무엇을 만들고 있는가
2. 현재 상태: 어디까지 완료되었는가
3. 다음 단계: 무엇을 해야 하는가
4. 주요 결정사항: 어떤 기술적 선택을 했는가

이 요약을 다음 대화 시작 시 참고할 수 있게
마크다운 형식으로 정리해줘.

팁 2: 반복 작업 템플릿화

비슷한 작업을 반복할 때는 템플릿을 만드세요:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

앞으로 새로운 API를 추가할 때마다 사용할
"API 추가 체크리스트"를 만들어줘:

포함할 항목:
1. 데이터베이스 마이그레이션
2. Mapper 작성
3. DTO 정의
4. Service 로직
5. Controller 엔드포인트
6. 단위 테스트
7. API 문서
8. 프론트엔드 API 클라이언트

각 항목에 대한 상세 가이드와
코드 스니펫 템플릿을 포함해줘.

팁 3: 에러 로그 최대한 활용

1
2
3
4
5
6
7
8
9
10
11
12
13

다음 에러 로그 파일을 분석해줘:

[전체 로그 붙여넣기]

다음 정보를 추출해줘:
1. 에러 발생 시간과 빈도
2. 주요 에러 타입별 분류
3. 각 에러의 원인 추정
4. 우선순위 (빈도 x 심각도)
5. 수정 방안

표 형식으로 정리하고,
가장 먼저 수정해야 할 3가지를 추천해줘.

팁 4: 코드 품질 메트릭 추적

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

현재 프로젝트의 코드 품질을 평가해줘:

메트릭:
1. 코드 복잡도 (Cyclomatic Complexity)
2. 코드 중복률
3. 테스트 커버리지
4. 문서화 비율
5. 기술 부채 추정

각 메트릭에 대해:
- 현재 값
- 업계 표준
- 개선 권장사항
제시해줘.

그리고 품질 개선 로드맵을 만들어줘.

Part 5: 팀 협업에서의 활용

여러 개발자가 함께 바이브 코딩하기

상황 1: 코드 리뷰 자동화

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

다음 PR을 리뷰해줘:

PR #42: Add portfolio management feature

Files changed: 18
+ 1,234 lines
- 234 lines

[git diff 붙여넣기]

리뷰 기준:
1. 코딩 컨벤션 준수
2. 로직 정확성
3. 테스트 충분성
4. 성능 이슈
5. 보안 고려사항

GitHub PR comment 형식으로
각 파일별 코멘트를 작성해줘.

상황 2: 팀 지식 공유

1
2
3
4
5
6
7
8
9
10
11
12
13
14

이번 sprint에서 구현한
"포트폴리오 관리 기능"에 대한
팀 공유 문서를 작성해줘:

대상: 팀 전체 개발자

포함할 내용:
1. 기능 개요 (비개발자도 이해 가능하게)
2. 기술적 아키텍처
3. 주요 의사결정과 근거
4. 배운 점과 개선 사항
5. 다른 팀원이 알아야 할 것

Confluence 형식으로 작성해줘.

상황 3: 온보딩 가이드

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

신규 팀원을 위한
"프로젝트 온보딩 가이드"를 만들어줘:

Day 1: 개발 환경 설정
Day 2: 프로젝트 구조 이해
Day 3: 첫 번째 작은 기능 구현
Day 4-5: 실제 기능 개발 참여

각 날짜별로:
- 학습 목표
- 실습 과제
- 참고 자료
- 체크리스트

마크다운 형식으로 작성해줘.

Part 6: 트러블슈팅 가이드

자주 발생하는 문제와 해결법

문제 1: Claude Code가 컨텍스트를 잃어버림

증상:

  • 이전에 했던 설명을 다시 요구
  • 일관성 없는 코드 생성
  • 프로젝트 구조를 잊어버림

해결책:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

[대화 시작 시]

현재 프로젝트 정보:

프로젝트명: stock-portfolio-system
기술 스택:
- Backend: Spring Boot 3.2 + MyBatis
- Frontend: React 18 + TypeScript
- Database: PostgreSQL 15

현재 작업:
- 포트폴리오 관리 기능 구현 중
- Phase 3 (Build) 단계
- 백엔드 API 70% 완료

주요 컨벤션:
- REST API: /api/{resource}/{action}
- 컴포넌트: PascalCase
- 변수: camelCase

이 컨텍스트를 유지하면서 작업을 계속해줘.

문제 2: 생성된 코드가 동작하지 않음

해결 프로세스:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

생성된 코드가 동작하지 않아.

1단계: 문제 재현
   - 어떤 동작이 실패하는가?
   - 에러 메시지는?
   - 재현 가능한 최소 예제

2단계: 원인 분석
   - 로그 확인
   - 디버거 사용
   - 단계별 추적

3단계: 수정 및 검증
   - 수정된 코드
   - 테스트 케이스
   - 재발 방지책

위 프로세스로 함께 디버깅해줘.

문제 3: UI/UX가 기대와 다름

반복적 개선:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

포트폴리오 테이블 UI가 마음에 안 들어.

현재 상태: [스크린샷 또는 설명]

원하는 모습:
- 더 넓은 여백
- 수익률에 색상 (빨강/초록)
- 반응형 디자인
- 호버 효과

참고 디자인:
- Robinhood 앱의 포트폴리오 화면

위를 참고해서 UI를 개선해줘.
단, 기존 데이터 구조는 유지하면서.

결론: 효과적인 바이브 코딩을 위한 핵심 원칙

원칙 1: 계획에 시간을 투자하라

코드 작성은 AI가 빠르게 하지만, 무엇을 만들지 결정하는 것은 여전히 인간의 몫입니다.

  • PRD와 TRD를 꼼꼼히 작성하세요
  • Use case를 명확히 정의하세요
  • 기술적 제약사항을 미리 파악하세요

원칙 2: 검증을 생략하지 마라

AI가 생성한 코드를 맹목적으로 신뢰하지 마세요.

  • 다른 AI로 검증하세요
  • 보안 취약점을 확인하세요
  • 성능을 테스트하세요

원칙 3: 단계별로 진행하라

한 번에 모든 것을 만들려고 하지 마세요.

  • 작은 단위로 나누어 구현하세요
  • 각 단계마다 테스트하세요
  • 문제를 조기에 발견하세요

원칙 4: 문서화를 자동화하라

코드와 문서를 함께 생성하세요.

  • API 명세를 자동 생성하세요
  • 주석을 자동 작성하세요
  • README를 지속적으로 업데이트하세요

원칙 5: 팀과 공유하라

혼자만의 바이브 코딩은 제한적입니다.

  • 프롬프트 패턴을 공유하세요
  • 베스트 프랙티스를 문서화하세요
  • 실패 사례도 공유하세요

다음 단계

이 가이드를 마스터했다면:

  1. 실전 프로젝트에 적용
    • 소규모 기능부터 시작
    • 6단계 워크플로우 적용
    • 결과 측정 및 개선
  2. 팀에 도입
    • 파일럿 프로젝트 시작
    • 팀원 교육
    • 가이드라인 수립
  3. 고급 기법 학습
    • Multi-Agent 협업
    • 커스텀 프롬프트 개발
    • AI 도구 통합

문서 작성일: 2025-12-27 작성자: Claude Code 바이브 코딩 가이드 버전: 1.0 라이선스: CC BY-SA 4.0

부록: 프롬프트 템플릿 모음

계획 수립 템플릿

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# PRD 작성 프롬프트

다음 기능에 대한 PRD를 작성해줘:

## 기능 개요
[간단한 설명]

## 사용자 요구사항
- [사용자 관점 요구사항 1]
- [사용자 관점 요구사항 2]

## 기술 제약사항
- [기술 스택]
- [성능 요구사항]
- [보안 요구사항]

## 산출물
1. User Stories (우선순위 포함)
2. Functional Requirements
3. Non-Functional Requirements
4. UI/UX Mockup (텍스트 설명)
5. Success Metrics

코드 리뷰 템플릿

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 코드 리뷰 프롬프트

다음 코드를 리뷰해줘:

[코드 또는 파일 경로]

## 리뷰 기준
1. 코드 품질
   - 가독성
   - 유지보수성
   - 재사용성

2. 보안
   - 취약점 검사
   - 입력 검증
   - 인증/인가

3. 성능
   - 알고리즘 효율성
   - 리소스 사용

4. 테스트
   - 테스트 커버리지
   - Edge case 처리

## 산출물
- Severity별 이슈 리스트
- 개선 코드
- 테스트 케이스

디버깅 템플릿

1
2
3
4
5
6

# 디버깅 프롬프트

## 문제 상황
[문제 설명]

## 에러 메시지

[에러 로그 전체]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

## 재현 방법
1. [단계 1]
2. [단계 2]
3. [에러 발생]

## 예상 동작
[정상적인 동작]

## 실제 동작
[비정상적인 동작]

## 관련 코드
[파일 경로 또는 코드]

## 요청사항
1. 에러 원인 분석
2. 해결 방법 (여러 옵션)
3. 테스트 케이스
4. 재발 방지 방법

이 가이드가 여러분의 바이브 코딩 여정에 도움이 되길 바랍니다! 🚀

AI, Claude Code
AI Developer vibe-coding claude-code Guide Claude.write
이 기사는 저작권자의 CC BY 4.0 라이센스를 따릅니다.