좋은 CLAUDE.md 를 붙였는데도 클로드가 여전히 신입 같다면 파일 탓이 아닙니다. 구조가 그렇게 생겼습니다. 왜 그런지를 공식 문서로 확인하고, 부탁을 장치로 바꾸는 세 자리를 실제로 돌아가는 화면 기준으로 적었습니다.
카파시도 똑같이 당하고 있었습니다
기능 하나 고쳐달라고 했더니 멀쩡하던 데가 깨지고, 그래놓고 「다 됐습니다」로 끝나는 경험. 아마 대부분 해보셨을 겁니다.
바이브 코딩이라는 말을 만든 안드레 카파시가 2026년 1월 글에서 이 증상에 이미 이름을 붙여놨습니다. 덤벙대는 성급한 신입이 할 법한, 미묘한 개념적 실수.
그러면서 세 가지를 꼽습니다.
- 묻지도 않고 멋대로 가정한 다음 그대로 달려간다
- 헷갈려도 정리하지 않고, 되묻지도 않는다
- 시키지도 않은 코드까지 건드린다
겪으신 게 이런 내용 아닌가요.
그런데 그 아래에 폭탄이 있습니다
진짜는 그 아래에 있습니다. 같은 글에서 카파시가 이렇게 써놨습니다.
All of this happens despite a few simple attempts to fix it via instructions in CLAUDE.md.
이 모든 일이, CLAUDE.md 에 지시를 넣어서 고쳐보려 했는데도 여전히 일어나더라. 본인 문장 그대로입니다.
그 유명한 65줄짜리 CLAUDE.md 가 나온 바로 그 글에 이렇게 적혀 있습니다. 참고로 그 파일은 카파시가 직접 만든 게 아니라 그의 글을 보고 다른 개발자가 정리한 겁니다. 깃허브 스타가 이십만 개가 넘고요. 카파시 본인은 2026년 5월에 앤트로픽에 들어갔습니다. 클로드를 만드는 바로 그 회사죠.
좋은 CLAUDE.md 를 가져다 붙였는데도 클로드가 여전히 신입 같은 건 여러분 잘못이 아닙니다. 글의 주인공인 카파시조차 규칙을 파일에 적는 것만으로는 이 증상을 잡지 못했습니다.
CLAUDE.md 는 시스템 프롬프트가 아닙니다
그럼 왜 파일에 적어놔도 규칙이 안 지켜질까요. 앤트로픽 공식 문서에 답이 있습니다.
CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself.
CLAUDE.md 내용은 시스템 프롬프트가 아니라 그 뒤에 오는 유저 메시지로 전달됩니다. 여러분이 채팅창에 친 말이랑 같은 자리인 겁니다. 그래서 문서가 바로 이어서 못을 박습니다. 엄격하게 지켜진다는 보장은 없다고요.
명령이라고 생각하고 썼는데, 사실은 부탁이었던 겁니다.
클로드는 매일 아침 기억을 잃고 출근합니다
어제 화를 내면서 알려준 건 다 어디 갔을까요. 공식 문서 첫 줄이 답입니다. 모든 클로드 코드 세션은 새 컨텍스트 윈도우로 시작한다.
세션을 새로 열 때 클로드한테 들어가는 건 이 목록이 전부입니다.
- 시스템 프롬프트
- 클로드가 스스로 적어둔 메모
- 환경 정보
- 도구와 스킬 이름
- CLAUDE.md
여기 없는 건 안 들어갑니다. 어제 나눈 대화도 안 들어갑니다.
여기에 하나가 더 붙습니다. 긴 세션에서 /compact 로 대화를 압축하면
클로드는 자기한테 무슨 스킬이 있는지 그 목록을 잃어버립니다. 문서 원문에
그대로 있습니다. 이 목록은 압축 후에 다시 주입되지 않고, 실제로 불러 쓴 스킬만
살아남는다고요.
긴 세션 후반에 갑자기 멍청해진 게 아니라 메뉴판을 버린 겁니다.
같은 세션인데 갈수록 이상해지는 것도 기분 탓이 아닙니다. 공식 문서가 맨 앞에 적어놨습니다. 컨텍스트는 금방 차고, 차는 만큼 성능이 떨어진다. 2025년 벤치마크 연구에서는 32,000 토큰 지점에서 13개 모델 중 11개가 짧을 때보다 성능이 절반 아래로 떨어졌습니다.
먼저 기억부터 잡습니다
규칙 파일은 부탁이고, 기억은 매일 리셋되고, 세션은 길어질수록 흐려집니다. 그럼 어떻게 해야 하느냐. 두 단계입니다. 먼저 기억하게 만들고, 그다음에 동료로 키웁니다.
기억 쪽은 이미 켜져 있는 도구부터 쓰면 됩니다. 터미널에 /memory 를
쳐보세요. 오토 메모리라고, 클로드가 여러분한테 받은 교정을 스스로 적어두는
기능인데 기본값이 켜짐입니다. 노트가 네 종류인데 그중 하나가 피드백이고요.
그동안 고쳐준 것들을 거기다 적고 있었습니다.
쓰는 법은 그냥 채팅에 치면 됩니다. 「항상 pnpm 써, npm 말고」라고 하면 저장되고, CLAUDE.md 에 넣고 싶으면 「이거 CLAUDE.md 에 추가해줘」라고 하면 됩니다.
CLAUDE.md 에서 뺄 것과 넣을 것
그럼 그 65줄 파일은 요즘 왜 잘 안 먹힐까요.
앤트로픽 공식 문서에 CLAUDE.md 에 넣을 것과 뺄 것이 표로 있습니다. 빼라는 쪽에 이런 항목이 있어요. 클로드가 이미 아는 자명한 조언. 「깨끗한 코드를 써라」 같은 겁니다. 그 65줄의 상당 부분이 정확히 이 종류입니다.
길어서 문제가 아니라 종류가 문제입니다. 경고도 붙어 있습니다. 비대한 CLAUDE.md 는 클로드가 여러분의 진짜 지시를 무시하게 만든다고요.
넣을 기준도 한 줄로 정리돼 있습니다.
클로드가 같은 걸 두 번 틀렸다면, 그건 규칙이 빠져 있다는 신호다. 그때 한 줄을 추가해라. 두 번 틀린 것만 적는 겁니다.
요즘은 /doctor 로 지울 만한 걸 골라 제안받을 수도 있습니다.
비용도 같이 걸립니다. 클로드 코드는 요청마다 지금까지의 대화 전체를 다시 보냅니다.
하루 종일 열어둔 세션에서는 한 줄만 물어봐도 대화 전체 값이 나갑니다. 주제가
바뀌면 /clear 로 비우거나 새 세션으로 시작하는 게 낫습니다. 압축은
그 자체가 큰 요청이라 토큰을 쓰고, 비우는 건 공짜거든요.
부탁을 장치로 바꿉니다
여기까지가 기억하게 만드는 것이었습니다. 카파시도 글 마지막에 힌트를 남겼습니다. 뭘 할지 지시하지 말고 성공 기준을 줘라, 테스트를 먼저 쓰게 하고 그걸 통과시키게 하라.
그런데 보세요. 이것도 결국 말로 하는 부탁입니다. 클로드가 안 지키면 그만이죠.
앤트로픽 공식 문서에 사다리가 하나 있습니다. 이런 일이 생기면 이걸 추가해라, 하는 표인데 마지막 줄이 오늘의 전부입니다. 묻지 않고 매번 일어나야 하면 훅을 써라. 바로 옆에 이런 문장이 붙어 있습니다.
CLAUDE.md 에 적은 지시는 부탁이지 보장이 아니다. 훅은 강제다.
매번 지켜져야 하는 규칙이면 프롬프트가 아니라 장치로 만들라는 겁니다.
제 규칙 파일은 77줄이고 규칙은 네 개입니다. 처음엔 스무 개가 넘었는데 다 좋은 규칙이라고 생각했지만 저도 클로드도 안 지켰습니다. 네 개로 줄이니까 그때부터 지켜지더군요.
장치 하나, 완료의 기준을 바꿉니다
보통은 이렇게 시킵니다. 이 기능 만들어줘. 그리고 「다 됐어요」 하면 믿거나, 못 믿어서 10분 만에 받은 코드를 세 시간씩 눈으로 검수하거나.
순서를 뒤집습니다. 만들기 전에 이게 되면 성공이라는 기준부터 적게 합니다. 그러면 「다 됐다」의 근거가 클로드의 주장이 아니라 검사 결과가 됩니다.
그리고 한 문장을 꼭 붙여야 합니다.
안 붙이면 클로드가 코드 대신 테스트 쪽을 약하게 만들어서 초록불을 만드는 쪽으로 샙니다. TDD 를 만든 켄트 벡이 위험 신호로 딱 집은 게 이겁니다. 테스트를 꺼버리거나 지워버리는 것이요. 실제로 에이전트가 「테스트를 다 지우고 끝난 척하겠습니다」라고 말한 적도 있다고 합니다. 시험지를 지우고 만점 받는 겁니다.
프롬프트 끝에 네 단어를 붙이면 도움이 됩니다. Use red green TDD. 모델들이 이 말을 테스트 먼저 쓰고 실패를 확인한 다음 구현하라는 뜻으로 알아듣습니다.
그래도 부탁인 자리가 하나 남습니다. 「다 됐어요」라고 말하는 그 순간입니다. 그래서 클로드가 일을 끝내려는 바로 그 순간에 훅을 겁니다. 검사를 돌렸는데 통과 못 하면 턴 자체가 안 끝납니다. 마무리하려다 막히고, 검사 결과를 읽고, 다시 고치러 갑니다. 다 됐다는 말을 시스템이 못 하게 막는 겁니다.
앤트로픽 공식 문서에도 이 방식이 그대로 있습니다. 스톱 훅이 검사를 돌리고, 통과할 때까지 턴이 끝나는 걸 막는다고요.
이 관점으로 접근하면 클로드가 일하는 동안 화면을 지켜보고 있을 필요가 없습니다. 자동 검사가 대신 지켜보니까요.
저는 한 발 더 갑니다. 한 번씩 일부러 코드를 망가뜨려서 테스트가 진짜로 잡는지 봅니다. 검증도 검증해야 하거든요. 제 서비스에 테스트를 처음 붙였을 때 이미 만들어둔 기능 몇 개가 바로 실패했습니다. 동작한다고 믿고 몇 달을 쓰던 것들이었어요. 신고가 없었던 건 멀쩡해서가 아니라 그 길을 아무도 안 밟았거나 사용자가 그대로 떠났기 때문이었고요.
장치 둘, 저장하는 순간
화면은 깨져도 되돌리면 그만인데 데이터는 민감도가 다릅니다.
회원 표에 칸 하나만 추가해달라고 해도, 이미 쌓여 있는 데이터 수천 건에는 그 칸이 없습니다. 클로드가 이걸 대충 처리하면 멀쩡하던 앱이 없는 칸을 찾다가 멈춥니다.
그렇다고 「데이터 구조 바꿀 때 이력도 같이 남겨」라고 매번 말로 부탁하는 건 확률에 기대는 일입니다. 열 번 중 아홉 번을 지켜도 한 번이 사고나면 재앙이고요.
답은 말을 그만두는 겁니다. 알아서 기억해서 해주기를 바라던 것을, 그렇게 하지 않으면 아예 실행도 못 하게 바꿉니다. 코드를 저장하는 순간 검사가 자동으로 돌게 하는 거죠.
제 서비스는 이 장치 하나로 서른 번이 넘는 데이터 구조 변경을 사고 한 번 없이 넘겼습니다. 규칙이 제 기억이 아니라 장치에 들어가 있으니까 제가 잊어버려도 지켜집니다. 잔소리를 장치가 대신하는 겁니다.
장치 셋, 합치는 순간
어젯밤엔 분명 잘 됐는데 아침에 열어보니 서비스가 죽어 있던 적 있으시죠. 깨진 코드가 그대로 배포된 겁니다.
제 서비스는 제가 만들었는데도 main 브랜치에 직접 올리는 게 아예 불가능합니다. 모든 변경이 검토 요청을 거치고, 자동 검사가 통과해야 합치는 버튼이 살아납니다. 검사가 빨간불이면 버튼이 죽어 있고요.
혼자 만드는 서비스인데 왜 이렇게까지 하냐면요.
혼자일수록 검토해줄 사람이 없습니다. 사람이 없으면 장치가 그 역할을 해야 합니다.
부끄럽지만 이 장치도 사고를 한 번 겪고 나서야 걸었습니다. 걸고 나서는 눈에 띄게 줄었고요.
셋이 같은 말을 합니다
오늘 나온 문장 세 개를 나란히 놓아보겠습니다.
- 셸 스크립트 말고, 스킬을 설치해라
- 비대한 CLAUDE.md 는 클로드가 진짜 지시를 무시하게 만든다
- 열 줄이 스무 줄보다 잘 지켜진다
셋이 같은 말을 하고 있습니다. 저는 이 결론을 검색해서 얻은 게 아니라 사고 나면서 얻었고, 그걸 책에 적어놨습니다.
