카파시의 CLAUDE.md 해설: Skills Search 뒤에 있는 하나의 파일

전 세계 Google 트렌드에서 지난 7일 동안, 2026년 10월 23일에 확인한 기준으로 "karpathy skills"는 "claude skills" 시드 아래에서 상승 검색어로 나타납니다. 그 검색을 따라가는 사람은 모두 같은 곳에 도착합니다: github.com/multica-ai/andrej-karpathy-skills, 2026년 10월 23일에 확인한 기준 GitHub에서 222,612개의 스타를 보인 저장소입니다. 이 저장소의 설명에는 "skill"이라는 단어가 전혀 포함되어 있지 않습니다. 설명은 다음과 같습니다: "Claude Code 동작을 개선하기 위한 단일 CLAUDE.md 파일로, LLM 코딩 함정에 관한 Andrej Karpathy의 관찰에서 도출되었습니다."

질의와 대상 사이의 간극은 사소한 기술적 문제가 아니다. 스킬과 CLAUDE.md 파일은 서로 다른 일을 하는 서로 다른 메커니즘이며, 이 저장소에 대해 사람들이 하는 거의 모든 주장은 둘 중 어느 것인지를 아는 데 의존하거나, 조용히 잘못된 쪽을 전제한다. 안에 있는 안내는 단일 파일이다. 그 파일을 둘러싼 저장소에는 플러그인 매니페스트와 skills 아래의 폴더도 있는데, 아마 검색창에 나오는 단어는 여기서 비롯된 것일 것이다. 패키징과 페이로드를 분리하는 것이 여기서 첫 번째로 유용한 수다.

숫자는 모두 GitHub에서 가져왔으며 2026년 10월 23일에 확인한 값입니다: 스타 222,612개, 포크 22,321개, 2026년 1월 27일 생성, 2026년 4월 20일 마지막 푸시, MIT 라이선스. 흥미로운 것은 마지막 두 항목입니다. 이 저장소는 약 6개월 동안 푸시를 받지 않았는데도 스타 수는 계속 증가했습니다.

파일이 작업을 수행하고, 패키징이 검색어를 설명합니다.

저장소를 열어 파일 목록을 보면 불일치가 쉽게 드러납니다. 루트에는 CLAUDE.md가 있고, 그 옆에 CURSOR.md, EXAMPLES.md, 동일한 가이드라인을 Cursor 프로젝트 규칙으로 담은 .cursor/rules 폴더, .claude-plugin 폴더, 그리고 skills/karpathy-guidelines 디렉터리가 있습니다. README에서 권장하는 설치 경로는 플러그인 마켓플레이스이며, 그 결과를 "모든 프로젝트에서 스킬을 사용할 수 있게" 만든다고 설명합니다.

그러니까 검색어가 틀렸다기보다는 부정확한 편입니다. skills 폴더가 있고, 플러그인이 있습니다. 없는 것은 각기 다른 작업을 수행하는 별도의 스킬들입니다. 사람들이 보통 '스킬 팩'이라고 할 때 의미하는 형태, 즉 SKILL.md와 해당 기능에 필요한 지원 파일들을 담고 한 가지 작업을 위해 호출되는 폴더 말입니다. 여기서는 전체 지침이 상시 지침을 담은 단일 문서이며, 플러그인은 그 문서를 프로젝트에 전달하기 위해 존재합니다.

그 구분이 당신에게 중요한지는 그 검색에서 무엇을 원했는지에 달려 있습니다. 도구 모음을 찾고 있었다면, 이건 그게 아닙니다. 코딩 에이전트가 프로젝트 전반에서 행동하는 방식을 바꿔 주는 짧은 규칙집을 원했다면, 바로 그게 이것이며, 누군가가 왜 그것을 스킬이 아니라 파일로 작성했는지 이해할 가치가 있습니다.

그것이 반박하기 위해 작성된 불만 사항들

README에 명시된 출처는 Andrej Karpathy가 X에 올린 게시물이며, README는 모델이 코드를 작성하는 방식에 관한 세 가지 불만을 인용하기 위해 이 게시물을 인용한다. 네 가지 원칙이 거의 일대일로 대응하므로 이 불만들은 전체를 읽어 볼 가치가 있다.

첫째: 모델은 "당신을 대신해 잘못된 가정을 세우고 확인도 없이 그 가정을 그대로 따라간다"며, "자신의 혼란을 관리하지 않고, 명확한 설명을 구하지 않으며, 불일치를 드러내지 않고, 트레이드오프를 제시하지 않으며, 마땅히 반박해야 할 때 반박하지 않는다." 무엇이 묘사되고 있는지 주목하라. 이것은 틀린 답변에 대한 불평이 아니다. 망설임 없이 전달되는 유창한 틀린 답변, 즉 질문을 불러일으켰어야 할 불확실성이 대신 자신감 있는 코드를 만들어낸 경우에 대한 불평이다.

두 번째: 그들은 "코드와 API를 정말 좋아서 과도하게 복잡하게 만들고, 추상화를 비대하게 늘리며, 죽은 코드를 정리하지 않는다… 100줄이면 될 일을 1000줄이 넘는 비대한 구현으로 만들어 버린다"는 것입니다. 이는 기능 하나를 요청했다가 프레임워크 하나를 받아 본 사람이라면 누구나 익숙한 이야기입니다.

세 번째는 더 미묘하며, diff를 검토하는 사람에게는 가장 비용이 큰 문제입니다. 그들은 "충분히 이해하지 못한 주석과 코드를, 설령 작업과 직교하더라도, 부수 효과로서 여전히 때때로 변경하거나 제거합니다." 한 주석에 대한 직교적 편집은 그 자체로는 작습니다. 하지만 코드베이스 전체에 걸쳐 곱해지면, 그것이 바로 검토 대기열이 아무도 요청하지 않은 변경으로 가득 차는 방식이며, 우회 방법이 왜 존재했는지 누구도 알기 전에 그 우회 방법을 설명하는 주석이 사라지는 방식입니다.

네 가지 원칙, 그리고 각 원칙이 남기는 시험

이 파일은 네 가지 원칙을 담고 있습니다. 각 원칙에는 짧은 규칙 세트가 따르며, 그중 두 원칙은 아무것도 설치하지 않고도 diff에 적용할 수 있는 한 줄짜리 테스트를 명시합니다. 이 파일의 성격은 규칙에서 드러납니다.

코딩하기 전에 생각하세요

제목의 지침은 “가정하지 말라. 혼란을 숨기지 말라. 트레이드오프를 드러내라.”입니다. 그 아래에는 가정을 명시적으로 밝히고 추측하기보다 질문하며, 요청이 모호할 때는 여러 해석을 제시하고, 더 단순한 접근이 존재하면 반대 의견을 제시하며, 혼란스러울 때는 멈추고 무엇이 불분명한지 밝힌 뒤 명확화를 요청하라고 되어 있습니다. 이는 첫 번째 불만을 정면으로 겨냥합니다. 그 메커니즘은 “더 조심하라”가 아니라, 조용한 선택을 눈에 보이는 선택으로 바꾸어 검토자가 코드가 존재한 뒤가 아니라 그 전에 반대할 수 있게 하는 것입니다.

단순함 우선

{{1}}규칙은 문제를 해결하는 최소한의 코드이며, 추측성 요소는 전혀 없습니다{{/1}}: {{2}}요청받은 것 이상의 기능도 없고{{/2}}, {{3}}일회성 코드를 위한 추상화도 없고{{/3}}, {{4}}아무도 요청하지 않은 유연성이나 구성 가능성도 없고{{/4}}, {{5}}불가능한 시나리오를 위한 오류 처리도 없습니다{{/5}}, 그리고 "{{6}}200줄을 50줄로 줄일 수 있다면 다시 작성하라{{/6}}". {{7}}판단 기준은 단 하나의 질문입니다 — 시니어 엔지니어라면 이것이 지나치게 복잡하다고 말할까요?{{/7}} — {{8}}그것은 판단의 문제이며, 공공연히 그렇습니다{{/8}}.

수술적 변경

여기서 파일은 지침을 두 부분으로 나누는데, 그것이 그 안에서 가장 유용한 부분입니다. 기존 코드를 편집할 때: 인접한 코드, 주석, 서식을 개선하지 마세요; 고장 나지 않은 것을 리팩터링하지 마세요; 당신이라면 다르게 하겠다 해도 기존 스타일을 따르세요; 관련 없는 죽은 코드는 삭제하지 말고 언급하세요. 자신의 변경이 고아를 만들 때: 변경으로 인해 사용되지 않게 된 import, 변수, 함수는 제거하되, 요청받지 않는 한 기존의 죽은 코드는 그대로 두세요. 기준은 변경된 모든 줄이 요청으로 직접 이어져야 한다는 것입니다.

목표 중심 실행

성공 기준을 정의하고 검증될 때까지 반복하라. README는 그 변환을 쌍으로 보여 준다. "검증 추가" 대신 잘못된 입력에 대한 테스트를 작성한 뒤 통과시키라. "버그 수정" 대신それを 재현하는 테스트를 작성한 뒤 통과시키라. "X 리팩터링" 대신 전후로 테스트가 통과하는지 확인하라. 여러 단계 작업의 경우 각 단계가 자체 검증을 명시하는 짧은 계획을 요구한다. README는 여기서 Karpathy를 다시 인용한다: "LLM은 특정 목표를 달성할 때까지 반복하는 일을 유난히 잘한다… 무엇을 하라고 말하지 말고, 성공 기준을 주고 지켜보라."

파일, 스킬, 플러그인은 서로 다른 세 가지입니다.

실무 동작이 다르기 때문에 그 구조를 정확히 이해할 가치가 있습니다. {{1}}CLAUDE.md는 프로젝트 지침 파일입니다. 즉 Claude Code가 저장소에 대한 상시 컨텍스트로 읽는 텍스트이며, 이번 턴에 누군가 요청했는지 여부와 관계없이 존재합니다.{{/1}} 스킬은 SKILL.md가 포함된 폴더로, 해당 기능을 언제 사용해야 하는지를 설명하며, 작업에서 필요로 할 때 로드되고 그 전에는 로드되지 않습니다. 플러그인은 마켓플레이스를 통해 설치되는 배포 패키지로, 스킬, 명령 및 기타 구성 요소를 포함할 수 있습니다. 이 구분은 지침이 컨텍스트에 들어가는 시점과 누가 결정하는지에 관한 것이지 품질에 관한 것이 아닙니다.

그런 의미에서 CLAUDE.md는 세 가지 중 가장 무딘 방식입니다. 해당 프로젝트에서는 항상 켜져 있고, 그 프로젝트의 모든 작업에 적용되며, 작업이 한 줄짜리 오타 수정이든 마이그레이션이든 매 턴마다 컨텍스트를 차지합니다. 이 파일 자체의 README도 Tradeoff Note라는 섹션에서 그 비용을 인정합니다. 가이드라인은 속도보다 신중함 쪽으로 치우쳐 있으며, 사소한 작업 — 단순한 오타 수정, 명백한 한 줄짜리 수정 — 에 대해서는 판단력을 발휘해야 한다고 말합니다. 목표는 단순한 작업을 느리게 만드는 것이 아니라, 사소하지 않은 작업에서 비용이 큰 실수를 줄이는 것이라고 밝힙니다.

그것은 상시 지시 파일이 할 수 있는 일에 대한 타당한 설명입니다. 그것은 모델이 갖지 못한 능력을 추가할 수는 없습니다. 그것은 모델의 기존 행동이 나타날 가능성을 높이거나 낮출 수 있을 뿐입니다. 그래서 그 파일은 더 나아지도록 장려하는 방식이 아니라 제약 — 이것은 하지 말고, 저것은 먼저 물어보라 — 으로 작성됩니다.

222,612개의 별이 측정하는 것

그들은 관심을 측정한다. 그것은 폄하도 아니고 아무 의미 없는 일도 아니다. 2026년 1월에 생성되어 4월에 마지막으로 푸시된 저장소가 2026년 10월 23일까지 GitHub에서 222,612개의 별과 22,321개의 포크에 도달했으며, 그날 확인된 기준이므로 널리 공유되었고 자기만의 복사본을 원하는 사람들이 포크했다는 뜻이다. 별 수는 얼마나 많은 사람이 북마크할 가치가 있는 무언가를 발견했는지를 보여주는 합리적인 대리 지표다.

그것은 효과의 대리 지표가 아니며, 저장소도 그렇게 가장하지 않는다. 그 안 어디에도 공개되지 않은 것은 다음과 같다. 해당 파일이 있을 때와 없을 때의 결과를 비교하는 벤치마크, 그것이 작동하는지 측정하는 방법론, 통제군과의 비교가 없다. 실제 코드베이스에서의 전후 비교도, 리뷰어 연구도, 사고 발생률도 없다. 이런 파일은 모델 동작에 관한 가설을 우아하게 서술한 것일 뿐이며, 아무도 그 실험을 수행하지 않았다.

대신 README가 제공하는 것은 'How to Know It's Working'이라는 섹션인데, 여기에는 관찰할 수 있는 네 가지가 나열되어 있습니다: diff에서 불필요한 변경이 줄어드는 것, 과도한 복잡화로 인한 재작성이 줄어드는 것, 실수 후가 아니라 구현 전에 명확화 질문이 도착하는 것, 그리고 깔끔하고 최소한의 풀 리퀘스트. 이는 합리적인 신호입니다. 또한 아무것도 측정하지 않았다면 바로 쓰게 될 내용이기도 하며, 이 파일을 적용하는 사람이 스스로 보고하는 것입니다. 이것들을 이미 통과했다는 증거가 아니라, 자신의 저장소에서 이 파일이 충족해야 할 체크리스트로 읽으세요.

설치할 때 실제로 입력하는 것

README에는 두 가지 경로가 제시되어 있습니다. 권장 경로는 Claude Code 내에서 실행됩니다. 마켓플레이스를 추가한 다음 플러그인을 설치하면, 이후 가이드라인이 저장소별이 아니라 여러 프로젝트 전반에 적용됩니다. 두 번째는 프로젝트별 방식입니다. 원본 CLAUDE.md를 새 저장소로 가져오거나 기존 저장소에 덧붙이는 것입니다. 또한 커밋된 Cursor 프로젝트 규칙도 있어서, 해당 폴더를 Cursor에서 열면 동일한 가이드라인이 적용됩니다. 이는 이 파일이 프로젝트 수준 지침 파일을 읽는 여러 도구에서 이식 가능하도록 작성되었으며, 특정 공급업체의 로더에 종속되지 않는다는 점을 보여주는 세부 사항입니다.

README를 그대로 따르면 분명히 마주치게 될 테니 짚고 넘어갈 만한 거친 부분이 하나 있습니다. 마켓플레이스 명령은 forrestchang/andrej-karpathy-skills를 가리키는데, 페이지 상단의 저장소 URL은 multica-ai/andrej-karpathy-skills입니다. 두 문자열 모두 2026년 10월 23일에 읽은 같은 README에 나옵니다. 불일치를 확인할 수는 있지만 왜 존재하는지는 말씀드릴 수 없습니다. 따라서 솔직한 조언은 하나가 실패하면 다른 경로를 시도하고, 두 문자열 중 하나는 오래된 것으로 간주하라는 것입니다.

첫 페이지에서 눈여겨볼 또 하나는 저장소가 multica-ai에 의해 유지 관리된다는 점이며, README의 서두 인용문은 Multica를 “재사용 가능한 스킬로 코딩 에이전트를 실행하고 관리하기 위한 오픈소스 플랫폼”이라고 소개합니다. 이는 정당한 공개이며, 패키징이 지금과 같은 모습을 띠는 이유를 보여주는 단서이기도 합니다. 재사용 가능한 스킬에 관심이 있는 프로젝트는 자체 가이드를 설치 가능한 형태로 제공할 가능성이 높은데, 플러그인이 바로 그런 것입니다.

그것의 전제를 물려받지 않고 그것을 사용하기

커스터마이징 섹션은 대부분의 독자가 건너뛰는 부분입니다. 이 파일은 프로젝트별 지침을 대체하는 것이 아니라 그것과 병합되도록 설계되었으며, 제공하는 예시는 구체적입니다. TypeScript strict 모드를 사용하고, 모든 API 엔드포인트에는 테스트가 있어야 하며, 특정 파일의 기존 오류 처리 패턴을 따르십시오. 이는 장식이 아닙니다. 일반적인 규칙집과 여러분의 코드가 어디에 있는지 아는 지침 세트의 차이입니다.

실용적인 이유로 쌓아 두기보다 병합하는 편이 낫다. 파일을 그대로 붙여 넣었는데 프로젝트에 자체 관례가 있다면 두 지침 세트가 서로 어긋날 수 있으며, 모델이 그 불일치를 조정하는 일은 바로 첫 번째 원칙이 없애려는 혼란이다. 자신의 관례를 같은 파일에 같은 목소리로 작성하면 지침의 표면이 감사 가능할 만큼 작게 유지된다.

그리고 당연히 감사해야 합니다. 이 문서는 저장소의 모든 요청에 적용될 행동 지침을 담은 짧은 문서입니다. 올바른 질문은 222,612명이 틀릴 수 있는지가 아니라 — 그런 프레이밍은 아무것도 해결하지 못합니다 — 각 규칙이 당신이 실제로 목격한 실패와 일치하는지입니다. 당신의 diff에 즉흥적인 주석 재작성이 한 번도 포함된 적이 없다면, 'Surgical Changes' 섹션은 아무 이득 없이 컨텍스트를 소모합니다. 삭제하세요. 이 파일은 MIT 라이선스가 적용되어 있으며 편집되도록 만들어진 것입니다.

한 계층 아래로 내려가면, 이 중 어느 것도 어떤 모델이 응답하는지를 바꾸지 않습니다. CLAUDE.md 파일은 요청이 모델에 도달한 뒤 처리되는 방식을 좌우하지만, 그 요청을 받는 모델에 대해서는 아무것도 말하지 않습니다. 두 번째 결정은 모델 앞에 있는 무언가의 몫입니다. 이를 구성하는 한 가지 방법은 하나의 키로 200개 이상의 모델을 제공하는 단일 OpenAI 호환 엔드포인트를 두고, 제공자 간 자동 장애 조치와 제공자 목록 가격을 0% 마크업으로 그대로 전달하는 것입니다. 우리는 모델을 호스팅합니다; 우리는 Claude Code를 만들지 않으며, 당신의 저장소에 있는 어떤 것도 우리에게 보이지 않습니다.

검색은 계속 스킬이라고 말할 것입니다. 사람들이 에이전트의 동작을 바꾸기 위해 설치하는 것에 붙인 단어가 그것이고, 이 저장소를 둘러싼 패키징도 그 단어를 쓰기 때문입니다. 산출물은 파일 하나입니다. 세 가지 특정 불만에 대응해 작성된 상시 지침 문서 하나로, 네 가지 원칙과 직접 적용할 수 있는 일련의 테스트를 담고 있습니다. 그 불만들이 당신의 저장소처럼 들리는지로 판단하세요. 그것이 스타 수보다 더 나은 질문입니다. 스타 수는 당신이 방금 보인 것과 같은 반응을 가진 사람이 몇 명이었는지만 측정했을 뿐입니다.