카파시 CLAUDE.md — GitHub 10만 스타 받은 65줄 파일 정리

Claude Code로 코드를 받아봤는데 몇 줄로 끝날 일을 1,000줄로 부풀리고, 묻지도 않은 코드까지 멋대로 고친 경험이 한 번쯤 있을 겁니다. 이 상태로 그냥 쓰면 리뷰 시간은 폭증하고, 부수효과로 새 버그가 뭉텅이로 따라붙는 일이 반복됩니다.

10년 이상 개발자로서 Claude Max와 Gemini Pro를 병행 운용하는 관점에서 최근 화제가 된 카파시 CLAUDE.md를 정리해 봤습니다. 이 글을 끝까지 읽으면 4가지 핵심 원칙, 적용 방법 3가지, 기존 CLAUDE.md와 충돌할 때의 대처법까지 가져가게 됩니다.

 

카파시 CLAUDE.md가 뭔가

이번 화제의 출발점은 Andrej Karpathy(OpenAI 공동창업자, 전 Tesla AI 디렉터)가 X에 올린 짧은 글이었습니다. 카파시는 LLM이 코드를 짤 때 반복하는 3가지 문제를 지적했습니다.

AI 코딩 3대 고질병	실제 증상
잘못된 가정	묻지도 않고 멋대로 해석한 뒤 작업 시작
코드 부풀리기	몇 줄로 될 것을 1,000줄로 짜고, 안 쓰는 코드 방치
멋대로 수정	부탁하지도 않은 코드 변경, 주석 임의 삭제

카파시의 결론은 한 문장이었습니다.

"명령하지 말고 성공 기준을 주고 지켜보라."

이 글을 본 개발자 Forrest Chang이 다음 날 카파시의 메시지를 4가지 행동 원칙으로 추출해 단 65줄짜리 CLAUDE.md로 정리했습니다. 며칠 만에 forrestchang/andrej-karpathy-skills 레포가 GitHub 10만 스타를 돌파했고, 이게 지금 우리가 부르는 카파시 CLAUDE.md입니다. 정확한 레포 주소는 글 하단 출처 섹션에 정리했습니다.

 

4가지 행동 원칙 정리

카파시 CLAUDE.md의 본질은 새 기술이 아니라 4가지 행동 원칙입니다. 한 줄씩 영어 원문을 박고 풀어보겠습니다.

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

"Don't assume. Don't hide confusion. Surface tradeoffs."
추측하지 마라. 혼란을 숨기지 마라. 트레이드오프를 드러내라.

핵심은 AI에게 선택지를 우리에게 돌려달라고 명시하는 겁니다.

• 실행 전 가정한 내용을 명시적으로 밝힌다
• 여러 해석이 가능하면 선택하지 말고 모두 제시한다
• 더 간단한 방법이 있으면 같이 언급한다 (필요하면 반박도)
• 이해 안 되면 멈추고 다시 질문한다

"로그인 기능 추가해 줘"라는 한 줄 요청을 받았을 때의 차이입니다.

원칙 없음	원칙 적용
"JWT 기반으로 구현했습니다" → 200줄 우르르	"JWT/Session/OAuth 3가지 중 어떤 방식을 선호하시나요?"
멋대로 가정 후 진행	트레이드오프 제시 후 질문
다시 걷어내고 재작성	한 번에 올바른 방향

 

원칙 2. Simplicity First — 단순함이 최우선

"Minimum code that solves the problem. Nothing speculative."
문제를 해결하는 최소한의 코드만. 추측성 코드 금지.

• 요청한 기능 외에는 추가 기능 없음
• 일회용 코드에는 추상화 불필요
• 요청하지 않은 유연성/설정 가능성 없음
• 200줄 짰는데 50줄로 가능하면 다시 써라

"두 숫자를 더하는 함수" 요청에 어떤 차이가 나는지 보면 직관적입니다.

// 원칙 없음 — 인터페이스 + 클래스로 9줄
interface Calculator {
  calculate(a: number, b: number): number;
}
class AdditionCalculator implements Calculator {
  calculate(a: number, b: number): number {
    return a + b;
  }
}
const calc: Calculator = new AdditionCalculator();

// 원칙 적용 — 함수 1개로 끝
function add(a: number, b: number): number {
  return a + b;
}

물론 복잡한 도메인 모델에서는 인터페이스 추상화가 의미 있을 때도 있습니다. 다만 그건 매우 특수한 경우고, 대부분의 경우 단순한 구현이 이해·토큰 절약·유지보수 모든 면에서 유리합니다.

 

원칙 3. Surgical Changes — 수술하듯 수정하라

"Touch only what you must. Clean up only your own mess."
꼭 필요한 것만 건드려라. 본인이 만든 쓰레기만 치워라.

• 변경된 모든 줄이 사용자 요청에 직접 연결되어야 함
• 기존 코드 편집 시 근처의 코드/주석/서식을 임의로 개선하지 말 것
• 멀쩡한 것을 굳이 리팩토링하지 말 것
• 관련 없는 미사용 코드 발견 시 삭제 말고 알려줄 것
• 마지막에 "시킨 것만 변경했는지" 자체 확인

"이 함수의 버그 고쳐 줘" 한 줄 요청에 대한 차이입니다.

원칙 없음	원칙 적용
버그 수정 + 주석 스타일 변경 + 근처 함수 리팩토링 + 안 쓰는 import 삭제	버그 수정만. "안 쓰는 import 있는데 정리할까요?" 물어봄
리뷰 범위 폭증	리뷰 범위 최소
부수효과로 새 버그 발생 가능	변경 범위 명확

핵심 질문 한 줄로 정리됩니다. "내가 시킨 것만 수정했는가?"

 

원칙 4. Goal-Driven Execution — 목표 기반 실행

"Define success criteria. Loop until verified."
성공 기준을 정의하라. 검증될 때까지 반복하라.

영상에서 "가장 중요한 원칙"으로 꼽힌 항목입니다. 카파시의 "명령하지 말고 성공 기준을 주고 지켜보라"를 코드 레벨로 풀어낸 것입니다.

모호한 과제	검증 가능한 목표
버그 수정해	버그 재현 테스트 작성 → 통과시켜라
리팩토링 해	리팩토링 전후 테스트 모두 통과 확인
성능 개선해	벤치마크 작성 → 30% 이상 개선 검증
API 추가해	통합 테스트 작성 → 통과 확인

"무엇을 해라" 대신 "무엇이 통과되면 끝"을 명시하는 것이 핵심입니다. 이전에 정리했던 Claude Code 필수 설정 가이드에서 다룬 자동 검증 훅과 결합하면 검증 루프가 자연스럽게 닫힙니다.

 

적용 방법 3가지

설치는 30초면 끝납니다. 상황별로 3가지 방법이 있고, 각각 동작 방식이 다릅니다.

 

방법 1. 스킬로 설치 (Claude Code Skills)

플러그인 마켓플레이스를 통해 스킬로 추가합니다. 명시적으로 호출해야 적용되는 방식입니다.

# 1. 마켓플레이스에 스킬 추가
/plugin marketplace add forrestchang/andrej-karpathy-skills

# 2. 스킬 설치
/plugin install karpathy-guidelines@andrej-karpathy-skills

# 3. 확인 — karpathy-guidelines 스킬이 보이면 OK
/ka

스킬 설치 흐름이 처음이면 Claude Code에 프로급 디자인 스킬 세팅하기 — Impeccable 가이드에서 다룬 절차가 그대로 적용됩니다.

방법 2. CLAUDE.md 파일로 다운로드

세션 시작 시 자동으로 로드됩니다.

# 원본 raw URL은 출처 섹션 참고 — 변수로 한 번만 잡고 사용
RAW_URL="<raw.githubusercontent.com 경로>"

# 전역 설치 (~/.claude/CLAUDE.md)
curl -o ~/.claude/CLAUDE.md "$RAW_URL"

# 프로젝트만 설치 (./CLAUDE.md)
curl -o ./CLAUDE.md "$RAW_URL"

방법 3. 수동 복사 (야매)

GitHub 레포에서 CLAUDE.md 원문을 그대로 열어서 복사한 뒤, 프로젝트 루트나 ~/.claude/에 새 파일 만들고 붙여넣고 저장하면 끝입니다. 명령어 입력이 귀찮을 때 이 방법이 가장 빠릅니다. 레포 주소는 출처 섹션 참고.

어떤 방법을 쓸까

정답은 없습니다. 매번 자동 적용하고 싶으면 CLAUDE.md, 가끔만 명시 호출하고 싶으면 스킬입니다.

방법	로드 방식	추천 상황
스킬	명시적 호출 (/ka)	가끔만 적용하고 싶을 때, 컨텍스트 절약 우선
CLAUDE.md	자동 로드	매 세션마다 자동 적용하고 싶을 때
수동 복사	자동 로드	명령어 입력 귀찮을 때

트러블슈팅 — 기존 CLAUDE.md를 덮어쓴 경우

방법 2를 그대로 따라가다 실수하기 쉬운 부분입니다.

• 증상: curl -o ./CLAUDE.md ... 실행 후 기존 프로젝트 가이드라인이 통째로 사라짐. Git 추적 중이면 diff에서 변경 폭이 눈에 띄게 큼.
• 원인: curl -o는 기본 동작이 무차별 덮어쓰기입니다. 백업 옵션이 따로 없습니다.
• 해결: Git 추적 중이면 git checkout -- CLAUDE.md로 즉시 복원합니다. Git 밖이면 ~/.claude/CLAUDE.md(전역) 쪽에 카파시 원칙만 두고, 프로젝트 CLAUDE.md는 기존 내용을 살린 뒤 4원칙 섹션을 수동으로 병합하는 게 안전합니다. 다음부터는 cp CLAUDE.md CLAUDE.md.bak && curl -o ... 식으로 한 줄 백업을 앞에 끼웁니다.

 

65줄짜리 텍스트가 왜 10만 스타를 받았나

새 기술도, 화려한 프레임워크도 없습니다. 그냥 65줄 마크다운 한 장입니다. 그런데도 10만 명이 스타를 누른 이유는 한 문장으로 정리됩니다.

AI는 코드를 못 짜는 게 아니라 너무 잘 짭니다. 너무 빨리, 너무 자신있게.
문제는 능력 부족이 아니라 브레이크가 없다는 것이었습니다.

 

CLAUDE.md는 새 능력을 추가한 게 아니라 AI에게 브레이크를 달아준 것입니다. 4년째 블로그 운영하며 Claude Code 워크플로우 글들을 다뤄왔는데, 이번 카파시 CLAUDE.md가 특히 의미 있다고 본 지점은 다음과 같습니다.

• 불필요한 변경 사항 감소 → 코드 리뷰 부담 절감
• 과도한 복잡성으로 인한 재작성 감소 → 토큰 비용 절감
• Claude Code가 구현 전에 명확하게 질문함 → 의도 일치율 상승
• 검증 단계가 자동으로 들어감 → 회귀 버그 감소

"무엇을 해라" 대신 "성공 기준이 무엇이냐"를 정의하는 사고방식. AI 시대 협업의 본질이 바뀐 부분이 여기에 있습니다. 동일 환경이면 위 설치 스니펫 그대로 써도 됩니다.

 

자주 묻는 질문

Q. 카파시 CLAUDE.md는 정확히 무엇인가요?
A. Andrej Karpathy의 X 포스트에서 시작된 LLM 코딩 행동 원칙 4가지를, 개발자 Forrest Chang이 65줄짜리 마크다운으로 정리한 파일입니다. Claude Code가 세션 시작 시 자동으로 읽어 들여 코드 생성 방식에 영향을 줍니다. 새 기술이 아니라 행동 가드레일입니다.

 

Q. 기존 CLAUDE.md가 이미 있는데 덮어쓰면 어떻게 되나요?
A. curl -o는 무조건 덮어쓰기라 기존 내용이 사라집니다. Git 추적 중이면 git checkout --으로 복원할 수 있고, 안전하게 가려면 카파시 4원칙 섹션만 따로 떼어서 기존 CLAUDE.md 끝에 추가하는 방식이 권장됩니다. 또는 ~/.claude/CLAUDE.md(전역)에 두고 프로젝트 CLAUDE.md는 그대로 살려도 됩니다.

 

Q. 스킬과 CLAUDE.md 중 뭐가 더 좋은가요?
A. 매 세션마다 자동 적용하고 싶으면 CLAUDE.md, 가끔만 명시 호출하고 싶으면 스킬입니다. 컨텍스트 토큰을 아껴야 하는 상황(긴 코드베이스 작업)이면 스킬이 유리하고, 매 코드 작업마다 4원칙을 강제하고 싶으면 CLAUDE.md가 낫습니다.

 

Q. 65줄짜리 텍스트가 정말 효과 있나요?
A. 효과가 있는 이유는 65줄 안에 LLM이 자주 어기는 4가지 행동 패턴에 대한 명시적 금지 규칙이 들어 있기 때문입니다. 시스템 프롬프트 가드레일 역할을 하므로, 같은 모델이라도 코드 출력 결과가 눈에 띄게 단순해집니다. 다만 "한 번도 안 어긴다"가 아니라 "확률이 줄어든다"에 가깝습니다.

 

Q. 한국어 프로젝트에서도 동작하나요?
A. 동작합니다. CLAUDE.md 자체는 영어지만 Claude는 다국어를 같은 시스템 프롬프트로 처리하므로, 한국어 요청에도 4원칙이 적용됩니다. 코드 주석이나 변수명은 평소대로 한국어/영어 섞어 써도 됩니다.

---

📎 이 카테고리의 다른 글

• Claude Code 창시자와 해커톤 우승자의 공통 꿀팁 7가지 — 2026-04-05
• Claude Code 필수 설정 가이드 — 2026-03-20
• [설치 가이드] Claude Code에 프로급 디자인 스킬 세팅하기: Impeccable 완벽 가이드 — 2026-04-02

같은 AI 활용법 카테고리에서 이어서 읽기