60줄짜리 AI 코딩 하네스 4가지 원칙 - 카파시 CLAUDE.md(Github star 10만 개)

포스팅 개요

2026년 들어 클로드 코드(Claude Code) 생태계에서 가장 화제가 된 GitHub 저장소가 하나 있습니다. 이름은 andrej-karpathy-skills입니다. 카파시가 X(구 트위터)에 올린 짧은 글 한 편에서 영감을 받아 한 개발자가 그 다음 날 만든 저장소인데요(이름만 들으면 안드레이 카파시(Andrej Karpathy)가 직접 만든 공식 저장소처럼 보이지만, 사실은 그렇지 않습니다.) 그런데 이 저장소가 단 한 장의 마크다운 파일을 중심으로 GitHub에서 별 10만 개를 넘기는 폭발적인 반향을 일으켰습니다.

저는 이전 글들에서 그동안 클로드 코드의 스킬, 룰, 서브 에이전트이라는 개념을 차례로 다뤄왔습니다. 이번에 살펴볼 카파시 저장소는 그 모든 흐름이 가장 압축된 형태로 구현된 사례에 가깝다고 생각합니다. 거대한 프레임워크가 아니라 단 한 장의 텍스트 파일이 어떻게 AI(LLM)의 코딩 행동을 바꿔놓는지를 보여주는 좋은 예시라고 보여집니다.

---

포스팅 본문

들어가기 전! 이름과 다른 저장소?

먼저 사실관계부터 정확히 정리하고 시작하려고 합니다. 여러 커뮤니티에 본문은 정확하게 쓰면서도 제목만 보면 "Karpathy's CLAUDE.md", "Andrej Karpathy's Claude Code Skills"처럼 카파시 본인의 작품처럼 오해되는 경우가 다수 있습니다.

저장소의 풀네임은 forrestchang/andrej-karpathy-skills( https://github.com/forrestchang/andrej-karpathy-skills/tree/main )입니다. 소유자는 카파시 본인이 아니라 Jiayuan Zhang(영문명 Forrest Chang, GitHub 핸들 forrestchang)이라는 개발자입니다.  github.com/karpathy( https://github.com/karpathy ) 프로필을 직접 들어가 보면 nanoGPT, llm.c, micrograd, autoresearch 같은 저장소만 있고, "skills"라는 이름의 저장소는 존재하지 않습니다.

 

 

출발점은 카파시가 2026년 1월 26일 X에 올린 글이었습니다.

11월에는 80% 수동 코딩과 20% 에이전트였던 자신의 워크플로우가 1월에는 완전히 역전되어 80% 에이전트와 20% 손보기로 바뀌었다는 회고에서 시작합니다. 그러면서 그가 그동안 클로드와 작업하며 반복적으로 마주친 LLM 코딩의 구조적 약점을 정리해서 적었습니다.

그 글을 본 forrestchang은 다음 날인 1월 27일에 저장소를 만들고, 카파시의 진단을 토대로 한 장의 CLAUDE.md를 공개했습니다. 그것이 폭발적으로 퍼진 것으로 저는 이해하고 있습니다. (혹시 틀리다면 말씀해주세요!)

 

저장소 안을 들여다보면 정말 단순합니다. 핵심은 CLAUDE.md 한 파일입니다. 그 외 파일들도 있지만, 영어와 중국어 README, 4가지 원칙의 실제 코드 사례를 담은 EXAMPLES.md, Cursor 통합용 .cursor/rules 디렉터리, 그리고 클로드 코드 마켓플레이스 등록을 위한 .claude-plugin 디렉터리뿐입니다. 주요 내용은 60여 줄짜리 마크다운 한 장이죠.

 

통계로 살펴보면 2026년 1월 27일 첫 커밋 이후 약 3개월 만에 별 10만 개를 돌파했으며, GitHub 글로벌 트렌딩 상위권에 오랫동안 머물렀습니다.

[1] 카파시가 진단한 LLM 코딩의 4가지 고질병

forrestchang이 만든 4가지 원칙을 이해하려면, 카파시가 무엇을 보고 있었는지를 먼저 살펴봐야 합니다. README는 카파시 X 글의 핵심 문장을 그대로 인용하는 방식으로 시작합니다. 한 문장 한 문장이 LLM과 같이 일해본 사람이라면 누구나 한 번씩은 부딪힌 장면이라고 봅니다. 개인적으로도 정말 많이 겪었던 문제이기도 합니다.

 

1. 잘못된 가정

"The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

 

첫 번째 진단은 잘못된 가정입니다. 모델은 사용자를 대신해 자기 멋대로 해석한 뒤 그대로 수행합니다. 자기 안의 혼란을 체크하지도 않고,  더 나은 방법이 있어도 반박하지 않고 시킨대로 진행합니다. 사실 그래서 잘못된 코드가 나오는 것이 아니라 잘못된 문제를 해결한 코드가 나옵니다. 가장 성가시고 무서운 종류의 실패에 가깝습니다.

 

2. 추상화 부풀리기

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

 

두 번째는 코드와 추상화의 비대화(부풀리기)입니다. 100줄이면 끝날 일을 1000줄로 부풀립니다. 추상 클래스, 전략 패턴, 설정 객체, 의존성 주입 같은 도구들을 일단 모조리 동원합니다. 모델 입장에서는 "잘 짜인 코드"의 패턴을 따라간 것이지만, 결과적으로는 사람도 LLM 자신도 다음에 다시 읽기 어려운 거대한 구조물이 남습니다.

 

3. 이해하지 못한 코드의 변경/삭제

"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."

 

세 번째는 이해하지 못한 코드의 변경과 삭제입니다. 요청한 작업과 직접 관련 없는 코드와 주석까지 손을 댑니다. 따옴표 스타일을 바꾸고, 타입 힌트를 끼워 넣고, 인접한 함수의 변수명을 "(본인이 생각했을 때)더 좋게" 다듬습니다. PR diff가 100줄 변경이라고 떠 있지만, 그 중 사용자가 요청한 변경은 5줄에 불과합니다. 나머지 95줄은 모두 검토자의 시간을 빼앗는 노이즈가 됩니다.

 

4. 검증 가능한 성공 지표의 부재

"LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."

 

네 번째는 검증 가능한 성공 기준의 부재입니다. 모델은 "수정해줘", "더 빠르게 만들어줘", "리팩토링해줘" 같은 모호한 지시 위에서 자기 판단으로 무언가를 진행합니다. 끝났다고 선언했을 때 그게 정말 끝난 것인지 확인할 객관적 기준이 없습니다. 카파시는 이 부분을 가장 강하게 강조합니다.

 

즉, 명령형으로 시키지 말고 성공 기준을 주고 지켜보라는 것입니다. 한 줄로 요약된 이 문장이 4번째 원칙의 핵심 철학이 되며, 사실상 저장소 전체의 방향타라고 봐도 무방합니다.

---

[2] CLAUDE.md에 작성된 4가지 원칙과 실제 코드

 

이 repo에 있는 CLAUDE.md는 위 4가지 진단에 정확히 1대 1로 대응하는 4개 원칙으로 구성되어 있습니다. README의 매핑 표를 보면 어떤 진단이 어떤 원칙으로 받아내지는지 한눈에 들어옵니다.

원칙	대응하는 진단
Think Before Coding	잘못된 가정, 숨겨진 혼란, 누락된 트레이드오프
Simplicity First	과도한 복잡화, 부풀려진 추상화
Surgical Changes	직교한 부수 변경, 손대선 안 될 코드 건드리기
Goal-Driven Execution	검증 가능한 성공 기준 부재

 

각 원칙을 짧게 짚어 보고, EXAMPLES.md의 실제 코드를 한 개씩 살펴보겠습니다.

원칙 1. Think Before Coding

"가정하지 말고, 혼란을 숨기지 말고, 트레이드오프를 드러내라." 코드를 시작하기 전에 자기가 어떤 전제로 움직이고 있는지 명시하고, 해석이 둘 이상이면 둘 다 제시하고, 더 단순한 방법이 있다고 판단되면 그 의견을 내라는 것입니다.

EXAMPLES.md에 등장하는 사례 하나를 살펴보겠습니다. 사용자가 "검색을 더 빠르게 만들어줘"라고 했을 때, 잘못된 행동은 일단 LRU 캐시와 비동기 처리, DB 인덱스를 한 번에 200줄짜리 변경으로 밀어 넣는 것입니다. 옳은 행동은 다음과 같이 멈춰서 되묻는 것입니다.

"검색을 더 빠르게"가 의미할 수 있는 것:

1. 응답 시간 단축 (500ms → 100ms)
   - DB 인덱스, 자주 쓰는 쿼리 캐시
2. 동시 처리량 증가 (throughput)
   - async/await, 커넥션 풀링
3. 체감 속도 개선 (UX)
   - 부분 결과 즉시 표시, 점진 로딩

지금 검색은 평균 ~500ms입니다.
어떤 측면이 가장 중요한가요?

 

이게 단지 우리가 흔히 생각하는 "친절한 답변"이 아닙니다.

모델이 잘못된 문제를 해결하기 전에 멈추는 행위 그 자체가 이후에 나오는 여러 실패의 step을 막는 것이며, 개발자의 의도를 명확히 할 수 있는 것입니다.

원칙 2. Simplicity First

두 번째 원칙은 단순함입니다. 요청 외 기능 금지, 단일 사용 코드에 추상화 금지, 요청되지 않은 유연성 금지, 일어날 수 없는 시나리오에 에러 처리 금지. 그리고 "200줄로 쓴 것을 50줄로 줄일 수 있다면 다시 써라."

EXAMPLES.md의 할인 계산 함수 사례가 있는데요.

사용자는 "할인을 계산하는 함수를 추가해줘"라고만 했는데, LLM은 이렇게 답하기도 합니다.

class DiscountStrategy(ABC):
    @abstractmethod
    def calculate(self, amount: float) -> float: ...

class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage): self.percentage = percentage
    def calculate(self, amount): return amount * (self.percentage / 100)

class FixedDiscount(DiscountStrategy): ...
class DiscountCalculator: ...
# 사용 시 30줄 이상의 셋업 필요

 

디자인 패턴 책에서 본 것과 같은 잘 정돈된 코드입니다.

그러나 사용자가 부탁한 것은 단지 한 가지 종류의 할인 계산이었습니다. 단순히 아래 두 줄로 끝날 수 있는 것이죠.

def calculate_discount(amount: float, percent: float) -> float:
    """percent should be 0-100."""
    return amount * (percent / 100)

 

이 비교가 보여주는 것은 "디자인 패턴이 나쁘다"가 아닙니다. 카파시의 표현을 빌리면 패턴이 등장하는 타이밍의 문제입니다.

복잡성은 필요해진 다음에 도입해야지, 미리 깔아두는 순간 모든 비용이 지속적으로 증가하기 때문입니다.

CLAUDE.md는 이 판단 기준을 "시니어 엔지니어가 보면 과도하다고 할 코드인가? 그렇다면 단순화해라." 라고 명시해뒀습니다.

원칙 3. Surgical Changes

세 번째 원칙은 외과의처럼 필요한 부분만 수정하라는 것입니다. 인접 코드와 주석을 "개선"하지 말고, 깨지지 않은 것을 리팩토링하지 말고, 기존 스타일을 그대로 따르라는 지침입니다. 핵심 검증 기준은 한 줄로 정리됩니다. "변경된 모든 줄이 사용자 요청과 직접 1대 1로 추적되어야 한다."

EXAMPLES.md의 업로드 함수 사례가 좋은 그림을 보여줍니다. 사용자는 "upload 함수에 로깅을 추가해줘"라고만 했습니다.

흔히 AI가 수행하는 잘못된 행동은 아래와 같이 수행합니다.

- def upload_file(file_path, destination):
+ def upload_file(file_path: str, destination: str) -> bool:
+     """Upload file to destination with logging."""
+     logger.info(f"Uploading {file_path} to {destination}")
      try:
-         with open(file_path, 'rb') as f:
+         with open(file_path, "rb") as f:
              data = f.read()
-         response = requests.post(destination, files={'file': data})
+         response = requests.post(destination, files={"file": data})
+         success = response.status_code == 200

 

로깅 한 가지를 부탁했는데 따옴표 스타일이 작은따옴표에서 큰따옴표로 바뀌고, 타입 힌트가 추가되고, 독스트링이 생기고, 불리언 반환 로직까지 바뀌었습니다. 진짜 많이 발생하는 현상인데요. 원칙3은 이런 현상을 보이지 않게 옳은 변경은 따옴표를 그대로 두고, 타입 힌트도 그대로 두고, 로깅 호출 라인만 정확히 추가하라고 지시하는 것입니다.

원칙 4. Goal-Driven Execution

마지막 원칙이 카파시 글의 핵심이라고 볼 수 있고, 저 개인적으로도 정말 많이 쓰는 방법인데요(은근히 반가웠음).

"성공 기준을 정의하고, 검증될 때까지 루프를 돌려라."

~ 대신에	이렇게 변환!
"검증 추가"	"잘못된 입력에 대한 테스트를 작성한 뒤 통과시켜라"
"버그 수정"	"버그를 재현하는 테스트를 먼저 쓰고, 통과시켜라"
"X 리팩토링"	"리팩토링 전후 테스트가 모두 통과하는지 보장하라"

 

동사를 명령형에서 검증 가능한 목표로 바꾸는 것이 핵심입니다.

repo에 있는 EXAMPLES.md의 "API에 rate limiting을 추가해줘" 사례에서는 한 번에 300줄 변경을 던지는 대신 다음과 같이 단계별 검증을 끼워 넣습니다.

1. 단일 엔드포인트에 인메모리 rate limiting 추가
   검증: 100회 요청 → 처음 10건 성공, 나머지 429 응답
         curl로 11번 호출하여 rate limit 에러 확인
2. 미들웨어로 추출 (전체 엔드포인트 적용)
   검증: /users, /posts에 모두 rate limit 적용됨
         기존 엔드포인트 테스트가 여전히 통과
3. Redis 백엔드 추가 (멀티 서버용)
   검증: 앱 재시작 후에도 rate limit 유지
4. 엔드포인트별 설정값 추가
   검증: /search 10/min, /users 100/min 분리 적용

 

각 단계에 명시적 검증이 붙어 있는 것이 보이시나요?

이렇게 적어두면 모델은 한 단계가 끝났는지 스스로 판단할 수 있고, 검증이 실패하면 다음 단계로 넘어가지 않습니다.

카파시가 말한 "성공 기준을 주고 지켜보라"가 실제로 동작하는 형태라고 볼 수 있습니다.

[3] 설치 방법

설치는 두 가지 혹은 세가지 방법이 있는데요. 정말 간단합니다. 

첫 번째는 클로드 코드 플러그인 방식입니다.

클로드 코드 안에서 마켓플레이스를 추가한 뒤 플러그인을 설치하면, 이 가이드라인이 모든 프로젝트에서 스킬로 활성화됩니다.

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

 

두 번째는 더 단순합니다.

CLAUDE.md를 그냥 다운로드하는 방식입니다. 새 프로젝트라면 그대로 받고, 기존 CLAUDE.md가 있다면 뒤에 이어 붙이면 됩니다.

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

 

세 번째는 그냥 github에 있는 내용을 복사해서 본인 CLAUDE.md에 붙여 넣는 것입니다. 

어쩌면 가장 간단한 것 같네요 ㅎㅎ

[4] 그냥 하네스 엔지니어링 아닌가?

요즘 하네스 엔지니어링(harness engineering)이라는 말이 많이 들립니다. 이는 곧, 모델 자체가 아니라 모델이 일하는 환경, 즉 시스템 프롬프트, 도구 정의, 컨텍스트 윈도우, 대화 흐름의 설계까지 포함한 환경 전체를 가리키는 것입니다.

카파시 저장소는 그 추상적 개념의 가장 작은 실제 구현이라고 볼 수 있습니다. 그걸 매우 짧게 잘 만든 것이죠. 

CLAUDE.md 파일은 60여 줄짜리 마크다운에 불과합니다. 그런데 이 파일을 프로젝트 루트에 두면, 클로드 코드는 이를 모든 작업의 시스템 프롬프트 일부로 자동 주입합니다. 즉, 개발자가 "버그 수정해줘"라고 입력하는 그 순간 모델은 4가지 원칙이 켜져 있는 상태로 답변을 생성합니다. 개발자가 한 일은 마크다운을 한 장 작성한 것뿐이지만, claude code는 이를 토대로 동작되는 것이죠.

 

바로 이 지점이 하네스 엔지니어링의 본질이라고 생각합니다. 모델 자체가 아니라 모델 주변(컨텍스트 혹은 그 이상)을 바꾸는 것입니다.

그리고 모델 주변을 바꾸는 방법으로 이 60여 줄짜리 마크다운으로도 동작이 될 수 있다는 것을 보여준 것이죠. 

 

좋은 하네스는 양이 아니라 명확함이라는 사실이 보이는 지점인 것 같습니다.

[5] 직접 적용해본 감각

저도 이 가이드라인을 실제 작업에서 며칠간 써봤습니다. 기존에 이미 쓰고 있는 방식이 70%여서 큰 어려움은 없었습니다. 개인적으로는 함께 쓸려나가던 따옴표 변환, 타입 힌트 자동 추가, 리포맷 같은 행동이 사라지는 것이 참 마음에 들더군요. 개인적으로는 처음에는 "원래 이런 작은 정리도 같이 해주는 게 편하지 않나"라는 생각이 있었는데, 몇 번 써보니 이 방법이 조금 더 명확한 것 같습니다.

 

두 번째 차이는 모델이 먼저 질문하는 빈도가 늘었다는 것입니다(사실 이 지점은 개인적으로 단점이 되는 지점도 있네요 ㅎㅎ). "사용자 데이터 내보내기 기능을 만들어줘"라고 시켰을 때, 가이드라인이 없는 상태라면 즉시 JSON 직렬화 코드부터 짜기 시작합니다. 가이드라인이 깔린 상태에서는 "전체 사용자입니까, 필터된 부분집합입니까", "파일로 다운로드입니까, API 응답입니까", "어떤 필드를 포함합니까" 같은 질문을 먼저 던져옵니다. 계속 모니터링을 하면서 봐야하는 지점이 있지만, 멀리 봤을 때 잘못된 코드를 한 번에 다 지우고 다시 짜는 것보다 훨씬 빠른 길이라고 생각합니다.

 

단, 이 방법은 속도보다는 신중함을 강조하는 방법입니다. README의 "Tradeoff Note"에도 나와있구요. 그래서 상황에 따라 유연하게 변경해서 쓰시면 될 것 같습니다.

---

마무리하며

이번 글에서는 안드레 카파시가 언급한 LLM 코딩의 구조적 약점을 개선한 60여 줄짜리 CLAUDE.md 파일에 대해서 간단하게 리뷰해봤습니다. 

비록 부족한 글이지만, 의미 있는 인사이트가 되었으면 합니다. 의견이나 다른 시각, 틀린 부분이 있다면 댓글로 자유롭게 남겨주시면 감사하겠습니다.