obsidian/dev/karpathy-coding-principles.md

title, updated, tags

title	updated	tags
Karpathy 코딩 4원칙 (LLM 코딩 참고용)	2026-05-04	dev llm coding reference

출처

• 레포: https://github.com/forrestchang/andrej-karpathy-skills
• Andrej Karpathy의 LLM 코딩 관찰을 4원칙으로 정리한 가이드
• 본 문서는 코딩 작업 시 참고용. CLAUDE.md에는 적용하지 않음 (이유는 맨 아래 참조)

문제 정의

LLM이 코딩할 때 자주 하는 4가지 실수:

1. 잘못된 가정을 silent하게 진행
2. 과도하게 추상화/일반화
3. 요청 범위 밖까지 손대기
4. 명확한 성공 기준 없이 "고쳤다" 선언

4원칙

1. Think Before Coding (생각 먼저, 코드 나중)

"Don't assume. Don't hide confusion. Surface tradeoffs."

• 가정을 명시적으로 표면화. silent하게 결정 내리지 말 것
• 모호한 부분이 있으면 여러 해석 제시 후 선택 요청
• 혼란스러우면 멈춰서 물어볼 것

예시: "유저 데이터 export 기능 추가해줘" 라는 요청에

• 전체 vs 필터링?
• 다운로드 파일 vs 백그라운드 잡 vs API 엔드포인트?
• 어떤 필드?
• 보통 몇 명 규모?

→ 위를 모두 추측하지 말고 물어볼 것.

2. Simplicity First (단순함 먼저)

"Minimum code that solves the problem. Nothing speculative."

• 요청한 것만 구현. 미요청 기능 추가 금지
• 1회성 추상화 금지 (use case 1개에 strategy pattern + abstract base class 금지)
• speculative error handling 금지
• 벤치마크: "시니어가 이걸 over-engineered라고 할까?"

예시: 할인 계산 함수 하나 → 그냥 함수 하나로. 추상 베이스 클래스나 strategy pattern은 진짜 다양성이 생긴 후에.

3. Surgical Changes (외과적 변경)

"Touch only what you must. Clean up only your own mess."

• 필요한 것만 건드릴 것
• 기존 스타일 보존 (quote 스타일, 타입힌트 스타일 등)
• 무관한 리팩토링 금지
• import/변수 정리는 본인이 만든 미사용분만. 기존에 있던 미사용은 손대지 말 것

예시: "빈 이메일에서 크래시 나는 거 고쳐줘" 라는 버그 픽스에서

• 이메일 validation 로직 전체 개선 ❌
• quote 스타일 통일 ❌
• 타입힌트 추가 ❌
• 그 버그만 고치기 ✅

4. Goal-Driven Execution (목표 기반 실행)

"Define success criteria. Loop until verified."

• 시작 전에 검증 가능한 성공 기준 정의
• 가능하면 테스트 먼저 작성 → 통과시키는 방향으로 구현
• 복잡한 작업은 단계별 검증 체크포인트 둘 것
• "고쳤다"가 아니라 "검증했다"가 종료 조건

예시: "인증 시스템 고쳐줘"

• ❌ 막연히 코드 수정 후 "고쳤습니다"
• ✅ 1) 재현 테스트 작성 → 2) 버그 재현 확인 → 3) 픽스 → 4) 테스트 통과 → 5) 회귀 없음 확인

핵심 한 줄

"Good code is code that solves today's problem simply, not tomorrow's problem prematurely."

kappa 환경에 적용 안 한 이유 (참고)

CLAUDE.md에 4원칙을 직접 박지 않은 이유:

원칙	현재 상태
1. Think Before Coding	feedback_act_dont_ask, feedback_less_confirmation로 정반대 방침 (확인 질문 최소화). 인프라 운영 위주라 추론·실행 비용이 작은 컨텍스트
2. Simplicity First	Claude Code 시스템 프롬프트에 "Don't add features...beyond what the task requires" 동일 문구 이미 존재
3. Surgical Changes	시스템 프롬프트의 "Avoid backwards-compatibility hacks", "Don't add error handling for scenarios that can't happen"로 커버
4. Goal-Driven Execution	verify-before-done 스킬이 종료 직전 검증을 강제 (시점이 다름 — Karpathy는 시작 전 정의)

다른 코딩 프로젝트(특히 외부 협업 / 신규 코드베이스)에서는 4원칙이 그대로 유효하므로 그때 이 문서 참고할 것.