Claude Code 바이브 코딩 배포 전 5개 서브에이전트 20종 QA 및 일괄 수정 프롬프트

AI 코딩 어시스턴트를 활용해 빠르게 프로토타입이나 웹사이트를 구축하는 '바이브 코딩(vibe coding)'이 확산되면서, 빠른 개발 속도 뒤에 누락되기 쉬운 UI 결함과 모바일 깨짐 현상을 배포 전에 걸러내는 체계적인 품질 검수(QA) 기법이 주목받고 있습니다. AI 엔지니어 @polydao가 Claude Code(Opus 5.5) 환경에서 5개의 읽기 전용(read-only) 서브에이전트를 병렬로 띄워 20개 항목을 점검하고 단일 패스로 일괄 수정하는 실전 프롬프트를 공개했습니다.

이미지 출처: @polydao

복수의 AI 에이전트가 동시에 같은 소스코드를 수정하면 코드 충돌이나 중복 버그가 발생하기 쉽습니다. 이 워크플로우는 검수 단계에서는 읽기 전용 서브에이전트들이 파일 수정 없이 결함만 추출하게 하고, 최종 수정은 메인 세션이 한 번에 처리하도록 분리하여 안정성을 확보하는 것이 핵심입니다.

5개 영역 20가지 배포 전 필수 체크리스트

@polydao가 제시한 20개 검수 항목은 웹사이트 배포 직전 반드시 점검해야 할 5개 도메인으로 나뉩니다.

1. 디자인 일관성 (Design that holds together)

• DESIGN 파일 우선 정의: 사전에 DESIGN 명세 문서를 작성하고 모든 색상, 폰트 크기, 간격(spacing), 모서리 곡률(radius)을 이에 일치시킵니다.
• 팔레트와 타이포그래피 위계: 색상 팔레트를 절제되게 유지하고 폰트 크기 및 두께 위계를 명확히 구성합니다.
• 컴포넌트 시각 통일: 동일한 유형의 버튼, 카드, 입력창(input)은 동일한 룩앤필을 유지합니다.
• 시각적 강조와 여백 조절: 지나치게 밋밋한 페이지는 강조 요소를 추가하고, 과밀한 페이지는 불필요한 요소를 덜어냅니다.
• 명도 대비 가독성: 어두운 배경과 밝은 배경 모두에서 텍스트 가독성을 유지합니다.

2. 모바일 반응형 (Mobile)

• 가로 스크롤 및 화면 탈출 차단: 어떤 요소도 가로로 스크롤되거나 화면 밖으로 넘치지 않아야 합니다.
• 실제 모바일 메뉴 제공: 좁은 화면에서 동작하는 완성도 높은 모바일 내비게이션 메뉴를 구현합니다.
• 터치 영역 확보: 엄지손가락으로 쉽게 누를 수 있도록 버튼 크기를 충분히 확보합니다.
• 텍스트 확대 대응: 브라우저 텍스트 확대 설정 시에도 레이아웃이 깨지지 않고 유지되어야 합니다.

3. 모든 인터랙션 상태 (Every state)

• 3대 화면 상태 구현: 로딩(loading), 빈 화면(empty), 오류(error) 상태 각각에 전용 화면을 마련합니다.
• 버튼 피드백 상태: 모든 버튼에 호버(hover), 누름(pressed), 비활성화(disabled) 상태 스타일을 개별 지정합니다.
• 폼 유효성 검사 피드백: 폼 오류는 해당 필드 바로 옆에 표시하고, 제출 중(submitting), 성공(success), 실패(failure) 메시지를 명확히 출력합니다.
• 트랜지션 애니메이션: 모달(modal), 드롭다운(dropdown), 탭(tab) 전환 시 자연스러운 트랜지션을 적용합니다.

4. 실제 사용자 관점 검증 (Click it like a real user)

• 핵심 퍼널 완주: 회원가입(sign-up) 및 결제(checkout) 흐름을 처음부터 끝까지 직접 동작 검증합니다.
• 미동작 버튼 및 깨진 링크 추적: 동작하지 않는 버튼이나 잘못된 링크를 전수 색출합니다.
• 키보드 접근성: 마우스 없이 키보드 조작만으로 전체 사이트를 원활하게 이용할 수 있는지 확인합니다.

5. 출시 전 메타데이터 및 완성도 (Pre-launch)

• 명확한 한 줄 가치 제안: 홈 화면 첫 화면에서 서비스가 제공하는 가치를 한 줄로 명확하게 설명합니다.
• 단일 주요 CTA(Main Button): 각 페이지마다 가장 중요한 단 하나의 메인 행동 유도 버튼을 배치합니다.
• 필수 메타데이터 등록: 모든 페이지에 제목(title), 설명(description), 파비콘(favicon)을 지정합니다.
• 플레이스홀더 텍스트 전면 삭제: 개발 과정에서 임시로 넣어둔 'Lorem ipsum' 등 모든 플레이스홀더 문구를 삭제합니다.

추론 노력(Effort) 설정 기준: Medium 기본과 High 선택

프롬프트 작성 시 각 하위 에이전트의 추론 노력(Effort) 파라미터는 작업의 복잡도와 토큰 비용 효율을 고려해 차등 설정합니다.

• Anthropic 비용 가이드: 명확하게 범위가 한정된 일상적 코드 검수 및 단순 수정 작업에는 medium 노력이 가장 비용 효율적이며 권장되는 기본값입니다. 디자인 규약이나 모바일 메타데이터 점검 등 4개 서브에이전트는 medium 설정만으로도 충분한 품질을 보장합니다.
• Thariq의 벤치마크 테스트 결과: 추론 노력을 높이는(high) 설정은 복잡한 엣지케이스 탐색과 다단계 교차 검증에서 강력한 성능을 발휘합니다. 따라서 다단계 폼 처리, 결제 유효성 검사, 회원가입 예외 경로 등 복합적인 사용자 시나리오를 다루는 '실제 사용자(real user)' 검수 서브에이전트에 한해 high 노력을 지정하는 것이 가장 균형 잡힌 전략입니다.

Claude Code 실행 프롬프트 전문

Claude Code 세션에 전체 체크리스트 맥락을 제공한 뒤, 하단에 다음 실행 지시문을 입력하여 자동 검수 및 수정을 시작할 수 있습니다.

Run a pre-ship check on this repo.

You: main session, Opus 5.5, medium effort.
Spawn 5 read-only subagents, one per group:

design (medium) - DESIGN file, styles/globals.css, tailwind.config.ts, components/ui/
mobile (medium) - app/layout.tsx, components/nav/, every page at 375px
states (medium) - components/forms/, every loading, empty and error view
real user (high) - app/signup/, app/checkout/, every link and button
launch (medium) - app/page.tsx, page metadata, public/favicon.ico

Each subagent:
- checks only its group
- edits nothing
- returns issue, file:line, severity

Then:
1. merge all five lists into .claude/preship/issues.json, grouped by file, no duplicates
2. stop and show me the list - no edits until I confirm
3. after I confirm, fix everything yourself in one pass, so no two agents touch the same file
4. save before and after screenshots to .claude/preship/screens/

프롬프트 동작 단계

1. 서브에이전트 병렬 검수: 5개 서브에이전트가 각자 지정된 디렉토리와 파일만 검수하며, 소스코드를 수정하지 않고 결함 목록(이슈 내용, 파일:라인 번호, 심각도)만 추출합니다.
2. 이슈 목록 취합 및 중복 제거: 5개 에이전트의 결과를 파일별로 정리하고 중복을 제거하여 .claude/preship/issues.json에 저장합니다.
3. 사용자 승인 게이트: 분석된 결함 목록을 사용자에게 제시하고, 사용자의 명시적 확인이 있을 때까지 수정을 대기합니다.
4. 메인 세션 단일 패스 수정: 사용자가 승인하면 메인 Opus 5.5 세션이 모든 파일을 단일 패스로 수정하여 에이전트 간 파일 수정 충돌을 원천 차단합니다.
5. 스크린샷 증적 저장: 수정 전후 화면 스크린샷을 .claude/preship/screens/에 보관하여 시각적 검증을 완료합니다.

원문 출처

• Mr. Buzzoni (@polydao) X 포스트: Claude Code tip: before you ship a vibe-coded site, let Opus 5.5 send 5 subagents through these 20 checks