사이드 프로젝트를 하다가 AI 한테 “로그인 기능 추가해줘” 라고 했더니, 멀쩡하게 돌아가던 인증 로직을 통째로 갈아엎어놨다.
바이브 코딩이라고 “느낌 가는 대로” 던지면 알아서 할 줄 알았는데 방향이 산으로 가서 오히려 손으로 짜는 것보다 시간이 더 걸렸다.
이게 요즘 다들 말하는 바이브 코딩의 함정이에요.
안드레 카파시가 처음 던진 개념이다. “구체적인 로직을 짜지 않고 직관대로 큰 그림만 던져도 AI 가 코드를 만들어준다” 는 게 핵심이라 편하다.
대신 고삐를 놓으면 훅 간다.
그런데 이건 md 파일 하나로 끝나는 얘기가 아니다.
AI 코딩 에이전트를 매일 굴리다 보면 md 파일을 쓰는 층위가 최소 넷으로 나뉜다. 이걸 뭉뚱그려 “가드레일 파일 하나” 로 퉁치면 오히려 관리가 안 된다.
네 단계를 설정 예시와 같이 정리해둔다.
레벨 1 — 규칙 파일 (정적 가드레일)
가장 기본이 되는 층위다. “이 프로젝트에서 절대 하지 말아야 할 것, 항상 지켜야 할 규칙” 을 미리 박아두는 파일입니다.
도구마다 이름과 위치가 다르다. Claude Code 는 프로젝트 루트의 CLAUDE.md(전역은 ~/.claude/CLAUDE.md), Cursor 는 .cursor/rules 디렉토리를 쓴다. 레거시 .cursorrules 는 이제 안 쓴다.
Claude Code 공식 문서도 “CLAUDE.md 는 단순 문서가 아니라 팀과 AI 에이전트 사이의 행동 계약” 이라고 못 박는다. 50~200줄 안으로 짧게 유지하고 자세한 내용은 별도 문서로 링크하라고 권장한다.
Cursor 는 관련 정리 글 을 보면 파일 확장자에 따라 특정 규칙만 자동 적용되는 “Auto Attached” 옵션까지 생겼다.
이 바닥은 반년 전 블로그 글이 이미 틀린 경우가 흔하다. .cursorrules 가 딱 그랬다.
내가 쓰는 규칙 파일은 이런 형태다.
# CLAUDE.md
## 절대 규칙
- 기존 테스트 코드는 물어보지 않고 삭제/수정하지 않는다
- DB 마이그레이션 파일은 새로 만들지, 기존 걸 고치지 않는다
- 인증/결제 관련 코드는 수정 전 반드시 계획부터 설명한다
## 코드 스타일
- 커밋 전엔 항상 `npm run lint` 통과 확인
- 새 라이브러리 추가 전엔 이유를 먼저 말해줄 것
레벨 2 — 메모리 파일 (세션 누적 기억)
규칙 파일이 “고정된 원칙” 이라면 메모리는 “대화하면서 쌓이는 사실” 이다.
둘을 헷갈리면 안 된다. 규칙 파일에 “이 API 는 v2 를 쓴다” 같은 프로젝트 사실을 계속 추가하면 파일이 산으로 간다. 반대로 매번 바뀌는 맥락을 규칙처럼 고정하면 오래된 정보가 규칙인 척 살아남는다.
메모리는 “지난주에 이 라이브러리를 도입하기로 했다”, “이 사람은 이런 방식을 선호한다” 처럼 시간이 지나며 갱신되는 정보를 담는 별도 층위다.
규칙은 세션 시작 시 항상 로드되는 계약서고, 메모리는 관련 있을 때 상기되는 기록입니다.
레벨 3 — 계획(Plan) 문서
이게 바이브 코딩 사고를 막는 데 제일 효과가 크다.
코드부터 짜게 시키지 말고 “이 작업을 어떻게 할 건지 계획을 md 로 먼저 써봐” 라고 시킨다.
범위가 큰 작업일수록 계획 문서를 먼저 리뷰하면 인증 로직을 통째로 갈아엎는 사고를 코드 짜기 전에 걸러낼 수 있다.
# Plan: 로그인 기능 추가
## 변경 범위
- 기존 인증 로직(AuthService)은 건드리지 않음
- 새 엔드포인트만 추가
## 단계
1. LoginController 추가
2. 기존 AuthService.authenticate() 재사용
3. 테스트 코드 추가
## 리스크
- 기존 세션 관리 방식과 충돌 여부 확인 필요
계획 단계에서 “기존 인증 로직을 건드리네” 싶으면 그 자리에서 잡는다.
실행하고 되돌리는 것보다 훨씬 싸다.
레벨 4 — 재사용 가능한 스킬/플레이북 문서
반복되는 작업(배포 체크리스트, 코드 리뷰 기준, PR 템플릿)을 매번 설명하지 않고 md 로 절차를 문서화해두면, AI 가 필요할 때 그 문서를 그대로 따라간다.
규칙 파일이 “하지 말아야 할 것” 위주라면 스킬 문서는 “이 작업은 이 순서대로” 하는 실행 절차다.
헷갈리면 안 되는 인접 개념이 하나 있다. MCP(Model Context Protocol)입니다.
MCP 는 AI 가 외부 도구나 데이터 소스(DB, API, 사내 시스템)에 표준화된 방식으로 연결되게 해주는 프로토콜이다. 규칙·메모리·스킬 md 는 AI 에게 “어떻게 행동할지” 를 알려주는 지침 문서다.
하나는 “무엇에 연결할지”, 다른 하나는 “어떻게 행동할지” 라 층위가 다르다. 섞어서 이해하면 아키텍처 설계할 때 꼬인다.
4단계 비교
바이브 코딩에서 흔한 실수
규칙을 욕심내서 다 욱여넣기. 100줄씩 채우면 AI 가 다 못 지킨다.
“이것도 적자, 저것도 적자” 하다가 파일이 길어져서 정작 핵심 규칙이 씹히는 걸 겪었다. “진짜 어기면 안 되는 것” 위주로 짧게 쓰고 세세한 취향은 뺀다.
규칙 파일을 방치하는 것. 코드베이스는 계속 바뀌는데 규칙 파일을 갱신하지 않으면 AI 가 옛날 아키텍처를 사실로 믿고 따라간다. 규칙 파일이 아예 없는 것보다 위험할 수 있다.
md 파일을 버전 관리 안 하는 것. git 에 커밋하지 않고 개인 로컬에만 두면 팀원마다 다른 규칙으로 AI 를 굴린다. 코드 리뷰하듯 규칙 파일도 PR 로 리뷰하고 같이 커밋한다.
정리
진짜 1회성 프로토타입 만들 때는 가드레일 없이 그냥 던져도 돼요.
근데 여러 세션에 걸쳐 계속 작업하거나 협업하는 프로젝트라면, 규칙(정적 원칙) → 메모리(누적 맥락) → 계획(실행 전 합의) → 스킬(반복 절차), 이 네 층위를 구분해서 갖춰두는 게 진짜 시간 아끼는 지름길이에요.
처음 설정할 때 몇 십 분 투자하면 나중에 몇 시간짜리 삽질을 막아줘요.
층위 구분 없이 파일 하나에 다 몰아넣고 있었다면 한번 나눠보길 권한다.