A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.
제 새 프로젝트 Multica를 확인해보세요 — 재사용 가능한 스킬로 코딩 에이전트를 실행하고 관리하기 위한 오픈소스 플랫폼입니다.
>
X에서 저를 팔로우하세요: https://x.com/jiayuanjy
Andrej Karpathy의 관찰에서 파생된, Claude Code의 동작을 개선하기 위한 단일 CLAUDE.md 파일입니다.
English | 简体中文
Andrej의 글에서:
"모델들이 당신을 대신해 잘못된 가정을 하고 확인 없이 그대로 실행합니다. 혼란을 관리하지 않고, 명확성을 구하지 않으며, 불일치를 표면화하지 않고, 트레이드오프를 제시하지 않으며, 필요할 때 반박하지 않습니다."
"코드와 API를 지나치게 복잡하게 만들고, 추상화를 부풀리며, 죽은 코드를 정리하지 않습니다... 100줄이면 충분할 것을 1000줄에 걸쳐 부풀려진 구조를 구현합니다."
"여전히 때때로 충분히 이해하지 못한 주석과 코드를 작업과 직교하더라도 부수 효과로 변경하거나 제거합니다."
이러한 문제를 직접 해결하는 하나의 파일에 담긴 네 가지 원칙:
| 원칙 | 해결 대상 | ||
|---|---|---|---|
| 코딩 전에 생각하기 | 잘못된 가정, 숨겨진 혼란, 누락된 트레이드오프 | ||
| 단순성 우선 | 과도한 복잡성, 부풀려진 추상화 | ||
| 정밀한 변경 | 직교하는 수정, 건드리면 안 되는 코드 건드리기 | ||
| 목표 기반 실행 | 테스트 우선, 검증 가능한 성공 기준을 통한 활용 |
가정하지 마세요. 혼란을 숨기지 마세요. 트레이드오프를 표면화하세요.
LLM은 종종 조용히 하나의 해석을 선택하고 실행합니다. 이 원칙은 명시적인 추론을 강제합니다:
문제를 해결하는 최소한의 코드. 추측성 코드는 없음.
과도한 엔지니어링 경향에 맞서기:
테스트: 시니어 엔지니어가 이것이 지나치게 복잡하다고 말할까요? 그렇다면 단순화하세요.
반드시 필요한 것만 건드리세요. 자신의 변경 사항만 정리하세요.
기존 코드를 편집할 때:
변경으로 인해 고립된 코드가 생기면:
테스트: 변경된 모든 줄은 사용자의 요청에 직접 연결되어야 합니다.
성공 기준을 정의하세요. 검증될 때까지 반복하세요.
명령형 작업을 검증 가능한 목표로 변환:
| 대신... | 다음으로 변환 | ||
|---|---|---|---|
| "유효성 검사 추가" | "잘못된 입력에 대한 테스트를 작성하고 통과시키세요" | ||
| "버그 수정" | "버그를 재현하는 테스트를 작성하고 통과시키세요" | ||
| "X 리팩터링" | "전후에 테스트가 통과하는지 확인하세요" |
다단계 작업의 경우 간단한 계획을 명시하세요:
1. [단계] → 확인: [검사]
2. [단계] → 확인: [검사]
3. [단계] → 확인: [검사]강력한 성공 기준은 LLM이 독립적으로 반복할 수 있게 합니다. 약한 기준("작동하게 만들기")은 지속적인 명확화를 필요로 합니다.
옵션 A: Claude Code 플러그인 (권장)
Claude Code 내에서 먼저 마켓플레이스를 추가하세요:
/plugin marketplace add forrestchang/andrej-karpathy-skills그런 다음 플러그인을 설치하세요:
/plugin install andrej-karpathy-skills@karpathy-skills이렇게 하면 가이드라인이 Claude Code 플러그인으로 설치되어 모든 프로젝트에서 스킬을 사용할 수 있습니다.
옵션 B: CLAUDE.md (프로젝트별)
새 프로젝트:
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md기존 프로젝트 (추가):
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md이 저장소에는 커밋된 Cursor 프로젝트 규칙(.cursor/rules/karpathy-guidelines.mdc)이 포함되어 있어 Cursor에서 프로젝트를 열 때 동일한 가이드라인이 적용됩니다. 설정, 다른 프로젝트에서 규칙 사용, Claude Code와의 관계에 대해서는 CURSOR.md를 참조하세요.
Andrej로부터:
"LLM은 특정 목표를 달성할 때까지 반복하는 데 매우 뛰어납니다... 무엇을 해야 하는지 말하지 말고, 성공 기준을 제시하고 지켜보세요."
"목표 기반 실행" 원칙이 이를 포착합니다: 명령형 지시를 검증 루프가 있는 선언적 목표로 변환하세요.
다음과 같은 경우 이 가이드라인이 작동하고 있는 것입니다:
이 가이드라인은 프로젝트별 지침과 병합되도록 설계되었습니다. 기존 CLAUDE.md에 추가하거나 새로 만드세요.
프로젝트별 규칙의 경우 다음과 같은 섹션을 추가하세요:
## 프로젝트별 가이드라인
- TypeScript strict 모드 사용
- 모든 API 엔드포인트에는 테스트가 있어야 함
- `src/utils/errors.ts`의 기존 오류 처리 패턴 따르기이 가이드라인은 속도보다 신중함에 치우칩니다. 사소한 작업(간단한 오타 수정, 명백한 한 줄짜리)의 경우 판단을 사용하세요 — 모든 변경에 전체 엄격함이 필요한 것은 아닙니다.
목표는 간단한 작업을 느리게 하는 것이 아니라, 중요하지 않은 작업에서 비용이 많이 드는 실수를 줄이는 것입니다.
MIT