andrej-karpathy-skills

andrej-karpathy-skills

2026년 3월 5일 · @gongsoonyee

들어가며

클로드 코드 같은 코딩 에이전트를 쓰다 보면 “분명 시킨 건 맞게 했는데, 뭔가 미묘하게 어긋나 있다”는 느낌을 받을 때가 있다. 안드레이 카파시(Andrej Karpathy)도 비슷한 이야기를 했다. LLM이 하는 실수가 문법 오류 같은 단순한 문제가 아니라, 약간 산만하고 성급한 주니어 개발자가 할 법한 미묘한 실수라서 결국 사람이 결과물을 계속 감시해야 한다는 것이다.

LLM이 자주 하는 실수 패턴

카파시가 예시로 언급한 패턴은 다음과 같다.

  • 모델이 잘못된 가정을 하고, 확인하지 않은 채 그대로 작업을 실행한다
  • 혼란을 관리하지 못한다
  • 명확한 설명을 요청하지 않는다
  • 반박해야 할 때 반박하지 않는다
  • 상충되는 선택지(트레이드오프)를 제안하지 않는다

여기에 더해, 코드를 필요 이상으로 복잡하게 만들거나, 작업과 상관없는 주석이나 코드를 슬쩍 지워버리는 문제도 자주 거론된다. 한 번쯤 diff를 열어보고 “이건 왜 바뀌었지?” 싶었던 경험이 있다면 공감할 것이다.

andrej-karpathy-skills란?

LLM이 이런 실수를 하지 않도록 누군가 행동지침을 만들었다. 개발자 Forrest Chang이 카파시의 LLM 코딩 함정에 대한 관찰을 하나의 실행 가능한 CLAUDE.md 파일로 정리한 것이 바로 andrej-karpathy-skills다.

이름 때문에 오해하기 쉬운데, 이건 카파시의 공식 저장소가 아니다. 그가 공개적으로 남긴 관찰을 한 파일로 압축한 커뮤니티 프로젝트다. 그럼에도 반응은 뜨거워서, GitHub에서 빠르게 스타를 모으며 화제가 됐다.

핵심은 4가지 원칙

지침은 네 가지 원칙, 즉 Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution으로 구성되어 있다. 간단히 풀어보면 이렇다.

1. 코딩 전에 생각하기 (Think Before Coding)

바로 코드부터 짜지 말고, 가정을 명시하고 모호한 부분은 먼저 질문하라는 원칙이다. 위에서 말한 “잘못된 가정을 확인 없이 실행”하는 문제를 직접 겨냥한다.

2. 단순함 우선 (Simplicity First)

요청받지 않은 추상화나 기능을 덧붙이지 말고, 문제를 해결하는 가장 단순한 코드를 쓰라는 것이다.

3. 외과수술식 변경 (Surgical Changes)

필요한 부분만 정확히 고치라는 원칙이다. LLM은 자기가 이해하지 못한 주석이나 코드를 부작용처럼 지워버리기도 하는데, 그 코드가 작업과 무관한 경우에도 그렇다는 문제를 막기 위한 장치다.

4. 목표 중심 실행 (Goal-Driven Execution)

“되게 해줘” 같은 막연한 요청 대신, 검증 가능한 성공 기준을 세우고 그걸 만족할 때까지 반복하게 만드는 원칙이다. README에서도 기준이 약하면 계속 확인이 필요하다고 짚고 있다. LLM은 명확한 목표가 주어지면 그걸 달성할 때까지 반복하는 데 능하다는 카파시의 관찰과 연결된다.

사용 방법

방법은 두 가지다. 자신의 프로젝트 CLAUDE.md에 지침을 복사해 붙여넣거나, 클로드 코드 플러그인으로 설치하면 된다.

방법 1: 클로드 코드 플러그인 (권장)

클로드 코드 안에서 마켓플레이스를 추가한 뒤 플러그인을 설치한다.

1
2

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

한 번 설치하면 모든 프로젝트에서 사용할 수 있다.

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

새 프로젝트라면 파일을 그대로 받으면 된다.

1

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

이미 CLAUDE.md가 있는 프로젝트라면 기존 내용 뒤에 덧붙인다.

1
2

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

행동 지침

LLM의 일반적인 코딩 실수를 줄이기 위한 행동 지침이다. 프로젝트별 지침이 있을 경우 본 가이드라인과 병합하여 사용한다.

트레이드오프: 본 지침은 속도보다 신중함에 우선순위를 둔다. 사소한 작업은 상황에 맞게 판단한다.

1. 구현 전 사고 (Think Before Coding)

가정하지 않는다. 모호함을 숨기지 않는다. 트레이드오프를 명확히 밝힌다.

구현을 시작하기 전 다음을 준수한다:

  • 자신의 가정을 명시적으로 기술한다. 불확실한 경우 질문한다.
  • 해석의 여지가 여러 가지라면 임의로 선택하지 말고 대안들을 제시한다.
  • 더 간단한 접근 방식이 있다면 제안한다. 정당한 사유가 있다면 사용자의 요청에 반대 의견을 제시한다.
  • 불분명한 부분이 있다면 작업을 중단한다. 혼란스러운 부분을 구체적으로 언급하며 질문한다.

2. 단순성 우선 (Simplicity First)

  • 문제를 해결하는 최소한의 코드만 작성한다. 추측에 기반한 코드는 배제한다.
  • 요청되지 않은 기능은 추가하지 않는다.
  • 일회성 코드를 위해 추상화 계층을 만들지 않는다.
  • 요청되지 않은 유연성이나 설정 가능성을 고려하지 않는다.
  • 발생 불가능한 시나리오에 대한 예외 처리를 하지 않는다.
  • 200줄의 코드를 50줄로 줄일 수 있다면 코드를 다시 작성한다.
  • “시니어 엔지니어가 보기에 이 코드가 지나치게 복잡한가?”라고 자문한다. 그렇다면 단순화한다.

3. 정밀한 수정 (Surgical Changes)

필요한 부분만 수정한다. 본인이 만든 코드의 뒷정리만 수행한다.

기존 코드를 편집할 때 다음을 준수한다:

  • 인접한 코드, 주석, 포맷을 임의로 개선하지 않는다.
  • 망가지지 않은 부분을 리팩토링하지 않는다.
  • 본인의 스타일과 다르더라도 기존 스타일을 따른다.
  • 작업과 무관한 데드 코드를 발견하면 보고하되 직접 삭제하지 않는다.

수정으로 인해 사용되지 않게 된 요소가 발생할 경우:

  • 본인의 수정으로 인해 불필요해진 임포트, 변수, 함수는 제거한다.
  • 기존에 존재하던 데드 코드는 요청이 없는 한 그대로 둔다.
  • 테스트 기준: 변경된 모든 라인은 사용자의 요청사항과 직접적으로 연결되어야 한다.

4. 목표 중심 실행 (Goal-Driven Execution)

성공 기준을 정의한다. 검증될 때까지 반복한다.

작업을 검증 가능한 목표로 변환한다:

  • “유효성 검사 추가” → “잘못된 입력에 대한 테스트 작성 후 통과 확인”
  • “버그 수정” → “버그를 재현하는 테스트 작성 후 통과 확인”
  • “X 리팩토링” → “리팩토링 전후의 테스트 통과 확인”

다단계 작업의 경우 간략한 계획을 수립한다:

  1. [단계] → 검증: [확인 사항]
  2. [단계] → 검증: [확인 사항]
  3. [단계] → 검증: [확인 사항]

성공 기준이 명확해야 독립적인 작업이 가능하다. “작동하게 만들기”와 같은 모호한 기준은 불필요한 재질의를 야기한다.

지침 작동 확인: Diff 내 불필요한 변경 감소, 복잡성으로 인한 재작성 빈도 감소, 구현 전 질문을 통한 명확한 의사결정 증대.

참고 링크

comments powered by Disqus