UX 개발 / Claude Code

카파시 스타일로 Claude Code 다듬기: andrej-karpathy-skills 실전 가이드

Claude CodeAndrej KarpathyAgent SkillsCLAUDE.mdAI CodingPrompt EngineeringCode Review

AI 코딩 도구가 만드는 가장 골치 아픈 문제는 문법 오류만이 아니다. 요청하지 않은 추상화를 추가하고, 작은 버그를 고치면서 주변 파일까지 정리하며, 모호한 요구사항을 임의로 해석한 뒤 “완료”라고 말하는 경우가 더 위험하다.

andrej-karpathy-skills는 이런 행동을 줄이기 위한 짧은 코딩 지침 모음이다. Andrej Karpathy가 LLM 코딩의 함정을 설명한 X 게시물에서 아이디어를 가져와, Claude Code와 Cursor에서 재사용할 수 있는 네 가지 원칙으로 정리했다.

먼저 이름 때문에 생길 수 있는 오해부터 바로잡자. 이 저장소는 Karpathy가 직접 만든 공식 스킬이 아니다. Karpathy의 관찰을 바탕으로 커뮤니티가 만든 MIT 라이선스 프로젝트이며, 저장소 manifest의 작성자도 forrestchang으로 표시되어 있다. 이 글은 2026년 8월 6일 기준 저장소의 README, SKILL.md, CLAUDE.md, plugin manifest, Cursor rule과 Claude Code 공식 문서를 교차 확인해 작성했다.

이 저장소에는 무엇이 들어 있나

핵심 내용은 같지만 적용 방식이 세 가지로 제공된다.

파일대상동작 방식추천 상황
skills/karpathy-guidelines/SKILL.mdClaude Code plugin관련 작업에서 불러오거나 명시적으로 실행여러 프로젝트에서 필요할 때만 사용
CLAUDE.mdClaude Code프로젝트 지침으로 매 세션 로드팀 전체가 항상 적용해야 할 때
.cursor/rules/karpathy-guidelines.mdcCursoralwaysApply: true project ruleCursor 저장소에 상시 적용할 때

Claude Code 공식 문서에 따르면 CLAUDE.md는 매 세션 context에 들어가지만, skill 본문은 호출되거나 관련성이 있다고 판단될 때만 로드된다. 따라서 상시 규칙은 CLAUDE.md, 상황별 체크리스트는 skill로 두는 편이 context를 효율적으로 사용한다.

네 가지 핵심 원칙

1. 코딩 전에 생각하기

요구사항의 빈칸을 조용히 상상해서 채우지 않는다. 전제를 먼저 밝히고, 해석이 여러 개라면 선택지와 차이를 설명하며, 확신이 없으면 질문한다.

예를 들어 “검색을 빠르게 만들어 줘”라는 요청을 받았다고 하자. 곧바로 캐시나 검색 엔진을 넣기보다 다음을 먼저 확인한다.

  • 느린 구간이 입력 반응, API, 데이터베이스 중 어디인가?
  • 목표 응답 시간과 데이터 규모는 얼마인가?
  • 최신성이 조금 늦어져도 캐시를 써도 되는가?
  • 현재 병목을 보여 주는 측정 결과가 있는가?

좋은 AI 코딩은 답을 빨리 내는 것이 아니라, 틀린 문제를 빠르게 푸는 일을 피하는 것에서 시작한다.

2. 단순성을 우선하기

오늘 필요한 문제만 해결한다. 한 번 쓰는 추상화, 요청하지 않은 설정 옵션, 미래를 가정한 확장 지점은 만들지 않는다. 같은 결과를 200줄 대신 50줄로 명확하게 만들 수 있다면 다시 줄인다.

단, “단순하게”는 오류 처리나 보안을 생략하라는 뜻이 아니다. 필요한 검증은 남기되, 실제 요구사항으로 설명할 수 없는 구조를 걷어내라는 뜻이다.

3. 필요한 부분만 정밀하게 바꾸기

버그 한 개를 고치면서 따옴표 스타일, 타입 힌트, 주석, 주변 함수 이름까지 바꾸지 않는다. 기존 코드의 스타일을 따르고, 사용자가 요청한 결과와 연결되는 줄만 수정한다.

실전에서는 작업 후 다음 질문을 던지면 된다.

Show every changed file and explain how each changed block is required by my request.
Flag any formatting, cleanup, or refactoring that is unrelated.

설명하기 어려운 변경은 대부분 이번 작업의 범위를 벗어난다. 관련 없는 오래된 코드를 발견했다면 삭제하지 말고 별도 항목으로 알려 주는 것이 안전하다.

4. 검증 가능한 목표로 실행하기

“인증을 개선한다” 같은 모호한 목표를 그대로 실행하지 않는다. “비밀번호 변경 후 기존 세션이 무효화되는 실패 테스트를 만들고, 수정 후 통과시키며, 기존 인증 테스트도 통과시킨다”처럼 관찰 가능한 성공 조건으로 바꾼다.

1. 버그를 재현하는 테스트 작성 → 현재 코드에서 실패 확인
2. 최소 수정 구현 → 재현 테스트 통과 확인
3. 관련 회귀 테스트 실행 → 기존 동작 유지 확인
4. diff 검토 → 요청과 무관한 변경이 없는지 확인

이 원칙은 계획을 길게 쓰라는 뜻이 아니다. 각 단계 뒤에 무엇으로 성공을 확인할지 붙이라는 뜻이다.

설치 방법 A: Claude Code plugin으로 사용하기

여러 프로젝트에서 필요할 때 불러오려면 plugin 방식이 가장 편하다. Claude Code 안에서 현재 GitHub 저장소를 marketplace로 추가한 뒤 plugin을 설치한다.

/plugin marketplace add multica-ai/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

설치 화면에서 범위를 선택할 수 있다.

  • user: 내 모든 프로젝트
  • project: 저장소 팀원과 공유
  • local: 이 저장소에서 나만 사용

설치 결과에 안내가 표시되면 /reload-plugins를 실행한다. 이 plugin의 명시적 호출 이름은 다음과 같다.

/andrej-karpathy-skills:karpathy-guidelines

skill 설명이 코딩·리뷰·리팩터링 작업을 대상으로 하므로 Claude가 관련성을 판단해 불러올 수도 있지만, 중요한 변경 전에는 위 명령으로 직접 실행하는 편이 확실하다.

검증 메모: 저장소가 multica-ai 조직으로 이동했지만, 확인 시점의 README 설치 예시는 이전 forrestchang 경로를 사용하고 있었다. GitHub 리다이렉트에 기대지 않도록 이 글에서는 현재 canonical 경로인 multica-ai/andrej-karpathy-skills를 사용했다.

설치 방법 B: 프로젝트 CLAUDE.md에 적용하기

팀 규칙으로 항상 적용하고 싶다면 저장소의 CLAUDE.md 내용을 프로젝트 지침에 합친다. 기존 CLAUDE.md가 있다면 바로 덮어쓰거나 무조건 이어 붙이지 않는다. 먼저 별도 파일로 받아 충돌과 중복을 검토한다.

curl -fsSL \
  https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md \
  -o /tmp/karpathy-guidelines.md

diff -u CLAUDE.md /tmp/karpathy-guidelines.md

그다음 필요한 원칙만 기존 문서에 병합한다. 프로젝트별 예외도 함께 적어야 한다.

## Karpathy-inspired coding guidelines

- State assumptions before editing when the request is ambiguous.
- Prefer the smallest implementation that meets the stated requirement.
- Do not reformat or refactor unrelated code.
- Define a verification step for every implementation step.

## Project-specific exceptions

- Changes to authentication must include integration tests.
- Generated API clients may be updated only with `npm run generate:api`.

Claude Code의 CLAUDE.md는 강제 정책이 아니라 모델에 제공되는 지침이다. 반드시 차단해야 하는 배포·보안 규칙은 CI, 권한 설정, hook 같은 실행 가능한 장치로 보완한다.

바로 써먹는 프롬프트 세 가지

기능 구현 전

Apply the Karpathy guidelines to this task.
Before editing, list your assumptions and any ambiguous requirements.
Propose the smallest solution, name the files you expect to change,
and attach a verification method to each step. Wait if a decision changes scope.

버그 수정

Reproduce the reported bug first. Define the failing test or observable check,
then make the smallest change that fixes it. Run the focused test and relevant
regression tests. Do not clean up unrelated code. Summarize the final diff.

코드 리뷰

Review this diff using the Karpathy guidelines.
Find hidden assumptions, speculative abstractions, unrelated edits,
and steps without verification. Separate correctness issues from optional ideas.
Do not modify files.

마지막 문장처럼 “파일을 수정하지 말라”는 범위도 명확히 적어야 리뷰 요청이 구현 작업으로 번지는 일을 막을 수 있다.

실전 운영 루틴

작은 팀이라면 다음 흐름만으로도 효과를 확인할 수 있다.

  1. 작업 시작 전에 성공 조건을 한두 문장으로 적는다.
  2. 범위가 모호하거나 영향이 큰 작업에서 skill을 호출한다.
  3. 구현 전에 예상 변경 파일과 검증 방법을 확인한다.
  4. 구현 후 focused test와 관련 회귀 테스트를 실행한다.
  5. git diff --stat과 실제 diff에서 무관한 변경을 걷어낸다.
  6. PR 설명에 “요청 → 변경 → 검증”의 연결을 남긴다.

효과는 거창한 점수보다 다음 질문으로 측정하는 편이 낫다.

  • 요청하지 않은 파일 변경 수가 줄었는가?
  • 구현 후 다시 걷어내는 코드가 줄었는가?
  • 중요한 전제를 수정 전에 확인했는가?
  • 각 변경을 테스트나 관찰 결과로 설명할 수 있는가?

어디까지 믿어야 할까

이 지침은 좋은 기본값이지만 모든 상황의 정답은 아니다.

  • 사소한 문구 수정에도 긴 질문과 계획을 요구하면 속도만 느려진다.
  • 최소 diff가 구조적 문제를 영원히 미루는 핑계가 되어서는 안 된다. 리팩터링이 필요하면 별도 범위와 성공 조건으로 합의한다.
  • 테스트가 잘못된 동작을 고정하면 “테스트 통과”만으로는 충분하지 않다. 사용자 관점의 결과도 확인한다.
  • 보안, 데이터 손실, 결제처럼 실패 비용이 큰 영역에서는 단순성보다 방어와 독립 검증이 우선할 수 있다.
  • 제3자 plugin은 설치 전 source, manifest, 권한과 업데이트 정책을 직접 검토해야 한다.

또한 이 저장소의 원칙은 “카파시가 보증한 표준”이 아니라 그의 관찰을 재구성한 커뮤니티 해석이다. 이름보다 실제 지침이 프로젝트에 맞는지를 기준으로 채택해야 한다.

최종 체크리스트

  • 이 프로젝트가 Karpathy의 공식 배포물이 아님을 이해했다.
  • 상황별 사용은 skill, 상시 팀 규칙은 CLAUDE.md로 구분했다.
  • 설치 전 repository source와 manifest를 확인했다.
  • 코딩 전에 모호한 전제와 선택지를 드러냈다.
  • 현재 요구를 넘는 추상화와 설정을 추가하지 않았다.
  • 모든 변경 줄을 사용자 요청과 연결해 설명할 수 있다.
  • 각 구현 단계에 테스트나 관찰 가능한 검증을 붙였다.
  • 강제해야 하는 보안·배포 규칙은 CI나 hook으로 보완했다.

andrej-karpathy-skills의 진짜 가치는 새로운 코딩 기법을 가르치는 데 있지 않다. AI가 코드를 많이 쓰는 방향이 아니라, 먼저 생각하고, 필요한 만큼만 바꾸고, 결과를 증명하는 방향으로 작업 리듬을 되돌려 준다는 데 있다.

참고 자료

Related