코드 짜달랬더니 쓸데없이 2000줄 써줌..이 파일 하나로 해결했습니다. 안드레 카파시 claude.md

[한 줄 요약]
AI 코딩 도구의 무분별한 리팩토링과 코드 비대화를 막기 위해, 안드레 카파시의 조언을 기반으로 만든 65줄짜리 'CLAUDE.md' 규칙 파일 하나로 AI의 코딩 효율을 극대화할 수 있다.

솔직히 말하겠습니다. 저도 처음엔 AI 코딩 도구 쓰면서 감동받았습니다. "오, 이거 천재잖아?" 했다가도, 결과물을 보고 "이게 뭐야…" 하며 뒷목을 잡은 경험이 다들 있을 것입니다.

버그 하나 고쳐달라고 했더니 관련도 없는 함수 세 개를 멋대로 "개선"해놓거나, 단순한 기능 하나 추가했을 뿐인데 디자인 패턴까지 통째로 바꿔버리곤 합니다. 심지어 기존에 열심히 적어둔 주석을 멋대로 지워버리기도 하죠. 결국 AI한테 맡겼다가 내가 짠 코드를 내가 못 알아보게 되는 킹받는 상황이 발생합니다.

"요청한 딱 그 부분만 수정해줘." 이 당연한 말 한마디가 AI에게는 왜 이렇게 어려운 걸까요?

---

📦 65줄짜리 텍스트 파일이 깃허브 트렌딩 1위 찍은 이유

최근 테슬라와 OpenAI 출신의 그 유명한 안드레 카파시(Andrej Karpathy)가 X(트위터)에 올린 글이 엄청난 화제가 됐습니다. 요지는 간단합니다. 자신도 AI 코딩에 완전히 정착했는데, 거대언어모델(LLM)들이 맨날 똑같은 실수를 반복한다는 지적이었습니다.

그런데 누군가 카파시의 글을 보고 딱 65줄짜리 마크다운(MD) 파일을 만들어 GitHub에 올렸습니다. 별도의 소스코드나 라이브러리도 없이 그냥 쌩 텍스트 파일인데, 올라오자마자 스타(Star)가 9만 개를 넘어섰습니다.

이 마법 같은 파일의 이름은 바로 CLAUDE.md입니다. Anthropic의 터미널 AI 코딩 에이전트인 '클로드 코드(Claude Code)'는 프로젝트 폴더에 이 파일이 있으면 매 세션마다 자동으로 이 규칙을 읽어 들입니다. 쉽게 말해 AI 비서에게 업무를 시작하기 전 "야, 우리 프로젝트에서는 딱 이 규칙대로만 행동해" 하고 미리 경고장을 날리는 셈입니다.

---

📊 카파시가 콕 집은 AI 코딩의 4가지 문제점과 해결책

이 65줄짜리 파일에는 개발자들이 AI에게 가장 빡쳤던 순간들을 해결할 4가지 절대 원칙이 담겨 있습니다.

1. 코딩 전에 먼저 생각하기 (Think First)

가정을 함부로 세우지 말고 모르면 차라리 질문하라는 규칙입니다. 여러 해석이 가능하면 지 혼자 조용히 독단적으로 처리하지 말고 반드시 인간 개발자에게 먼저 물어보도록 강제합니다. 기본 AI들은 이 당연한 걸 안 지켜서 사고를 칩니다.

2. 단순하게 먼저 (Keep It Simple)

안 시킨 기능은 절대 추가하지 말라는 원칙입니다. 50줄로 끝낼 수 있는 깔끔한 코드를 200줄로 늘려 쓰지 말고, 굳이 필요 없는 추상화 패턴을 만들지 말라는 뜻입니다. "더 좋게 만들어드렸어요!"라며 생색내다 코드를 망치는 AI의 오지랖을 원천 차단합니다.

3. 외과적으로 정밀하게 수정하기 (Surgical Modifications)

이 파일에서 가장 중요한 핵심입니다. 건드려야 할 버그 지점 딱 한 곳만 외과 수술하듯 정밀하게 건드리라는 규칙입니다. 관련 없는 코드를 혼자 리팩토링하는 행위를 금지하며, 원래 있던 레거시 코드(Dead code)는 AI가 건드릴 영역이 아님을 명시합니다.

4. 목표 중심으로 실행하기 (Task-Oriented)

단순히 "버그 고쳐줘"라고 명령하는 대신, "버그를 재현하는 테스트 코드를 먼저 만들고 그걸 통과시켜줘"처럼 검증 가능한 목표를 가이드합니다. AI는 스스로 루프를 돌며 결과물을 자가 검증할 수 있는 환경일 때 가장 압도적인 퍼포먼스를 내기 때문입니다.

---

🛍️ 실제로 쓸 만할까? (실전 적용 트릭)

결론부터 말하면 진짜로 쓸 만합니다. 이 파일을 다운로드받아 프로젝트 루트(최상단) 폴더에 던져놓기만 하면 끝입니다. 따로 세팅할 것도 없고 클로드 코드가 알아서 매번 실행할 때마다 정독하고 시작합니다.

물론 복잡한 대규모 프로젝트라면 본인 팀의 코딩 스타일이나 고유한 기술 스택에 맞게 내용을 몇 줄 더 커스터마이징해야 합니다. 하지만 아무런 가이드라인 없이 야생 상태의 AI에게 코딩을 맡기는 것과, 이 파일 하나를 족보처럼 쥐여주고 시작하는 것은 결과물의 퀄리티와 코드 가독성 측면에서 하늘과 땅 차이입니다.

"이 규칙들은 사실 시니어 개발자가 신입 주니어 개발자에게 첫날 알려주는 기본 소양이다. 그동안 우리는 AI에게 이 기본적인 소양 교육을 안 시키고 일을 시켰던 것이다."