Karpathy Skills 분석 (65줄 CLAUDE.md)

최근 AI Agent를 활용하다보면

잘 만들어내긴 하지만 생각보다 자기 마음대로 개발하는 경우가 있다.

 

예를 들면 간단한 수정만 요청했는데, 갑자기 구조를 바꾸거나

기존 코드를 지우고 추상화나 디자인 패턴을 적용하겠다면서 필자에게 자랑을 한다.

이런 증상을 겪던 중, Andrej Karpathy의 글을 보고 생각이 조금 바뀌었다.

 

문제는 단순히 AI가 부족해서가 아니라,

AI가 어떻게 행동해야 하는지에 대한 규칙이 부족했기 때문이었다.

 

그래서 이번에는 Karpathy의 X를 분석하고 해당 글의 철학을 담은

forrestchang의 Karpathy Skills를 실무에 도입해본 후기를 남겨보려고 한다.

 

미남 카파시 (출처 : 나무위키)

Andrej Karpathy는 AI·LLM 분야에서 가장 영향력 있는 엔지니어 중 한 명이다.

• 前 OpenAI 연구원
• 前 Tesla AI Director

특히 최근에는 X(Twitter)를 통해 AI Coding·Agent Workflow·LLM 개발 방식에 대한 생각을 자주 공유하고 있다.

Karpathy가 말한 AI Coding의 변화

X의 Andrej Karpathy님(@karpathy)

Karpathy는 최근 X에서 AI Coding에 대한 생각을 공유했다.

 

이제 개발자는 코드를 직접 치는 사람이 아니라,

AI에게 목표와 제약조건을 정의하는 사람에 가까워지고 있다는 것이다.

Andrej Karpathy (@karpathy)

“Don't tell it what to do,
 give it success criteria and watch it go.”

AI Coding Workflow 관련 X(Twitter) 글 중

즉, AI에게

• 이 함수 만들어줘
• 이 부분 수정해줘
• 이 코드 추가해줘

처럼 구현 위주의 명령보다

• 이 테스트를 통과해야 한다.
• 기존 구조를 깨면 안 된다.
• 변경 범위는 최소화해야 한다.
• 불확실하면 질문해야 한다.

처럼 성공 기준을 정의하는 방식이 더 중요해졌다는 의미다.

 

결국 AI Coding은 단순한 코드 자동완성이 아니라,

목표와 성공 기준을 기반으로 스스로 작업을 반복 수행하는 Agent 개발 방식에 가까워지고 있다.

Karpathy가 말한 AI Agent의 위험성

Karpathy가 지적한 문제 중 가장 공감됐던 부분은 AI Agent의 실패 방식이다.

Andrej Karpathy (@karpathy)

“The mistakes have changed.
 They are subtle conceptual errors that a slightly sloppy, hasty junior dev might do.”

AI Coding Workflow 관련 X(Twitter) 글 중

예전 AI의 실수는 비교적 단순했다.

문법 오류가 나거나, 존재하지 않는 라이브러리를 사용하는 식이었다.

 

하지만 최근 에이전트의 실수는 조금 다르다.

성급한 주니어 개발자가 저지를 수 있는 실수를 저지른다.

• 잘못된 가정을 기반으로 구현한다.
• 불확실한 요구사항을 질문하지 않는다.
• 필요 이상으로 추상화한다.
• 관련 없는 코드를 함께 수정한다.
• 기존 패턴을 무시하고 새 구조를 만든다.

이러한 실수가 발생하는 이유는 AI가 너무 자신 있게 진행하기 때문이다.

모르면 멈춰야 하는데, 멈추지 않고 그럴듯한 방향으로 계속 간다.

 

그래서 AI Agent를 사용할 때는 성능 좋은 모델보다,

행동을 제어하는 규칙이 더 중요해진다.

forrestchang의 Karpathy Skills

이런 Karpathy의 문제의식을 AI Agent에서 사용할 수 있도록 정리한 마켓플레이스가 있다.

바로 forrestchang의 andrej-karpathy-skills이다.

 

해당 Skill의 핵심 문장은 아래와 같다.

Behavioral guidelines to reduce common LLM coding mistakes.

직역하면, LLM이 코딩할 때 자주 저지르는 실수를 줄이기 위한 행동 가이드라인이다.

AI가 너무 자신 있게 (나처럼) 잘못된 방향으로 가지 않도록, 행동 방식을 제한하는 규칙에 가깝다.

 

개인적으로는 Karpathy가 말한 AI Coding의 문제를

forrestchang이 CLAUDE.md에 65줄로 다시 정리한 것처럼 느껴졌다. 

해당 내용은 크게 4가지로 나눠볼 수 있으며, 각각을 자세히 살펴보겠다.

 

1️⃣ Think Before Coding

첫 번째는 코딩하기 전에 생각하라는 규칙이다.

 

요구사항이 애매한데도, Claude가 스스로 해석해서 바로 구현을 시작하는 경우가 있다.

이를 막기 위한 장치라고 생각하면 된다.

• 가정을 명시하기
• 불확실하면 질문하기
• 여러 해석이 가능하면 선택지를 제시하기

해당 부분은 Karpathy가 말한 “AI는 혼란을 관리하지 못하고, 질문하지 않는다”는 문제를 담고있는 것 같다.

 

2️⃣ Simplicity First

두 번째는 단순함을 우선하라는 규칙이다.

 

간단한 기능 하나를 요청했는데, 불필요한 확장·추상 클래스를 함께 만들어버리는 경우가 있다.

해당 규칙은 과잉 구현을 명확히 금지한다.

• 요청받지 않은 기능 추가 금지
• 한 번만 쓰는 코드에 추상화 금지
• 요구하지 않은 유연성·설정화 금지
• 불가능한 시나리오에 대한 과한 예외 처리 금지
• 200줄로 작성했는데 50줄로 가능하다면 다시 단순화

개인적으로 가장 마음에 들었던 문장은 아래 기준이다.

Would a senior engineer say this is overcomplicated?

즉, AI에게 “시니어 개발자가 봤을 때 과한 설계인가?”를 스스로 점검하게 만드는 것이다.

 

3️⃣ Surgical Changes

세 번째는 수술하듯 필요한 부분만 수정하라는 규칙이다.

 

AI Agent에게 기존 코드를 맡겼을 때 가장 무서운 부분은 작업 범위가 너무 광범위해진다는 것이였다.

해당 규칙은 이를 명확하게 금지하고 있다.

• 꼭 필요한 파일과 라인만 수정하기
• 주변 코드, 주석, 포맷팅을 임의로 개선하지 않기
• 깨지지 않은 코드를 리팩토링하지 않기
• 기존 스타일이 마음에 들지 않아도 맞춰가기
• 관련 없는 dead code는 삭제하지 말고 언급만 하기

여기서 핵심 기준은 매우 명확하다.

Every changed line should trace directly to the user's request.

즉, 변경된 모든 라인은 사용자의 요청과 직접 연결되어야 한다는 의미다.

 

4️⃣ Goal-Driven Execution

네 번째는 목표 기반으로 실행하라는 규칙이다.

 

이 부분이 Karpathy의 생각과 가장 직접적으로 연결된다고 느꼈다.

Karpathy는 AI에게 세부 구현을 지시하기보다, 성공 기준을 주고 반복하게 하라고 말했다.

 

forrestchang의 Skill도 동일하게 작업을 검증 가능한 목표로 바꾸도록 유도한다.

• validation 추가 → "잘못된 입력에 대한 테스트를 작성하고 통과시키기"
• 버그 수정 → "버그를 재현하는 테스트를 작성하고 통과시키기"
• 리팩토링 → "수정 전후 테스트가 모두 통과하는지 확인하기"

멀티 스텝 작업에서는 아래처럼 각 단계마다 검증 기준을 두는 방식이다.

1. 요구사항 분석 → verify: 불확실한 부분 질문
2. 최소 변경 구현 → verify: 변경 범위 확인
3. 테스트 실행 → verify: 기존 테스트 통과

이 방식의 장점은 AI가 혼자 오래 작업하더라도, 검증 가능한 루프 안에서 움직인다는 점이다.

 

결국 Goal-Driven Execution은 AI에게 자유를 주는 것이 아니라,

목표와 검증 기준 안에서만 자유롭게 움직이게 하는 방식이다.

 

🦀 요약 🦀

시간이 부족한 분들을 위해 요약해보자면,

forrestchang의 Karpathy Skills는 Karpathy의 생각을 실제 AI Agent 환경에서 사용할 수 있도록 정리한 행동 규칙에 가깝다.

• Think Before Coding → AI가 멋대로 가정하지 못하게 한다.
• Simplicity First → AI가 과하게 추상화하지 못하게 한다.
• Surgical Changes → AI가 요청 범위 밖의 코드를 건드리지 못하게 한다.
• Goal-Driven Execution → AI가 성공 기준을 기준으로 반복하게 한다.

해당 Skill은 AI가 위험하게 행동하지 않도록 통제하는 최소한의 가드레일이라고 이해하면 쉽다.

그런 의미에서 이 Skill은 65줄로 시작하는 가벼운 Harness Engineering이라고 볼 수 있다.

(* 하네스 엔지니어링은 TODO...)

사용법

andrej-karpathy-skills/CLAUDE.md at main · multica-ai/andrej-karpathy-skills

사용법은 크게 두 가지이다.

CLAUDE.md에 65줄의 프롬프트를 넣거나, 필자처럼 skill로 등록해 쓰는 방식이다.

 

이번에는 skill로 등록 후, 사용해볼 예정이다.

단순 수정 작업에까지 이런 철학이 매번 따라붙을 필요는 없다고 판단했고, 필요한 순간에서만 사용하기 위함이다.

 

1️⃣ Plugin 설치 (Claude Code)

설치는 Claude Code에서 아래 명령어로 진행할 수 있다.

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

설치 후, claude code 종료 후 /plugins를 수행하면 아래와 같은 화면을 확인해볼 수 있다.

 

2️⃣ Skill 사용

원하는 요구사항을 입력했더니 , 바로 구현을 진행하지 않고 질의응답(Q&A) 시간을 가졌다.

Q&A를 통해 애매한 부분을 명확히 한 뒤, 그제서야 구현 단계로 넘어갔다.

 

문서를 정의하고 지시하는 것만 수행해봤지, 이렇게 질문을 받아보는 것은 처음이다.

이처럼 사람이 AI 작업 중간에 개입해서 검증·수정·승인하는 방식을

고급 용어(?)로 HITL(Human-In-The-Loop)이라고 부른다. 자주 사용되는 용어이니, 알아두면 도움이 될 것이다.

적용 후기

많이 써본 건 아니지만, 일주일 동안 사용해본 경험을 공유하고자 한다.

 

☀️ 장점

• 과한 추상화가 줄어든다.
• 불필요한 리팩토링이 줄어든다.
• 불명확한 요구사항에 대해 질문하는 빈도가 늘어난다.

특히 마음에 들었던 부분은 HITL, 즉 Human-in-the-Loop가 강화된다는 점이다.

AI가 모르는 것을 아는 척하고 진행하는 것이 아니라, 개발자에게 확인을 요청하는 방향으로 바뀐다.

 

물론 이 과정이 귀찮게 느껴질 수도 있지만 운영 코드에서는 오히려 안전장치라고 생각한다.

 

☁️ 단점

• 접근이 다소 보수적이다.
• 한 번에 시-원하게 개발되는 느낌은 아니다.
• 영향 범위가 큰 작업에서는 우회하려는 경향이 있다.

즉, 우리 모두가 꿈꾸는 엔터 한 번으로 모든 개발이 끝나는 느낌은 아니다.

오히려 AI가 중간중간 "이 방향이 맞는지 확인해달라"고 요청하는 경우가 생긴다.

 

하지만 개인적으로는 이 점이 단점이면서도 장점이라고 생각한다.

프로젝트가 아니라 운영을 하는 입장에서는 느리더라도 안정적으로 개발되는 것을 선호하기 때문이다.

오늘의 결론

이번 시간에는 Karpathy의 AI Coding 글과,

이를 Claude Code에서 활용할 수 있도록 만든 Karpathy Skills를 살펴보았다.

 

AI Native의 핵심은 이제 단순히 "AI가 코드를 얼마나 잘 짜는가"가 아닌 것 같다.

AI를 얼마나 통제 가능한 방식으로 일하게 만드는가가 더 중요해지고 있다.

 

그 관점에서 Karpathy Skills는 65줄로 시작해볼 수 있는 가장 가벼운 Harness Engineering이라고 생각한다.