요즘 개발자 커뮤니티에서 한 파일이 돌풍을 일으키고 있다. 단 65줄짜리 Markdown 파일 하나를 넣으면 Claude Code가 "확 똑똑해진다"는 것이다. Andrej Karpathy의 LLM 코딩 비판에서 영감을 받아 커뮤니티가 만든 이 파일은 GitHub에서 폭발적인 반응을 얻었고, 우리 팀 Slack에서도 "바로 복붙", "내 것도 똑똑해져라" 같은 반응이 쏟아졌다.

솔직히, 나도 처음엔 손이 갔다. 그런데 잠깐. 정말 65줄로 해결되는 문제일까?

일단, 뭐가 들어있길래

CLAUDE.md의 핵심은 4가지 원칙이다.

Think Before Coding. 코드부터 치지 말고 가정을 명시하고, 모르겠으면 질문하고, 혼란스러우면 멈춰라.

Simplicity First. 요청 안 한 기능, 추상화, 에러 처리를 추가하지 마라. 200줄로 짠 걸 50줄로 줄일 수 있으면 다시 써라.

Surgical Changes. 요청된 부분만 고쳐라. 옆에 있는 코드가 마음에 안 들어도 건드리지 마라.

Goal-Driven Execution. "기능 추가해줘" 대신 "이 테스트를 통과시켜줘"처럼 검증 가능한 목표로 바꿔서 실행하라.

LLM으로 코딩해본 사람이라면 고개가 끄덕여질 것이다. Claude가 멀쩡한 코드를 갑자기 리팩토링하거나, 안 부탁한 에러 핸들링을 잔뜩 붙이거나, "이왕 하는 김에" 옆 파일까지 손대는 경험, 다들 있지 않은가.

그런데 말입니다

여기서 한 발 물러서 생각해보자.

이건 프롬프트 엔지니어링의 재포장이다. "구체적으로 지시하면 더 잘 따른다"는 건 LLM 사용의 기본 중 기본이다. CLAUDE.md는 이 당연한 원리를 깔끔하게 정리한 것이지, 새로운 기술적 돌파구가 아니다. Karpathy의 이름값과 GitHub 바이럴이 결합되면서 마법의 해결책처럼 보이는 것뿐이다. 참고로, 이 파일은 Karpathy 본인이 만든 것도 아니다. 그의 비판에서 "영감을 받아" 커뮤니티가 작성한 것이다.

"넣었더니 나아졌다"는 확증 편향일 수 있다. 같은 작업을 CLAUDE.md 유무로 통제 실험해본 사람이 얼마나 될까. LLM 출력은 본질적으로 확률적이다. 어제 잘 된 프롬프트가 오늘 엉뚱한 결과를 낼 수 있다. 잘 된 케이스만 기억하고 "역시 효과 있어!"라고 말하기 쉬운 구조다.

원칙끼리 충돌한다. "Simplicity First"는 최소한의 코드를 요구하는데, "Goal-Driven Execution"은 테스트를 먼저 작성하라고 한다. 테스트 작성 자체가 추가 작업량 아닌가? 또 "요청 안 한 에러 처리를 하지 마라"는 원칙은 프로토타입에선 맞지만, 프로덕션 코드에서는 위험한 조언이 될 수 있다.

근본적인 한계를 가린다. LLM의 과잉 행동은 모델 아키텍처와 학습 데이터에서 오는 구조적 문제다. 프롬프트로 억제할 수는 있지만, 컨텍스트가 길어지면 65줄의 가이드라인은 점점 희미해진다. 10개 파일을 동시에 편집하는 복잡한 작업에서 이 원칙들이 얼마나 살아남을까?

그래서, 진짜 효과를 보려면

CLAUDE.md의 방향 자체는 틀리지 않았다. 문제는 "범용 65줄을 복붙하면 끝"이라는 접근이다. 실제로 효과를 보려면 이렇게 해보자.

범용 원칙 대신 프로젝트 고유 컨텍스트를 넣어라. "단순하게 작성하라"는 모델이 이미 안다. 그보다 "우리는 monorepo이고, packages/ 간 의존성을 함부로 추가하지 마라", "DB 마이그레이션은 반드시 backward compatible하게"처럼 우리 프로젝트에서 실제로 반복되는 실수를 막는 지시가 훨씬 강력하다.

"하지 마라"보다 "이렇게 해라"로 써라. LLM은 금지 지시를 잘 어긴다. "불필요한 추상화를 하지 마라" 대신 "새 함수를 만들기 전에, 기존 코드에서 같은 역할을 하는 함수가 있는지 먼저 확인하고 알려줘"가 훨씬 잘 먹힌다.

팀에서 실제로 겪은 실수를 기반으로 점진적으로 쌓아가라. 처음부터 완벽한 가이드라인을 만들 필요 없다. Claude가 실제로 삽질한 케이스를 모아서 하나씩 추가하면 된다. 살아있는 문서로 운영하는 것이다.

길이를 관리하라. 가이드라인이 길어질수록 모델이 앞부분을 무시할 확률이 높아진다. 정말 중요한 규칙 10~15개 이내, 우선순위 높은 것을 위에 배치하자.

효과를 검증하라. 같은 작업을 가이드라인 유무로 비교해보고, 실제로 차이가 나는 항목만 남겨라. "있으면 좋겠지" 수준의 항목은 컨텍스트만 차지한다.

마무리

CLAUDE.md 열풍은 개발자들이 LLM 코딩 도구에 느끼는 공통된 불만 — 과잉 행동, 엉뚱한 가정, 불필요한 리팩토링 — 을 정확히 건드렸기 때문에 터졌다. 그 불만은 진짜이고, 프롬프트로 행동을 유도하는 방향도 맞다.

다만 범용 65줄을 복붙하는 것과 우리 팀·우리 코드베이스에 맞는 가이드라인을 만드는 것은 전혀 다른 이야기다. 전자는 5초면 되지만 효과가 불확실하고, 후자는 시간이 들지만 실제로 동작한다.

결국 AI 코딩 도구를 잘 쓰는 비결은, 은탄환을 찾는 게 아니라 내 맥락을 AI에게 잘 전달하는 근육을 꾸준히 기르는 것이다. 65줄짜리 파일이 그 여정의 출발점이 될 수는 있지만, 종착점은 아니다.