Ch12. 바이브코딩 실전 패턴

탐색→계획→구현→커밋 워크플로, 검증 루프 닫기, 세션 시작 루틴, 다섯 가지 안티패턴, /effort·/loop·/branch·--worktree 가속 명령을 실전 관점에서 정리합니다

핵심 요약

공식 권장 워크플로는 탐색→계획→구현→커밋이며, 한 문장으로 설명되는 작은 작업만 계획 단계를 건너뜁니다.
Claude는 "끝난 것처럼 보이면" 멈추므로, 테스트·빌드 종료 코드·린터 같은 검증 수단을 줘 루프를 닫는 것이 핵심입니다.
대표 안티패턴은 kitchen sink 세션·컨텍스트 누적 방치·검증 없는 연속 진행·반복 교정·과도한 CLAUDE.md이며 대부분 /clear로 대응합니다.
/effort로 추론 강도를 조절하고(Fable 5·Opus 4.8 기본 high, max·ultracode는 세션 한정), ultrathink 키워드는 그 턴만 깊게 합니다.
/loop는 세션 범위 반복 검증, /branch는 대화 분기, --worktree는 격리 실험에 쓰며, 위험한 변경도 안전하게 시도할 수 있습니다.

바이브코딩(Vibe Coding)은 AI에게 의도를 전달하고 코드 생성을 맡기는 개발 방식입니다. 이 장에서는 Claude Code 환경의 실전 패턴을 정리합니다.

멀티세션 전략 매트릭스

상황	전략
독립적인 기능 2~3개	worktree별 병렬 세션
분석 후 구현	Plan 모드로 분석 → 실행 세션 분리
큰 리팩토링	분석 후 파트별 세션 분리
버그 수정 + 기능 개발	세션 분리 (컨텍스트 오염 방지)
반복적 단순 작업	슬래시 커맨드 + 헤드리스

공식 권장 워크플로: 탐색 → 계획 → 구현 → 커밋

Anthropic 공식 베스트 프랙티스는 research/planning과 implementation을 분리하라고 권장합니다. 바로 코딩에 들어가면 "엉뚱한 문제"를 풀 위험이 있습니다. Plan 모드에서 먼저 파일을 읽고 계획을 세운 뒤 모드를 빠져나와 구현하고, 마지막에 커밋·PR로 마무리하세요. 단, 한 문장으로 diff를 설명할 수 있을 만큼 범위가 명확한 작은 작업(오타 수정, 로그 추가, 변수명 변경 등)은 계획 단계를 건너뛰는 편이 낫습니다.

효과적인 프롬프팅

DO: 구체적 지시

✅ "src/auth/login.ts에서 JWT 토큰 만료 시
   리프레시 토큰으로 자동 갱신하는 로직을 추가해줘.
   현재 handleLogin 함수에 구현하고,
   실패 시 /login으로 리다이렉트."

DON'T: 모호한 지시

❌ "로그인을 개선해줘"
❌ "인증 쪽을 좀 고쳐줘"
❌ "더 좋게 만들어줘"

프롬프트 구조 템플릿

[무엇을] src/auth/login.ts의 JWT 갱신 로직
[어떻게] 토큰 만료 시 리프레시 토큰으로 자동 갱신
[제약] 기존 handleLogin 함수 내에 구현
[에러 처리] 실패 시 /login으로 리다이렉트

컨텍스트를 풍부하게 전달하는 방법

공식 문서는 프롬프트에 구체적인 컨텍스트를 함께 주라고 강조합니다.

@로 파일 참조: @src/utils/auth.js처럼 경로를 직접 가리키면 Claude가 해당 파일을 읽고 답합니다. 파일이 위치한 디렉터리·상위 디렉터리의 CLAUDE.md도 함께 컨텍스트에 추가됩니다.
이미지 붙여넣기: 스크린샷·디자인 목업을 드래그&드롭하거나 CLI에 Ctrl+V(macOS도 cmd+v가 아니라 Ctrl+V)로 붙여 넣습니다.
데이터 파이프: cat error.log | claude처럼 파일 내용을 직접 흘려보낼 수 있습니다.
기존 패턴 참조: "홈 페이지의 위젯 구현을 보고 같은 패턴으로 만들어줘"처럼 코드베이스의 예시를 지목합니다.

검증 루프 닫기

Claude가 스스로 검증할 수단을 줘라

공식 베스트 프랙티스의 핵심 원칙입니다. Claude는 "끝난 것처럼 보이면" 멈춥니다. 실행 가능한 검증 수단(테스트, 빌드 종료 코드, 린터, 출력 비교 스크립트, 스크린샷 비교)을 주면 사람이 일일이 확인하지 않아도 Claude가 통과할 때까지 직접 반복합니다.

검증을 거는 강도는 단계적으로 선택할 수 있습니다.

한 프롬프트 안에서: "구현 후 테스트를 돌리고 실패하면 고쳐줘"처럼 같은 메시지에 검증을 포함.
세션 전반에서: /goal 조건으로 설정 — 매 턴마다 별도 평가자가 재확인하고 조건이 충족될 때까지 작업을 계속합니다.
결정론적 게이트: Stop 훅으로 스크립트를 실행해 통과 전까지 턴 종료를 막습니다(연속 8회 차단 시 Claude Code가 훅을 무시하고 종료).
제2의 시각: /code-review 같은 검증 서브에이전트가 새 컨텍스트에서 diff만 보고 결과를 반박해 봅니다.

세션 시작 루틴

상태 확인

/usage   ← 플랜 사용량 확인
/cost    ← 토큰 사용량 확인

작업 범위 선언

"이번 세션에서는 사용자 프로필 API를 구현할 거야.
관련 파일: src/api/profile/, src/types/user.ts"

모델 선택

/model   ← 작업 복잡도에 맞는 모델 선택

/model은 v2.1.153부터 선택한 모델을 새 세션의 기본값으로 저장합니다(사용자 설정의 model 필드에 기록). 피커에서 Enter는 모델 전환과 기본값 저장을, s는 현재 세션에만 적용을 뜻합니다.

안티패턴

공식 문서가 정리한 대표적인 실패 패턴과 해결책입니다.

1. 하나의 세션에서 모든 것 (kitchen sink session)

❌ 세션 하나에서:
   → 버그 수정 → 새 기능 → 리팩토링 → 문서 → 테스트

✅ 작업별 세션 분리:
   → 세션1: 버그 수정
   → 세션2: 새 기능
   → 세션3: 테스트

해결: 무관한 작업 사이에는 /clear로 컨텍스트를 초기화합니다.

2. 컨텍스트 누적 방치

❌ 컨텍스트를 과도하게 누적

✅ 작업 경계에서 /clear 또는 /compact

Claude Code는 컨텍스트 한도에 근접하면 자동으로 압축(auto compaction) 합니다. 더 세밀하게 제어하려면 /compact <instructions>(예: /compact API 변경에 집중해)를 쓰고, 무관한 작업 사이에는 /clear로 아예 초기화하는 편이 좋습니다. 대화 일부만 압축하려면 Esc + Esc 또는 /rewind로 체크포인트를 선택해 "여기서부터/여기까지 요약"을 고를 수 있습니다.

3. 결과 검증 없이 연속 진행 (trust-then-verify gap)

❌ "A 만들어줘" → "B 만들어줘" → "C 만들어줘"

✅ "A 만들어줘" → 확인 → "B 만들어줘" → 확인

해결: 항상 검증 수단(테스트, 스크립트, 스크린샷)을 제공합니다. 검증할 수 없으면 배포하지 않습니다.

4. 반복 교정의 함정 (correcting over and over)

같은 문제를 두 번 넘게 교정했다면 컨텍스트가 실패한 접근들로 오염된 상태입니다.

해결: /clear로 초기화한 뒤, 배운 내용을 반영한 더 구체적인 프롬프트로 새로 시작합니다.

5. CLAUDE.md 없이 작업 / 과도한 CLAUDE.md

❌ 매번 같은 규칙을 반복 설명
❌ 너무 긴 CLAUDE.md (중요한 규칙이 묻혀 무시됨)

✅ CLAUDE.md에 규칙을 한 번 적고 세션마다 자동 로드
✅ "이 줄을 지우면 Claude가 실수할까?"를 기준으로 가지치기

CLAUDE.md는 매 대화 시작 시 로드되므로 널리 적용되는 내용만 넣어 간결하게 유지하세요. /init으로 초기 파일을 만든 뒤 다듬는 것이 좋습니다. 가끔만 필요한 도메인 지식·워크플로는 CLAUDE.md 대신 스킬로 분리하면 필요할 때만 로드됩니다. 홈 폴더(~/.claude/CLAUDE.md)·프로젝트 루트(./CLAUDE.md)·개인용(./CLAUDE.local.md, .gitignore 대상) 등에 배치할 수 있고, @path/to/import 문법으로 다른 파일을 가져올 수 있습니다.

바이브코딩 가속 명령

/effort — 추론 강도(비용·속도) 최적화

/effort 명령으로 모델 추론 강도(effort level) 를 조절해 비용과 속도를 최적화합니다. 인자 없이 실행하면 좌우 화살표로 고르는 인터랙티브 슬라이더가 열리고, 레벨 이름을 붙이면 곧바로 적용됩니다. /effort auto는 모델 기본값으로 되돌립니다. 적용은 현재 응답이 끝나기를 기다리지 않고 즉시 반영됩니다.

effort 레벨	용도
`low`	짧고 범위가 좁은 지연 민감 작업
`medium`	비용 민감 작업 (일부 지능 희생 감수)
`high`	토큰·지능 균형. Fable 5·Opus 4.8·Opus 4.6·Sonnet 4.6 기본값
`xhigh`	더 깊은 추론, 더 높은 토큰 소비. Fable 5·Opus 4.8·Opus 4.7에서 선택 가능
`max`	가장 깊은 추론. 토큰 제한 없음. 현재 세션에만 적용(오버싱킹 주의)
`ultracode`	xhigh 추론 + 자동 동적 워크플로 오케스트레이션. 현재 세션에만 적용

/effort low    ← 빠른 탐색
/effort high   ← 깊은 사고가 필요한 작업
/effort        ← 슬라이더 열기
/effort auto   ← 모델 기본값으로 복귀

레벨은 모델에 따라 다릅니다

지원 레벨은 모델별로 다릅니다. Fable 5·Opus 4.8·Opus 4.7은 low/medium/high/xhigh/max, Opus 4.6·Sonnet 4.6은 low/medium/high/max를 지원합니다. 지원하지 않는 레벨을 지정하면 해당 모델이 지원하는 가장 가까운 하위 레벨로 폴백됩니다(예: Opus 4.6에서 xhigh는 high로 실행). low/medium/high/xhigh는 세션 간 유지되지만 max·ultracode는 세션 한정입니다. 참고: 프롬프트 어디든 ultrathink 키워드를 넣으면 세션 설정을 바꾸지 않고 그 턴에만 더 깊은 추론을 요청할 수 있습니다.

/loop — 반복 검증 자동화

/loop 번들 스킬로 배포 모니터링과 반복 검증을 자동화합니다(v2.1.72 이상 필요). 세션이 열려 있는 동안 프롬프트를 주기적으로 다시 실행하며, 인터벌과 프롬프트는 둘 다 선택 사항입니다.

/loop 5m 배포가 끝났는지 확인하고 결과를 알려줘   ← 고정 크론 스케줄
/loop CI 통과 여부와 리뷰 코멘트를 확인해         ← Claude가 매번 간격을 동적으로 선택
/loop                                            ← 내장 유지보수 프롬프트(또는 loop.md)
/loop 20m /review-pr 1234                        ← 다른 커맨드를 반복 실행

인터벌 단위는 s(초)·m(분)·h(시간)·d(일)이며, 크론은 1분 단위라 초는 올림 처리됩니다.
/loop는 세션 범위입니다. 새 대화를 시작하면 사라지고, --resume·--continue로 (미만료 시) 복원됩니다.
반복 작업은 생성 7일 후 자동 만료됩니다. 대기 중에는 Esc로 중단합니다.
내장 프롬프트는 .claude/loop.md 또는 ~/.claude/loop.md로 커스터마이즈할 수 있습니다.

더 지속적인 스케줄링이 필요하면

세션이 닫혀도 돌아야 한다면 Routines(Anthropic 인프라), 데스크톱 예약 작업, GitHub Actions를 고려합니다.

/branch — 대안 탐색 (구 /fork)

/branch [name] 명령으로 현재 대화를 그 지점에서 분기해 다른 접근법을 시도합니다. 분기로 전환되고 원래 대화는 그대로 보존되므로, /resume으로 언제든 돌아갈 수 있습니다. /fork는 기본적으로 /branch의 별칭입니다.

/branch              ← 현재 대화를 분기하여 다른 접근법 시도
/branch try-redis    ← 이름을 붙여 분기

/fork의 동작 변화

환경 변수 CLAUDE_CODE_FORK_SUBAGENT가 설정되어 있으면 /fork는 더 이상 /branch의 별칭이 아니라 포크된 서브에이전트를 스폰합니다. 대화 분기를 원한다면 /branch를 쓰는 것이 명확합니다.

Voice mode (음성 받아쓰기) 활용

/voice 명령으로 음성을 프롬프트로 받아쓰기 할 수 있습니다(v2.1.69 이상 필요). 코드를 읽으면서 키보드에서 손을 떼지 않고 지시를 입력하니 빠른 반복 작업에 유용합니다. 음성은 Anthropic 서버로 전송돼 전사되므로 Claude.ai 계정 로그인이 필요하며, API 키·Bedrock·Vertex AI·Foundry를 쓸 때는 동작하지 않습니다.

/voice        ← 켜기/끄기 토글 (모드 유지)
/voice hold   ← Hold(누르고 말하기, push-to-talk) 모드 — 기본값
/voice tap    ← Tap(탭으로 시작·종료) 모드 (v2.1.116 이상)
/voice off    ← 끄기

20개 언어 STT 지원: 한국어(ko)·영어(en)·일본어(ja)·독일어(de)·프랑스어(fr)·스페인어(es) 등 총 20개 언어. 언어는 /config의 language 설정을 따르며, 미지정 시 영어로 폴백합니다.
Push-to-Talk 키 커스터마이즈: 받아쓰기 키는 Chat 컨텍스트의 voice:pushToTalk 액션에 바인딩되며 기본값은 Space입니다. ~/.claude/keybindings.json에서 meta+k 같은 조합키로 변경하면, hold 모드의 키-리피트 워밍업 없이 첫 키 입력에 바로 녹음이 시작되어 타이핑 간섭이 없습니다.
레포명·git 브랜치명이 인식 힌트로 자동 추가되고, regex·OAuth·JSON·localhost 같은 개발 용어에 대한 음성 인식 정확도가 튜닝되어 있습니다.
전사는 Claude 메시지·토큰을 소비하지 않으며 /usage 한도에도 포함되지 않습니다.

줄단위 응답 스트리밍 (v2.1.78)

응답 텍스트가 생성되는 대로 줄 단위로 스트리밍됩니다. 코드 생성 과정을 실시간으로 확인하며 빠르게 피드백할 수 있습니다.

`!` Bash 모드

프롬프트에서 ! 접두사를 붙이면 셸 명령을 직접 실행할 수 있습니다. Claude를 거치지 않고 빠르게 명령을 실행해야 할 때 유용합니다.

! git status    ← Claude를 거치지 않고 직접 실행
! yarn test     ← 빠른 테스트 확인

--worktree 플래그로 안전한 실험

--worktree(축약 -w) 플래그로 메인 작업에 영향 없이 격리된 git worktree에서 시도할 수 있습니다(v2.1.49). 이름을 붙이면 .claude/worktrees/<이름>/ 경로에 worktree-<이름> 브랜치로 만들어지고, 이름을 생략하면 bright-running-fox 같은 이름이 자동으로 붙습니다.

claude --worktree feature-auth   ← 격리된 worktree에서 실험
claude --worktree bugfix-123     ← 다른 터미널에서 두 번째 격리 세션
claude --worktree                ← 이름 자동 생성

worktree는 기본적으로 원격의 기본 브랜치(origin/HEAD)에서 분기하므로 깨끗한 트리에서 시작합니다. 별도 체크아웃이라 .env 같은 gitignore 대상 파일은 복사되지 않습니다. 프로젝트 루트에 .worktreeinclude 파일(.gitignore 문법)을 두면 지정한 파일을 새 worktree에 자동으로 복사합니다. 위험한 변경을 자유롭게 테스트한 뒤 결과만 선택적으로 병합하세요.

여러 세션 병렬 실행 방식 비교

worktree 외에도 데스크톱 앱(세션마다 worktree 자동 생성), Claude Code on the web(클라우드 VM), 에이전트 팀(자동 조율) 등으로 병렬 작업을 확장할 수 있습니다. 신선한 컨텍스트가 코드 리뷰 품질을 높이므로, 한 세션이 작성하고 다른 세션이 리뷰하는 Writer/Reviewer 패턴도 효과적입니다.

참고 문서

베스트 프랙티스(영어): https://code.claude.com/docs/en/best-practices
일반 워크플로(영어): https://code.claude.com/docs/en/common-workflows
Plan 모드 개요(영어): https://code.claude.com/docs/en/permission-modes
worktree 병렬 세션(영어): https://code.claude.com/docs/en/worktrees
effort 레벨·모델 설정(영어): https://code.claude.com/docs/en/model-config
음성 받아쓰기(영어): https://code.claude.com/docs/en/voice-dictation
/usage, /cost, /model, /compact 등 명령(한국어): https://code.claude.com/docs/ko/slash-commands