andrej-karpathy-skills

KO | EN

gitlite — search

#javascript #python #llm #go #rust #docker #nodejs #windows #awesome #cli #vue #mcp #ios #open-source

andrej-karpathy-skills

(★ 204,772)

Andrej Karpathy의 LLM 코딩 함정에 대한 관찰을 바탕으로 Claude Code 동작을 개선하는 단일 CLAUDE.md 파일입니다.

파일 탐색기

최종 버전 다운로드 (.zip)

- marketplace.json
- plugin.json
- - karpathy-guidelines.mdc
- - SKILL.md
CLAUDE.md
CURSOR.md
EXAMPLES.md
README.md
README.zh.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Karpathy-Inspired Claude Code Guidelines

> 내 새 프로젝트 [Multica](https://github.com/multica-ai/multica)를 확인해보세요 — 재사용 가능한 스킬을 통해 코딩 에이전트를 실행하고 관리하는 오픈소스 플랫폼입니다.
>
> X 팔로우하기: [https://x.com/jiayuan_jy](https://x.com/jiayuan_jy)

LLM 코딩의 함정에 대한 [Andrej Karpathy의 관찰](https://x.com/karpathy/status/2015883857489522876)을 바탕으로 Claude Code의 동작을 개선하기 위한 단일 `CLAUDE.md` 파일입니다.

English | [简体中文](./README.zh.md)

## 문제점

Andrej의 게시물 내용:

> "모델들은 여러분을 대신해 잘못된 가정들을 하고, 이를 확인하지 않은 채 그대로 진행합니다. 혼란을 관리하지 않고, 명확한 설명을 구하지 않으며, 모순을 드러내지 않고, 트레이드오프를 제시하지 않으며, 반박해야 할 때 반박하지 않습니다."

> "그들은 코드와 API를 지나치게 복잡하게 만들고, 추상화를 비대화하며, 죽은 코드를 정리하지 않는 경향이 있습니다... 100줄이면 충분한 곳에 1000줄이 넘는 비대한 구조를 구현합니다."

> "그들은 여전히 작업과 관련이 없는(orthogonal) 경우에도, 부작용으로 충분히 이해하지 못한 주석과 코드를 때때로 변경하거나 제거합니다."

## 해결책

이러한 문제들을 직접적으로 해결하는 하나의 파일에 담긴 네 가지 원칙:

| 원칙 | 해결하는 문제 |
|-----------|-----------|
| **코딩 전 생각하기 (Think Before Coding)** | 잘못된 가정, 숨겨진 혼란, 누락된 트레이드오프 |
| **단순함 우선 (Simplicity First)** | 지나친 복잡성, 비대한 추상화 |
| **정밀한 수정 (Surgical Changes)** | 무관한 수정, 건드리지 말아야 할 코드 수정 |
| **목표 지향적 실행 (Goal-Driven Execution)** | 테스트 선행을 통한 활용, 검증 가능한 성공 기준 |

## 상세 네 가지 원칙

### 1. 코딩 전 생각하기

**가정하지 마세요. 혼란을 숨기지 마세요. 트레이드오프를 드러내세요.**

LLM은 종종 암묵적으로 해석을 선택하고 그대로 진행합니다. 이 원칙은 명시적인 추론을 강제합니다:

- **가정을 명시적으로 진술하기** — 확실하지 않다면 추측하지 말고 질문하세요.
- **여러 해석 제시하기** — 모호함이 존재할 때 암묵적으로 선택하지 마세요.
- **필요할 때 반박하기** — 더 단순한 접근 방식이 있다면 그렇게 말하세요.
- **혼란스러울 때 멈추기** — 무엇이 불분명한지 명시하고 명확한 설명을 요청하세요.

### 2. 단순함 우선

**문제를 해결하는 최소한의 코드. 추측성 코드는 금물.**

과잉 엔지니어링 경향과의 싸움:

- 요청받은 것 이상의 기능 금지
- 단일 사용 코드를 위한 추상화 금지
- 요청되지 않은 "유연성"이나 "설정 가능성" 금지
- 불가능한 시나리오에 대한 오류 처리 금지
- 200줄짜리를 50줄로 만들 수 있다면 다시 작성하세요.

**테스트:** 시니어 엔지니어가 이것이 지나치게 복잡하다고 말할 것인가? 그렇다면 단순화하세요.

### 3. 정밀한 수정

**반드시 필요한 부분만 건드리기. 자신의 실수는 스스로 정리하기.**

기존 코드를 수정할 때:

- 인접한 코드, 주석, 포맷팅을 "개선"하려 하지 마세요.
- 망가지지 않은 것을 리팩터링하지 마세요.
- 다르게 작성하고 싶더라도 기존 스타일을 따르세요.
- 관련 없는 죽은 코드를 발견했다면 언급만 하고 삭제하지는 마세요.

수정으로 인해 고아 코드가 생겼을 때:

- 당신의 수정으로 인해 사용되지 않게 된 임포트/변수/함수를 제거하세요.
- 요청받지 않았다면 기존의 죽은 코드를 제거하지 마세요.

**테스트:** 변경된 모든 라인은 사용자의 요청에 직접적으로 추적될 수 있어야 합니다.

### 4. 목표 지향적 실행

**성공 기준 정의하기. 검증될 때까지 반복하기.**

명령형 작업을 검증 가능한 목표로 변환:

| 기존 방식... | 다음으로 변환... |
|--------------|-----------------|
| "유효성 검사 추가" | "잘못된 입력에 대한 테스트를 작성한 후 통과시키기" |
| "버그 수정" | "버그를 재현하는 테스트를 작성한 후 통과시키기" |
| "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 (프로젝트별)**

새 프로젝트:
```bash
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
```

기존 프로젝트 (추가):
```bash
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
```

## Cursor와 함께 사용하기

이 저장소에는 커밋된 Cursor 프로젝트 규칙([`.cursor/rules/karpathy-guidelines.mdc`](.cursor/rules/karpathy-guidelines.mdc))이 포함되어 있어, Cursor에서 프로젝트를 열었을 때 동일한 가이드라인이 적용됩니다. 설정 방법, 다른 프로젝트에서의 규칙 사용법, 그리고 이것이 Claude Code와 어떤 관련이 있는지에 대해서는 **[CURSOR.md](CURSOR.md)**를 참조하세요.

## 핵심 통찰

Andrej의 말:

> "LLM은 특정 목표를 달성할 때까지 반복 작업을 수행하는 데 매우 뛰어납니다... 무엇을 해야 할지 지시하지 말고, 성공 기준을 제시하고 어떻게 하는지 지켜보세요."

"목표 지향적 실행" 원칙은 이를 포착합니다: 명령형 지시사항을 검증 루프가 있는 선언적 목표로 변환합니다.

## 동작하고 있는지 확인하는 방법

다음과 같은 현상이 보인다면 이 가이드라인이 제대로 작동하고 있는 것입니다:

- **diff에서 불필요한 변경 감소** — 요청된 변경사항만 나타납니다.
- **과잉 복잡성으로 인한 재작성 감소** — 코드가 처음부터 단순합니다.
- **구현 전에 명확화 질문 제기** — 실수를 저지른 후가 아닙니다.
- **깔끔하고 최소한의 PR** — 곁다리 리팩터링이나 "개선" 작업이 없습니다.

## 커스터마이징

이 가이드라인은 프로젝트 고유의 지침과 병합되도록 설계되었습니다. 기존 `CLAUDE.md`에 추가하거나 새로 만드세요.

프로젝트 전용 규칙의 경우 다음과 같은 섹션을 추가하세요:

```markdown
## Project-Specific Guidelines

- TypeScript 엄격 모드 사용
- 모든 API 엔드포인트에는 테스트가 있어야 함
- `src/utils/errors.ts`의 기존 오류 처리 패턴 준수
```

## 트레이드오프 참고 사항

이 가이드라인은 속도보다는 **신중함**에 무게를 둡니다. 사소한 작업(간단한 오타 수정, 명확한 한 줄짜리 수정)의 경우 판단력을 발휘하세요. 모든 변경에 엄격한 규칙이 필요한 것은 아닙니다.

목표는 단순한 작업을 느리게 만드는 것이 아니라, 중요하지 않은 작업에서의 비용 많이 드는 실수를 줄이는 것입니다.

## 라이선스

MIT

andrej-karpathy-skills

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

andrej-karpathy-skills

파일 탐색기

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README