카파시 스킬 설치법: CLAUDE.md 하나로 클로드 코드 실수 줄이기

카파시 스킬 CLAUDE.md 파일 화면 위에 '카파시 스킬 설치법' 제목

깃허브 별 22만 개짜리 저장소를 열어 봤는데 프로그램이 없어요. 핵심은 65줄짜리 문서 한 장입니다. 이름은 카파시 스킬, 저장소 이름으로는 andrej-karpathy-skills예요.

클로드 코드에 “이것 좀 추가해 줘” 했는데 시키지도 않은 기능까지 잔뜩 붙여 온 적 있다면 딱 그 문제를 겨냥한 파일이에요. CLAUDE.md(클로드 코드가 작업 때마다 읽는 지침 파일)에 넣어 두면 끝이라 설치도 1분이면 됩니다. 실제로 달라지는지 궁금해서 제 라즈베리파이에서 같은 요청을 파일 있을 때와 없을 때로 나눠 돌려 봤어요.

andrej-karpathy-skills 깃허브 저장소 첫 화면, 별 227k 포크 22.6k
별 22.7만 · 포크 2.3만 · 출처: andrej-karpathy-skills 깃허브

카파시 스킬, 카파시가 만든 건 아니에요

이름 때문에 헷갈리기 쉬운데, 안드레이 카파시 본인 저장소가 아닙니다. 카파시가 2026년 1월 X(옛 트위터)에 클로드로 코딩하며 느낀 점을 올렸고, 그 글을 바탕으로 개발자 forrestchang이 지침 파일로 묶은 거예요. 저장소는 1월 27일에 만들어졌고, README도 “카파시의 관찰에서 나온(derived from)” 파일이라고 적어 뒀습니다. 카파시의 공식 프로젝트처럼 소개하는 글은 걸러서 보시는 게 좋아요.

README가 인용한 카파시의 불만은 세 가지입니다. 모델이 멋대로 가정하고 확인 없이 달린다, 코드와 API를 지나치게 복잡하게 만든다(100줄이면 될 걸 1000줄로), 작업과 상관없는 주석·코드를 건드린다. X 원문은 제 환경에서 열리지 않아서 README에 실린 인용문 기준으로 옮겼어요.

README에 인용된 카파시의 LLM 코딩 문제 지적 세 문장
README에 인용된 카파시의 지적 · 출처: andrej-karpathy-skills 깃허브

CLAUDE.md 원칙 4가지

파일은 이 세 불만에 맞춘 규칙 네 개로 되어 있어요.

카파시 스킬 원칙 4가지와 각각 고치려는 문제를 정리한 README 표
원칙 4가지 · 출처: andrej-karpathy-skills 깃허브
  • 코딩 전에 생각하기(Think Before Coding): 가정을 말하고, 불확실하면 묻고, 더 단순한 길이 있으면 반박하기
  • 단순함 먼저(Simplicity First): 요청 안 한 기능, 한 번 쓰는 코드의 추상화, 일어날 수 없는 상황의 오류 처리 넣지 않기
  • 필요한 곳만 수정(Surgical Changes): 옆 코드 “개선” 금지, 기존 스타일 따르기, 내가 만든 찌꺼기만 치우기
  • 목표 기준으로 실행(Goal-Driven Execution): 할 일을 검증 가능한 성공 기준으로 바꾸고 통과할 때까지 반복

처음 두 개는 읽자마자 고개가 끄덕여져요. 파일 맨 위에 적힌 한계도 솔직합니다. 속도보다 신중함에 무게를 둔 지침이라, 오타 수정 같은 사소한 일은 알아서 판단하라고 되어 있어요.

저장소 CLAUDE.md 파일 화면, 65줄 2.3KB
파일 전체 65줄 · 출처: andrej-karpathy-skills 깃허브

제일 실용적인 건 네 번째예요. “검증 기능 추가해 줘”를 “잘못된 입력 테스트를 쓰고 통과시켜 줘”로, “버그 고쳐 줘”를 “재현 테스트를 쓰고 통과시켜 줘”로 바꾸라는 거죠. 이건 파일을 안 깔아도 내일부터 말버릇만 바꾸면 써먹을 수 있습니다.

CLAUDE.md의 Goal-Driven Execution 원칙 본문
할 일을 성공 기준으로 바꾸기 · 출처: andrej-karpathy-skills 깃허브

카파시 스킬 설치법, 두 가지 중 고르기

README가 권장하는 건 플러그인 방식입니다. 클로드 코드 안에서 두 줄을 차례로 입력하면 돼요.

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

다른 하나는 프로젝트 폴더에 파일을 직접 받는 방식이에요. 새 프로젝트라면 이렇게 받습니다.

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

이미 CLAUDE.md가 있는 프로젝트에 위 명령을 쓰면 안 돼요. -o는 파일을 덮어쓰기 때문에 애써 적어 둔 내 지침이 날아갑니다. 기존 프로젝트는 README에 있는 덧붙이기 명령을 쓰세요.

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
카파시 스킬 플러그인 설치 명령과 curl 설치 명령이 적힌 README 화면
공식 README의 설치 명령 · 출처: andrej-karpathy-skills 깃허브

저장소 주소가 multica-ai로 옮겨졌는데 명령에는 옛 이름 forrestchang이 그대로예요. 옛 주소도 새 저장소로 넘어가게 되어 있고, 제가 받아 봤을 때도 정상이었습니다.

둘의 차이도 알아 두세요. 플러그인은 모든 프로젝트에서 쓸 수 있는 스킬(상황에 맞을 때 불러오는 지침)로 들어가고, CLAUDE.md 방식은 그 프로젝트에서만 세션 시작 때 읽힙니다. 팀원과 같은 규칙을 공유하려면 저장소에 파일을 넣는 쪽이, 혼자 여러 프로젝트에 쓰려면 플러그인이 편해 보여요.

라즈베리파이에서 CLAUDE.md를 curl로 받아 65줄을 확인한 터미널
직접 받아 본 결과 · 출처: 부컴 라즈베리파이 직접 실행

직접 돌려 보니 21줄이 3줄로

저장소의 EXAMPLES.md에는 모델이 흔히 하는 실수와 고친 예시가 원칙별로 9개 실려 있어요. 첫 예시가 “사용자 내보내기 기능 추가”입니다. 묻지도 않고 전체 사용자, 저장 위치, 필드까지 정해 버린 코드가 나쁜 예로 나와요.

EXAMPLES.md의 사용자 내보내기 잘못된 예시 코드
묻지 않고 정해 버린 코드 · 출처: andrej-karpathy-skills 깃허브

그래서 비슷하게 시험해 봤습니다. 사용자를 읽는 함수만 있는 11줄짜리 utils.py를 폴더 두 개에 똑같이 넣고, 한쪽에만 CLAUDE.md를 받았어요. 그리고 양쪽 클로드 코드(소네트 모델)에 “사용자 데이터를 내보내는 기능을 추가해 줘, 파일은 고치지 말고 답변으로만 보여 줘”라고 같은 문장을 넣었습니다.

파일이 없는 쪽은 export_users를 21줄로 짰어요. JSON과 CSV 둘 다, 필드 선택 옵션, 예외 처리까지 먼저 다 넣은 다음에 확인 질문을 하더군요. 파일이 있는 쪽은 3줄이었습니다. 기존 코드가 JSON을 쓰니 JSON으로 가정한다고 먼저 밝히고, 디렉터리 생성이나 예외 처리는 요청이 없어서 뺐다고 적었어요. 저장한 뒤 다시 읽어 비교한다는 검증 계획도 붙었습니다.

CLAUDE.md 유무에 따라 export_users 코드가 21줄과 3줄로 달라진 비교 결과
1번씩 돌린 비교 · 출처: 부컴 라즈베리파이 직접 실행

다만 이건 작은 파일로 1번씩 돌린 결과라 “7분의 1로 줄어든다” 같은 뜻은 아니에요. 파일이 없는 쪽도 끝에 확인 질문 3개를 했고, 코드 자체가 틀린 것도 아니었습니다. 게다가 CSV가 정말 필요했다면 21줄 쪽이 더 빨랐겠죠. 달라진 건 “먼저 만들고 묻느냐, 먼저 묻고 작게 만드느냐”였어요.

쓰기 전에 알아 둘 것

공식 문서 기준으로 CLAUDE.md는 강제 설정이 아니에요. 문서에는 클로드가 이 파일을 맥락으로 받아들일 뿐 강제 설정으로 다루지 않는다고 나옵니다. 어떤 행동을 반드시 막아야 한다면 훅(PreToolUse hook)을 쓰라고 안내해요. “삭제 금지” 같은 안전장치를 이 파일에 맡기면 안 됩니다.

Claude Code 공식 문서 How Claude remembers your project 화면
CLAUDE.md 공식 문서 · 출처: Claude Code 공식 문서

길이는 걱정 없어요. 공식 문서는 CLAUDE.md 파일 하나를 200줄 아래로 유지하라고 권하는데 이 지침은 65줄입니다. 다만 기존 파일에 덧붙이면 그만큼 늘어나니, 합쳐서 200줄을 넘으면 내 지침부터 정리하는 게 좋아요. 그리고 이 파일은 영어로 되어 있어서 한국어로 된 프로젝트 지침과 섞이는데, README도 프로젝트별 규칙과 합쳐서 쓰라고 안내합니다.

커서(Cursor)를 쓴다면 저장소의 .cursor/rules/karpathy-guidelines.mdc 파일을 내 프로젝트의 .cursor/rules/ 폴더로 복사하면 같은 지침이 적용돼요.

저장소 CURSOR.md, 커서에서 같은 지침을 쓰는 방법
커서 사용법 · 출처: andrej-karpathy-skills 깃허브

또 하나, 저장소 마지막 커밋은 2026년 4월 20일이에요. 6개월 넘게 고친 게 없지만 문서 한 장이라 큰 문제는 아니라고 봅니다. README 맨 위에는 제작자의 새 프로젝트 Multica 홍보 문구가 있으니 이것도 감안해서 보시고요. 라이선스는 MIT입니다.

저장소 커밋 기록, 마지막 커밋 2026년 4월 20일
마지막 커밋 4월 20일 · 출처: 저장소 커밋 기록

어떤 사람에게 맞을까

제 생각엔 클로드 코드를 막 쓰기 시작했는데 CLAUDE.md에 뭘 적을지 모르겠는 분께 가장 잘 맞아요. 설치라고 할 것도 없고, 마음에 안 들면 지우면 끝이니 부담이 없습니다. superpowers처럼 스킬 15개로 작업 순서를 통째로 바꾸는 도구가 부담스러웠다면 더 그렇고요. AI가 코드를 덜 짜게 만든다는 점에서는 앞서 다룬 포니테일과 방향이 비슷하고, 플러그인 설치 방식이 낯설면 클로드 코드 공식 플러그인 글을 먼저 보셔도 좋아요.

플러그인 쪽은 이번에 설치하지 않았어요. 제 자동화 스크립트 폴더에 걸어 두고 며칠 써 본 뒤, 하나 고쳐 달랬는데 옆 코드까지 건드리는 일이 실제로 줄어드는지 후기로 정리해 볼 생각입니다. 클로드 코드 쓰면서 제일 자주 겪는 실수는 뭔가요?


출처
· multica-ai/andrej-karpathy-skills 깃허브 저장소·README
· CLAUDE.md 원문
· EXAMPLES.md
· CURSOR.md
· 저장소 커밋 기록
· Claude Code 공식 문서: How Claude remembers your project
(2026년 10월 31일 확인)

컴퓨터가 고장 났다면 부산 컴퓨터수리 · 출장수리 부컴에 맡겨 주세요. 부산·울산·김해·양산 어디든 직접 방문합니다.

함께 보면 좋은 글

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다