Ch.6

AI에게 원칙을 가르치는 법

CLAUDE.md, 프롬프트 전략, 코드 리뷰

CLAUDE.md — AI에게 아키텍처를 주입하는 법

바이브 코딩의 근본적인 문제가 있다. AI에게 “이 기능 만들어줘”라고 하면, AI는 그때그때 판단해서 코드를 짠다. 어떤 때는 상태를 이렇게 관리하고, 어떤 때는 저렇게 관리한다. 일관성이 없다. 프로젝트가 커질수록 스파게티 코드가 된다.

해결책은 AI가 매번 읽는 규칙 문서를 만드는 것이다. Claude Code에서는 CLAUDE.md, Cursor에서는 .cursorrules, Replit에서는 프로젝트 설명란에 작성한다.

📄 CLAUDE.md 핵심 구조

# CLAUDE.md

## 패키지 관리자
yarn을 사용한다. npm 사용 금지.

## 파일 규칙
- 한 파일 200줄 이하
- 컴포넌트는 단일 책임 원칙

## 상태 관리
- 글로벌 상태: Zustand 사용
- 로컬 상태: useState만 사용
- 컴포넌트에서 직접 fetch 금지

## 코드 스타일
- TypeScript 필수
- 모든 함수에 타입 명시
- any 타입 사용 금지

## 보안
- API 키는 환경 변수만 사용
- .env.local은 git에 올리지 않음

이 파일이 있으면 AI는 매 대화마다 이 규칙을 읽고 따른다. AI에게 매번 “TypeScript 써줘”, “200줄 넘기지 마”라고 반복할 필요가 없다. 한 번 잘 작성해두면 프로젝트 전체의 일관성이 유지된다.

효과적인 CLAUDE.md 작성 원칙

구체적으로 쓴다

✗ 코드를 잘 짜줘

✓ 한 파일 200줄 이하, any 타입 금지

이유를 적는다

✗ npm 사용 금지

✓ npm 사용 금지 (yarn.lock 사용 중, 섞으면 의존성 충돌)

예시를 넣는다

✗ 좋은 코드를 짜라

✓ 상태관리 예시: const useUserStore = create(...

점진적으로 추가한다

✗ 처음부터 100줄

✓ 버그 발견할 때마다 규칙 추가

💡 실전 팁: 버그에서 규칙이 태어난다

처음부터 완벽한 CLAUDE.md를 쓸 필요 없다. 바이브 코딩을 하다가 같은 버그가 두 번 나오면, 그때 규칙을 추가하면 된다. “이 패턴은 버그를 만드니까 하지 마” — 이런 규칙이 쌓이면서 CLAUDE.md가 점점 강력해진다.

프롬프트 전략 — AI에게 코딩을 시키는 기술

바이브 코딩의 품질은 프롬프트에 달려 있다. “로그인 기능 만들어줘”와 “Firebase Auth를 사용해서 Google OAuth 로그인을 구현해줘. 인증 상태는 AuthContext로 중앙 관리하고, 로그인 안 된 사용자는 /login으로 리다이렉트해줘”는 완전히 다른 결과를 만든다.

좋은 프롬프트의 5요소

1맥락 (Context)

현재 Next.js + Firebase 프로젝트이고, 상담 일지 관리 앱이다.

2구체적 요구 (Specific Ask)

상담 일지 CRUD를 만들어줘. 상담사만 자기 일지를 볼 수 있어야 해.

3제약 조건 (Constraints)

Zustand store를 통해서만 데이터에 접근해. 컴포넌트에서 직접 Firestore 호출하지 마.

4기술 스택 (Stack)

TypeScript 사용, Firestore 사용, 기존 AuthContext 연동해줘.

5기존 패턴 참조 (Reference)

users 컬렉션 CRUD를 참고해서 같은 패턴으로 만들어줘.

AI에게 코드 리뷰 시키기

AI가 코드를 짜는 것보다 더 유용한 활용법이 있다. AI에게 코드 리뷰를 시키는 것이다. AI가 짠 코드를 다른 AI(또는 같은 AI의 새 대화)에게 검토하게 하면, 보안 취약점, DRY 위반, 성능 문제를 찾아준다.

📋 코드 리뷰 프롬프트 템플릿

이 코드를 리뷰해줘. 다음 기준으로:
1. 보안 취약점 (API 키 노출, 인증 우회 등)
2. DRY 위반 (중복 코드)
3. SSOT 위반 (같은 데이터가 여러 곳)
4. 상태 관리 문제
5. 에러 핸들링 부족
6. 성능 문제 (불필요한 리렌더링 등)

각 이슈에 대해 위치, 문제, 해결 방안을 알려줘.

바이브 코딩의 최종 원칙

🎯 프로덕션 바이브 코딩 체크리스트

☐ CLAUDE.md (또는 .cursorrules)가 프로젝트에 있는가?

☐ TypeScript를 사용하고, any 타입이 없는가?

☐ 글로벌 상태가 중앙 store로 관리되는가?

☐ 같은 로직이 두 곳 이상에 중복되지 않는가? (DRY)

☐ API 키가 환경 변수로 관리되는가?

☐ Firebase 보안 규칙이 설정되어 있는가?

☐ yarn build가 에러 없이 성공하는가?

☐ 큰 변경 전에 git commit을 했는가?

코드를 짤 줄 몰라도 소프트웨어의 원칙은 알 수 있다. 이 원칙을 AI에게 가르치면, AI는 더 좋은 코드를 짠다. 바이브 코딩의 진짜 실력은 프롬프트에 있고, 프롬프트의 품질은 원칙에 대한 이해에서 나온다.

← Ch.5 보안과 배포 목차로 →