"AI 코딩 에이전트 길들이기 — Karpathy의 4원칙으로 Claude & Cursor 장악하기"

# CLAUDE.md 실전 적용 — Claude Code & Cursor에 Karpathy 원칙 심기

4개의 원칙을 이해했다면 이제 실제 프로젝트에 적용할 차례다. andrej-karpathy-skills는 이 원칙들을 `CLAUDE.md` 단일 파일로 구현했다. 특별한 설정 없이 파일 하나를 프로젝트 루트에 두는 것만으로 적용된다.

---

## 1. 설치 방법 두 가지

### Option A: Claude Code Plugin (권장)

```bash
# Claude Code 내에서 실행
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
```

플러그인으로 설치하면 **모든 프로젝트에 자동 적용**된다. 프로젝트마다 파일을 복사할 필요 없다.

### Option B: CLAUDE.md 직접 추가

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

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

---

## 2. CLAUDE.md가 작동하는 원리

Claude Code는 실행 시작 전에 현재 디렉터리(및 상위)에서 `CLAUDE.md`를 자동으로 읽는다. 이 파일의 내용이 시스템 컨텍스트로 매 요청에 포함된다.

```
사용자 요청 처리 흐름:
1. CLAUDE.md 읽기 → 시스템 컨텍스트에 추가
2. 사용자 요청 수신
3. 시스템 컨텍스트 + 요청으로 응답 생성
```

`CLAUDE.md`가 없으면 모델은 기본 행동 패턴으로 동작한다. `CLAUDE.md`가 있으면 명시된 원칙들이 모든 응답에 영향을 미친다.

---

## 3. Cursor 적용

같은 원칙이 Cursor에도 그대로 적용된다. 저장 위치만 다르다.

```bash
# 프로젝트 루트에서 실행
mkdir -p .cursor/rules
curl -o .cursor/rules/karpathy-guidelines.mdc \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/.cursor/rules/karpathy-guidelines.mdc
```

`andrej-karpathy-skills` 리포에 `.cursor/rules/karpathy-guidelines.mdc`가 이미 포함되어 있다. Claude Code의 `CLAUDE.md`와 동일한 내용이 Cursor rule 형식으로 변환된 것이다.

---

## 4. 프로젝트별 커스터마이징

4원칙은 공통 베이스다. 여기에 프로젝트별 규칙을 추가하는 것이 권장 패턴이다.

```markdown
# CLAUDE.md

## Think Before Coding
...

## Simplicity First
...

## Surgical Changes
...

## Goal-Driven Execution
...

## Project-Specific Guidelines

- TypeScript strict mode 사용
- 모든 API 엔드포인트에 Jest 통합 테스트 필수
- 에러 핸들링은 `src/utils/errors.ts` 패턴 따를 것
- DB 쿼리는 직접 SQL 금지, ORM(Prisma) 사용
- DB 마이그레이션 파일은 수정하지 않음, 새 마이그레이션으로 변경
```

---

## 5. 실전 확인 — 원칙이 작동하는 신호

파일을 설치했다고 끝이 아니다. 실제로 원칙이 적용되는지 확인해야 한다. 원문에서 제시하는 4가지 신호:

```
✅ 원칙이 작동 중:

1. diff에 불필요한 변경이 줄었다
   → 요청된 부분만 수정됨

2. 과설계가 첫 시도에서 줄었다
   → 단순한 코드가 바로 나옴

3. 구현 전에 명확화 질문이 온다
   → 모호한 요청에서 가정을 먼저 제시함

4. PR이 깔끔해졌다
   → drive-by 리팩터링, 무관한 변경 없음
```

이 신호들이 안 보인다면 CLAUDE.md가 적용되고 있는지 경로를 확인하거나, 내용을 더 명시적으로 작성해야 할 수 있다.

---

## 6. Tradeoff — 주의할 점

`CLAUDE.md`는 모든 요청에 적용된다. 간단한 작업도 신중하게 접근한다는 것은 때로 느리게 느껴진다.

원칙 문서의 솔직한 경고:

> "These guidelines bias toward caution over speed.
> For trivial tasks (simple typo fixes, obvious one-liners),
> use judgment — not every change needs the full rigor."

타자 오류 수정, 한 줄짜리 수정에까지 Think Before Coding 루틴을 돌리면 답답하다. 이 원칙은 판단이 필요한 비자명한 작업에서 진가를 발휘한다.

> 💡 **핵심**: `CLAUDE.md`는 설치가 끝이 아니다. 원칙이 실제로 작동하는지 diff와 응답 패턴으로 확인하고, 프로젝트 특성에 맞게 확장해야 완성된다.

> 💡 **다음 챕터**: 이제 4원칙을 넘어서 — 내 팀, 내 프로젝트에 맞는 AI 코딩 가이드라인을 직접 만드는 방법.

"CLAUDE.md 실전 적용 — Claude Code & Cursor에 Karpathy 원칙 심기"

// COMMENTS

ON THIS PAGE