[Claude] bkit Vibecoding Kit 완벽 가이드: Claude Code PDCA 플러그인으로 AI 바이브코딩 품질 관리하기

 

안녕하세요!

재아군의 관찰인생입니다.

 

AI 코딩 도구를 사용하다 보면 한 가지 고민이 생깁니다. "AI가 작성한 코드, 정말 괜찮은 걸까?"

Cursor, Copilot, Claude Code 같은 AI 코딩 도구가 보편화되면서 바이브코딩(Vibecoding)이라는 새로운 개발 패러다임이 등장했습니다. 자연어로 지시하면 AI가 코드를 생성하는 방식이죠. 하지만 생산 속도만큼 품질 관리가 따라오지 못하면, 기술 부채가 눈덩이처럼 쌓이게 됩니다.

 

오늘 소개할 bkit(Vibecoding Kit)은 바로 이 문제를 해결하기 위해 만들어진 Claude Code 전용 PDCA 플러그인입니다. 설계 문서와 실제 구현 코드 사이의 갭을 자동으로 감지하고, 90% 이상의 일치율이 될 때까지 반복 개선하는 체계적인 품질 관리 시스템입니다.

 

 

 

1. bkit이란? — AI 바이브코딩의 품질 관리 프레임워크

 

핵심 정의

 

bkit(Vibecoding Kit)은 Claude Code 위에서 동작하는 PDCA(Plan-Do-Check-Act) 기반 개발 품질 관리 플러그인입니다.

14개의 전문 에이전트와 21개의 스킬을 통해 AI가 생성한 코드의 품질을 체계적으로 검증하고 개선합니다.

 

핵심 철학은 단순합니다. "설계 없는 구현은 없고, 검증 없는 완료는 없다."

 

구분	일반 AI 코딩	bkit 적용 AI 코딩
개발 흐름	프롬프트 → 코드 생성 → 끝	Plan → Design → Do → Check → Act → Report
품질 보증	개발자 수동 리뷰	Gap Detector 자동 검증 (90% 이상 필수)
설계 문서	선택 사항	필수 (Plan → Design 단계)
반복 개선	수동 피드백 루프	PDCA Iterator 자동 반복 (최대 5회)
프로젝트 레벨	구분 없음	Starter / Dynamic / Enterprise 3단계

 

등장 배경: 바이브코딩의 그림자

 

바이브코딩은 개발 속도를 혁신적으로 높여주었지만, 동시에 새로운 문제들을 만들어냈습니다.

 

1. 설계 없는 구현: "일단 만들어줘"로 시작하면 AI는 묻지 않고 코드를 생성합니다. 아키텍처 설계 없이 기능만 쌓이면 유지보수가 불가능한 스파게티 코드가 됩니다.
2. 검증 부재: AI가 "완료했습니다"라고 하면 정말 완료된 것일까요? 설계 의도와 실제 구현 사이에 미묘한 괴리가 생기는 경우가 빈번합니다.
3. 컨텍스트 유실: 대화 세션이 끝나면 이전에 논의했던 설계 결정, 제약 조건, 트레이드오프가 모두 사라집니다.
4. 품질 기준 부재: "이 정도면 됐나?"라는 주관적 판단에 의존하게 되고, 프로젝트마다 품질 편차가 커집니다.

 

bkit은 이 모든 문제를 PDCA 사이클이라는 검증된 품질 관리 방법론으로 해결합니다.

 

 

---

 

2. PDCA 사이클 — bkit의 핵심 워크플로우

 

bkit의 모든 기능 개발은 6단계 PDCA 사이클을 따릅니다. 각 단계는 명확한 산출물과 완료 기준이 있으며, /pdca 명령어 하나로 전체 흐름을 제어합니다.

 

Phase 1: Plan — 요구사항 정의

 

# 새 기능의 PDCA 사이클 시작
/pdca plan my-new-feature

# 생성되는 문서: docs/01-plan/features/my-new-feature.plan.md
# 내용: 기능 설명, 목표, 제약 조건, 성공 기준

 

Product Manager 에이전트가 요구사항을 분석하고, 기능 명세서를 docs/01-plan/ 디렉토리에 생성합니다. 이 단계에서 스코프를 명확히 정의하지 않으면 이후 모든 단계가 흔들립니다.

 

Phase 2: Design — 아키텍처 설계

 

# 설계 문서 생성
/pdca design my-new-feature

# 생성되는 문서: docs/02-design/features/my-new-feature.design.md
# 내용: 파일 구조, 함수 시그니처, 데이터 흐름, API 스펙

 

CTO Lead 에이전트와 Frontend/Backend Architect가 협력하여 구체적인 기술 설계를 수행합니다. 이 문서가 이후 Gap Analysis의 기준선(baseline)이 됩니다.

 

Phase 3: Do — 구현

 

# 구현 시작
/pdca do my-new-feature

# Design 문서를 참조하며 실제 코드 구현
# 에이전트가 설계 문서의 파일 구조, 함수 시그니처를 따라 코드 생성

 

Phase 4: Check — Gap Analysis (핵심!)

 

# 설계 vs 구현 갭 분석
/pdca analyze my-new-feature

# 생성되는 문서: docs/03-analysis/my-new-feature.analysis.md
# 결과 예시:
# ✅ MATCH  (32개) — 설계대로 구현됨
# ⚠️ PARTIAL (3개) — 부분적으로 구현됨
# ❌ MISSING (1개) — 미구현
# 📊 Match Rate: 90.3%

 

Gap Detector 에이전트가 설계 문서의 모든 항목(40~100개)을 하나씩 실제 코드와 대조합니다. 각 항목에 MATCH(1.0), PARTIAL(0.5), MISSING(0.0) 점수를 부여하고, 전체 일치율을 산출합니다.

 

90% 룰: 일치율이 90% 미만이면 다음 단계로 진행할 수 없습니다. PDCA Iterator가 자동으로 부족한 부분을 수정하고, 다시 Gap Analysis를 수행합니다. 최대 5회 반복합니다.

 

Phase 5: Act — 자동 반복 개선

 

# Match Rate < 90%일 때 자동 개선
/pdca iterate my-new-feature

# Iteration 1: 85.2% → PARTIAL/MISSING 항목 수정 → 재분석
# Iteration 2: 92.1% → 90% 초과! 완료
# → 자동으로 Report 단계로 진행

 

Phase 6: Report — 완료 보고서

 

# 완료 보고서 생성
/pdca report my-new-feature

# Plan → Design → Do → Check → Act 전 과정 요약
# 최종 Match Rate, 반복 횟수, 주요 변경사항 기록

 

 

 

---

 

3. 에이전트 시스템 — 14개 전문가 팀이 협업하는 구조

 

bkit의 가장 강력한 특징 중 하나는 에이전트 팀(Agent Teams) 시스템입니다. CTO Lead 에이전트가 전체를 조율하고, 각 전문 에이전트가 자신의 역할을 수행합니다.

 

핵심 에이전트 구성

 

에이전트	역할	트리거 키워드
CTO Lead	전체 PDCA 워크플로우 조율, 기술 방향 결정	team, project lead, architecture
Gap Detector	설계-구현 간 갭 분석, Match Rate 산출	verify, 검증, 확인
PDCA Iterator	Match Rate < 90% 시 자동 반복 개선	iterate, auto-fix, 개선해줘
Code Analyzer	코드 품질, 보안, 성능 분석	analyze, 분석, code review
Product Manager	요구사항 분석, 기능 명세서 작성	requirements, 요구사항
Frontend Architect	UI/UX 설계, React/Next.js 아키텍처	frontend, UI, component
Backend Expert	인증, DB, API 설계 (bkend.ai BaaS)	login, database, API
Security Architect	OWASP Top 10 검증, 취약점 분석	security, 보안, vulnerability
QA Strategist	테스트 전략 수립, 품질 메트릭 정의	test strategy, QA plan
Infra Architect	AWS, Kubernetes, Terraform 인프라	AWS, k8s, CI/CD
Report Generator	PDCA 완료 보고서 자동 생성	report, 보고서, 진행 상황

 

에이전트들은 자동 트리거 방식으로 동작합니다. 사용자가 "검증해줘"라고 말하면 Gap Detector가, "보안 괜찮아?"라고 말하면 Security Architect가 자동으로 활성화됩니다. 8개 언어(한국어, 영어, 일본어, 중국어, 스페인어, 프랑스어, 독일어, 이탈리아어)를 지원합니다.

 

오케스트레이션 패턴

 

CTO Lead는 상황에 따라 다양한 패턴으로 에이전트를 조율합니다.

 

• Leader → Leader: CTO가 직접 순차적으로 에이전트에게 지시
• Swarm: 여러 에이전트가 병렬로 독립 작업 수행 (예: 보안 검사 + 코드 분석 동시 실행)
• Council: 여러 에이전트의 의견을 종합하여 최종 결정

 

 

---

 

4. 스킬 시스템 & 9단계 개발 파이프라인

 

에이전트가 "누가 할 것인가"를 결정한다면, 스킬은 "어떻게 할 것인가"를 정의합니다. bkit은 21개의 스킬을 제공하며, 이는 크게 3가지 카테고리로 나뉩니다.

 

PDCA 관리 스킬

 

# PDCA 전체 흐름 제어
/pdca plan {feature}      # 요구사항 문서 생성
/pdca design {feature}    # 설계 문서 생성
/pdca do {feature}        # 구현 시작
/pdca analyze {feature}   # Gap 분석
/pdca iterate {feature}   # 자동 반복 개선
/pdca report {feature}    # 완료 보고서
/pdca status              # 현재 진행 상황
/pdca next                # 다음 단계 안내

 

9단계 개발 파이프라인 스킬

 

bkit은 프로젝트를 Starter / Dynamic / Enterprise 3단계로 분류하고, 각 레벨에 맞는 9단계 파이프라인을 제공합니다.

 

Phase	단계	스킬	설명
1	Schema	/phase-1-schema	용어 정의, 데이터 구조 설계
2	Convention	/phase-2-convention	코딩 규칙, 네이밍 컨벤션
3	Mockup	/phase-3-mockup	UI/UX 모커 생성
4	API	/phase-4-api	백엔드 API 설계 및 구현
5	Design System	/phase-5-design-system	컴포넌트 라이브러리 구축
6	UI Integration	/phase-6-ui-integration	실제 UI 구현 및 API 연동
7	SEO & Security	/phase-7-seo-security	SEO 최적화, 보안 강화
8	Review	/phase-8-review	전체 코드 리뷰, Gap 분석
9	Deployment	/phase-9-deployment	프로덕션 배포, CI/CD

 

프로젝트 레벨별 차이

 

• Starter: 정적 웹사이트, HTML/CSS 기본. 초보자 친화적 가이드 제공 (/starter)
• Dynamic: 풀스택 앱, 인증/DB 포함. bkend.ai BaaS 통합 (/dynamic)
• Enterprise: 마이크로서비스, Kubernetes, Terraform. CTO 레벨 아키텍처 (/enterprise)

 

---

 

5. Gap Detection 심층 분석 — bkit의 진짜 가치

 

bkit의 가장 핵심적인 가치는 Gap Detection에 있습니다. AI가 "다 만들었습니다"라고 했을 때, 정말 설계대로 구현되었는지를 객관적으로 검증하는 시스템입니다.

 

Match Rate 산출 방식

 

# Gap Analysis 점수 산출 공식
# 설계 문서의 각 항목(40~100개)을 검사

MATCH   = 1.0  # 설계대로 완벽하게 구현됨
PARTIAL = 0.5  # 구현되었으나 일부 누락 또는 차이 있음
MISSING = 0.0  # 구현되지 않음

Match Rate = (sum of all scores) / (total items) * 100

# 실제 예시 (blog-writer 프로젝트)
# observer-content-improvement: 95.1% (42개 항목 중 40 MATCH, 2 PARTIAL)
# yolo-thumbnail-variety: 98.2% (36개 항목 중 35 MATCH, 1 PARTIAL)
# blog-writer-refactor: 90.7% (54개 항목 중 49 MATCH, 3 PARTIAL, 2 MISSING)

 

자동 반복 개선 (Evaluator-Optimizer 패턴)

 

Match Rate가 90% 미만이면 PDCA Iterator가 자동으로 Generator-Evaluator 루프를 실행합니다.

 

1. Gap Detector가 PARTIAL/MISSING 항목 목록 제공
2. Iterator가 해당 항목을 코드에서 수정
3. Gap Detector가 재분석 수행
4. 90% 이상이면 완료, 미만이면 2번으로 돌아감
5. 최대 5회 반복 후 강제 종료 (무한 루프 방지)

 

왜 90%인가? 100%를 목표로 하면 미세한 구현 차이(변수명 스타일, 공백 등)로 인해 무의미한 반복이 발생합니다. 90%는 "설계 의도가 충실히 반영됨"을 의미하는 실용적 기준선입니다.

 

---

 

6. 실무 활용 가이드 — 5분 만에 시작하기

 

설치 및 초기 설정

 

# 1. Claude Code가 설치되어 있어야 합니다
npm install -g @anthropic-ai/claude-code

# 2. 프로젝트 디렉토리에서 Claude Code 실행
cd my-project
claude

# 3. bkit 초기화 — 자동으로 .bkit/ 디렉토리와 에이전트 설정 생성
# Claude Code 대화에서:
> bkit 설정해줘

# 또는 직접 설치
> /bkit

 

첫 번째 PDCA 사이클 실행

 

# Step 1: 새 기능 계획 수립
> /pdca plan user-authentication

# Step 2: 설계 문서 생성
> /pdca design user-authentication

# Step 3: 구현 시작
> /pdca do user-authentication

# Step 4: 구현 완료 후 검증
> /pdca analyze user-authentication
# 결과: Match Rate 87.3% — 90% 미만!

# Step 5: 자동 개선
> /pdca iterate user-authentication
# Iteration 1: 87.3% → 93.1% — 통과!

# Step 6: 완료 보고서
> /pdca report user-authentication

 

유용한 명령어 모음

 

명령어	설명
/pdca status	모든 기능의 현재 PDCA 단계와 Match Rate 확인
/pdca next	현재 단계의 다음 액션 안내
/simplify	코드 리팩토링, 중복 제거, 품질 개선
/code-review	코드 품질 분석 및 개선 제안
/zero-script-qa	테스트 스크립트 없이 Docker 로그 기반 QA
/development-pipeline start	9단계 파이프라인 처음부터 시작

 

 

---

 

7. 경쟁 도구 비교 — bkit vs 다른 AI 코딩 품질 도구

 

비교 항목	bkit	Cursor Rules	GitHub Copilot Workspace
품질 검증	Gap Detection + 자동 반복	규칙 기반 프롬프트	Plan → Implement (검증 없음)
설계-구현 연결	설계 문서 ↔ 코드 자동 대조	없음	Plan만 존재, 검증 없음
에이전트 시스템	14개 전문 에이전트 + CTO 조율	단일 AI	단일 AI
프로젝트 레벨	Starter/Dynamic/Enterprise	구분 없음	구분 없음
다국어 지원	8개 언어 자동 감지	영어 중심	영어 중심
기반 플랫폼	Claude Code 전용	Cursor 전용	GitHub 전용

 

bkit의 가장 큰 차별점은 "설계와 구현의 자동 대조 검증"입니다. Cursor Rules는 코드 생성 규칙을 프롬프트로 지정하지만, 생성된 코드가 설계 의도대로인지 검증하는 메커니즘은 없습니다. GitHub Copilot Workspace는 Plan 단계가 있지만, Plan과 실제 코드 간의 일치도를 측정하는 기능은 제공하지 않습니다.

 

---

 

8. 마무리 — bkit으로 바이브코딩 품질 관리 시작하기

 

bkit Vibecoding Kit의 핵심을 한 문장으로 요약하면 이렇습니다.

 

"AI가 코드를 만드는 시대에, 설계와 구현의 갭을 자동으로 감지하고 메워주는 품질 관리 프레임워크"

 

바이브코딩이 "빠르게 만드는 기술"이라면, bkit은 "빠르게 만들면서도 품질을 유지하는 기술"입니다. PDCA 사이클, 14개 전문 에이전트, Gap Detection 시스템이 결합되어, AI 코딩의 가장 큰 약점인 "검증 부재"를 체계적으로 해결합니다.

 

특히 다음과 같은 분들에게 bkit을 강력히 추천합니다.

 

• Claude Code를 사용하면서 코드 품질이 일정하지 않다고 느끼는 개발자
• AI 코딩으로 빠르게 프로토타입을 만들지만, 프로덕션 수준의 품질이 필요한 팀
• 설계 문서를 작성하지만, 실제 구현과의 괴리를 수동으로 확인하는 데 지친 아키텍트
• 바이브코딩을 시작했지만, 체계적인 방법론이 필요하다고 느끼는 분

 

재아군의 관찰인생이었습니다. 다음 글에서 더 유익한 개발 이야기로 찾아뵙겠습니다!

 

---

 

본 글은 실제 bkit v1.5.8 기반으로 작성되었으며, 버전에 따라 일부 기능이 다를 수 있습니다.