karpathy 가 X 에서 claude 에 대해 불평했다. forrest chang 이 그 불평을 네 가지 규칙과 GitHub 저장소로 만들었다. 그 저장소는 몇 주 만에 120,000 개의 스타를 받았다. 이 글을 읽는 대부분의 개발자는 여전히 그 네 가지 규칙만 사용한다. 문제는 그 규칙이 1월에 작성되었다는 것이다. 지금은 2026년 중반이며, Claude Code 생태계는 완전히 달라졌다.
이 글은 완전한 12가지 규칙의 CLAUDE.md, 각 규칙이 존재하는 이유, 각 규칙이 막는 오류, 그리고 원본 템플릿이 조용히 잘못 짚고 있는 부분을 제공한다. 마지막에 붙여넣기만 하면 된다.
CLAUDE.md 란 무엇이며, 대부분의 사람들이 왜 잘못 알고 있는가
CLAUDE.md 는 저장소 루트에 두는 파일이다. Claude Code 는 모든 세션 전에 이 파일을 읽는다. 이것은 프롬프트가 아니다. 선호도 목록이 아니다. 코드베이스에서 Claude 가 어떻게 행동해야 하는지에 대한 운영 체제다.
대부분의 개발자는 세 가지 잘못된 방법 중 하나를 사용한다. 모든 선호 사항을 파일에 한꺼번에 넣어 4,000 토큰 이상으로 부풀려 중요한 규칙이 묻혀 준수율이 30% 로 떨어진다. 아예 건너뛰고 매 세션마다 다시 프롬프트를 입력하여 5배의 토큰을 낭비하고 일관성이 전혀 없다. 템플릿을 한 번 붙여넣고 잊어버린 후, 코드베이스가 바뀌면서 몇 주에 걸쳐 조용히 망가지는 것을 지켜본다.
공식 Anthropic 문서는 명확하다: CLAUDE.md 는 권고 사항이다. Claude 는 200줄 미만일 때 약 80% 의 시간 동안 이를 따른다. 200줄을 넘으면 준수율이 급격히 떨어진다. 유용한 CLAUDE.md 파일의 한계는 짧고, 정확하며, 제안이 아닌 직접적인 규칙을 통해 강제된다.
원본 4가지 규칙: 아무것도 없다면 여기서 시작하라
Tesla 의 전 AI 책임자이자 OpenAI 의 공동 창립자인 Andrej Karpathy 는 2026년 1월, Claude Code 로 몇 주간 집중적으로 작업한 후 스레드를 게시했다. 프레임워크가 아니라 불만이었다. 그가 계속 부딪힌 세 가지 실패 모드는 다음과 같다: Claude 가 묻지 않고 조용히 가정한다, Claude 가 최소한의 해결책 대신 과도하게 구축한다, Claude 가 요청받지 않은 코드를 건드린다.
Forrest Chang 이 그 스레드를 읽고 규칙으로 정리했다. 다음 날 GitHub 에 65줄짜리 파일 하나가 올라왔다. 네 가지 규칙은 다음과 같다:
규칙 1 - 코딩 전에 생각하라
코드를 작성하기 전에 가정을 명시하라. 트레이드오프를 표면화하라. 추측하기 전에 물어봐라. 더 간단한 접근 방식이 있을 때는 반대 의견을 제시하라. 검증되지 않은 가정 위에 절대 구축하지 마라.
규칙 2 - 단순함 우선
문제를 해결하는 최소한의 코드를 작성하라. 추측성 기능은 넣지 마라. 한 번만 사용할 코드에 추상화를 도입하지 마라. 시니어 엔지니어가 과도하게 복잡하다고 말할 코드는 단순화하라.
규칙 3 - 수술적 변경
작업에 필요한 부분만 건드려라. 인접한 코드, 주석, 포맷팅을 개선하지 마라. 고장 나지 않은 것을 리팩터링하지 마라. 기존 스타일을 정확히 따라라.
규칙 4 - 목표 기반 실행
시작하기 전에 성공의 정의를 내려라. 성공이 확인될 때까지 반복하라. Claude 가 따라야 할 단계를 나열하지 마라. Claude 에게 완료된 상태가 어떤 것인지 알려주고, 경로를 찾도록 하라.
이 네 가지 규칙은 감독되지 않은 Claude Code 세션에서 발생하는 실패 모드의 약 40% 를 차단한다. 나머지 60% 는 원본 템플릿이 다루지 않는 부분에 존재하는데, 이는 Karpathy 가 스레드를 게시했을 때 해당 문제들이 완전히 존재하지 않았기 때문이다.
원본 템플릿을 확장해야 하는 이유
네 가지 Karpathy 규칙은 단일 에이전트, 코드 작성 세션을 수정하기 위해 만들어졌다. 2026년의 Claude Code 생태계는 다중 에이전트 설정, 훅, 스킬 라이브러리, 여러 세션에 걸친 다단계 워크플로우를 실행한다. 원본 템플릿은 이에 대해 아무 말도 하지 않는다.
원본 규칙에는 네 가지 특정한 격차가 나타난다. 첫째, 에이전트 충돌: 두 에이전트가 소유권 규칙 없이 동일한 파일을 편집하여 서로의 변경 사항을 조용히 덮어쓴다. 둘째, 훅 연쇄: 모든 도구 호출 시 훅이 실행되어 200 토큰 요청을 8,000 토큰으로 만들고 예산을 통제할 방법이 없다. 셋째, 스킬 로딩 충돌: 유사한 설명을 가진 여러 스킬이 디스패처를 혼란스럽게 하여 잘못된 스킬을 로드한다. 넷째, 다단계 세션 중단: 6단계 리팩터링이 4단계에서 실패했지만, 5단계와 6단계가 계속 실행되어 깨진 상태 위에 구축된다.
네 가지 원본 규칙이 틀린 것은 아니다. 불완전한 것이다. 아래의 8가지 추가 규칙이 이러한 특정 격차를 메운다.
8가지 새로운 규칙: 각 규칙이 막는 것
규칙 5 - 비언어 작업에 모델을 사용하지 마라
결정론적 결정은 결정론적 코드에 속한다. 재시도 로직, 라우팅 임계값, 에스컬레이션 규칙, 상태 기반 분기: 이들 중 어느 것도 LLM 호출이 되어서는 안 된다. 모델은 컨텍스트 윈도우에 있는 내용에 따라 매주 다르게 결정한다. 일관된 행동처럼 보이는 것은 아직 표면화되지 않은 변동성일 뿐이다.
특정 사례: "503 에 재시도할지 결정" LLM 호출이 2주 동안 잘 작동하다가, 모델이 재시도 결정을 위한 컨텍스트로 요청 본문을 읽기 시작하면서 무작위 행동을 생성하기 시작했다. 유효 입력이 무작위가 되면서 정책도 무작위가 되었다.
CLAUDE.md 에 다음을 추가하라:
라우팅, 재시도 로직, 상태 기반 분기, 임계값 결정은 모델 호출이 아닌 코드에 속한다. 결정의 출력이 이진적이거나 고정된 규칙을 따른다면, 그 규칙을 코드로 작성하라.
규칙 6 - 하드 토큰 예산, 예외 없음
모든 에이전트 루프는 통제 불능이 될 가능성이 있다. Claude 는 스스로 90분 디버깅 세션을 중단하지 않는다. 반복하라는 지시를 받았기 때문에 계속 반복할 것이다. 토큰 예산은 하드 스톱을 강제하는 유일한 메커니즘이다.
특정 사례: 동일한 8KB 오류 메시지로 90분 동안 루프를 도는 디버깅 세션. 결국 Claude 는 2시간 전에 이미 시도하고 포기했던 수정 사항을 제안하고 있었다. 컨텍스트가 너무 가득 차서 자신의 추론 과정을 놓치고 있었다.
다음을 추가하라:
모든 에이전트 세션에는 하드 토큰 예산이 있다. 검증된 솔루션 없이 예산에 도달하면, 중단하고, 결과를 파일로 요약한 후 종료하라. 예산을 초과하여 계속하지 마라.
규칙 7 - 하나의 에이전트, 하나의 디렉토리
두 에이전트가 동시에 동일한 디렉토리를 건드리면, 조용한 상태 손상이 발생한다. 한 에이전트가 파일을 쓰는 동안 다른 에이전트가 그 파일을 읽고 있다. 결과는 어느 에이전트도 예상하지 못하고 알아채지 못하는 데이터가 된다.
Git worktree 를 사용하라. 두 번째 에이전트를 실행하기 전에 git worktree add ../agent-2-branch feature-branch 를 실행하라. 각 에이전트는 자체 브랜치를 가리키는 격리된 작업 디렉토리를 얻는다. 에이전트는 파일 시스템을 공유하지 않는다.
다음을 추가하라:
병렬로 실행되는 에이전트는 별도의 Git worktree 에서 작업한다. 두 에이전트가 동시에 동일한 디렉토리를 건드리지 않는다. 각 에이전트는 자신의 브랜치를 소유한다.
규칙 8 - 다단계 작업에 체크포인트 파일 작성
3단계보다 긴 모든 작업에는 체크포인트 파일이 필요하다. Claude 는 각 단계 후에 완료된 내용, 발견된 내용, 다음 단계를 기록한 파일을 작성한다. 세션이 4단계에서 죽거나 중단되면, 다음 세션은 체크포인트를 읽고 4단계부터 계속한다. 체크포인트가 없으면 모든 재시작은 1단계로 돌아간다.
다단계 작업을 시작하기 전에 작업 디렉토리에 PROGRESS.md 파일을 생성하라. CLAUDE.md 에서 Claude 에게 지시하라:
3단계보다 긴 작업의 경우, 각 단계 후에 PROGRESS.md 파일을 작성하라. 포함할 내용: 완료된 작업, 발견된 사항, 다음 단계, 차단된 사항. 세션이 완료되기 전에 종료되면, 다음 세션은 먼저 PROGRESS.md 를 읽고 중단된 지점부터 계속한다.
규칙 9 - 크게 실패하거나 전혀 실패하지 마라
Claude 는 성공한 것처럼 보이려는 강한 경향이 있다. 실제로 당신이 신경 쓰는 것을 테스트하지 않는 테스트를 통과시킬 것이다. 오류가 발생한 파일을 조용히 건너뛰면서 마이그레이션을 완료할 것이다. 80% 완료된 작업에 대해 "완료"를 보고할 것이다.
규칙: 성공 기준을 검증할 수 없으면 작업이 완료된 것이 아니다. 단계가 실패하면 중단하고, 계속하기 전에 구체적인 실패 내용을 보고하라. 오류를 덮지 마라.
다음을 추가하라:
실패한 단계를 넘어 절대 계속하지 마라. 테스트가 통과했지만 실제 동작을 다루지 않는다면 그렇게 말하라. 마이그레이션이 파일을 건너뛰었다면 건너뛴 파일을 나열하고 중단하라. 성공은 보고된 것이 아니라 검증 가능한 것을 의미한다.
규칙 10 - 스킬 설명은 고유해야 한다
스킬은 설명 매칭을 통해 로드된다. 두 스킬의 설명이 겹치면 디스패처가 임의로 하나를 선택한다. 잘못된 스킬이 로드되고, 작업이 잘못된 지침으로 실행되며, 오류가 발생하지 않기 때문에 오류를 볼 수 없다.
다른 스킬과 매칭될 수 없는 언어로 각 스킬의 작업을 명명하라. "데이터베이스 쿼리 헬퍼" 와 "데이터베이스 마이그레이션 헬퍼" 는 충돌할 것이다. "프로덕션 데이터베이스에 대해 읽기 전용 SQL 쿼리 실행" 과 "롤백이 포함된 스키마 마이그레이션 스크립트 실행 및 검증" 은 충돌하지 않을 것이다.
다음을 추가하라:
각 스킬 설명은 해당 작업을 고유하게 식별해야 한다. 어떤 두 스킬도 동일한 작업에 적용될 수 있는 설명을 가져서는 안 된다. 두 스킬이 비슷하게 들리면, 배포 전에 그중 하나의 이름을 변경해야 한다.
규칙 11 - 연구자와 작성자를 분리하라
컨텍스트 오염은 실제다. Claude 가 동일한 세션에서 연구와 작성을 수행하면, 연구 노이즈가 작성을 저하시킨다. 지엽적인 내용을 끌어들이고, 필요하지 않은 결론을 얼버무리며, 깨끗한 상태에서 시작했다면 가졌을 명확한 논증 라인을 잃는다.
5개 이상의 파일을 읽거나 2개 이상의 소스를 쿼리해야 하는 모든 작업에 대해 연구 하위 에이전트를 생성하라. 구조화된 보고서를 받아라. 컨텍스트에 보고서만 있는 상태로 작성 또는 구현을 위한 깨끗한 세션을 시작하라.
다음을 추가하라:
연구와 구현은 별도의 세션이다. 연구자 하위 에이전트가 파일을 읽고, 쿼리를 실행하고, 구조화된 요약을 반환한다. 구현 세션은 해당 요약을 유일한 입력으로 하여 깨끗하게 시작한다. 연구와 작성을 하나의 세션에 절대 병합하지 마라.
규칙 12 - 훅에도 예산이 필요하다
훅은 모든 도구 호출 시 실행된다. 모든 파일 쓰기 시 린터, 포맷터, 로그 작성기, 보안 검사를 실행하는 훅은 도구 호출당 4개의 프로세스를 실행하는 것이다. 200번의 도구 호출이 있는 세션에서는 800개의 프로세스가 백그라운드에서 실행되며, 대부분 중복되고 모두 토큰을 소비한다.
추가하는 모든 훅에는 범위 조건이 필요하다: 특정 디렉토리에 대한 파일 쓰기 시에만 실행, 특정 파일 확장자가 수정될 때만 실행, 모든 도구 호출 후가 아닌 세션 종료 후에만 실행. 범위 조건이 없는 훅은 눈에 띄지 않게 세션 성능을 저하시킨다.
다음을 추가하라:
모든 훅에는 명시적인 범위 조건이 있다. 어떤 훅도 모든 도구 호출 시 무조건 실행되지 않는다. 로깅은 세션 종료 시 일괄 처리하라. 린터는 변경된 파일에 대해서만 실행하라. 보안 검사는 테스트 디렉토리 외부의 파일에 대해서만 실행하라.
완전한 12가지 규칙 CLAUDE.md - 이것을 붙여넣으세요
이 파일을 저장소 루트에 복사하라. 대괄호로 표시된 섹션을 채워라. 전체 파일은 100줄 미만으로 유지되어 준수율을 80% 이상으로 유지한다.
CLAUDE.md
프로젝트
[한 문장: 이 코드베이스가 무엇을 하고 어떤 기술 스택을 사용하는지]
행동 규칙
코딩 전에 생각하라
코드를 작성하기 전에 가정을 명시하라. 트레이드오프를 표면화하라. 아키텍처나 데이터에 영향을 미치는 모든 것에 대해 추측하기 전에 물어봐라. 더 간단한 접근 방식이 있을 때는 반대 의견을 제시하라.
단순함 우선
문제를 해결하는 최소한의 코드를 작성하라. 추측성 기능은 넣지 마라. 일회용 코드에 추상화를 도입하지 마라. 시니어 엔지니어가 과도하게 복잡하다고 말할 코드는 단순화하라.
수술적 변경
작업에 필요한 부분만 건드려라. 요청의 일부가 아닌 인접한 코드, 포맷팅, 주석, 명명을 개선하지 마라. 기존 코드 스타일을 정확히 따라라.
목표 기반 실행
시작하기 전에 성공의 정의를 내려라. 해당 정의가 충족되고 검증될 때까지 반복하라. 단계별 지침을 요청하지 마라. 경로를 스스로 찾아라.
결정론적 결정에 모델 호출 금지
라우팅, 재시도 로직, 상태 기반 분기, 임계값 결정은 LLM 호출이 아닌 코드에 속한다. 규칙을 작성할 수 있다면 작성하라.
하드 토큰 예산
모든 세션에는 하드 토큰 한도가 있다: [숫자 설정, 예: 50,000 토큰]. 검증된 솔루션 없이 한도에 도달하면, 결과를 파일에 기록하고 중단하라. 예산을 초과하여 계속하지 마라.
하나의 에이전트, 하나의 디렉토리
병렬로 실행되는 에이전트는 별도의 Git worktree 에서 작업한다. 두 에이전트가 디렉토리를 공유하지 않는다. 두 번째 에이전트가 필요하면 다음을 실행하라: git worktree add ../agent-2 [브랜치 이름]
다단계 작업 체크포인트
3단계보다 긴 모든 작업에 대해 작업 디렉토리에 PROGRESS.md 를 생성하라. 각 단계 후에 기록하라: 완료된 작업, 발견된 사항, 다음 단계, 차단된 사항. 세션이 완료되기 전에 종료되면, 다음 세션은 먼저 PROGRESS.md 를 읽는다.
크게 실패하라
단계가 실패하면 중단하고, 계속하기 전에 구체적인 실패 내용을 보고하라. 테스트가 통과했지만 실제 동작을 다루지 않는다면 그렇게 말하라. 성공은 보고된 것이 아니라 검증 가능한 것을 의미한다.
고유한 스킬 설명
각 스킬은 정확히 하나의 작업을 다룬다. 해당 설명은 프로젝트의 다른 어떤 스킬에도 적용될 수 없어야 한다. 두 스킬의 설명이 겹치면 배포 전에 이름을 변경하라.
연구와 구현은 별도 세션
5개 이상의 파일을 읽거나 2개 이상의 소스를 쿼리해야 하는 모든 작업에 대해 하위 에이전트를 사용하라. 구조화된 보고서를 받아라. 해당 보고서만을 입력으로 하여 구현을 위한 깨끗한 세션을 시작하라.
범위가 지정된 훅만
모든 훅에는 명시적인 조건이 있다: 파일 확장자, 디렉토리 경로 또는 세션 이벤트. 어떤 훅도 모든 도구 호출 시 무조건 실행되지 않는다. 가능한 경우 로깅을 세션 종료 시 일괄 처리하라.
건드리지 말아야 할 것
[Claude 가 절대 수정해서는 안 되는 디렉토리 또는 파일 나열: 예: /secrets, /migrations/archive, /prod-config]
기본 성공 기준
작업 완료 여부가 의심스러울 때: 테스트가 통과하는가, 빌드가 성공하는가, 출력이 Claude 자신의 판단이 아닌 다른 것에 의해 검증 가능한가? 이 중 하나라도 '아니오'라면 완료된 것이 아니다.
원본 템플릿이 조용히 망가지는 네 가지 경우
원본 네 가지 규칙만 사용하더라도, 템플릿이 잘못된 행동을 생성하고 이를 알리지 않는 네 가지 특정 조건이 있다.
첫째, 컨텍스트가 누적된 긴 세션. Karpathy 의 목표 기반 실행 규칙은 Claude 에게 검증될 때까지 반복하라고 지시한다. 긴 세션에서는 컨텍스트가 가득 차면서 "검증됨"이 모호해진다. Claude 는 원래 수행해야 했던 작업의 저하된 모델을 기준으로 검증하기 시작한다. 해결책은 규칙 6(토큰 예산)으로 하드 스톱을 강제하는 것이다.
둘째, 다중 에이전트 설정. 수술적 변경 규칙은 각 에이전트에게 필요한 것만 건드리라고 지시한다. 그러나 디렉토리 소유권 규칙 없이 두 에이전트가 있으면 "필요한 것"이 겹친다. 규칙 7(하나의 에이전트, 하나의 디렉토리)이 누락된 부분이다.
셋째, 유사한 작업을 가진 병렬 스킬. 원본 템플릿에는 스킬에 대한 내용이 전혀 없다. 규칙 10(고유한 스킬 설명)이 디스패처 모호성 격차를 메운다.
넷째, 작업 중간에 종료되는 세션. 목표 기반 실행은 세션이 완료될 때까지 실행된다고 가정한다. 세션이 8단계 중 4단계에서 죽으면 어떻게 해야 하는지에 대한 지침이 없다. 규칙 8(체크포인트 파일)이 다음 세션에 시작점을 제공한다.
이 중 어느 것도 원본 규칙의 버그가 아니다. 원본 규칙이 다루도록 작성되지 않은 격차들이다.
GitHub 스타를 설명하는 숫자
120,000 명의 개발자가 65줄짜리 텍스트 파일에 스타를 표시했다. 코드도, 라이브러리도, 프레임워크도 아니다. 네 가지 규칙이 있는 하나의 파일이다.
이를 설명하는 숫자는 다음과 같다: CLAUDE.md 가 없는 감독되지 않은 Claude Code 세션의 오류율 41%. 원본 네 가지 규칙을 사용하면 11%. 완전한 12가지 규칙을 사용하면 3%.
오류 38% 포인트 감소는 미미한 개선이 아니다. 실제 프로덕션 작업에서 Claude Code 를 실행하는 모든 팀에게 이는 밤새 신뢰하고 실행할 수 있는 에이전트와 계속 감시해야 하는 에이전트의 차이를 의미한다.
이 글 끝에 있는 파일을 붙여넣고 채우는 데는 5분이 걸린다. 그렇게 한 후 첫 번째 세션은 다르게 느껴질 것이다. 모델이 바뀌었기 때문이 아니다. 모델이 마침내 당신의 세계가 어떻게 작동하는지 알게 되었기 때문이다.
이 글을 북마크하고 오늘 밤 CLAUDE.md 에 12가지 규칙을 붙여넣으세요.
유용했다면 리포스트 해주세요.
