단 65줄 깃허브 10만 스타를 받은 CLAUDE.md - by. 안드레 카파시

65줄짜리 마크다운 한 장이 깃허브 10만 스타를 받은 이유

2026년 1월, 한 개발자가 GitHub: forrestchang/andrej-karpathy-skills 저장소를 공개했다. 안에 든 핵심 파일은 단 하나, 65줄짜리 CLAUDE.md. 5월 초 기준 이 저장소는 107,000 스타를 넘겼다. 흔한 에이전트 모음, 거대한 프롬프트 라이브러리도 아니다. 단 하나의 마크다운 파일이다.

이 파일이 주목받은 배경에는 OpenAI·테슬라 AI 책임자 출신 안드레이 카파시(Andrej Karpathy)의 트윗이 있다. 카파시는 자신이 LLM을 코딩에 쓰면서 매번 부딪히는 실패 패턴 4가지를 정리했고, forrestchang이 이를 그대로 4가지 원칙의 CLAUDE.md로 압축했다.

카파시가 지적한 LLM 코딩의 4가지 실패 패턴

원문을 그대로 옮기면 다음과 같다.

"모델은 사용자를 대신해 잘못된 가정을 내리고, 확인 없이 그대로 달려간다. 자신의 혼란을 관리하지 않고, 명확화를 요청하지 않으며, 모순을 드러내지 않고, 트레이드오프를 제시하지 않으며, 반박해야 할 때 반박하지 않는다."

"코드와 API를 과도하게 복잡하게 만들고, 추상화를 부풀리고, 죽은 코드를 정리하지 않는다. 100줄이면 충분한 일을 1,000줄짜리 부풀린 구조로 구현한다."

"충분히 이해하지 못한 코멘트와 코드를 — 작업과 무관한데도 — 부수효과로 변경하거나 삭제하기도 한다."

이 세 문단을 풀어보면 LLM 코딩 실패는 다음 네 가지로 압축된다.

CLAUDE.md는 이 네 가지 실패에 정확히 대응하는 4가지 원칙으로 구성됐다.

원칙 1 — 코딩 전에 생각하라 (Think Before Coding)

"가정하지 마라. 혼란을 숨기지 마라. 트레이드오프를 드러내라."

구현 전에 다음 4가지를 강제한다.

• 가정을 명시적으로 표현한다. 불확실하면 묻는다.
• 여러 해석이 가능하면 모두 제시한다. 조용히 하나를 고르지 않는다.
• 더 단순한 접근이 있으면 말한다. 필요할 때 반박한다.
• 혼란스러우면 멈춘다. 무엇이 불명확한지 명명하고 묻는다.

잘못된 예시 — 추측해서 달려가는 LLM

사용자가 "사용자 데이터 내보내기 기능 추가해줘"라고 했을 때, 평범한 LLM은 곧장 다음과 같이 작성한다.

def export_users(format='json'):
users = User.query.all()
if format == 'json':
with open('users.json', 'w') as f:
json.dump([u.to_dict() for u in users], f)
return f"Exported {len(users)} users"

문제: 모든 사용자를 내보낼지(개인정보 영향), 어떤 필드를 포함할지, 파일 위치는 어디로 할지, 다운로드인지 백그라운드 잡인지 — 단 하나도 묻지 않았다.

올바른 예시 — 가정을 표면화

구현 전 다음을 명확히 해야 합니다:

범위: 모든 사용자 vs 필터링된 일부? (개인정보 영향)
형식: "내보내기"의 의미가
- 브라우저 다운로드인가요?
- 백그라운드 잡 + 이메일 알림인가요?
- 데이터를 반환하는 API 엔드포인트인가요?
필드: 어떤 사용자 필드를 포함하나요? (민감 필드 검토 필요)
규모: 평균 사용자 수는? (접근 방식이 달라집니다)

가장 단순한 접근: 페이지네이션된 JSON을 반환하는 API 엔드포인트.
파일 기반 내보내기가 필요하면 추가 정보가 필요합니다. 어느 쪽이 좋으세요?

원칙 2 — 단순함 우선 (Simplicity First)

"문제를 해결하는 최소한의 코드. 추측성은 금지."

규칙은 다섯 가지다.

• 요청한 것 외의 기능 금지
• 단일 사용 코드의 추상화 금지
• 요청하지 않은 "유연성"·"설정 가능성" 금지
• 발생 불가능한 시나리오에 대한 에러 처리 금지
• 200줄로 쓴 게 50줄이면 충분하면 다시 써라

테스트는 한 줄이다. "시니어 엔지니어가 이걸 보고 과도하게 복잡하다고 할까?" 그렇다면 단순화하라.

잘못된 예시 — 할인 계산 1줄을 위해 30줄 추상화

class DiscountStrategy(ABC):
@abstractmethod
def calculate(self, amount: float) -> float: pass

class PercentageDiscount(DiscountStrategy):
def __init__(self, percentage): self.percentage = percentage
def calculate(self, amount): return amount * (self.percentage / 100)

class FixedDiscount(DiscountStrategy): ...

@dataclass
class DiscountConfig:
strategy: DiscountStrategy
min_purchase: float = 0.0
max_discount: float = float('inf')

class DiscountCalculator:
def __init__(self, config): self.config = config
def apply_discount(self, amount): ...

올바른 예시 — 1 함수, 1 줄

def calculate_discount(amount: float, percent: float) -> float:
"""Calculate discount amount. percent should be 0-100."""
return amount * (percent / 100)

복잡성은 실제로 필요할 때 도입한다. 미래의 가능성을 위해 미리 추상화하지 않는다.

원칙 3 — 외과수술적 변경 (Surgical Changes)

"건드려야 할 것만 건드려라. 네가 만든 흔적만 정리해라."

기존 코드를 편집할 때 강제되는 4가지:

• 인접 코드, 코멘트, 포매팅을 "개선"하지 마라
• 깨지지 않은 것을 리팩터하지 마라
• 네가 다르게 짤지라도 기존 스타일을 따라라
• 무관한 죽은 코드를 발견했다면 — 언급만 하고 삭제하지 마라

변경이 만든 고아(orphan)에 대한 규칙:

• 네 변경이 만들어낸 사용 안 되는 import/변수/함수만 제거
• 기존 죽은 코드는 요청 없이 제거하지 마라

테스트: 변경된 모든 줄이 사용자 요청과 직접 연결되는지 추적 가능해야 한다.

원칙 4 — 목표 주도 실행 (Goal-Driven Execution)

"성공 기준을 정의하라. 검증될 때까지 반복하라."

명령형 작업을 검증 가능한 목표로 변환한다.

여러 단계 작업이라면 짧은 계획을 명시한다.

1. [단계] → 검증: [확인 방법]
[단계] → 검증: [확인 방법]
[단계] → 검증: [확인 방법]

강한 성공 기준은 LLM이 독립적으로 루프하게 한다. 약한 기준 ("작동하게 해줘")은 끊임없는 명세 변경을 부른다.

한국 개발자가 바로 적용하는 방법

1. CLAUDE.md를 프로젝트 루트에 둔다

가장 간단한 도입은 curl 한 줄이다.

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Claude Code는 작업 시작 시 자동으로 같은 디렉토리의 CLAUDE.md를 컨텍스트에 로드한다.

2. Claude Code 플러그인으로 전역 설치

여러 프로젝트에 한꺼번에 적용하고 싶다면 플러그인 마켓플레이스를 추가한다.

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

3. 기존 프로젝트 CLAUDE.md와 병합한다

이미 프로젝트별 CLAUDE.md(빌드 명령, 코딩 컨벤션, 폴더 구조)가 있다면 카파시 4원칙을 출력 스타일 섹션 위쪽에 붙이면 된다. 기존 컨벤션은 "what(무엇을)"을, 4원칙은 "how(어떻게)"를 다루므로 충돌하지 않는다.

우리가 적용한 통합 CLAUDE.md

본사 워크스페이스에서는 기존 73줄짜리 CLAUDE.md(테스트 명령, 아키텍처, 출력 스타일)에 카파시 4원칙을 결합해 통합 버전을 만들었다. 핵심 변경점은 다음과 같다.

• 기존 "브리프 규칙"(요청이 불완전하면 질문) → 원칙 1과 통합, 더 강한 표현으로 보강
• 기존 "출력 스타일"(군더더기 금지) → 원칙 2와 결합
• 새로 추가: 원칙 3 외과수술적 변경 — "변경된 모든 줄이 요청과 직접 연결" 테스트
• 새로 추가: 원칙 4 목표 주도 실행 — TDD 워크플로(/tdd 커맨드)와 직접 연결

마무리 — 65줄이 강한 이유

이 파일이 10만 스타를 받은 진짜 이유는 짧기 때문이다. 5,000줄짜리 거대한 프롬프트 가이드를 LLM에게 넘기면 토큰 비용이 폭증하고, 정작 핵심 규칙은 컨텍스트 중간에 묻혀 잊힌다. 65줄은 매 메시지마다 LLM이 정확히 다 읽고 적용할 수 있는 분량이다.

"무엇을 추가할까"보다 "무엇을 빼야 핵심이 또렷해질까"를 묻는 것이 좋은 시스템 프롬프트의 출발점이다. 카파시의 4원칙은 그 자체가 원칙 2 "단순함 우선"의 완벽한 시연이다.

오늘 당신의 프로젝트 루트에 CLAUDE.md를 만들어 보자. 4원칙이면 충분하다.