핵심 원칙 — 단 하나
작성된 계획을 내가 직접 검토하고 승인하기 전까지,
클로드한테 코드를 절대 쓰게 하지 마라.
기획과 코딩의 분리. 이것이 가장 중요한 원칙입니다.
❌ 일반적인 AI 코딩
프롬프트 → 코드 생성 → 에러 수정 → 반복
복잡해지는 순간 결과물이 무너짐
✅ 바이브 코딩 워크플로우
리서치 → 계획 → 주석 피드백 → 구현
삽질 제거, 아키텍처 주도권 유지, 토큰 절약
4단계 파이프라인
1단계: 리서치 — 코드베이스 깊이 읽기
모든 의미 있는 작업은 코드베이스를 깊이 읽는 것부터 시작합니다. 클로드에게 관련 부분을 철저하게 이해하게 하고, 발견한 내용을 반드시 별도 마크다운 파일(research.md)에 작성하게 합니다.
프롬프트 예시
이 폴더를 깊이 읽고, 어떻게 동작하는지 깊이 이해하고,
모든 세부 사항을 파악해라.
끝나면 research.md에 상세 보고서를 작성해라.💡 핵심 팁
"깊이", "매우 상세히", "세부 사항" 같은 단어가 중요합니다. 이런 단어 없이 시키면 클로드가 대충 훑어보고 함수 시그니처 수준에서 넘어갑니다. 인풋이 강력해야 아웃풋도 나옵니다.
⚠️ AI 코딩에서 가장 비싼 실패
문법 에러나 로직 버그가 아닙니다. 그 자체로는 멀쩡하게 돌아가는데 주변 시스템을 슬금슬금 망가뜨리는 구현이 진짜 무서운 겁니다.
- 기존 레이어를 완전히 무시하는 함수
- ORM 관계를 고려 안 한 마이그레이션
- 이미 있는 로직을 그대로 중복해서 만든 API 엔드포인트
→ 리서치 단계가 이런 걸 막아줍니다.
2단계: 계획 — 상세 구현 플랜 작성
리서치를 검토한 후, 별도의 plan.md 파일에 상세 구현 계획을 작성하게 합니다.
프롬프트 예시
새 기능 ETF 리밸런싱을 구현하는 상세 plan.md를 작성해라.
코드 스니펫도 포함.
변경 사항을 제안하기 전에 소스 파일을 읽고
실제 코드베이스를 기반으로 계획을 작성해.계획에 포함될 내용:
| 접근 방식 | 상세 설명 |
| 코드 스니펫 | 실제 변경 사항을 보여주는 코드 |
| 파일 경로 | 수정될 파일 목록 |
| 트레이드오프 | 고려 사항, 장단점 |
왜 내장 Plan Mode를 안 쓰나?
- MD 파일은 에디터에서 직접 편집 가능
- 원하는 곳에 인라인 메모를 달 수 있음
- 프로젝트 안에 실제 산출물로 남음
- 세션이 날아가도 문서는 살아남음
3단계: 주석 달기 — 검토 & 피드백 루프
여기가 진짜 핵심입니다. 클로드가 작성한 계획을 에디터에서 열고, 문서 안에 직접 메모를 추가합니다.
피드백 루프
클로드가 plan.md 작성
↓
내가 에디터에서 검토 + 주석/메모 추가
↓
"문서에 메모를 추가했어. 반영하고 업데이트해. 아직 구현하지 마."
↓
클로드가 계획 업데이트
↓
만족할 때까지 반복 (보통 1~수회)메모의 종류:
| 유형 | 메모 예시 |
|---|---|
| 잘못된 가정 수정 | "아니, 이건 PUT이 아니라 PATCH여야 해" |
| 접근 방식 거부 | "이 부분 제거해. 여기는 캐싱이 필요 없어" |
| 이유 설명 | "부모가 재시도 처리하니까 이 재시도 로직은 중복이야. 제거하고 그냥 실패하게 둬" |
| 방향 전환 | "이거 틀렸어. visibility 필드는 개별 아이템이 아니라 리스트 자체에 있어야 해. 스키마 재구조화해" |
| 간단한 확인 | "선택 사항 아님" (옵셔널 파라미터 옆에 두 단어) |
⚠️ 반드시 포함해야 하는 문장
"아직 구현하지 마."
이 문장 없으면 클로드가 "정도면 충분하지" 하고 혼자 판단해서 바로 코드를 짜기 시작합니다. 주도권을 주지 마세요.
4단계: 구현 — 멈추지 않고 전부 실행
계획이 완전히 준비되면 구현 명령을 내립니다. 이 시점에서 모든 결정은 이미 내려진 상태입니다.
표준 구현 프롬프트
전부 구현해라.
작업이나 단계를 완료하면 계획 문서에서 완료로 표시해라.
모든 작업과 단계가 완료될 때까지 멈추지 마라.
any 타입을 쓰지 마라.
지속적으로 타입 체크를 실행해서 새로운 문제를 만들지 마라.구현 단계에서의 역할 전환:
1~3단계
설계자 / 아키텍트
4단계
감독자
감독자 모드에서의 프롬프트는 극적으로 짧아집니다:
감독 프롬프트 예시
"리밸런스 이벤트 함수를 구현 안 했잖아."
"설정 페이지를 메인 앱에 만들었는데 어드민 앱에 있어야 해. 옮겨."
"더 넓게. 아직 잘려. 2픽셀 간격 있어."운전대 꼭 잡기 — 방향 조정 패턴
| 패턴 | 예시 |
|---|---|
| 좋은 건 취하고 나머진 버리기 | "첫 번째 방법은 async로 깔끔하게 가자. 네 번째랑 다섯 번째는 빼. 노력 대비 얻는게 없어." |
| 지금 안 할 건 과감하게 쳐내기 | "다운로드 기능은 계획에서 빼. 지금 안 만들 거야." |
| 건드리면 안 되는 선 긋기 | "이 세 함수의 시그니처는 절대 바꾸면 안 돼." |
| 기술 선택은 내가 하기 | "그 모델 말고 이 모델 써." / "직접 만들지 말고 라이브러리에 이미 있는 메서드 갖다 써." |
잘못된 방향일 때 — Git 리셋
잘못된 방향이면 패치하지 말고 되돌려라
"전부 이전으로 되돌려.
이제 목록 뷰를 더 심플하게 만드는 것만. 그것 외엔 아무것도 하지 마."Git reset/revert + 범위 좁히기가 점진적 수정보다 거의 항상 더 좋은 결과를 만듭니다.
하나의 긴 세션
리서치, 기획, 구현을 별도 세션으로 나누지 않습니다. 하나의 긴 세션 안에서 쭉 이어갑니다.
- 구현 시점에 클로드는 이미 리서치하고 계획 짜고 주석 반영하면서 이해를 쌓아온 상태
- 컨텍스트 윈도우가 꽉 차면 Auto Compaction이 맥락을 유지
- 결정적으로 plan.md는 영구적인 파일 — 압축이 되든 원본이 살아남음
전체 요약
| 리서치 | 무지한 변경을 막아줌 |
| 계획 | 잘못된 변경을 막아줌 |
| 주석 달기 | 내 판단을 주입함 |
| 구현 | 모든 결정이 끝난 뒤 방해 없이 실행 |
핵심
클로드한테 코드를 잘 쓰게 만드는게 아니라,
코드를 쓰기 전에 뭘 써야 하는지를 확실하게 만드는 것.
그게 전부입니다.
📎 참고 링크