dev: Karpathy LLM 코딩 4원칙 참고 문서 추가

dev/_index.md

@@ -12,5 +12,6 @@ tags: [moc, dev]
 | [[claude-code-setup]] | Claude Code 설정 및 인스트럭션 |
 | [[dev-environment]] | 개발 환경 및 도구 (Chrome CDP 등) |
 | [[go-vibe-coding]] | Go 바이브코딩 가이드 |
+| [[karpathy-coding-principles]] | Karpathy LLM 코딩 4원칙 (외부 코딩 프로젝트 참고용) |
 | [[obsidian-schema]] | Obsidian Frontmatter 스키마 (Bases/Dataview 쿼리용) |
 | [[workstations]] | 개인 워크스테이션 / 모바일 디바이스 인벤토리 |

dev/karpathy-coding-principles.md

@@ -0,0 +1,93 @@
+---
+title: Karpathy 코딩 4원칙 (LLM 코딩 참고용)
+updated: 2026-05-04
+tags: [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원칙이 그대로 유효**하므로 그때 이 문서 참고할 것.