‘카파시 가이드라인’ 깊이 읽기 — LLM 코딩 실수를 줄이는 4원칙, 그리고 그대로 베끼면 안 되는 이유

요즘 개발자 사이에서 “카파시의 CLAUDE.md”라고 불리며 퍼진 짧은 문서가 있습니다. LLM이 코딩할 때 반복하는 실수를 줄이기 위한 행동 지침 네 가지를 담은 파일입니다. 짧고 날카로워서 그대로 자기 프로젝트의 CLAUDE.md에 붙여 넣는 사람이 많습니다.

이 글에서는 그 문서를 자연스러운 한국어로 옮기고, 각 원칙이 어떤 LLM 실패 모드를 정조준하는지, 무엇을 배울 수 있는지, 그리고 한 가지 중요한 함정 — 그대로 베끼면 안 되는 이유까지 분석합니다.

먼저, 출처부터 정확히

널리 “카파시가 쓴 메모리 파일”로 알려져 있지만, 정확히는 그렇지 않습니다. 이건 GitHub 레포 forrestchang/andrej-karpathy-skills(및 포크 multica-ai/andrej-karpathy-skills)에 있는 파일이고, 레포 자신이 밝히는 정체성은 이렇습니다.

“A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy’s observations on LLM coding pitfalls.” (카파시가 관찰한 LLM 코딩의 함정에서 도출한, Claude Code 행동 개선용 단일 CLAUDE.md 파일)

즉 카파시 본인의 저작이 아니라, 그가 공개적으로 언급해 온 LLM 코딩의 약점들을 커뮤니티가 한 장짜리 행동 지침으로 정리한 것입니다. Claude Code 플러그인(skill)으로 설치하거나, 그냥 프로젝트에 CLAUDE.md로 붙여 쓸 수 있습니다. 출처를 정확히 두고 시작해야, 이 문서가 “권위”가 아니라 “관찰의 정리”로 제대로 읽힙니다.

원문 + 번역 — 네 가지 원칙

문서는 본론에 앞서 솔직한 단서를 하나 답니다.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

(트레이드오프: 이 지침은 속도보다 신중함 쪽으로 치우쳐 있다. 사소한 작업에는 알아서 판단하라.)

“무조건 옳다”가 아니라 “신중함을 택한 대신 속도를 양보했다”고 미리 인정하는 점이 좋습니다. 그럼 네 원칙을 하나씩 봅니다.

1. Think Before Coding — 코딩 전에 생각하라

Don’t assume. Don’t hide confusion. Surface tradeoffs.

(가정하지 마라. 혼란을 숨기지 마라. 트레이드오프를 드러내라.)

구현에 들어가기 전에:

전제를 명시적으로 말하라. 불확실하면 물어라.
해석이 여러 갈래면 전부 제시하라 — 혼자 하나를 골라 조용히 진행하지 마라.
더 단순한 방법이 있으면 말하라. 근거가 있으면 반박하라.
불분명하면 멈춰라. 무엇이 헷갈리는지 이름 붙이고, 물어라.

겨냥하는 실패 모드: 숨은 가정으로 잘못된 방향을 질주하는 것. LLM은 모호한 요청을 만나면 빈칸을 조용히 메우고 달려 나가는 경향이 있는데, 그 추측이 틀리면 결과 전체가 어긋납니다.

2. Simplicity First — 단순함이 먼저다

Minimum code that solves the problem. Nothing speculative.

(문제를 푸는 최소한의 코드. 추측성 코드는 금지.)

요청받지 않은 기능은 만들지 마라.
한 번만 쓸 코드에 추상화를 두지 마라.
요청하지 않은 “유연성”이나 “설정 가능성”을 넣지 마라.
일어날 수 없는 상황에 대한 에러 처리를 하지 마라.
200줄을 썼는데 50줄로 될 일이면, 다시 써라.

판별 테스트도 제시합니다 — “시니어 엔지니어가 이걸 보고 과하게 복잡하다고 할까?” 그렇다면 단순화하라. 겨냥하는 실패 모드: 요청하지도 않은 기능·추상화로 코드를 부풀리는 과잉 설계(over-engineering).

3. Surgical Changes — 외과수술 같은 변경

Touch only what you must. Clean up only your own mess.

(꼭 건드려야 할 것만 건드려라. 네가 어지른 것만 치워라.)

기존 코드를 고칠 때:

옆에 있는 코드·주석·포매팅을 “개선”하지 마라.
망가지지 않은 것을 리팩터링하지 마라.
네가 다르게 짰을 스타일이라도, 기존 스타일을 따라라.
무관한 죽은 코드를 발견하면 말로 알리되, 지우지는 마라.

그리고 자기가 만든 흔적은 자기가 치웁니다 — 내 변경 때문에 쓰이지 않게 된 import·변수·함수는 제거하되, 원래 있던 죽은 코드는 시키지 않는 한 건드리지 않는다. 판별 테스트: 바뀐 모든 줄이 사용자의 요청으로 곧장 추적되는가? 겨냥하는 실패 모드: 무관한 코드까지 손대서 진단이 어려운 거대한 diff를 만드는 것.

4. Goal-Driven Execution — 목표 기반 실행

Define success criteria. Loop until verified.

(성공 기준을 정의하라. 검증될 때까지 반복하라.)

작업을 검증 가능한 목표로 바꿉니다.

“검증 로직 추가” → “잘못된 입력에 대한 테스트를 먼저 쓰고, 통과시켜라”
“버그 고치기” → “버그를 재현하는 테스트를 쓰고, 통과시켜라”
“X 리팩터링” → “리팩터링 전후로 테스트가 통과하는지 보장하라”

여러 단계 작업이면 짧은 계획을 먼저 말하게 합니다.

1. [단계] → 검증: [확인 방법]
2. [단계] → 검증: [확인 방법]
3. [단계] → 검증: [확인 방법]

문서의 통찰 한 줄: 강한 성공 기준이 있으면 모델은 알아서 반복하며 수렴하지만, 약한 기준(“되게 만들어”)은 계속 사람이 끼어들어 확인해야 한다. 겨냥하는 실패 모드: “되게 해줘” 같은 약한 목표가 부르는 끝없는 재확인 루프.

잘 작동하고 있다는 신호

문서는 마지막에 자기 검증 기준을 둡니다.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

(이 지침이 효과를 내고 있다면: diff에 불필요한 변경이 줄고, 과잉 복잡성 때문에 다시 짜는 일이 줄고, 확인 질문이 실수 뒤가 아니라 구현 전에 나온다.)

무엇을 배울 것인가

이 한 장짜리 문서가 잘 만들어진 이유는 분명합니다. 단순히 “좋은 말”의 나열이 아니라, 구체적인 LLM 실패 모드를 하나씩 정조준한 처방이기 때문입니다.

1) 각 원칙이 실제 실패 모드에 1:1로 대응한다

원칙	겨냥하는 LLM 실패 모드
Think Before Coding	숨은 가정으로 질주, 모호함을 임의 해석
Simplicity First	요청 안 한 기능·추상화로 코드 비대화
Surgical Changes	무관한 코드까지 손대 거대·불투명한 diff
Goal-Driven Execution	약한 성공 기준이 부르는 끝없는 재확인

좋은 지침은 추상적 미덕(“깔끔하게 짜라”)이 아니라, 모델이 실제로 빠지는 함정을 지목합니다. 자기 프로젝트의 지침을 쓸 때도 “내 에이전트가 반복하는 실수”를 먼저 적고 거기에 대응시키면 훨씬 잘 먹힙니다.

2) “하지 마라” + 판별 테스트로 쓰여 있다

이 문서의 문장 대부분은 금지형(No features…, Don’t refactor…)이고, 결정적으로 판별 테스트가 붙습니다. “시니어가 과하다고 할까?”, “바뀐 모든 줄이 요청으로 추적되는가?” 같은 한 줄짜리 자가 점검은, 모델이 스스로 멈춰 판단할 지점을 만들어 줍니다. 모호한 격려보다 검사 가능한 기준이 행동을 바꿉니다.

3) 가이드라인 자신에게도 성공 기준을 둔다

“이 지침이 효과를 내고 있다면…” 절은 메타적으로 영리합니다. 4번 원칙(성공 기준을 정의하라)을 문서 자신에게 적용한 셈입니다. 측정 가능한 신호(불필요한 diff 감소, 재작성 감소, 사전 질문 증가)가 있어야 “이 규칙이 실제로 쓸모 있나”를 판단할 수 있습니다.

4) 트레이드오프를 솔직히 인정한다

맨 앞의 “속도보다 신중함으로 치우쳐 있다”는 고백이 이 문서의 신뢰도를 높입니다. 만능이라고 주장하지 않기 때문에, 어디서 이득이고 어디서 과한지 사용자가 스스로 판단할 여지를 남깁니다.

그대로 베끼지 마라 — 템플릿이 아니라 메뉴다

여기서부터가 가장 중요한 분석입니다. 이 파일이 바이럴됐다고 해서 모든 프로젝트에 통째로 붙이는 것은 오히려 역효과일 수 있습니다.

별점은 수요를 증명하지, 효과를 증명하지 않는다. 많은 사람이 유용하다고 느낀 것과, 그 규칙이 내 레포에서 효과를 낸다는 것은 다른 문제입니다.
추상적 구호는 행동을 바꾸지 못한다. “be simple”보다, 파일 경로·명령·테스트 게이트가 박힌 구체적 운영 절차가 모델을 실제로 움직입니다. 같은 “surgical changes”라도 패키지 마이그레이션과 한 줄 버그픽스에서는 의미가 완전히 다릅니다.
맥락에 따라 가치가 갈린다. 제품 요구가 모호한 상황엔 “Think Before Coding”이 빛나지만, 코드베이스가 이미 명확한 패턴을 갖췄다면 같은 규칙이 불필요한 질문만 늘릴 수 있습니다.
더 나은 구조가 있다. 모든 걸 CLAUDE.md 한 곳에 욱여넣는 대신, 전역 가이드 + 작업별 skill + 자동 hook으로 나눠 두면 컨텍스트는 가볍게 유지하면서 필요한 지점에만 정확한 지시를 둘 수 있습니다.

핵심은 이것입니다. 지침 파일도 다른 인프라 코드처럼 제 값을 증명해야 하며, 평판에 기대 쌓이게 둬선 안 됩니다.

그래서 어떻게 쓸까

메뉴로 보라. 네 원칙 중 내 프로젝트가 실제로 겪는 실패 모드에 맞는 것만 고릅니다.

내 레포 언어로 구체화하라. 예를 들어 “Surgical Changes”를 이렇게 바꿉니다.

변경은 요청된 파일에만 한정한다.
포매터는 `npm run format`만 쓰고, 무관한 파일의 포맷을 바꾸지 마라.
기존 dead code는 지우지 말고 PR 설명에 목록으로만 남겨라.
diff가 요청 범위를 벗어나면 멈추고 이유를 보고하라.

검증 가능한 성공 기준을 붙여라. “되게 해줘” 대신 “이 테스트를 통과시켜라”로. 그래야 4번 원칙대로 모델이 알아서 수렴합니다.
분산하라. 항상 필요한 것만 전역 가이드에, 특정 작업에만 필요한 것은 skill에, 강제하고 싶은 규칙은 hook으로.

한 줄 정리

이 문서의 진짜 가치는 “카파시”라는 이름이 아니라, LLM이 코딩에서 반복하는 네 가지 실수를 정확히 지목하고 판별 테스트까지 붙였다는 점에 있습니다. 배울 것은 베껴 붙이는 행위가 아니라, 그 접근법 — 내 에이전트의 실패 모드를 적고, 금지형 규칙과 검사 가능한 기준으로 바꾸고, 효과를 측정하는 것 — 입니다. 좋은 지침은 권위가 아니라 검증으로 제 값을 합니다.