AI는 왜 '눈치 없는 신입'처럼 구는가
바이브 코딩(코드를 직접 쓰지 않고 AI에게 시켜서 소프트웨어를 만드는 방식)을 처음 하면, AI가 실력은 뛰어난데 우리 사정을 몰라 엉뚱하게 일하는 걸 자주 겪는다. 안 시킨 기능을 얹고, 한 곳만 고치라니 옆까지 건드리고, '다 됐어요'라는데 정작 눌러보면 안 된다.
AI가 모자라서가 아니다. 상대(나)가 뭘 원하는지, 우리 프로젝트가 어떤지 모르기 때문이다. 실력 좋은 신입이 첫 출근날 회사 사정을 모르는 것과 똑같다. 그래서 필요한 게 몇 장의 '메모'다 — 신입 책상에 붙여두면 매번 다시 설명하지 않아도 되는 지침.
그 메모를 어디에 붙이나 — 하네스
이 메모를 붙이는 곳이 CLAUDE.md(또는 AGENTS.md)라는 파일이다. 프로젝트 폴더 맨 위에 두는 글자 파일로, AI가 매 대화를 시작할 때 자동으로 먼저 읽는다. 이렇게 AI가 나에게 맞춰 일하도록 판을 미리 깔아두는 것을 하네스(harness)라고 한다.
무엇을 적을까. 다행히 개발자들이 오래전부터 정리해 둔 원칙 몇 개가 그대로 좋은 메모가 된다. 크게 두 묶음이다 — (A) AI에게 일 시키는 법, (B) 코드와 정보를 정돈하는 법.
A묶음 — AI에게 시키는 법: 안드레이 카파시의 4원칙
안드레이 카파시는 '바이브 코딩'이라는 말을 만든 AI 연구자다. 그가 정리한, AI에게 코드를 시킬 때의 네 가지 지침을 비개발자 눈높이로 풀면 이렇다.
생각 먼저(Think First). 유능한 신입일수록 물어보면 곧장 자기 방식대로 만들어 온다. '회원가입 만들어줘' 했더니 이메일 가입으로 다 만들었는데 나는 카카오 로그인을 원했다면, 처음부터 다시다. 그래서 만들기 전에 '이렇게 이해했는데 맞나요?'를 먼저 말하게 한다. 말로 방향 맞추는 5초가 다 뜯어고치는 30분을 아낀다.
군더더기 없이(Simplicity First). AI는 '친절하게' 안 시킨 기능까지 얹는 버릇이 있다. 저장 버튼 하나 요청했는데 자동저장·버전관리까지 딸려온다. 셋 다 안 쓰는데 셋 다 고장날 수 있는 지점이 된다. 지금 시킨 최소한만 만들게 한다.
딱 고칠 데만(Surgical Changes). '버튼 색만 파랑으로' 했는데 버튼을 통째로 새로 짜다 클릭 동작을 지워버리는 일이 흔하다. 색은 바뀌었는데 눌러도 반응이 없다. 요청한 부분만 고치고 관련 없는 데는 손대지 말게 한다.
될 때까지(Goal-Driven). 완료 기준이 없으면 AI는 '일단 됐어요'에서 멈춘다. 화면만 만들고 실제 저장 연결은 빼먹은 채로. 반대로 '저장 후 새로고침해도 글이 남아야 함'이라고 못박으면, 그 상태가 될 때까지 스스로 고치고 다시 시도한다 — 이게 대규모 언어모델(LLM)의 가장 큰 강점이다.
B묶음 — 코드·정보 정돈: SSOT·DRY·KISS·YAGNI
이건 코드 자체를 깔끔하게 두는 원칙이다. 당장 몰라도 되지만, 알아두면 AI가 만든 결과물이 나중에 덜 꼬인다.
정답은 한 곳(SSOT, Single Source of Truth). 같은 정보를 여러 곳에 복붙하면 반드시 어긋난다 — 하나만 고치고 나머지를 까먹기 때문이다. 한 곳에 두고 나머지는 그걸 참조하게 한다. 반복 금지(DRY, Don't Repeat Yourself)는 그 코드 버전으로, 같은 코드가 두 번 넘게 나오면 한 번 만들어 재사용한다. 아래가 실제 코드 예시다.
쉽게(KISS, Keep It Simple). 똑똑한 척 복잡하게 만들지 말고 이해하기 쉬운 방법을 먼저 고른다. 지금 것만(YAGNI, You Aren't Gonna Need It). '나중에 쓸까 봐'는 지금 만들지 않는다. 눈치챘겠지만 KISS·YAGNI는 카파시의 '군더더기 없이'와 사실상 같은 말이다.
// 나쁜 예 — 브랜드 색이 여러 곳에 흩어짐
버튼_색 = "#E1892F"
제목_색 = "#E1892F"
링크_색 = "#E1892F"
// 색을 바꾸려면 세 곳을 다 고쳐야 하고, 하나만 빠뜨려도 색이 제각각
// 좋은 예 — 한 곳에 정의하고 갖다 씀 (SSOT + DRY)
브랜드_색 = "#E1892F"
버튼_색 = 브랜드_색
제목_색 = 브랜드_색
링크_색 = 브랜드_색
// 이제 브랜드_색 한 줄만 바꾸면 버튼·제목·링크가 한꺼번에 바뀐다여덟 개 같지만, 실은 네 상식이다
지금까지 여덟 개를 봤지만, 겹치는 걸 걷어내면 외울 건 네 가지 상식뿐이다.
여덟 개 약자에 겁먹을 필요가 없다. '시키기 전에 확인하고 끝나면 검증한다 / 단순하게 간다 / 맡긴 데만 건드린다 / 한 곳으로 모은다' — 이 네 문장이 전부다.
| 상식 한 마디 | 묶이는 원칙 | 신입에게 하는 말 |
|---|---|---|
| ① 시키기 전 확인, 끝나면 검증 | 생각 먼저 + 될 때까지 | '이렇게 맞죠?' 먼저 · '됐어요' 대신 진짜 확인 |
| ② 단순하게 | 군더더기 없이 + KISS + YAGNI | 지금 시킨 것만 · 미리 만들지 마 |
| ③ 맡긴 데만 | 딱 고칠 데만 | 그 부분만 · 옆은 건드리지 마 |
| ④ 한 곳으로 모아라 | SSOT + DRY | 정답·양식은 한 곳에 · 복붙 금지 |
그대로 붙여넣는 CLAUDE.md (실제 예시)
지금까지의 원칙을 실제 파일로 옮기면 이렇게 된다. 프로젝트 폴더 맨 위에 CLAUDE.md라는 이름으로 저장하면 끝이다. (Claude Code를 쓰면 CLAUDE.md, Cursor·Codex 등 여러 도구를 섞어 쓰면 같은 내용을 AGENTS.md로 두면 된다.)
# 이 프로젝트에서 AI가 지킬 규칙
나는 개발자가 아니다. 전문용어는 쉬운 말로 풀어서, 짧고 간결하게 설명하라.
## 일하는 방식
- 생각 먼저: 코드를 짜기 전에 무엇을 어떻게 만들 건지 한국어로 먼저 설명하고 내 확인을 받아라. 요청이 애매하면 그냥 따르지 말고 되물어라.
- 군더더기 없이: 지금 요청을 푸는 최소한만 만들어라. 시키지 않은 기능은 넣지 마라.
- 딱 고칠 데만: 요청한 부분만 수정하고, 관련 없는 코드는 건드리지 마라.
- 될 때까지: 먼저 성공 기준을 정하고(예: 저장 후 새로고침해도 글이 남을 것), 실제로 그게 될 때까지 확인하며 반복하라.
## 코드·정보 정돈
- 정답은 한 곳(SSOT): 같은 설정값·정보는 한 곳에만 두고 나머지는 그걸 참조하라.
- 반복 금지(DRY): 같은 코드가 두 번 넘게 나오면 함수로 묶어 재사용하라.
- 쉽게(KISS): 복잡한 구조보다 이해하기 쉬운 방법을 먼저 골라라.
- 지금 것만(YAGNI): '나중에 필요할지도'는 지금 만들지 마라.
## 안전
- 파일 삭제처럼 되돌리기 어려운 작업 전에는 반드시 먼저 물어라.지금 바로 시작하기
네 단계면 된다. (1) 지금 만들고 있는 프로젝트 폴더를 연다. (2) 맨 위에 CLAUDE.md 파일을 새로 만든다 — 또는 AI에게 'CLAUDE.md 파일 만들어서 이 규칙들 넣어줘'라고 말로 시켜도 된다. (3) 위 내용을 붙여넣는다. (4) 다음 대화부터 AI가 이 메모를 먼저 읽고 시작한다.
바이브 코딩을 잘한다는 것은 코드를 잘 짜는 게 아니라, AI가 나를 잘 돕도록 판을 깔아주는 일에 가깝다. 그 판이 바로 신입 책상에 붙여둔 이 메모 몇 장이다.