
multica-ai/andrej-karpathy-skills
코딩 AI, 왜 부탁 안 한 것까지 고칠까
안드레이 카파시가 짚은 코딩 AI의 버릇을 네 가지 원칙으로 묶어, 클로드 코드가 읽는 규칙 파일(CLAUDE.md) 한 장에 담았어요
코딩 AI에게 "빈 이메일이 들어오면 검사기가 멈추는 버그 좀 고쳐 줘"라고 했어요. 금방 끝났다는데, 바뀐 내용을 열어 보니 주석이 새로 쓰여 있고 아무도 부탁하지 않은 아이디 길이 검사까지 붙어 있어요. 고칠 곳은 이메일 몇 줄이었는데 말이죠. AI 연구자 안드레이 카파시는 모델이 제대로 이해하지 못한 주석과 코드를 부탁받지 않았는데도 바꾸거나 지운다고 적었어요.이 저장소는 그 관찰을 네 가지 원칙으로 정리한 파일 한 장이에요. 카파시가 2026년 1월 26일 X에 코딩 AI의 실수를 적은 글을 올리고 반나절이 지나기 전에, 다른 개발자가 이 저장소를 열었죠. 카파시가 직접 만든 건 아니에요. 이번 주에만 깃허브 별을 3,713개 더 받았어요.
카파시가 짚은 코딩 AI의 세 가지 버릇
버릇 1짐작하고 그대로 달려요
export_users() 를 만들었어요.- 모든 사용자를 한꺼번에 내보내기로 짐작
- 저장 위치도 마음대로 정함
- 넣을 항목도 묻지 않고 고름
카파시: 모델은 사용자를 대신해 틀린 가정을 하고, 확인도 없이 그대로 밀고 나가요. 헷갈려도 묻지 않고, 장단점도 내놓지 않죠.
버릇 2작은 일을 크게 부풀려요
class DiscountStrategyclass PercentageDiscountclass FixedDiscountclass DiscountConfigclass DiscountCalculatorcalculate_discount()카파시: 코드와 구조를 지나치게 복잡하게 만들고 쓰지 않는 코드를 치우지 않아요. 100줄이면 될 것을 1000줄 넘게 짓기도 하고요.
버릇 3부탁 안 한 곳까지 고쳐요
카파시: 맡은 일과 상관없는데도, 잘 이해하지 못한 주석과 코드를 곁다리로 바꾸거나 지워요.
카파시의 글과 저장소의 EXAMPLES.md 에 나온 장면을 줄여서 저희가 그린 예시예요. 실제 코딩 AI가 내놓는 코드는 요청과 모델에 따라 달라져요.
한눈에
무엇인가요
규칙 파일 한 장이에요. 클로드 코드는 프로젝트 폴더에 있는 CLAUDE.md 를 대화마다 먼저 읽어요. 이 저장소는 그 파일에 넣을 행동 지침을 담았고, README는 코딩 AI가 흔히 저지르는 실수를 줄이려는 지침이라고 소개해요.카파시의 관찰에서 나왔어요. 카파시는 몇 주 동안 코딩 AI로 일하며 본 문제를 X에 적었어요. 짐작으로 내린 가정을 확인 없이 밀고 나가고, 코드를 지나치게 부풀리고, 상관없는 코드를 건드린다는 거예요. 이 저장소는 그 지적을 코딩 전에 생각하기, 단순함 먼저, 수술하듯 고치기, 목표로 일하기라는 네 원칙으로 바꿨어요.카파시가 만든 저장소는 아니에요. 깃허브 아이디 forrestchang 인 개발자가 카파시의 글을 바탕으로 정리했어요. README 제목도 '카파시에게서 영감을 얻은 클로드 코드 지침'이고, 저장소 이름에 카파시가 들어 있을 뿐이죠.
함께 쓰는 도구 · 클로드 코드 · 커서
이런 분께
- 코딩 AI가 부탁하지 않은 곳까지 고쳐 놔서 바뀐 내용을 다시 뒤지는 분
- 간단한 기능 하나에 복잡한 코드가 돌아와 당황한 적 있는 분
- CLAUDE.md 에 무엇을 써야 할지 몰라 출발점이 필요한 분
네 가지 원칙, 원문 뜻 그대로
1. 코딩 전에 생각하기. 원칙의 머리말은 "짐작하지 마세요. 헷갈리는 걸 숨기지 마세요. 장단점을 드러내세요"예요. 구현하기 전에 가정을 분명히 말하고, 확실하지 않으면 물어요. 해석이 여러 가지면 조용히 하나를 고르지 말고 모두 내놓아요. 더 단순한 방법이 있으면 말하고, 필요하면 반대해요. 불분명한 게 있으면 멈추고, 무엇이 헷갈리는지 말하고, 물어요.2. 단순함 먼저. 문제를 푸는 최소한의 코드만, 짐작으로 더하는 건 없이 짜요. 부탁받지 않은 기능, 한 번만 쓰는 코드에 씌우는 틀(추상화), 요청하지 않은 '유연성'이나 '설정 기능', 일어날 수 없는 상황에 대비한 오류 처리를 넣지 않아요. 200줄을 썼는데 50줄로 될 수 있다면 다시 써요. 숙련된 개발자가 보고 지나치게 복잡하다고 할지 스스로 물어보라고 해요.3. 수술하듯 고치기. 꼭 건드려야 할 곳만 건드리고, 내가 어지른 것만 치워요. 옆에 있는 코드, 주석, 서식을 '개선'하지 않고, 고장 나지 않은 걸 뜯어고치지 않고, 내 취향과 달라도 원래 스타일을 따라요. 상관없는 죽은 코드(아무 데서도 안 쓰는 코드)를 보면 알려만 주고 지우지 않아요. 내 변경 때문에 안 쓰이게 된 것만 지우죠. 바뀐 줄 하나하나가 사용자의 요청으로 곧장 이어져야 한다는 게 이 원칙의 시험이에요.4. 목표로 일하기. 성공 기준을 정하고, 확인될 때까지 반복해요. '입력 검사를 넣어 줘'는 '잘못된 입력에 대한 테스트를 쓰고 통과시키기'로, '구조를 정리해 줘'는 '정리 전후로 테스트가 통과하는지 확인하기'로 바꾸는 식이에요. 여러 단계짜리 일은 단계마다 무엇으로 확인할지 적은 짧은 계획을 먼저 세워요. 기준이 분명하면 AI가 혼자 반복할 수 있고, '되게만 해 줘' 같은 약한 기준은 계속 확인을 요구한다고 적어요.잘 듣고 있는지 아는 법. README는 바뀐 내용에 불필요한 변경이 줄고, 지나치게 복잡해서 다시 쓰는 일이 줄고, 실수한 뒤가 아니라 구현 전에 질문이 나오면 지침이 작동하는 거라고 적어요.
할 수 있는 일
바로 쓸 수 있나요
필요한 것클로드 코드(유료 요금제)나 커서 같은 코딩 AI 도구 하나
비용파일은 누구나 받을 수 있어요. README에는 MIT라고 적혀 있지만 라이선스 파일은 없어요(아래 주의 참고)
시작하기
- 클로드 코드에 플러그인 장터 추가
클로드 코드 대화창에 입력해요. README 명령에는 예전 주소(forrestchang)가 적혀 있는데, 지금의 multica-ai 저장소로 이어져요.
/plugin marketplace add forrestchang/andrej-karpathy-skills - 플러그인 설치
README가 권하는 방법이에요. 지침이 스킬(필요할 때 꺼내 읽는 작업 설명서)로 들어가 모든 프로젝트에서 쓸 수 있어요.
/plugin install andrej-karpathy-skills@karpathy-skills - 프로젝트 하나에만 넣으려면
플러그인 대신 CLAUDE.md 파일을 프로젝트 폴더에 받아요. 터미널(명령을 글자로 치는 창)에 붙여 넣어요. 새 프로젝트라면 첫 줄만, CLAUDE.md 가 이미 있다면 빈 줄 아래 두 줄을 쳐서 기존 파일 끝에 덧붙여요. curl 은 인터넷에서 파일을 받아 오는 명령이에요.
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md echo "" >> CLAUDE.md curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md - 커서라면
저장소의 .cursor/rules/karpathy-guidelines.mdc 파일을 내 프로젝트의 .cursor/rules/ 폴더에 복사해요(폴더가 없으면 만들어요). 커서는 기본적으로 CLAUDE.md 를 읽지 않는다고 CURSOR.md 가 적어요.
- 우리 프로젝트 규칙 더하기
이 지침은 프로젝트별 규칙과 합쳐 쓰도록 만들어졌어요. README는 '프로그램끼리 주고받는 주소(API)마다 테스트가 있어야 한다' 같은 우리만의 규칙을 같은 파일에 따로 칸을 만들어 적으라고 안내해요.
빈 이메일이 들어오면 검사기가 멈추는 버그를 고쳐 줘
EXAMPLES.md 에 실린 요청 예시를 우리말로 옮겼어요. 지침이 잘 듣는다면 이메일을 다루는 줄만 바뀌고, 주석이나 아이디 검사 같은 상관없는 곳은 그대로여야 해요.규칙이 있을 때와 없을 때, AI는 이렇게 달라져요
CLAUDE.md 의 네 원칙과 EXAMPLES.md 의 예시를 줄여서 저희가 그린 예시예요. 실제 질문과 코드는 쓰는 코딩 AI와 프로젝트에 따라 달라지고, 규칙이 있어도 늘 이렇게 움직인다는 보장은 없어요.
코딩 AI의 일하는 순서를 바꾸는 다른 도구
카파시 지침은 규칙 파일 한 장으로 태도만 바꾸고, 슈퍼파워와 스펙 킷은 작업 순서 자체를 단계별 도구로 정해 줘요(각 README 기준).
주의할 점
- 저장소에 라이선스 파일이 없어요. README 끝과 플러그인 설정 파일에는 MIT라고 적혀 있지만, 깃허브 저장소 정보의 라이선스 칸은 비어 있어요(2026-11-06 기준). 회사 일에 고쳐 쓰거나 다시 배포하려면 만든 사람에게 조건을 확인하는 게 안전해요.
- 카파시가 만든 파일이 아니라, 그의 글을 바탕으로 다른 개발자가 정리한 거예요. 카파시는 원문에서 CLAUDE.md 에 간단한 지시를 몇 가지 넣어 봤는데도 이런 실수가 일어난다고 적었어요. 지침 한 장이 실수를 없애 준다는 보장은 없어요.
- 속도보다 신중함 쪽으로 기운 지침이에요. 오타 고치기나 뻔한 한 줄 수정까지 모든 절차를 밟을 필요는 없으니 상황에 맞게 판단하라고 README가 적어요.
- 마지막으로 바뀐 날은 2026-04-20이고, 열린 이슈(오류·개선 요청)와 풀 리퀘스트(고쳐 달라는 제안)가 138개 쌓여 있어요. 예시 모음(EXAMPLES.md) 중 한 예시에서 틀린 코드와 고친 코드가 똑같다는 지적(#204)도 열려 있어요(2026-11-06 확인).
더 보기
깃허브 아이디 forrestchang 인 개발자가 만들었고, 지금은 그가 새로 시작한 프로젝트 Multica 의 조직 계정(multica-ai)에 있어요. 카파시 본인이 만들거나 참여했다는 내용은 README에 없어요.
카파시의 원문 글(X) ↗CLAUDE.md 원문 ↗틀린 예와 바른 예 모음(EXAMPLES.md) ↗커서에서 쓰는 법(CURSOR.md) ↗깃허브 저장소 ↗
낯선 말
- CLAUDE.md · 클로드 코드가 대화를 시작할 때 먼저 읽는 프로젝트 규칙 파일
- 플러그인 장터 · 클로드 코드에 기능 묶음을 찾아 설치하는 목록. 장터를 먼저 추가해야 그 안의 플러그인을 설치할 수 있어요
- 추상화 · 여러 경우에 두루 쓰려고 코드에 씌우는 틀. 한 번만 쓸 코드에 씌우면 읽기만 어려워져요
- 리팩터링 · 동작은 그대로 두고 코드 구조만 다시 짜는 일
- 죽은 코드 · 남아 있지만 어디서도 쓰지 않는 코드
- 디프(diff) · 파일에서 무엇이 바뀌었는지 줄 단위로 보여 주는 변경 내역
- 테스트 · 코드가 기대대로 움직이는지 자동으로 확인하는 작은 검사 코드
- 이슈 · 저장소에 올리는 오류 신고와 개선 요청 글
- 라이선스 · 남이 만든 코드를 쓰고 고치고 다시 나눠 줄 수 있는 조건을 정한 문서. MIT는 가장 자유로운 편이에요
- 플러그인 · 프로그램에 기능을 더하는 추가 묶음
댓글
AI 답은 참고 자료예요. 법·세금·돈·건강처럼 삶에 큰 영향을 주는 일에서는 AI 답이 정답이 될 수 없어요. 최종 판단은 전문가나 공식 기관에서 확인하세요.



