코딩 기호가 적힌 종이
지금 CLAUDE.md를 다시 봐야 합니다
CLAUDE.md는 Claude Code가 모든 세션 시작 시 자동으로 읽는 파일입니다. 한 번만 작성해두면 매 대화마다 같은 지시를 반복할 필요가 없습니다. 작업 규칙, 프로젝트 컨텍스트, 코드 스타일을 한 곳에 정리하는 가장 강력한 파일입니다.
문제는 대부분 잘못 쓰고 있다는 점입니다. 선호사항을 4,000토큰까지 채워 넣어 컴플라이언스가 30%로 떨어지거나, 아예 안 쓰고 매번 프롬프트로 떼우거나, 한 번 복사한 템플릿을 그대로 두고 잊어버립니다.
2026년 1월 말, Andrej Karpathy가 X에 Claude의 코딩 실수를 3가지 패턴으로 정리했습니다. 침묵하는 잘못된 가정, 과한 복잡화, 손대지 말아야 할 코드에 손대는 것. Forrest Chang은 이 내용을 4개 규칙으로 정리한 CLAUDE.md 한 장을 GitHub에 올렸고, 24시간 만에 5,828 스타, 2주 만에 60,000 북마크, 현재 120,000 스타를 기록했습니다.
그런데 4규칙은 2026년 1월 시점의 문제만 다룹니다. 그사이 Claude Code 생태계는 에이전트 오케스트레이션, 다단계 워크플로우, 훅 캐스케이드, 스킬 로딩 등 새로운 문제를 만들어냈습니다.
이 글에서는 Karpathy의 원본 4규칙과, 30개 코드베이스에서 6주간 테스트한 뒤 추가한 8규칙을 모두 정리합니다. 실수율은 41% → 3%까지 떨어졌습니다.
CLAUDE.md 작성의 3가지 원칙
규칙을 보기 전에 짚어야 할 원칙이 있습니다.
200줄을 넘기지 마세요. 200줄을 넘으면 중요한 규칙이 노이즈에 묻히고 컴플라이언스가 급락합니다.
규칙은 14개를 넘기지 마세요. 18개까지 테스트한 결과 14개를 넘으면 컴플라이언스가 76% → 52%로 떨어졌습니다.
모든 규칙은 "이 규칙이 어떤 실수를 방지하는가?"에 답할 수 있어야 합니다. 답할 수 없으면 빼세요.
이제 12가지 규칙을 하나씩 봅니다.
규칙 1: 코딩 전에 먼저 생각하기 (Karpathy 원본)
가정을 명시적으로 말할 것.
불확실하면 추측하지 말고 물어볼 것.
모호한 부분이 있으면 여러 해석을 제시할 것.
더 간단한 접근이 있으면 반박할 것.
혼란스러우면 멈추고 무엇이 불분명한지 말할 것.방지하는 실수: Claude가 본인 추측을 사실인 양 가정하고 그 위에 코드를 쌓는 경우. 가장 비싼 실수 유형입니다.
규칙 2: 단순함을 우선 (Karpathy 원본)
문제를 해결하는 최소한의 코드만 작성.
요청에 없는 기능은 추가 금지.
일회용 코드에 추상화 금지.
시니어 엔지니어가 "과하다"고 할 만하면 단순화.방지하는 실수: 요청하지 않은 기능 추가, 일회용 코드에 추상화 레이어 도입, 50줄로 끝날 일을 200줄로 만드는 패턴.
규칙 3: 외과수술 같은 변경 (Karpathy 원본)
꼭 필요한 곳만 건드릴 것.
주변 코드, 주석, 포매팅을 "개선"하지 말 것.
망가지지 않은 것을 리팩토링하지 말 것.
기존 스타일에 맞출 것.방지하는 실수: 부탁받지 않은 영역까지 손대는 행위. 직교(orthogonal)로 보이는 코드를 무심코 "개선"하는 것이 가장 흔한 사고의 원인입니다.
규칙 4: 목표 기반 실행 (Karpathy 원본)
성공 기준을 정의할 것.
검증될 때까지 반복할 것.
단계를 따르지 말고, 성공 조건을 정의하고 반복할 것.방지하는 실수: 단계만 따라가다 정작 결과가 틀리는 경우. 강한 성공 기준이 있어야 Claude가 자율적으로 루프를 돌 수 있습니다.
여기까지가 Karpathy의 원본 4규칙입니다. 30개 코드베이스 테스트에서 실수율을 약 41% → 11%로 줄였습니다. 이 4개만으로도 시작할 가치가 충분합니다.
문제는 나머지 11%입니다. 여기서부터는 2026년 5월 시점에서 추가된 8규칙을 봅니다.
규칙 5: 모델은 판단이 필요한 일에만 쓸 것
Claude를 쓰는 곳: 분류, 초안 작성, 요약, 비정형 텍스트 추출.
Claude를 쓰지 말 것: 라우팅, 재시도, 상태 코드 처리, 결정론적 변환.
상태 코드가 답할 수 있는 질문이라면, 코드가 답하게 할 것.언제 필요한가: Claude로 "503 오류 시 재시도할지 결정"하게 만든 코드가 2주 동안은 잘 작동하다가, 어느 순간부터 모델이 요청 본문을 판단 근거로 읽기 시작하면서 재시도 정책이 무작위로 변합니다. 결정론적인 일은 코드에게 시키는 것이 원칙입니다.
방지하는 실수: "Claude가 똑똑하니까" 어디든 끼워 넣다가 결정 흐름이 매주 달라지는 비결정성 도입.
규칙 6: 토큰 예산은 권고가 아닙니다
작업당 예산: 4,000 토큰.
세션당 예산: 30,000 토큰.
예산에 근접하면 요약하고 새로 시작.
초과 사실을 표면화할 것. 조용히 넘어가지 말 것.언제 필요한가: 90분 디버깅 세션에서 모델이 같은 8KB 에러 메시지를 두고 반복 시도하다가, 40턴 전에 거절당한 수정안을 다시 제안하는 경우. 토큰 예산이 있었다면 12분 시점에 멈출 수 있습니다.
방지하는 실수: 무한 반복 루프, 같은 컨텍스트 재읽기, 한도 폭발.
규칙 7: 충돌은 평균 내지 말고 표면화할 것
코드베이스 안의 두 패턴이 충돌하면, 섞지 말 것.
하나를 고를 것 (최신 또는 더 검증된 쪽).
이유를 설명하고, 다른 한쪽은 정리 대상으로 표시.
양쪽을 모두 만족시키는 "평균" 코드가 최악의 코드.언제 필요한가: 한 코드베이스에 try/catch 패턴과 글로벌 에러 바운더리 패턴이 공존하는 상황. Claude는 둘 다 만족시키려고 에러 핸들러를 이중으로 작성 합니다. 결과는 같은 에러를 두 번 삼키는 코드입니다.
방지하는 실수: 모순된 패턴을 합쳐 만든 "혼합 패턴"이 코드베이스를 일관성 없게 만드는 것.
규칙 8: 쓰기 전에 읽을 것
파일에 코드를 추가하기 전, 해당 파일의 export, 직접 호출자, 공통 유틸리티를 읽을 것.
기존 코드가 왜 그런 구조인지 모르겠다면, 추가하기 전에 물어볼 것.
"직교로 보입니다"는 이 코드베이스에서 가장 위험한 말입니다.언제 필요한가: Claude가 이미 존재하는 함수 옆에 똑같은 기능의 함수를 새로 만든 경우. 임포트 순서 때문에 새 함수가 우선되고, 6개월간 사용되던 원본은 무시됩니다.
방지하는 실수: 인접 코드를 안 읽고 새로 쓰는 행위. Karpathy의 "Surgical Changes"는 인접 코드를 안 건드리라고 했지, 이해부터 하라고 하진 않았습니다.
규칙 9: 테스트는 행동이 아닌 의도를 검증
모든 테스트는 "왜 이 동작이 중요한가"를 코딩해야 함.
"무엇을 하는가"만으로는 부족함.
비즈니스 로직이 바뀌어도 통과하는 테스트는 잘못된 테스트.언제 필요한가: Claude가 인증 함수에 12개의 테스트를 작성하고 전부 통과시켰는데, 프로덕션에서 인증이 깨진 경우. 테스트는 "함수가 무언가를 반환한다"만 확인하고, 올바른 값을 반환하는지는 확인하지 않았습니다. 함수는 상수를 반환했기 때문에 통과한 것입니다.
방지하는 실수: 의미 없는 통과 테스트로 자신감만 부풀리는 패턴.
규칙 10: 중요한 단계마다 체크포인트
다단계 작업의 각 단계 완료 후: 무엇을 했고, 무엇이 검증됐고, 무엇이 남았는지 요약.
당신이 설명할 수 없는 상태에서 계속 진행하지 말 것.
헤매기 시작하면 멈추고 다시 정리할 것.언제 필요한가: 6단계 리팩토링에서 4단계가 잘못된 상태로 진행됐고, 알아챘을 때는 이미 5, 6단계가 그 위에 쌓여 있는 상황. 풀어내는 데 처음부터 다시 하는 것보다 더 오래 걸립니다.
방지하는 실수: 다단계 작업의 누적 오류. 한 단계만 늦게 잡아도 전체를 폐기해야 하는 사태.
규칙 11: 컨벤션이 취향을 이깁니다
코드베이스가 snake_case면 snake_case 사용. camelCase 선호한다고 바꾸지 말 것.
클래스 컴포넌트 코드베이스면 클래스 컴포넌트. 훅이 좋다고 도입하지 말 것.
코드베이스 안에서는 일관성 > 취향.
정말 컨벤션이 해롭다고 생각하면, 별도 대화로 표면화할 것. 조용히 분기하지 말 것.언제 필요한가: 클래스 컴포넌트 코드베이스에 Claude가 React 훅을 도입한 경우. 훅 자체는 동작하지만 componentDidMount를 가정한 기존 테스트 패턴이 깨집니다. 제거하고 다시 쓰는 데 반나절이 듭니다.
방지하는 실수: "더 나은" 패턴을 일방적으로 도 입해 코드베이스에 두 가지 패턴이 공존하게 만드는 것.
규칙 12: 큰 소리로 실패할 것
무언가가 작동했는지 확신할 수 없으면, 명시적으로 말할 것.
"마이그레이션 완료"는 30개 레코드가 조용히 누락됐으면 틀린 말.
"테스트 통과"는 하나라도 스킵했으면 틀린 말.
"기능 작동"은 요청받은 엣지 케이스를 확인하지 않았으면 틀린 말.
불확실성을 숨기지 말고 표면화할 것.언제 필요한가: 마이그레이션이 "성공적으로 완료됐다"고 보고됐는데, 실제로는 제약 조건 위반으로 14%의 레코드가 조용히 누락됐던 경우. 11일 뒤 리포트가 이상해지면서 발견됩니다.
방지하는 실수: 가장 비싼 실수 유형 — 성공처럼 보이는 실패.
12규칙 전체 CLAUDE.md (복사해서 쓰세요)
아래 내용을 그대로 CLAUDE.md로 저장하고 프로젝트 루트에 두면 됩니다.
# CLAUDE.md — 12규칙 템플릿
이 규칙은 명시적으로 무효화하지 않는 한 이 프로젝트의 모든 작업에 적용됩니다.
원칙: 사소하지 않은 작업에서는 속도보다 신중함. 사소한 작업은 판단에 맡김.
## 규칙 1 — 코딩 전에 생각하기
가정을 명시적으로 말한다. 불확실하면 추측하지 말고 물어본다.
모호하면 여러 해석을 제시한다.
더 간단한 접근이 있으면 반박한다.
혼란스러우면 멈추고 무엇이 불분명한지 말한다.
## 규칙 2 — 단순함 우선
문제를 해결하는 최소한의 코드. 추측성 코드 금지.
요청에 없는 기능 추가 금지. 일회용 코드에 추상화 금지.
시니어 엔지니어가 과하다고 할 만하면 단순화.
## 규칙 3 — 외과수술 같은 변경
필요한 곳만 건드린다. 본인이 만든 흔적만 정리한다.
주변 코드, 주석, 포매팅을 "개선"하지 않는다.
망가지지 않은 것을 리팩토링하지 않는다. 기존 스타일에 맞춘다.
## 규칙 4 — 목표 기반 실행
성공 기준을 정의하고, 검증될 때까지 반복한다.
단계를 따르지 말고, 성공을 정의하고 반복한다.
## 규칙 5 — 모델은 판단이 필요한 일에만
사용: 분류, 초안 작성, 요약, 추출.
사용 금지: 라우팅, 재시도, 결정론적 변환.
코드가 답할 수 있으면 코드가 답한다.
## 규칙 6 — 토큰 예산은 권고가 아님
작업당 4,000 토큰. 세션당 30,000 토큰.
예산에 근접하면 요약하고 새로 시작.
초과를 표면화한다. 조용히 넘어가지 않는다.
## 규칙 7 — 충돌은 평균 내지 말고 표면화
두 패턴이 충돌하면 하나를 고른다 (더 최신 / 더 검증된 쪽).
이유를 설명하고 다른 한쪽은 정리 대상으로 표시.
충돌하는 패턴을 섞지 않는다.
## 규칙 8 — 쓰기 전에 읽기
코드 추가 전 export, 직접 호출자, 공통 유틸을 읽는다.
"직교로 보입니다"는 위험하다. 구조가 왜 그런지 모르면 묻는다.
## 규칙 9 — 테스트는 의도를 검증
테스트는 "왜 중요한가"를 코딩한다, "무엇을 하는가"가 아니라.
비즈니스 로직이 바뀌어도 통과하는 테스트는 잘못된 테스트.
## 규칙 10 — 중요한 단계마다 체크포인트
각 단계 완료 후 무엇을 했고, 검증됐고, 남았는지 요약.
설명할 수 없는 상태에서 계속 진행하지 않는다.
헤매면 멈추고 다시 정리.
## 규칙 11 — 코드베이스 컨벤션이 취향을 이긴다
코드베이스 안에서는 일관성 > 취향.
컨벤션이 해롭다고 생각하면 표면화한다. 조용히 분기하지 않는다.
## 규칙 12 — 큰 소리로 실패
"완료"는 무엇이라도 조용히 누락됐으면 틀린 말.
"테스트 통과"는 하나라도 스킵됐으면 틀린 말.
불확실성을 숨기지 말고 표면화한다.저장 후 본인 프로젝트 정보(스택, 테스트 명령어, 자주 발생하는 에러 패턴)는 12규칙 아래에 추가하세요. 총 200줄을 넘기지 말 것이 핵심입니다.
실측 데이터 — 41% → 3%
저자는 동일한 50개 대표 작업을 30개 코드베이스에서 6주간 추적했습니다.
구성
실수율
컴플라이언스
CLAUDE.md 없음
41%
—
Karpathy 4규칙만
11%
78%
12규칙 전체
3%
76%
흥미로운 점은 헤드라인 수치(41% → 3%)가 아니라, 4규칙에서 12규칙으로 늘려도 컴플라이언스가 거의 떨어지지 않았다는 것입니다(78% → 76%). 새 규칙이 원본 4규칙과 같은 주의력 예산을 놓고 경쟁하지 않기 때문입니다. 서로 다른 실패 유형을 다루기 때문입니다.
실수에서 배운 것들 — 효과 없었던 것
저자가 시도했다가 빼낸 패턴들입니다.
"신중하게", "정말 집중해서", "시니어처럼": 추상적 지시는 컴플라이언스 30%로 떨어집니다. 검증 가능한 구체적 명령("가정을 명시적으로 말할 것")이 필요합니다.
18개 이상의 규칙: 14개를 넘으면 Claude는 "규칙이 존재한다"는 패턴 매칭만 하고 실제 내용을 읽지 않게 됩니다.
예시 위주의 CLAUDE.md: 예시 3개가 규칙 10개와 같은 컨텍스트를 차지합니다. 예시는 구체적이지만 일반화되지 않습니다.
도구 의존 규칙: "항상 eslint 사용"은 eslint가 없는 환경에서 조용히 깨집니다. "코드베이스의 강제 스타일에 맞출 것"처럼 도구 비의존적 표현이 안전합니다.
⚠️ 주의할 점
CLAUDE.md는 권고입니다. Anthropic 공식 문서도 약 80% 컴플라이언스라고 명시합니다.
200줄을 넘기는 순간 중요한 규칙이 노이즈에 묻혀 컴플라이언스가 급락합니다.
본인 작업과 관련 없는 규칙은 빼세요. 다단계 파이프라인을 안 돌리면 규칙 10은 필요 없습니다. 린트로 스타일이 강제된 코드베이스면 규칙 11은 중복입니다.
6규칙의 실측 CLAUDE.md가 12규칙 중 6개를 안 쓰는 것보다 낫습니다. 본인 실패 패턴에 맞게 추리는 것이 핵심입니다.
자주 묻는 질문
CLAUDE.md는 어디에 둬야 하나요?
프로젝트 루트(./CLAUDE.md) 또는 전역 설정(~/.claude/CLAUDE.md)에 둘 수 있습니다. 프로젝트 루트의 CLAUDE.md는 해당 프로젝트에서만, 전역 파일은 모든 프로젝트에 적용됩니다. 12규칙은 전역에, 프로젝트별 스택 정보는 로컬에 두는 조합이 일반적입니다.
Karpathy 4규칙만 써도 충분한가요?
본인 작업이 단일 파일, 단발성 코딩 작업 위주라면 4규칙으로 충분합니다. 다만 다단계 파이프라인, 모노레포, 에이전트 워크플로우를 다룬다면 8규칙을 더하는 것이 안전합니다.
CLAUDE.md가 길어지면 어떻게 줄이나요?
Anthropic이 제안하는 자기 점검 질문이 있습니다. 각 줄을 보고 "이걸 빼면 Claude가 실수할까?"라고 물어보세요. "아니오"면 삭제하면 됩니다.
Claude는 CLAUDE.md를 항상 따르나요?
아닙니다. 공식 문서 기준 약 80%, 200줄을 넘기면 더 떨어집니다. 따라서 CLAUDE.md는 "강제"가 아닌 "행동 계약"으로 봐야 합니다.
규칙을 더 추가하고 싶을 때는?
Claude Code 창시자 Boris Cherny의 운영 원칙을 따르세요. "Claude가 같은 실수를 두 번 반복하면 CLAUDE.md에 추가한다." 미리 작성하지 말고, 실제 실수에 반응해 추가하는 방식이 컴플라이언스를 유지하는 비결입니다.
원문: Karpathy's 4 CLAUDE.md rules cut Claude mistakes from 41% to 11%. After 30 codebases, I added 8 more
참고 자료:
