[심층분석] 카파시가 짚어낸 LLM 코딩의 함정, 단 하나의 CLAUDE.md로 잡아낸다

AI가 코드를 짜주는 시대, 왜 우리는 여전히 답답할까

요즘 Claude Code나 Cursor 같은 AI 코딩 도구를 안 써본 개발자는 거의 없을 거예요. 한 줄 명령으로 함수를 뚝딱 만들어주고, 버그도 찾아주고, 심지어 테스트 코드까지 작성해주니까요. 그런데 막상 실무에서 며칠만 써보면 다들 비슷한 답답함을 느껴요. "내가 원한 건 이게 아닌데?" 하는 순간이 자꾸 오는 거죠.

이런 답답함의 정체를 가장 정확하게 짚어낸 사람이 바로 안드레이 카파시(Andrej Karpathy)예요. 테슬라 AI 책임자였고 OpenAI 창립 멤버였던 그가 최근 X(트위터)에 올린 글이 개발자 커뮤니티를 한 번 더 흔들었어요. 그리고 그 관찰을 바탕으로 누군가가 딱 한 개의 CLAUDE.md 파일로 정리한 가이드라인이 등장했는데요, 이게 바로 오늘 이야기할 multica-ai/andrej-karpathy-skills 리포지토리예요.

뭐가 그렇게 특별하냐고요? 사실 별거 없어요. 거창한 프레임워크도, 새로운 모델도 아니에요. 그냥 AI한테 "이렇게 일해줘"라고 부탁하는 규칙 문서 한 장이거든요. 그런데 이 한 장이 Claude Code의 행동을 눈에 띄게 바꿔놓는다는 게 핵심이에요. AI 코딩 도구를 매일 쓰는 사람이라면 한 번쯤 진지하게 읽어볼 만한 이야기예요.

카파시가 짚어낸 LLM 코딩의 세 가지 함정

먼저 카파시가 뭐라고 했는지부터 살펴볼게요. 그의 관찰은 크게 세 가지 문제로 압축돼요.

1. 멋대로 가정하고 달려간다

카파시의 표현을 그대로 옮기면 이래요.

> "모델들은 당신을 대신해서 잘못된 가정을 하고, 그걸 확인도 안 하고 그냥 달려간다. 자기 혼란을 관리하지 못하고, 명확하게 해달라고 묻지도 않고, 모순을 드러내지도 않고, 트레이드오프를 보여주지도 않고, 반박해야 할 때 반박하지도 않는다."

이게 무슨 말이냐면요, 예를 들어 "사용자 정보를 저장하는 함수 만들어줘"라고 했을 때, AI는 "DB에 저장하시는 건가요? 아니면 캐시에? 어떤 필드를?" 이렇게 묻지를 않아요. 그냥 자기가 그럴듯하게 추측해서 SQLite에 user 테이블 만들고 INSERT 쿼리 짜고 다 해버리는 거죠. 그런데 사실 당신은 Redis에 임시로 넣고 싶었던 거고요. 결과적으로 30분짜리 작업이 3시간짜리 삽질이 되는 거예요.

2. 모든 걸 과하게 만든다

두 번째 함정도 익숙할 거예요.

> "코드와 API를 과하게 복잡하게 만들고, 추상화를 부풀리고, 죽은 코드를 정리하지 않고... 100줄이면 될 걸 1000줄짜리 거창한 구조로 구현한다."

쉽게 말해 오버엔지니어링이에요. "두 숫자 더하는 함수" 부탁했더니 AbstractCalculatorFactory 만들고 OperationStrategy 인터페이스 만들고 BinaryOperationInterface 추상 클래스까지 만들어서 가져오는 거예요. 디자인 패턴 책에서 막 튀어나온 것처럼요. 정작 필요한 건 def add(a, b): return a + b 한 줄인데 말이죠.

AI가 이러는 이유는 단순해요. 학습 데이터에 "잘 설계된 코드"라고 라벨링된 것들이 대부분 엔터프라이즈급 코드베이스거든요. 그러니까 작은 작업에도 자꾸 엔터프라이즈 옷을 입히려고 하는 거예요.

3. 건드리면 안 되는 걸 건드린다

세 번째가 가장 짜증나는 부분이에요.

> "이해하지 못한 주석과 코드를 부수효과로 바꾸거나 삭제한다. 작업과 직접 관련이 없는데도 말이다."

예를 들어 로그인 함수 하나만 고쳐달라고 했는데, AI가 옆에 있던 # TODO: 나중에 리팩토링 주석을 "불필요해 보여서" 지워버리거나, 본인이 이해 못한 정규식을 "개선"한답시고 동작이 바뀌게 만드는 거죠. 외과 수술을 부탁했는데 멀쩡한 장기까지 손대는 의사랑 똑같아요.

네 가지 원칙: 단순하지만 강력한 처방전

이 세 가지 문제를 해결하기 위해 이 리포지토리가 제안하는 건 네 가지 원칙이에요. 그리고 이 원칙들을 한 개의 CLAUDE.md 파일에 적어두면, Claude Code가 매번 그 파일을 참고하면서 다르게 행동하게 돼요. (Claude Code는 프로젝트 루트의 CLAUDE.md를 자동으로 읽거든요. Cursor라면 .cursor/rules 폴더를 쓰고요.)

원칙 1: 코딩하기 전에 생각하기 (Think Before Coding)

핵심 메시지는 "가정하지 마. 혼란을 숨기지 마. 트레이드오프를 드러내." 예요. 구체적으로는 이런 행동을 강제해요.

• 가정을 명시적으로 말하기: "저는 지금 PostgreSQL을 쓴다고 가정하고 진행할게요" 같은 식으로 미리 꺼내놓는 거예요. 그러면 사용자가 "아 MySQL인데?" 하고 바로잡을 수 있죠.
• 여러 해석을 제시하기: 애매한 요구사항이면 "A로 해석할 수도 있고 B로 할 수도 있는데, 어느 쪽이세요?" 하고 묻기.
• 반박할 땐 반박하기: 사용자가 복잡한 방법을 제안해도 더 단순한 방법이 있으면 "이렇게 하면 더 간단한데 어떠세요?"라고 말하기.
• 혼란스러우면 멈추기: 모르겠으면 그냥 일단 하지 말고, 뭐가 불명확한지 콕 집어 묻기.

이게 별거 아닌 것 같지만 실제로 적용하면 효과가 커요. AI가 "네, 알겠습니다" 하고 무작정 달려가는 게 아니라, 잠깐 멈춰서 확인하는 습관이 생기거든요.

원칙 2: 단순함 먼저 (Simplicity First)

두 번째 원칙은 "문제를 해결하는 최소한의 코드만 써라. 추측성 기능은 금지." 예요. 세부 규칙은 이래요.

• 요청받지 않은 기능은 추가하지 않기
• 한 번만 쓸 코드에는 추상화 만들지 않기
• "나중에 유연하게 쓰려고" 같은 미래 대비용 코드 금지
• 죽은 코드는 즉시 삭제

이건 사실 YAGNI 원칙(You Aren't Gonna Need It, 어차피 안 쓸 거임)을 그대로 옮긴 거예요. 우리가 사람한테는 이걸 잘 적용하면서, 정작 AI한테는 "알아서 좋은 코드 짜줘"라고 막연하게 부탁하니까 오버엔지니어링이 나오는 거죠. 명시적으로 "단순하게"라고 적어두면 AI도 그 방향으로 움직여요.

원칙 3: 외과 수술식 변경 (Surgical Changes)

세 번째는 "건드릴 곳만 건드려라" 예요. 마치 외과 의사가 환자의 다른 부위는 그대로 두고 문제 부위만 도려내듯이요.

• 작업과 직접 관련 없는 코드는 손대지 말기
• 이해 못한 주석/코드는 절대 삭제하지 말기
• 리팩토링 요청이 따로 없으면 리팩토링하지 말기
• 변수명 "개선" 같은 거 마음대로 하지 말기

원칙 4: 목표 기반 실행 (Goal-Driven Execution)

마지막 원칙은 "테스트로 성공 기준을 먼저 만들고, 그걸 통과시키는 방향으로 일해라" 예요. 이게 뭐냐면, AI한테 "기능 만들어줘" 하지 말고 "이런 입출력이 통과되는 테스트를 먼저 만들고, 그걸 통과하는 코드를 짜줘"라고 시키는 거예요.

쉽게 비유하면, 양궁 선수한테 "잘 쏴봐" 하는 거랑 "저 과녁 정중앙 맞춰" 하는 거랑 차이예요. 후자가 훨씬 명확하잖아요. AI도 마찬가지로 "성공"의 정의가 명확할 때 훨씬 잘 작동해요. 검증 가능한 목표가 있으면 자기가 만든 결과물이 맞는지 스스로 확인할 수 있거든요.

다른 접근법과 뭐가 다를까

AI 코딩 가이드라인 시도는 이번이 처음이 아니에요. 비교해볼 만한 접근법이 몇 개 있어요.

Cursor Rules와 비교

Cursor는 .cursor/rules 디렉토리에 여러 규칙 파일을 두는 방식이에요. 파일별로 "테스트 작성 규칙", "리액트 컴포넌트 규칙" 이런 식으로 세분화하죠. 장점은 세밀한 제어가 가능하다는 거고, 단점은 규칙이 너무 흩어져서 관리가 힘들다는 거예요.

반면 카파시 가이드라인은 단 하나의 파일에 핵심 원칙만 압축해뒀어요. 마치 회사 행동강령처럼요. 세부 규칙은 없지만 "어떻게 일할 것인가"라는 철학이 분명해요.

Aider의 CONVENTIONS.md와 비교

Aider라는 또 다른 AI 코딩 도구는 CONVENTIONS.md 파일로 코딩 스타일을 정의해요. 그런데 이건 코드 스타일에 초점이 맞춰져 있어요. "들여쓰기는 4칸", "함수명은 snake_case" 같은 거요.

카파시 가이드라인은 AI의 의사결정 방식 자체를 다룬다는 점에서 한 단계 더 추상적이에요. 어떻게 코드를 쓰느냐가 아니라 어떤 태도로 작업에 임할 것인가를 정의하는 거죠.

시스템 프롬프트 튜닝과 비교

또 다른 접근은 아예 시스템 프롬프트를 길게 작성하는 거예요. "너는 시니어 개발자야, 코드는 깔끔하게, 어쩌고..." 하는 식이요. 그런데 이건 재사용성이 떨어져요. 매번 똑같은 프롬프트를 복붙해야 하고, 팀원들끼리 공유하기도 어렵죠.

반면 CLAUDE.md는 Git 저장소에 포함되는 파일이라 자연스럽게 팀 전체가 공유하게 돼요. 새로 합류한 팀원도 git clone 하면 자동으로 같은 규칙을 적용받는 거예요. 이게 진짜 큰 차이거든요.

한국 개발자에게 어떤 의미가 있을까

그럼 우리 한국 개발자들에게는 이게 어떤 의미일까요? 몇 가지 시나리오로 풀어볼게요.

시나리오 1: 스타트업 1인 개발자

혼자 사이드 프로젝트 만드는 분이라면, 지금 당장 프로젝트 루트에 CLAUDE.md를 만들고 이 네 원칙을 복사해두는 것만으로도 차이를 느낄 수 있어요. 특히 "단순함 먼저" 원칙이 효과 커요. MVP 만들 때 AI가 자꾸 거창한 구조 제안하면 진도가 안 나가거든요. 명시적으로 "단순하게"를 박아두면 빠르게 프로토타이핑 할 수 있어요.

시나리오 2: 중견 기업 팀 개발자

팀 단위로 일하시는 분이라면, 이 가이드라인을 팀 컨벤션과 합쳐서 커스터마이징하는 게 좋아요. 예를 들어 "외과 수술식 변경" 원칙에 "우리 팀은 PR 하나당 한 가지 관심사만"이라는 팀 규칙을 덧붙이는 거죠. PR 리뷰 부담이 확 줄어요.

시나리오 3: 레거시 시스템 유지보수

10년 된 시스템 만지는 분들한테는 "건드리면 안 되는 코드를 건드린다" 문제가 특히 치명적이에요. AI가 "이 코드 좀 이상한데?" 하면서 멀쩡히 돌아가던 비즈니스 로직을 "개선"해버리면 장애로 직결되니까요. 외과 수술식 변경 원칙을 강력하게 적용하고, 추가로 "수정 전 반드시 영향 범위를 보고하라" 같은 룰을 더하면 좋아요.

도입 시 주의점

다만 이걸 도입할 때 맹신은 금물이에요. 가이드라인이 있다고 AI가 100% 그대로 따르는 건 아니거든요. 특히 컨텍스트가 길어지면 AI가 초반의 CLAUDE.md 내용을 점점 잊어버려요. 그래서 중요한 작업 전엔 "우리 가이드라인 다시 확인해줘"라고 한 번씩 환기시켜주는 게 좋아요.

또 하나, 한국어로 번역해서 쓰는 것도 고려해보세요. 영어 그대로 둬도 작동은 하지만, 우리 팀이 한국어로 소통하는 환경이면 한국어 버전이 컨텍스트 일관성에 도움이 돼요. AI 응답도 자연스럽게 한국어로 정렬되고요.

학습 로드맵

이걸 제대로 활용하고 싶다면 순서는 이래요. 첫째, 원문 CLAUDE.md를 그대로 적용해보고 일주일 써보기. 둘째, 본인이나 팀에 맞게 한두 줄씩 추가/수정하기. 셋째, 카파시의 원글과 LLM 코딩 한계에 대한 다른 논의들도 읽어보면서 "왜" 이런 규칙이 필요한지 깊이 이해하기. 이 순서로 가면 단순히 복붙하는 게 아니라, 자기만의 AI 협업 방식을 만들 수 있어요.

AI 코딩 시대의 진짜 생산성은 어디서 올까

이 리포지토리가 던지는 메시지는 사실 깊어요. AI가 더 똑똑해지길 기다리는 게 아니라, 우리가 AI를 더 잘 쓰는 법을 배워야 한다는 거거든요. 모델 성능이 GPT-4에서 GPT-5로, Claude 3에서 Claude 4로 올라가는 동안에도 "멋대로 가정", "오버엔지니어링", "부수효과" 문제는 사라지지 않았어요. 이건 모델의 한계라기보다 인간이 명세를 모호하게 던지는 한계에 가까워요.

앞으로 AI 코딩 도구가 발전하는 방향은 크게 두 갈래일 거예요. 하나는 모델 자체가 더 똑똑해지는 길, 다른 하나는 사용자가 AI에게 일을 시키는 방법이 더 정교해지는 길이요. 카파시 가이드라인은 후자의 대표 사례예요. 그리고 후자가 어쩌면 더 실용적인 발전일 수도 있어요. 모델은 우리가 못 만들지만, 가이드라인은 오늘 당장 만들 수 있으니까요.

마지막으로 같이 생각해볼 만한 질문 몇 개 던질게요. 여러분은 AI 코딩 도구를 쓰면서 어떤 순간에 가장 답답함을 느끼셨나요? 그 답답함을 줄이기 위해 어떤 규칙을 만들어보셨나요? 혹시 팀 단위로 AI 사용 가이드라인을 만들어 운영하고 계신 분들 있다면, 어떤 항목이 가장 효과적이었는지도 궁금해요. 댓글로 경험을 공유해주시면 다음 글에 녹여서 더 깊이 있는 분석으로 돌려드릴게요.