Karpathy-Inspired Claude Code Guidelines: Andrej Karpathy의 LLM 코딩 함정 관찰에서 비롯된 Claude Code 동작 개선 가이드

9bow · 5월 6, 2026, 12:30오전

Karpathy-Inspired Claude Code Guidelines 소개

AI 코딩 에이전트를 사용하다 보면 공통적인 패턴의 실수들을 반복적으로 경험하게 됩니다. 에이전트가 모호한 부분을 스스로 가정하고 그냥 진행하거나, 100줄로 해결할 수 있는 문제를 1,000줄의 복잡한 추상화로 구현하거나, 이해하지 못하는 기존 코드를 슬그머니 삭제하거나 변경하는 경우입니다. Andrej Karpathy는 이러한 LLM 코딩의 함정들을 공개적으로 정리한 바 있으며, forrestchang이 이 관찰들을 바탕으로 Claude Code의 동작을 개선하는 단일 CLAUDE.md 파일인 Karpathy-Inspired Claude Code Guidelines 를 만들었습니다.

이 프로젝트의 핵심은 단순함에 있습니다. 복잡한 플러그인 시스템이나 설정 파일 없이, 단 하나의 CLAUDE.md 파일에 4가지 원칙을 담아 Claude Code의 동작 방식을 근본적으로 바꿉니다. 각 원칙은 Karpathy가 지적한 구체적인 문제를 직접 해결하도록 설계되어 있으며, 원칙들의 조합을 통해 에이전트가 "무엇을 해야 하는지 지시받는 대신 성공 기준을 부여받아 스스로 검증 루프를 돌리는" 방식으로 동작하게 됩니다. 이 접근법은 재시도 횟수를 줄이고 첫 번째 시도에서 원하는 결과를 얻을 가능성을 크게 높입니다.

이 가이드라인은 Claude Code 플러그인, 프로젝트별 CLAUDE.md, Cursor 규칙(.cursor/rules/karpathy-guidelines.mdc) 형태로 설치할 수 있어 다양한 AI 코딩 환경에서 활용할 수 있습니다. 특히 비자명한(non-trivial) 작업에서 발생하는 비용이 큰 실수를 줄이는 데 초점을 맞추고 있습니다. 단순한 오타 수정이나 명백한 한 줄 변경에는 과도한 엄격함이 필요하지 않으므로, 이 가이드라인은 상황에 맞는 판단력을 사용하도록 설계되어 있습니다. 프로젝트 저자인 Forrest Chang은 별도로 코딩 에이전트 운영 플랫폼인 Multica 프로젝트도 개발 중이며, andrej-karpathy-skills는 AI 에이전트의 행동을 정교하게 제어하려는 더 큰 흐름의 일부로 자리잡고 있습니다.

Karpathy-Inspired Claude Code Guidelines의 4가지 핵심 원칙

원칙 1: 코딩 전에 먼저 생각하기 (Think Before Coding)

Karpathy가 지적한 문제: "모델들은 당신을 대신해 잘못된 가정을 세우고 확인 없이 그냥 진행합니다. 혼란을 관리하지 않고, 명확화를 요청하지 않으며, 불일치를 표면화하지 않고, 트레이드오프를 제시하지 않으며, 해야 할 때 반박하지 않습니다."

이 원칙은 에이전트가 가정을 세우거나 혼란을 숨기지 않고, 트레이드오프를 명시적으로 추론하도록 강제합니다. 구현 전에 접근법의 근거를 명확히 하고, 모호한 부분은 진행 전에 물어보게 합니다.

원칙 2: 단순함 우선 (Simplicity First)

Karpathy가 지적한 문제: "코드와 API를 과도하게 복잡화하고, 추상화를 부풀리며, 죽은 코드를 정리하지 않습니다... 100줄로 해결할 수 있는 것을 1,000줄의 과도한 구조로 구현합니다."

이 원칙은 문제를 해결하는 최소한의 코드만 작성하도록 제한하며, 투기적(speculative) 구현을 금지합니다. 검증 테스트: "시니어 엔지니어가 이것을 과도하게 복잡하다고 할까?" 라는 질문으로 코드 복잡성을 자체 평가합니다.

원칙 3: 외과적 변경 (Surgical Changes)

Karpathy가 지적한 문제: "작업과 무관하더라도 충분히 이해하지 못하는 기존 주석과 코드를 변경하거나 삭제하는 경우가 있습니다."

이 원칙은 반드시 필요한 것만 수정하고, 자신이 만든 고아(orphan) 코드만 정리하도록 제한합니다. 모든 변경된 줄은 사용자의 요청으로 직접 추적 가능해야 합니다.

원칙 4: 목표 기반 실행 (Goal-Driven Execution)

Karpathy의 핵심 통찰: "LLM은 구체적인 목표를 달성할 때까지 루프를 도는 데 매우 뛰어납니다... 무엇을 해야 하는지 말하지 말고, 성공 기준을 주고 실행하게 하세요."

이 원칙은 명령적(imperative) 지시를 검증 가능한 목표로 변환합니다. 명확한 성공 기준이 있으면 LLM은 독립적으로 루프를 돌 수 있으며, 모호한 기준("작동하게 해줘")은 끊임없는 확인을 요구합니다.

Karpathy-Inspired Claude Code Guidelines 설치 및 사용법

방법 A: Claude Code 플러그인 (권장)

# Claude Code 내에서 마켓플레이스 추가 후 플러그인 설치
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

플러그인으로 설치하면 모든 프로젝트에서 가이드라인이 적용됩니다. (참고: 이전에는 /add-marketplace https://plugins.forrestchang.dev 와 /install karpathy-skills 형태의 구문을 사용했습니다.)

방법 B: 프로젝트별 CLAUDE.md

# 새 프로젝트
git clone https://github.com/forrestchang/andrej-karpathy-skills.git
cp andrej-karpathy-skills/SKILL.md ./CLAUDE.md

# 기존 프로젝트에 추가 (append)
cat andrej-karpathy-skills/SKILL.md >> ./CLAUDE.md

Cursor와 함께 사용

저장소에 포함된 .cursor/rules/karpathy-guidelines.mdc 파일을 프로젝트에 적용하면 Cursor에서도 동일한 가이드라인을 활용할 수 있습니다.

가이드라인이 효과적으로 작동하는 징후

이 가이드라인을 적용했을 때 다음과 같은 변화를 관찰할 수 있다면 효과가 있는 것입니다.

에이전트가 구현 전에 트레이드오프를 명시적으로 언급함
코드 리뷰에서 "왜 이렇게 복잡하게 했지?"라는 질문이 줄어듦
변경 사항이 요청 범위에 정확히 맞아떨어짐
에이전트가 성공 기준을 스스로 명시하고 달성 여부를 확인함

기존 프로젝트 가이드라인과 병합

이 가이드라인은 프로젝트별 지시문과 병합하도록 설계되어 있습니다. 기존 CLAUDE.md에 추가할 때 프로젝트 특화 규칙을 별도 섹션으로 추가할 수 있습니다.

## Project-Specific Rules

### Technology Stack
- Frontend: React 18 + TypeScript
- Backend: FastAPI + PostgreSQL
- Do not add new dependencies without asking

### Code Style
- Use functional components only
- No class components
- Prefer composition over inheritance

라이선스

Karpathy-Inspired Claude Code Guidelines 프로젝트는 MIT 라이선스로 공개되어 있습니다.

Karpathy-Inspired Claude Code Guidelines GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~