원문 제목: Karpathy의 4 CLAUDE.md 규칙은 Claude의 실수를 41%에서 11%로 줄였습니다. 30개의 코드베이스 이후, 더해진 8가지

역자 주: 2026년 1월, Andrej Karpathy는 Claude가 코드를 작성하는 방식에 대한 불평을 하면서, AI 프로그래밍 워크플로에서 매우 중요한 것으로 보이는 작은 파일인 CLAUDE.md를 언급했습니다. Forrest Chang은 그 이후 이러한 문제들을 4가지 행동 규칙으로 정리하여 Claude가 코딩할 때 발생하는 일반적인 오류를 억제하려고 했습니다: 암묵적 가정, 과도한 엔지니어링, 관련이 없는 코드를 손상시키는 오류, 그리고 명확한 성공 기준의 부재.

그러나 몇 달 후, Claude Code의 사용 사례는 더 이상 "모델이 코드 한 줄을 작성하는 것"만이 아니었습니다. 단계별 Agent, 후크 체인 트리거, 스킬 로딩 및 다중 코드베이스 협업이 일상화되면서, 새로운 실패 패턴도 나타나기 시작했습니다: 모델이 장기 작업에서 통제를 잃음, 테스트는 통과했지만 실제 논리를 검증하지 않음, 이전이 완료되었지만 암묵적으로 오류를 건너뛰고, 다른 코드 스타일이 잘못 섞임.

이 저자는 6주 동안 30개의 코드베이스에서 테스트한 후, Karpathy의 초기 4가지 규칙에 8가지 규칙을 추가했으며, AI 프로그래밍이 한 번의 보충에서 에이전트 기반 협업으로 발전함에 따른 새로운 문제를 다루려고 노력했습니다.

아래는 원문입니다:

2026년 1월 말, Andrej Karpathy는 Claude의 코드 작성 방식에 대한 트윗을 게시했습니다. 그는 설명이 없는 상황에서의 잘못된 가정, 장황한 복잡성, 그리고 수정하지 말아야 할 코드에 무관한 손상을 초래하는 세 가지 전형적 문제를 지적했습니다.

Forrest Chang은 이 트윗을 보고 불평 사항을 4가지 행동 규칙으로 정리하여 별도의 CLAUDE.md 파일에 작성한 후 GitHub에 게시했습니다. 이 프로젝트는 출시 첫 날부터 5,828개의 Star를 획득했고, 2주 내에 60,000회 북마크되었으며 현재 120,000개의 Star를 보유하며, 2026년 가장 빠르게 성장한 단일 파일 코드 리포지토리가 되었습니다.

이후, 저는 6주 동안 30개의 코드베이스에서 이를 테스트했습니다.

이 4가지 규칙은 실제로 효과가 있습니다. 이러한 규칙에 부합하는 작업에서는 이전에 약 40% 나오던 오류가 3% 미만으로 감소했습니다. 그러나 문제는이 템플릿이 원래 1 월에 Claude가 코드를 작성할 때 발생한 오류를 해결하기 위해 설계되었다는 것입니다.

2026 년 5 월이 되자, Claude Code 생태계가 직면한 문제는 다음과 같았습니다: 에이전트 간 충돌, 후크 체인 트리거, 스킬 로드 충돌 및 세션 간 다단계 작업 플로우 중단 등.

그래서, 나는 추가 8가지 규칙을 적용했습니다. 다음은 완전한 12가지 규칙 버전 CLAUDE.md입니다. 각각이 추가되는 이유와 기본 Karpathy 템플릿에서 어느 4곳에서 조용히 실패할 것인지에 대해 설명합니다.

설명을 건너뛰고 직접 복사하여 사용하려는 경우 전체 파일은 문서 맨 아래에 있습니다.

왜 중요한가

Claude Code의 CLAUDE.md는 전체 AI 프로그래밍 기술 스택 중에서 가장 과소 평가된 파일입니다. 대부분의 개발자들은 일반적으로 3가지 유형의 오류를 저지를 때가 많습니다:

첫째, 선호도 휴지통으로 간주하여 자신의 모든 습관을 그대로 넣고 마지막에는 4000개 이상의 토큰으로 팽창하여 규칙 준수율이 30%로 떨어집니다.

둘째, 아예 사용하지 않고 매번 다시 prompt합니다. 이러면 5배의 토큰이 낭비되며 서로 다른 세션 사이에 일관성이 부족합니다.

셋째, 템플릿을 복사한 후 더는 신경쓰지 않습니다. 이는 2주 정도 효과가 있을 수 있지만 코드베이스가 변경됨에 따라 무의식 중에 실효성을 잃을 수 있습니다.

Anthropic의 공식 문서는 명백합니다: CLAUDE.md는 본질적으로 건의사항일뿐입니다. Claude는 대략 80%의 시간을 이를 따를 것입니다. 200행을 넘으면 준수율이 뚜렷하게 감소합니다. 중요한 규칙이 소음에 묻히기 때문입니다.

Karpathy의 템플릿은 이 문제를 해결했습니다: 1개 파일, 65행, 4가지 규칙. 이것이 최소 기준입니다.

그러나 상한선을 더 높일 수 있습니다. 다음 8가지 규칙을 추가한 후에는, 이것이 2026년 1월에 Karpathy가 불평했던 코드 작성 문제뿐만 아니라 2026년 5월에 발생한 에이전트 조정 문제도 커버하게 됩니다––원본 템플릿이 작성될 때는 이러한 문제들이 존재하지 않았습니다.

초기 4가지 규칙

만약 당신이 아직 Forrest Chang의 저장소를 보지 않았다면, 먼저 이 기본 버전을 확인하세요:

규칙 1: 코딩하기 전에 생각하세요.

가정을 할 때 묵묵히 하지 마세요. 당신의 가정을 명확히하고, trade-off point를 노출하세요. 짐작하기 전에 질문하세요. 더 간단한 해결책이 존재할 때는 적극적으로 반대의견을 제시하세요.

규칙 2: 간단함 우선.
문제를 해결할 수 있는 가장 적은 양의 코드를 사용하세요. 상상 속의 기능을 추가하지 마세요. 일회성 코드에 추상화 계층을 설계하지 마세요. 만일 시니어 엔지니어가 오버컴플리케이션으로 판단할 경우, 단순화해야 합니다.

규칙 3: 정형적 수정.
반드시 수정해야 하는 부분만 변경하세요. 인접 코드, 주석 또는 형식을 "최적화"하지 마세요. 망가진 것이 없는 한 리팩터링하지 마세요. 기존 스타일을 유지하세요.

규칙 4: 목표 중심 실행.
먼저 성공기준을 정의한 후, 반복하여 검증을 완료할 때까지 진행하세요. Claude에게 각 단계마다 어떻게 해야 하는지 알려주지 마세요. 대신, 성공적인 결과가 어떻게 되어야 하는지를 알려준 후, 스스로 반복하도록 하세요.

이 네 가지 규칙은 '감독 없는 Claude Code 세션'에서 본 약 40%의 실패 패턴을 해결할 수 있습니다. 약 60%의 문제는 아래 빈 영역에 숨어 있습니다.

내가 추가한 8 가지 규칙과 그 이유

각각의 규칙은 실제 순간에서 나온 것입니다: Karpathy의 원래 4 가지 규칙이 충분하지 않았을 때. 아래에서 그 시나리오를 먼저 설명한 후, 해당 규칙을 제시하겠습니다.

규칙 5: 모델이 비언어적 작업을 수행하지 않게 하세요

Claude로 처리 가능: 분류, 초안 작성, 요약, 비구조화 된 텍스트에서 정보 추출. Claude로 처리하지 말아야 할 것: 라우팅, 재시도, 상태 코드 처리, 결정적 전환. 만약 상태 코드가 질문에 대답했다면, 단순 코드로 그 질문에 답하세요.

Karpathy의 규칙은 이를 다루지 않았습니다. 그 결과 모델은 결정적 코드가 처리해야 할 문제를 처리하기 시작했습니다: API 호출을 다시 시도해야 하는지, 메시지를 어떻게 라우팅해야 하는지, 처리를 언제 업그레이드해야 하는지. 결과는 매주 판단이 달랐습니다. 당신은 토큰당 0.003달러씩 과금되고, 불안정한 if-else로 이어지는 것입니다.

그 순간은 이와 같았습니다: 코드 부분이 Claude를 호출하여 '503를 만났을 때 재시도해야 하는지 여부를 판단'하도록합니다. 처음에는 잘 작동했지만 두 주 후 갑자기 불안정해졌습니다. 이는 모델이 요청 바디까지 판단 맥락으로 간주하기 시작했기 때문입니다. 재시도 전략은 무작위로 변화했으며, 프롬프트 자체가 무작위이기 때문에 그랬습니다.

규칙 6: 하드 토큰 예산 설정 및 예외 없음

단일 작업 예산: 4,000 토큰. 단일 세션 예산: 30,000 토큰. 작업이 예산 한도에 근접하면 현재 상태를 요약한 후 다시 시작합니다. 강제로 진행하지 마세요. 예산 초과 문제를 명확히 드러내는 것은 조용히 예산을 초과하는 것보다 좋습니다.

예산 제한이 없는 CLAUDE.md는 공백 수표와 같습니다. 각 루프마다 통제를 잃을 수 있고 50,000 토큰의 맥락 폐기물이 될 수 있습니다. 모델은 자체적으로 중지되지 않습니다.

그 순간은 이랬습니다: 디버그 세션이 90분 동안 계속되었습니다. 모델은 계속해서 8KB 오류 메시지를 중심으로 반복 수정하며 점차 어떤 수정을 시도했는지 잊어가고 있었습니다. 마지막으로 내가 거부한 수정 사항들을 제안하기 시작했습니다. 토큰 예산이 있다면, 이 프로세스는 12분에 종료되어야 합니다.

규칙 7: 충돌을 드러내고 평균 트레이드오프 하지 마세요

코드 라이브러리에 이미 존재하는 두 가지 모드가 서로 충돌하는 경우, 그것들을 섞지 마세요. 더 업데이트되거나 더 많이 테스트된 모드 중 하나를 선택하고 이유를 설명하며 다른 모드를 나중에 정리해야 함을 표시하세요. 두 규칙 세트를 모두 충족하려는 \"평균 코드\"는 최악의 코드입니다.

코드 라이브러리의 두 부분이 서로 충돌할 때, Claude는 양쪽을 동시에 만족시키려고 시도하며 결과는 일관성 없는 코드가 됩니다.

그 순간은 이랬습니다: 코드 라이브러리에는 두 가지 오류 처리 모드가 있었습니다. 하나는 async/await를 사용한 명시적 try/catch이고, 다른 하나는 전역 오류 경계였습니다. Claude가 작성한 새 코드는 두 가지를 모두 사용했습니다. 결과로 오류 처리가 두 번 이루어졌습니다. 나는 왜 오류가 두 번 소멸되었는지 이해하는 데 30분이 걸렸습니다.

규칙 8: 먼저 읽고 나서 작성하세요

파일에 새 코드를 추가하기 전에 해당 파일의 내보내기 내용, 직접 호출자, 및 명백히 관련된 공유 유틸리티 함수를 먼저 읽으세요. 기존 코드의 구성을 이해하지 못하면 직접 묻고 바로 추가하지 마세요. \"나에게는 이 부분이 관련이 없는 것 같은데\"는 이 코드 라이브러리에서 가장 위험한 문구입니다.

카파시의 \"외과 수술적인 수정\"은 Claude에게 이웃 코드를 수정하지 말라고 말했지만, Claude에게 먼저 이해하라고는 말하지 않았습니다. 이것이 없다면 Claude는 30줄 이상 떨어진 코드와 충돌하는 새 코드를 작성합니다.

그 순간은 이렇게 진행되었습니다: Claude는 기존 함수 옆에 완전히 동일한 기능을 가진 함수를 추가했는데, 원래 함수를 먼저 보지 않았기 때문입니다. 두 함수는 동일한 작업을 수행합니다. 그러나 import 순서로 인해 새 함수가 기존 함수를 덮어씁니다. 그리고 기존 함수는 사실상 6개월 동안의 유일한 기준으로 자리 잡았습니다.

규칙 9: 테스트는 선택 사항이 아니지만, 테스트 자체는 목표가 아닙니다

모든 테스트는 "이 동작이 왜 중요한가"를 코딩해야 하며, "그것이 무엇을 수행하는가"만으로는 충분하지 않습니다. `expect(getUserName()).toBe('John')`과 같은 테스트는 실제로 함수가 하드 코딩된 ID를 받는 경우 가치가 없습니다. 비즈니스 로직이 변경되었을 때 실패하는 테스트를 작성할 수 없다면, 해당 함수 자체에 문제가 있습니다.

Karpathy의 "목표 중심 실행"은 테스트가 성공 기준으로 사용될 수 있다는 것을 시사합니다. 그러나 실제로 Claude는 "테스트 통과"를 유일한 목표로 삼아, 겉핥기 테스트를 통과하는 코드를 작성하여 다른 부분을 망가뜨리게 됩니다.

그 순간은 이렇게 진행되었습니다: Claude는 인증 함수에 대해 12개의 테스트를 작성했으며, 모두 통과했습니다. 그러나 프로덕션 환경에서 인증 로직이 망가졌습니다. 이러한 테스트는 함수가 "무언가를 반환했는지"를 확인하는 것에 지나치며, 올바른 값을 반환하는지는 확인하지 않습니다. 함수가 테스트를 통과하는 이유는 상수를 반환하기 때문입니다.

규칙 10: 오랜 시간 실행되는 작업에는 체크포인트가 필요합니다

여러 단계로 이뤄진 작업에서는 각 단계를 완료한 후에 지금까지 한 일, 검증한 일, 남은 일을 요약해야 합니다. 이해할 수 없는 상태에서 계속해서 진행하면 안 됩니다. 혼란스러워지면 멈추고 현재 상태를 다시 설명해야 합니다.

Karpathy의 템플릿 상호작용은 일회성입니다. 그러나 실제 Claude Code 작업은 종종 여러 단계로 이루어지며, 20개 파일을 걸쳐 리팩터링하거나 세션에서 기능을 빌드하거나 여러 커밋을 통해 디버깅할 수 있습니다. 체크포인트가 없으면 한 번 틀리면 앞으로의 모든 진전이 사라질 수 있습니다.

그 순간은 이렇게 진행되었습니다: 6단계 리팩터링 작업에서 4단계에서 오류가 발생했습니다. 문제를 발견할 때, Claude는 이미 오류 상태에서 5단계와 6단계를 완료했습니다. 문제 해결과정은 전체 작업을 다시 시작하는 것보다 오래 걸렸습니다. 체크포인트가 있었으면 4단계에서 문제를 발견할 수 있었을 겁니다.

규칙 11: 약속이 새로운 아이디어보다 우선합니다

만약 코드베이스가 snake_case를 사용하고 당신이 camelCase를 더 선호한다면: snake_case를 사용하세요. 만약 코드베이스가 class-based 컴포넌트를 사용하고 당신이 hooks를 더 선호한다면: class-based 컴포넌트를 사용하세요. 다른 의견은 다른 토론입니다. 코드베이스 내에서 일관성은 개인적인 선호보다 우선합니다. 만약 당신이 특정 약속이 해로울 것으로 생각한다면 명확히 제안하세요. 조용히 fork한 경로를 열지 마세요.

이미 성숙한 패턴이 존재하는 코드베이스에서, Claude는 자신만의 스타일을 도입하는 것을 좋아합니다. 그 스타일이 "더 나은" 경우에도, 두 번째 세트의 패턴을 도입하는 것 자체가 어떤 단일 패턴보다도 더 나쁩니다.

그 순간은 이러했습니다: Claude는 class 컴포넌트를 기반으로 하는 React 코드베이스에 hooks를 도입했습니다. 이는 실제로 작동할 수 있었습니다. 그러나 동시에 그것은 componentDidMount에 의존하는 기존 테스트 패턴을 파괴했고, 결국 그것을 제거하고 다시 쓰는 데 반이 소요되었습니다.

규칙 12: 명시적인 실패를 원하며, 조용한 실패를 원치 않습니다

만약 어떤 일이 성공적으로 이루어졌는지 확신할 수 없다면, 명확히 말하세요. 만약 30 개의 레코드가 조용히 건너뛰어졌다면, "마이그레이션이 완료되었다"라고 말할 수 없습니다. 만약 어떤 테스트를 건너뛰었다면, "테스트 통과"라고 말할 수 없습니다. 만약 요구된 경계 조건을 확인하지 않았다면, "기능 사용 가능"하다고 말할 수 없습니다. 불확실성을 기본으로 노출하고 숨기지 마세요.

Claude의 가장 비싼 실패는 종종 성공처럼 보이는 실패입니다. 함수가 "작동한다" 하지만 잘못된 데이터를 반환하는 경우도 있고; 한 번의 마이그레이션이 "완료되었지만 30 개의 레코드를 건너 뛰는 경우도 있으며; "테스트 통과"하지만 어서션이 잘못되었다는 이유로 통과하는 경우도 있습니다.

그 순간은 이러했습니다: Claude가 데이터베이스 마이그레이션 한 번 "성공적으로 완료되었다"고 말했습니다. 그러나 실제로는 14%의 트리거 제약 충돌 레코드가 조용히 건너뛰어졌습니다. 건너뛰기 동작은 로그에 기록되었지만 명시적으로 노출되지 않았습니다. 11일 후, 보고서 데이터가 비정상적으로 작동하기 시작할 때 문제를 발견했습니다.

데이터 결과

6주 동안, 같은 세트의 50 가지 대표적인 작업을 추적했으며, 30 개의 코드베이스를 커버하여 세 가지 구성을 테스트했습니다.

오류율은 원래 의도와 일치하도록 작업을 수정하거나 다시 작성해야 하는 비율을 나타냅니다. 포함된 오류는 다음을 포함합니다. 조용한 가정 오류, 과도한 공학 문제, 무관한 파괴, 조용한 실패, 약속 위반, 충돌 적정화, 체크포인트 누락.

준수율은 특정 규칙이 적용될 때 Claude 가 이 규칙을 명시적으로 적용할 가능성을 의미합니다.

정말 흥미로운 결과는 오류율이 41%에서 3%로 줄어든 것만이 아닙니다. 더 중요한 것은 4가지 규칙에서 12가지 규칙으로 확장되었을 때, 준수 부담이 거의 증가하지 않았다는 점입니다. 준수율은 단지 78%에서 76%로 변했지만, 오류율은 8포인트 더 떨어졌습니다. 새로운 규칙은 이전 4가지 규칙이 처리하지 못한 실패 모델을 다루며, 이 규칙들은 서로 동일한 주의력 예산을 경쟁하지 않았습니다.

Karpathy 템플릿의 은밀한 실패 지점

새로운 규칙을 추가하지 않더라도 기존 4가지 규칙 템플릿은 최소한 4개의 지점에서 충분하지 않습니다.

첫째, 긴 실행 시간을 필요로 하는 에이전트 작업.
Karpathy의 규칙은 주로 Claude가 코드를 작성하는 그 순간에 해당합니다. 그러나 Claude가 여러 단계로 이루어진 파이프라인을 실행하는 동안에는 어떻게 될까요? 원본 템플릿에는 룰 예산이 없고, 체크포인트 룰도 없으며 "큰 소리로 실패" 규칙도 없습니다. 따라서 파이프라인은 천천히 드리프트됩니다.

둘째, 다중 코드베이스 일관성.
"기존 스타일과 일치"는 기본적으로 하나의 스타일만 고려합니다. 그러나 12개의 서비스가 있는 모노 레포에는 Claude가 어느 스타일을 따를지 결정해야 합니다. 원래 규칙은 그에게 선택지를 알려주지 않습니다. 따라서 그는 무작위로 선택하거나 여러 스타일을 균등하게 혼합해야 합니다.

셋째, 테스트 품질.
"목표 중심 실행"은 "테스트 통과"를 성공으로 간주하지만, 테스트 자체가 의미가 있어야 한다는 것을 명시하지 않습니다. 결과적으로 Claude는 거의 아무런 유효성 검사도 수행하지 않고 테스트 작성하면서 스스로를 잘 알고 있는 것으로 오해합니다.

넷째, 프로덕션 및 프로토타입 단계의 차이.
동일한 4가지 규칙은 프로덕션 코드의 과도한 공학화를 방지할 수 있지만, 프로토타입 개발을 느리게 할 수도 있습니다. 왜냐하면 프로토타입 단계에서는 종종 방향을 명확히 하기 위해 100줄의 탐색적인 매듭 코드가 필요하기 때문입니다. Karpathy의 "단순 우선"은 초기 코드에서 쉽게 과도하게 작동할 수 있습니다.

이 8가지 새로운 규칙은 Karpathy의 원래 4가지 규칙을 대체하는 것이 아니라, 그들의 공백을 보완하기 위한 것입니다. 원본 템플릿은 2026년 1월의 거의 자동 완성 형식의 코드 작성 시나리오에 해당하며, 그러나 2026년 5월에는 Claude Code가 에이전트 주도형, 다단계, 다중 코드베이스 협업 환경으로 진화했습니다. 두 상황이 다르기 때문입니다.

어떤 방법이 효과가 없었는가

이 12가지 규칙을 최종적으로 확정하기 전에 제가 시도한 다른 몇 가지 방법들이 있습니다.

Reddit / X에서 본 규칙을 추가.
이 중 대부분은 Karpathy의 원래 4가지 규칙을 다른 용어로 반복한 것이거나 Tailwind 클래스를 항상 사용하라는 것과 같이 일반화할 수 없는 도메인별 규칙이었기 때문에 마지막에 해당 내용을 삭제했습니다.

12가지 이상의 규칙.
제가 테스트한 최대 수는 18가지입니다. 14가지 이상이 되면 준수율이 76%에서 52%로 떨어집니다. 200줄이라는 제한이 실제로 존재합니다. 이 길이를 초과하면 Claude는 규칙을 하나씩 읽는 것이 아니라 "여기에 규칙이 있습니다"라는 패턴 매칭을 시작합니다.

특정 도구에 의존하는 규칙.
예를 들어 "항상 eslint를 사용하라"는 규칙은 프로젝트에 eslint가 설치되어 있지 않으면 그 규칙이 작동하지 않으며, 또한 조용히 실패합니다. 후에 이를 구체적인 도구에 의존하지 않는 표현으로 변경하여 "eslint를 사용하라"를 "코드베이스에서 이미 강제 적용된 스타일을 따르라"로 바꿨습니다.

규칙을 표시하는 대신 CLAUDE.md에 예제를 제공.
예제는 규칙보다 많은 문맥을 소비합니다. 세 가지 예제가 약 10가지 규칙에 상당하며 Claude가 쉽게 예제에 과적합됩니다. 규칙은 추상적이고 예제는 구체적입니다. 그러므로 규칙을 사용해야 합니다.

"조금 조심하라", "진지하게 고민하라", "조금 더 집중하라".
이러한 것들은 모두 소음입니다. 이러한 유형의 지시사항의 준수율이 약 30%로 떨어졌습니다. 이유는 이러한 지시사항이 확인할 수 없기 때문입니다. 후에 이를 "가정 명시", "명확하게 표현하라"와 같이 더 구체적인 명령형 규칙으로 대체했습니다.

Claude에게 "시니어 엔지니어처럼" 해달라고 지시.
이 방법은 효과가 없었습니다. Claude는 이미 자신을 시니어 엔지니어로 여기고 있습니다. 실제 문제는 Claude가 그렇게 수행하는지 여부에 있지만, 명령형 규칙은 이 차이를 줄일 수 있지만 정체성 단서는 그렇지 않습니다.

12가지 규칙 버전 CLAUDE.md

다음은 직접 복사하여 사용할 수 있는 전체 버전입니다.

현재 이 내용을 외부에 표시할 수 없습니다

이를 저장하여 저장소 루트 디렉토리에 CLAUDE.md로 저장하십시오. 이 12가지 규칙 아래에 기술 스택, 테스트 명령, 오류 패턴 등과 같은 프로젝트 전용 규칙을 추가하십시오. 전체 길이가 200줄을 초과하지 않도록하십시오. 이를 초과하면 규칙 준수율이 뚜렷하게 감소합니다.

설치 방법

두 단계면 됩니다:

1. Karpathy의 4가지 기본 규칙을 CLAUDE.md 파일에 추가합니다.
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. 이 문서의 규칙 5~12를 아래에 붙여 넣습니다.

파일을 저장할 때 저장지의 루트 디렉토리에 저장하세요. 여기서 >> 가 중요한데, 이것은 CLAUDE.md에 추가하고 덮어쓰기하지 않음을 의미합니다. 이미 작성된 프로젝트 특정 규칙을 덮어쓰지 않습니다.

마인드 모델

CLAUDE.md는 희망 목록이 아니라 여러분이 이미 관찰한 구체적인 실패 패턴을 막기 위한 행동 계약서입니다.

각 규칙은 한 가지 질문에 대답해야 합니다: 어떤 오류를 방지할까요?

Karpathy의 4가지 규칙은 2026년 1월에 본 실패 패턴을 막습니다: 무성명 가정, 과도한 엔지니어링, 관련 없는 파괴, 약한 성공 기준. 이들은 기본입니다. 건너뛰지 마세요.

저는 추가한 8가지 규칙은 2026년 5월 이후의 새로운 실패 패턴을 막습니다: 예산 제약이 없는 Agent 루프, 체크포인트 없는 다단계 작업, 핵심 논리를 테스트했다고 생각했지만 실제로 테스트하지 않은 테스트, 그리고 무성공을 무성공으로 포장하는 문제. 이들은 증분 패치입니다.

물론, 실제 효과는 사람마다 다릅니다. 당신이 다단계 파이프라인을 실행하지 않는다면, 규칙 10은 중요하지 않을 수 있습니다. 코드베이스가 이미 lint로 강제 실행되고 통일된 스타일만 있는 경우 규칙 11은 중복입니다. 이 12가지 규칙을 다 읽은 후, 실제로 당신이 실수한 부분에 집중하고, 그 이외의 부분은 삭제하세요.

실제 실패 패턴에 맞춘 6가지 규칙 버전의 CLAUDE.md가 있으면, 사용하지 않을 6가지 규칙이 있는 12가지 규칙 버전보다 낫습니다.

맺음말

2026년 1월 Karpathy의 그 트윗은 본질적으로 불평이었습니다. Forrest Chang은 그것을 4가지 규칙으로 변화시켰습니다. 결국, 12만 명의 개발자가 이 결과에 스타를 부여했습니다. 거기에서 대부분의 사람들은 오늘도 여전히 그 4가지 규칙만 사용하고 있습니다.

모델이 발전했고, 생태계도 변화했습니다. 다단계 에이전트, 후크 체인 트리거, 스킬 로딩, 다중 코드 라이브러리 협업 — 이러한 기능들은 Karpathy가 그 트윗을 쓴 때 아직 존재하지 않았습니다. 원래의 4가지 규칙은 이러한 문제를 해결하지 못했습니다. 이전 규칙들이 틀린 것은 아니었지만 불완전했습니다.

8가지 규칙이 추가되었습니다. 6주 동안, 30개의 코드 라이브러리를 대상으로 한 테스트. 오류율이 41%에서 3%로 감소했습니다.

오늘 밤 이 기사를 즐겨찾기에 추가하고, 이 12가지 규칙을 당신의 CLAUDE.md에 붙여넣으세요. 만약 이것이 당신에게 Claude의 우회를 줄여준다면, 환영합니다.

[원문 링크]

BlockBeats 공식 커뮤니티에 참여하세요:

Telegram 구독 그룹：https://t.me/theblockbeats

Telegram 토론 그룹：https://t.me/BlockBeats_App

Twitter 공식 계정：https://twitter.com/BlockBeatsAsia