유지보수 가능한 바이브 코딩 방법 (Claude Code, 프론트엔드 기준)
AI에게 코드를 맡기더라도 나중에 고칠 수 있는 프로젝트로 만들려면 시작 방식과 작업 순서가 중요하다는 정리
핵심은 네 가지
바닥부터 만들지 말고 공식 예제에서 시작
코드보다 디자인을 먼저 확정
모델을 역할별로 나눠서 사용
규칙 파일과 자동 검증으로 AI가 매번 같은 방식으로 일하게 만들기
1단계: 프로젝트 뼈대 잡기
프레임워크 선택: React Router, Next.js, TanStack Start 중 하나
공식 예제에서 시작
프레임워크 GitHub 저장소의
examples/폴더에 "이 라이브러리 조합이면 이렇게 구성" 같은 예제가 모여 있음AI가 처음부터 구조를 짜게 하면 매번 제각각이 되기 쉬움. 공식 예제는 검증된 구조라 이후 유지보수가 쉬움
패키지 최신화: 예제가 오래된 버전일 수 있으니 최신 버전으로 올리고 필요한 라이브러리 추가
스킬 설치
스킬은 Claude Code에 "이 라이브러리는 이렇게 쓰는 게 맞다"를 알려주는 지침 묶음
skills.sh에서 쓰는 프레임워크와 라이브러리에 맞는 스킬을 추천받아 프로젝트에 설치
모델이 모르는 최신 API나 권장 패턴을 보완하는 역할
2단계: 디자인 먼저, 개발은 나중에
PRD 작성: 무엇을 만들지, 어떤 기능이 필요한지 적은 기획 문서
디자인을 아티팩트로 요청: PRD를 바탕으로 화면을 먼저 만들어 달라고 요청하면 브라우저에서 바로 볼 수 있는 페이지로 나옴
요소별 피드백: 아티팩트에서
c키를 누르면 버튼, 카드 같은 UI 요소를 골라 "여기 이렇게 바꿔줘" 식으로 코멘트를 남길 수 있음디자인 확정 후 개발 시작
개발 도중 디자인을 계속 바꾸면 코드가 누더기가 되기 쉬움
화면을 먼저 굳혀두면 코드 수정 범위가 줄어듦
모델을 역할별로 나누기
역할 | 모델 | 이유 |
|---|---|---|
어드바이저 (검토, 방향 제시) | Fable | 필수. 가장 깊게 판단해야 하는 자리 |
기본 작업 | Opus 5.5 | 대부분의 구현 담당 |
E2E 테스트 | Sonnet 5.5 | 반복적인 테스트 작성과 실행에 적합 |
E2E 테스트: 실제 사용자처럼 브라우저에서 클릭하고 입력하며 전체 흐름이 동작하는지 확인하는 테스트
3단계: 다듬기
기능 하나가 끝날 때마다 작게 정리하고, 큰 정리는 Fable 어드바이저에 맡김
SEO
코드 최적화
리팩토링
쓰지 않는 코드 제거
구현과 검토를 분리해서, 만든 모델이 아닌 다른 시선으로 정리하게 하는 방식
덧붙이면 좋은 것
규칙 파일 만들기
스킬은 라이브러리 일반 지식, 프로젝트 고유 결정은
CLAUDE.md(또는AGENTS.md)에 적음폴더 구조, 네이밍, 금지사항, 검증 명령을 짧게 정리
이게 없으면 세션마다 코드 스타일이 달라짐
검증 자동화
hooks로 파일 수정 후 포맷, 린트, 타입 검사가 자동으로 돌게 설정
AI가 에러를 보고 스스로 고치므로 사람이 매번 확인할 일이 줄어듦
큰 기능은 계획부터
plan mode로 구현 계획을 먼저 받고 승인한 뒤 진행
작게 맡기고 diff 확인
한 번에 하나의 기능만 요청
커밋 전에 변경 내용을 직접 보고,
/code-review로 한 번 더 확인
리팩토링은 수시로
마지막에 몰아서 하면 범위가 너무 커짐
기능 하나 끝날 때마다
/simplify등으로 정리
세션은 작업 단위로
대화가 길어지면 이전 맥락이 섞여 엉뚱한 수정이 나오기 쉬움
E2E 테스트는 핵심 흐름만
로그인, 결제처럼 깨지면 안 되는 흐름 위주
UI 세부까지 고정하면 디자인 바꿀 때마다 테스트가 깨짐