Claude Code 필수 CLAUDE.md? 실제 티켓 10건으로 Karpathy Skills를 검증했다

결과부터. Karpathy Skills(커뮤니티가 정리한 CLAUDE.md 행동 준칙)가 정말 통하는지 실제 티켓 10건으로 검증했다. Claude Opus 4.8 고정, 바꾼 건 Karpathy 네 원칙 유무뿐. 일주일에 남는 숫자는 다음과 같다.

실망한 경우도 있다 — 상수 한 줄 티켓에서는 준칙이 거의 안 먹히고 「가정 확인」 라운드만 늘었다. 성공·실패를 모두 적는다. 저장소에 쓰는 CLAUDE.md 최종본(Claude Code Rules / Claude Code Prompt 검색용)도 붙인다.

Claude Code가 왜 엉뚱한 곳까지 고치나

모델이 약해서가 아니라 기본 최적화 목표가 엔지니어와 다르다 — 빨리 「완성된 것처럼」 보이는 패치. 추상을 늘리고, 이웃 파일을 건드리고, 애매함은 묻지 않는다. Andrej Karpathy는 X에서 네 가지 만성 증상을 정리했다: 듣기 전에 손대기, 단순 요구의 과설계, 건드리면 안 될 파일의 습관적 수정, 검증 가능한 목표 대신 「끝냈다」 선언.

2026년 봄 커뮤니티는 이를 수십 줄 CLAUDE.md로 압축했다(forrestchang/andrej-karpathy-skills, 통칭 Karpathy Skills). 새 런타임 없음 — 네 가지 행동 계약뿐. Claude Code는 매 세션 읽는다. 궁금했던 건 I tested it — 숫자가 얼마인가.

Karpathy Skills란

이름은 Skills지만 형태는 프로젝트 지시 파일. OpenAI GPT Skills도 OpenHuman SKILL.md 플러그인도 아니다. Claude Code는 세션 시작 시 저장소 루트 CLAUDE.md(와 글로벌 플러그인 동등 텍스트)를 읽고, 첫 요구 한 줄 전에 Agent의 생각과 diff 범위를 묶는다.

네 원칙은 업스트림 CLAUDE.md와 대응한다:

• Think Before Coding: 가정을 말하고, 애매함을 드러내고, 더 단순한 안이 있으면 먼저 제시. 조용히 한 해석으로 시작하지 않기.
• Simplicity First: 문제를 푸는 최소 코드만. 요청 없는 추상·설정·「나중용」 레이어 거절.
• Surgical Changes: 태스크에 필요한 줄만. 이웃 「정리」·포맷 금지. 자신이 넣은 데드코드는 제거. 레거시는 언급만.
• Goal-Driven Execution: 버그·검증 추가를 검증 가능한 목표로(가능하면 실패 테스트부터). 다단계는 단계마다 verify.

설치는 둘 중 하나: Claude Code 플러그인 /plugin install andrej-karpathy-skills@karpathy-skills, 또는 업스트림 CLAUDE.md를 루트에 병합 — 아래 「최종본」은 그대로 복사 가능.

검증 방법

변수 통제 절차(Mac mini M4 Cloud Mac에서 실행 — tmux 장주·xcodebuild 끊김 방지용. 숫자는 로컬 Mac에서도 재현 가능):

• 실제 티켓 10건: Swift 소기능 4, 교차 파일 이름 변경 2, 테스트 보강 2, CI 스크립트 2.
• 모델 고정: claude-opus-4-8, Effort high, 같은 주에 마이너 업그레이드 없음.
• 유일 변수: 대조군은 구 CLAUDE.md(Karpathy 없음). 실험군은 네 원칙 + 아래 팀 규칙 2조.
• 티켓당 2회(A→B 또는 날짜 교차)로 「그날 컨디션」 편향 완화.

리뷰에서 시간 쓰는 5지표 기록:

10티켓 결과

아래는 중앙값(n=10, 공식 벤치 아님). 하나만 기억하면 무관 diff −78%.

무관 diff 18% → 4%는 파일 수는 여전히 많아도 「Payment 모듈 습관 포맷」이 diff에서 사라진 체감 — Surgical Changes 곡선. 첫 CI 5/10 → 8/10은 주로 Goal-Driven Execution: 실패 테스트를 먼저 넣고 구현으로 가는 빈도 상승.

효과 큰 상황

• 교차 파일 이름 변경 / 시그니처 변경: 무관 diff −78% 체감 최대. CR이 지뢰밭이 되지 않음.
• 요구가 약간 애매한 소기능: Think Before Coding으로 가정 나열이 앞서며, 재작업 3회→1회(PAY-1842, AUTH-901).
• 테스트 추가 + 구현: 일발 통과율 상승. CLAUDE.md에 「빨강→초록」을 쓰면 안정.

코드 지식 그래프와 직교: 그래프는 「어디를」, CLAUDE.md는 「엉뚱히 건드리지 말 것」.

거의 안 먹는 상황(실패 사례 포함)

실망한 1건: 상수 하나. 티켓 CFG-77: maxRetryCount 3→5, 경로 명시됨. Karpathy 켜도 Agent는 「백오프 전략·단위 테스트 기본값도 바꿀까?」로 확인 1라운드 증가. diff 깔끔함은 무준칙과 동일, 총 +4분. 규격이 극도로 명확한 단일 수정에서는 네 원칙의 신중함이 거의 0 효과.

그 외 거의 무효:

• 팀 CLAUDE.md가 이미 길고 Karpathy와 중복 — 한계 효용 체감.
• 테스트 / xcodebuild 없음 — Goal-Driven이 닫히지 않아 「끝난 척」만 남음.
• 채팅만 하고 저장소에 안 씀 — CLAUDE.md 미로드.

내 CLAUDE.md 최종본(복사용)

CLAUDE.md, Claude Code Rules, Claude Code Prompt 검색자가 원하는 건 저장소에 붙일 완성본. Karpathy 네 원칙 + iOS 팀 규칙 2조 병합(본문 블록은 영어 유지):

# CLAUDE.md — Karpathy rules + Vuncloud iOS team

## Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing: state assumptions; if unclear, ask; if a simpler approach exists, say so.

## Simplicity First
Minimum code that solves the problem. Nothing speculative.
No extra abstractions, config, or error handling for impossible cases.

## Surgical Changes
Touch only what you must. Don't "improve" adjacent code or formatting.
Match existing style. Mention unrelated dead code; don't delete unless asked.

## Goal-Driven Execution
Transform tasks into verifiable goals (tests first when applicable).
Multi-step: list plan with verify check per step.

## Vuncloud: Build Verification (custom)
After code changes to Swift/ObjC targets, run before claiming done:
  xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16'
Report exit code. If tests fail, fix or stop — do not claim success.

## Vuncloud: Path Allowlist (custom)
Unless the user explicitly expands scope, only edit paths they named
or standard paired test paths (e.g. Sources/Foo/ ↔ Tests/Foo/).

업스트림 설치:

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

# 또는 per-project:
curl -fsSL -o /tmp/karpathy-claude.md \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# 기존 CLAUDE.md 덮어쓰지 말고 단락 병합

Cursor 사용자는 .cursor/rules/karpathy-guidelines.mdc 동기화. Karpathy 측정 시 claude-opus-4-8 고정, 모델 업과 섞지 말 것 — Opus 4.8 장주 가이드.

Cloud Mac 장시간 운용(Claude Code → tmux → Mac mini)

OpenHuman보다 Cloud Mac이 자연스러운 이유는 고리가 닫히기 때문: Claude Code 장세션 → tmux 끊김 방어 → 동일 머신 xcodebuild → 전용 Mac mini. 대조 실험·야간 Agent·시차 CR은 노트북 절전이 무섭다. 시범은 Cloud Mac으로 환경 안정만 취했고, 숫자는 로컬에서도 재현 가능.

• tmux + Claude Code: SSH 끊겨도 세션 유지(Opus 4.8 글 예시).
• 영구 볼륨의 CLAUDE.md: 준칙과 monorepo 동행, 설정 유실 없음.
• Goal-Driven 하드 검수: Build Verification을 CLAUDE.md에 쓰고 Scheme 실행까지 완료 보고.
• Mac 클라우드 CI와 동일 머신에서 수정 즉 검증.

대조 실험 스크립트 조각

TASK_ID="PAY-1842"
git diff --stat main...HEAD > "/tmp/${TASK_ID}-stat.txt"
git diff --name-only main...HEAD | wc -l | awk '{print "files_changed=" $1}'
# 무관 경로: 수동 또는 allowlist 비교
xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16' \
  | tee "/tmp/${TASK_ID}-xcodebuild.log"
echo "exit=$?" >> "/tmp/${TASK_ID}-xcodebuild.log"

Claude Code 요청은 목표 문장으로 네 번째 원칙을 찌른다:

목표: CheckoutViewModel.validateAmount에 비양수 검증 추가.
검증: 1) 0·음수·NaN 단위 테스트 추가; 2) xcodebuild test -scheme YourApp 통과;
범위: Sources/Checkout/와 대응 Tests/만. UI 테마·다른 모듈 금지.

자주 묻는 질문 (FAQ)

Karpathy 공식 작성? 준칙은 X 관찰에서 비롯. CLAUDE.md는 커뮤니티 정리(Forrest Chang 등). Karpathy가 관련 저장소 RT한 적 있음 — README를 정본으로.

Claude Code memory / 프로젝트 설명과 충돌? 병합이 맞다. 네 원칙을 앞에, 팀 네이밍·브랜치·테스트 명령을 뒤에.

Code Review 대체? 아니다. 노이즈 diff는 줄지만 머지 게이트·수동 CR·보안 스캔은 필수.

Cursor 사용자? .cursor/rules/ 복사. 같은 git이면 Claude Code와 의미 일치.

퍼센트 인용 가능? 자팀 대조 실험을 인용해 달라. 본문 표는 Vuncloud 시범(n=10, 엄격한 이중맹검 아님).

결론

Karpathy Skills를 쟀다. 「쓸 만하다」 수준이 아니다. 10티켓·Opus 4.8 고정: 무관 diff 약 78% 감소, 첫 CI +30pp; 상수 수정은 거의 도움 안 됨. 가치는 저장소에 쓴 CLAUDE.md — Karpathy 네 원칙 + 자체 빌드·경로 규칙. Claude Code를 7×24로 돌리려면 Mac mini Cloud Mac + tmux가 OpenHuman보다 자연스럽다. Agent·터미널·Xcode는 같은 macOS에 있어야 한다.