AI 코딩 오류 잡는 카파시의 65줄 CLAUDE.md
AI가 코드를 너무 잘 짜는 것이 문제라는 역설이 있다. 지나치게 빠르게, 자신감 있게 코드를 생성하며 불필요한 오류를 만드는 경우가 빈번하다. 이러한 AI 코딩의 고질병을 막는 65줄짜리 CLAUDE.md 파일이 개발자 커뮤니티에서 큰 주목을 받는다. 이 파일은 AI 코딩에 필수적인 ‘브레이크’ 역할을 수행한다.
안드레이 카파시, AI 분야의 선구자
안드레이 카파시는 오픈AI의 공동 창업자이자 전 테슬라 AI 디렉터이다. 현재 그는 AI 교육 회사 유레카 랩스를 운영한다. 카파시는 AI가 코드를 못 짜는 것이 아니라 “너무 잘 짜는 것”이 문제라고 지적한다. AI는 너무 빨리, 너무 자신감 있게 코드를 생성하여 불필요한 문제를 야기하므로, 이를 제어할 ‘브레이크’가 필요하다는 설명이다.
그의 코딩 노하우가 담긴 65줄짜리 CLAUDE.md 파일은 GitHub에서 석 달 만에 10만 개가 넘는 스타를 받았다. 이 파일은 카파시의 트위터 글 하나에서 시작되었다. 해당 글이 올라온 지 7시간 만에 포레스트 창이라는 개발자가 이 메시지를 깔끔하게 마크다운 파일로 정리하여 GitHub에 올리면서 급속도로 확산되었다. 많은 개발자가 AI 코딩의 비슷한 문제로 고통받았기 때문에 이 파일에 공감하며 큰 호응을 보냈다.
AI 코딩의 3가지 고질병
카파시는 AI가 코딩 시 반복하는 세 가지 고질병을 짚어낸다. 이 고질병들은 AI가 사용자의 의도를 정확히 파악하지 못하거나, 효율성보다 양을 중시하는 경향에서 발생한다.
AI가 반복하는 코딩 고질병은 다음과 같다.
| 고질병 | 설명 | 사례 |
|---|---|---|
| 잘못된 가정 | AI는 사용자의 요구를 명확히 확인하지 않고 임의로 해석하여 코드를 생성한다. 이는 중요한 질문을 하지 않고 스스로 결정을 내리는 데서 비롯된다. | 사용자가 로그인 기능 추가를 요청하면 AI는 이메일, 소셜 로그인 여부나 JWT, 세션 쿠키 방식 등 구체적인 사항을 묻지 않고 JWT 인증 시스템 200줄을 자체적으로 작성한다. 이는 간단한 세션 쿠키 로그인을 원했던 사용자에게 불필요한 코드를 만든다. |
| 코드 부풀리기 | 세 줄로 끝날 수 있는 간단한 기능을 200줄 이상의 방대한 코드로 만든다. AI는 ‘나중에 필요할 수 있다’는 명목으로 불필요한 기능, 추상화, 유연성을 추가하는 경향을 보인다. | 이메일 형식 검증을 요청하면 AI는 8가지 옵션, 별도의 설정 파일, 추상 인터페이스를 포함한 거대한 이메일 검증 클래스를 생성한다. 단 한 번 사용할 코드임에도 불구하고 복잡도를 증가시켜 가독성을 떨어뜨리고 유지보수 부담을 늘린다. |
| 멋대로 고치기 | 특정 함수 하나를 수정해달라고 요청했지만, AI는 인접한 다른 함수나 파일까지 함께 수정한다. 이는 코드 포맷팅, 변수명 변경, 오래된 주석 삭제 등 요청하지 않은 부수적인 변경을 포함한다. | 사용자가 한 함수만 살짝 고치길 원했음에도 AI는 인접 코드의 포맷팅을 정리하고, 변수명을 변경하며, 주석을 삭제한다. 이로 인해 검토해야 할 변경 사항이 수십 개로 늘어나고, 실제 요청과 곁다리 변경을 구분하기 어렵게 만든다. 때로는 멀쩡히 작동하던 코드가 오작동하는 원인이 된다. |
카파시의 4가지 원칙, AI 코딩에 브레이크 걸기
카파시의 65줄 CLAUDE.md 파일은 AI 코딩의 고질병들을 막기 위한 네 가지 핵심 원칙으로 구성된다. 이 원칙들은 AI가 더 신중하고 정확하게 코드를 생성하도록 유도한다.
카파시의 4가지 원칙은 다음과 같다.
| 원칙 | 핵심 내용 |
|---|---|
| 1. 코딩 전에 먼저 생각하라 | AI가 자신의 이해를 명확히 밝히고, 헷갈리면 질문하며, 단순한 방법을 제안하게 한다. |
| 2. 단순하게 먼저 | 불필요한 기능이나 추상화 없이 최소한의 코드를 만들도록 유도한다. |
| 3. 외과수술처럼 정확하게 | 요청받은 부분만 수정하고, 불필요한 인접 코드나 스타일을 건드리지 않도록 한다. |
| 4. 목표 중심으로 실행 | 모호한 지시 대신 검증 가능한 성공 기준을 제시하고, 테스트를 통해 확인하도록 한다. |
카파시는 AI에게 명령만 할 것이 아니라, 명확한 성공 기준을 주고 그 기준을 충족할 때까지 지켜보라는 점을 강조한다. 이 원칙들은 AI가 인간 개발자의 의도를 더 정확히 이해하고, 실용적이고 효율적인 코드를 생성하도록 돕는 강력한 도구가 된다.
한국어 환경에 맞춘 5가지 추가 규칙
영상 운영자는 카파시의 네 가지 원칙에 더해, 한국어 개발 환경에서 AI와 협업하며 직접 터득한 다섯 가지 규칙을 CLAUDE.md에 추가했다. 이 규칙들은 실제 개발 생산성을 높이는 데 기여한다.
영상 운영자가 추가한 5가지 규칙은 다음과 같다.
| 룰 | 설명 | 근거 및 효과 |
|---|---|---|
| 콜론으로 문장 끝내지 말기 | 한국어 문장 끝에 콜론 대신 마침표를 사용하게 한다. | AI는 영어 학습으로 인해 한국어 문장도 콜론으로 끝내는 경향이 있다. 마침표를 사용하면 한국어 출력이 훨씬 자연스러워진다. |
| 새 파일에 한국어 헤더 주석 한 줄 | 새 소스 파일을 만들 때 파일 맨 위에 그 파일이 무엇을 하는지 한 줄 주석을 넣게 한다. | AI는 코드베이스 전체를 읽지 않고 필요한 파일만 본다. 첫 줄 주석은 AI가 파일의 목적을 빠르게 파악하도록 돕고, 복잡한 코드베이스에서도 정확한 개발을 가능하게 한다. |
| 큰 작업은 계획, 체크리스트, 컨텍스트 노트 | 큰 기능 개발 전에 계획서, 해야 할 작업을 정리한 체크리스트, 의사결정 근거를 기록한 컨텍스트 노트를 만들게 한다. | 카파시의 ‘코딩 전에 먼저 생각하라’ 원칙을 적용한 것이다. 이 세 가지는 작업 진행의 물 흐름을 원활하게 하고, 다음 날 작업을 이어서 할 때도 혼란을 줄인다. |
| 작업 마무리 전 테스트 실행 | 코드 수정 세션에서 작업 완료를 선언하기 전에 반드시 테스트를 한 번 돌리게 한다. | AI는 코드를 수정해놓고 실제 작동 여부를 확인하지 않고 끝났다고 말하는 경향이 있다. 이는 카파시의 ‘목표 중심 실행’ 원칙을 보완한다. 명시적인 테스트 요구로 작업의 신뢰성을 높인다. |
| 의미 단위 커밋 | 의미 있는 작업이 끝나면 즉시 커밋하고, 커밋 메시지로 한 문장을 설명할 수 있는지 확인한다. | 여러 파일 수정 후 한 번에 커밋하는 것을 방지한다. 커밋 메시지가 명확하면 변경 이력을 쉽게 파악하고, 아직 섞여 있는 작업은 분리하도록 유도한다. |
CLAUDE.md 적용과 하네스 엔지니어링
이 65줄짜리 CLAUDE.md 파일은 누구나 쉽게 다운로드하여 적용할 수 있다. 파일 경로는 영상 설명에 제공한다.
CLAUDE.md 파일을 배치하는 방법은 두 가지이다.
- 프로젝트 폴더 내: 특정 프로젝트 폴더 안에 파일을 두면 해당 프로젝트에만 적용된다.
- 홈 디렉토리 내
.claude폴더: 홈 디렉토리 안의.claude폴더에 파일을 두면 모든 프로젝트에 전역으로 적용된다. 영상 운영자는 어떤 프로젝트를 하든 카파시의 원칙이 항상 적용될 수 있도록 전역 적용을 권장한다.
파일을 복사하여 붙여넣기하는 과정은 1분이면 완료된다.
카파시의 CLAUDE.md 파일은 사실 더 큰 그림의 한 조각이다. 이는 AI가 혼자서도 잘 작동하는 개발 환경을 구축하는 작업으로, 최근 하네스 엔지니어링(Harness Engineering)이라 부른다. CLAUDE.md는 이 하네스에서 가장 중요한 한 조각이 된다. AI의 코딩 능력을 최대한 활용하면서도 발생할 수 있는 오류를 최소화하는 환경을 만드는 것이 중요하다.
출처
- 미드나잇 로그 Midnight Log. (2026-05-04). 바이브코딩계 GD가 공유한 CLAUDE.md 나눕니다. YouTube.