Andrej Karpathy의 바이브 코딩 전환기 — CLAUDE.md로 LLM 에이전트 행동 교정하는 법
솔직히 말하면, 저도 처음에 "바이브 코딩"이라는 단어를 들었을 때 그냥 유행어겠거니 했습니다. 느낌으로 코드를 짠다는 게 대체 무슨 의미인지, 실제 현업에서 쓸 수 있는 이야기인지 감이 안 왔거든요. 근데 Andrej Karpathy가 직접 "8주 만에 수동 코딩 80%에서 에이전트 주도 코딩 80%로 전환했다"고 선언했을 때, 그제서야 이게 단순한 트렌드가 아니라는 걸 깨달았습니다.
카파시의 사상은 단순히 "AI로 코드를 짜세요"가 아닙니다. 그는 소프트웨어 자체의 패러다임이 세 번 변했다고 주장하면서, 각 단계마다 개발자가 어떻게 생각하고 일해야 하는지를 체계적으로 정리했습니다. 그 위에 실제로 Claude Code나 Cursor 같은 도구를 쓸 때 LLM이 저지르는 실수 패턴을 관찰하고, 이를 방지하는 구체적인 가이드라인 파일(CLAUDE.md)까지 만들어 공유했죠.
이 글을 다 읽고 나면, 지금 당장 프로젝트 루트에 CLAUDE.md를 추가하고 싶어질 겁니다. Software 1.0/2.0/3.0 프레임워크, LLM 코딩 함정 4원칙, 실전에서 바로 쓸 수 있는 CLAUDE.md 세팅, 그리고 RAG 없이 개인 지식 베이스를 구축하는 LLM 위키 패턴까지 한 번에 살펴봅니다.
핵심 개념
Software 1.0 → 2.0 → 3.0: 패러다임이 세 번 바뀌었다
카파시가 그린 큰 그림부터 이해하면 나머지가 훨씬 자연스럽게 읽힙니다.
| 단계 | 정의 | 핵심 매체 | 프로그래머의 역할 |
|---|---|---|---|
| Software 1.0 | 사람이 명시적으로 로직을 코드로 작성 | .py, .ts 소스 파일 |
알고리즘 설계·직접 구현 |
| Software 2.0 | 데이터로 모델이 동작을 학습 | 학습된 모델 파일 (.pt, .ckpt) |
데이터 큐레이션, 학습 파이프라인 설계 |
| Software 3.0 | 자연어 프롬프트로 LLM에 지시 | CLAUDE.md, 시스템 프롬프트 |
프롬프트 엔지니어링, 에이전트 오케스트레이션 |
Software 2.0에서 카파시의 핵심 통찰은 조금 더 급진적입니다. "코드가 아니라 데이터가 프로그램이다"라는 것인데, 개발자가 if-else를 직접 짜는 대신 대량의 데이터를 모델에 먹여서 행동을 정의한다는 발상이죠. 이게 익숙해지면 Software 3.0도 자연스럽게 이어집니다 — 이번엔 데이터 대신 자연어가 프로그램을 정의합니다.
Software 3.0 — LLM을 "런타임"으로 사용하고, 자연어를 "소스 코드"처럼 다루는 새로운 프로그래밍 패러다임.
CLAUDE.md나 시스템 프롬프트 파일이 곧 프로그램입니다.
흥미로운 점은 이 세 패러다임이 서로를 대체하는 게 아니라 계층적으로 공존한다는 겁니다. LLM 자체는 Software 2.0의 산물이고, 그 LLM을 프롬프트로 제어하는 건 Software 3.0, 그리고 생성된 코드를 프로덕션에 올리면 Software 1.0으로 다시 정착합니다. 세 레이어가 동시에 살아있는 거죠.
LLM 코딩 함정 4원칙 — 카파시가 관찰한 AI의 나쁜 버릇
카파시가 LLM과 함께 작업하면서 반복적으로 목격한 실수 패턴 네 가지입니다. 실무에서 자주 맞닥뜨리는 상황인데, 이걸 알고 나면 프롬프트를 짤 때 완전히 다르게 접근하게 됩니다.
- 가정 금지(No Assumptions): 모호한 요구사항에 LLM이 알아서 판단해서 채워 넣는 행동. 숨겨진 의존성이나 아키텍처 결정을 사용자 동의 없이 내려버립니다.
- 혼란 숨기지 않기(Surface Confusion): 불확실한 게 있으면 계속 나아가는 대신 즉시 질문해야 합니다. 조용히 틀린 방향으로 달리는 게 가장 위험합니다.
- 트레이드오프 명시(Explicit Trade-offs): 구현 방식이 여럿일 때, 알아서 하나를 선택하지 않고 각 선택의 장단점을 사용자에게 보여줘야 합니다.
- 목표 기반 실행(Goal-oriented Execution): 요청받은 것만 구현합니다. "이왕이면 이것도 추가하면 좋겠다"는 식의 불필요한 확장은 코드 비대화(bloat)의 원흉입니다.
코드 비대화(Bloat) — 100줄로 해결할 수 있는 문제를 LLM이 과도한 추상화, 불필요한 헬퍼 함수, 미래를 위한 "방어 코드" 등으로 1,000줄로 부풀리는 현상. 유지보수 비용을 크게 높입니다.
개념은 파악했으니, 이제 직접 쓸 수 있는 세팅으로 넘어가겠습니다.
실전 적용
예시 1: CLAUDE.md 스킬 파일로 AI 행동 교정하기
forrestchang/andrej-karpathy-skills 리포지토리는 카파시의 4원칙을 Claude Code가 이해할 수 있는 형태로 정리한 단일 CLAUDE.md 파일입니다. 프로젝트 루트에 이 파일을 추가하는 것만으로 AI의 행동 방식이 눈에 띄게 달라집니다.
핵심 지침이 어떻게 작성되는지 패턴을 보면 이렇습니다:
# Project Guidelines
## Core Principles
### No Assumptions
If a requirement is ambiguous, STOP and ask for clarification.
Do NOT infer intent from context alone.
### Surface Confusion Immediately
If you are confused about ANY part of the task, say so before proceeding.
"I'm not sure about X — should I do A or B?" is always better than guessing.
### Explicit Trade-offs
When multiple implementation approaches exist, present them with pros/cons.
Do not silently choose one approach when alternatives exist.
### Goal-Oriented Execution
Implement ONLY what was explicitly requested.
Do not add features, refactoring, or abstractions beyond the task scope.저도 처음엔 "마크다운 파일 하나가 뭘 얼마나 바꾸겠어" 싶었습니다. 근데 직접 테스트해보니, AI가 불확실한 부분에서 멈추고 질문을 던지는 빈도가 확연히 늘었고, 요청하지 않은 리팩터링을 알아서 추가하던 버릇이 눈에 띄게 줄었습니다. 예를 들어 "payment 기능 추가해줘"처럼 모호한 요구사항을 던졌을 때, 전에는 AI가 알아서 결제 흐름을 설계하고 코드를 써내려갔다면, 이제는 "어떤 PG사를 사용할지, 환불 처리는 포함인지 먼저 확인할 수 있을까요?"라고 먼저 물어오더라고요.
| 동작 | CLAUDE.md 없을 때 | CLAUDE.md 있을 때 |
|---|---|---|
| 모호한 요구사항 처리 | "payment 기능 추가해줘" → 알아서 설계·구현 | "PG사, 환불 처리 여부 먼저 확인 가능한가요?" |
| 범위 이탈 기능 추가 | 자주 발생 | 명시적으로 억제 |
| 구현 방식 선택 | 무언의 단독 결정 | 옵션과 트레이드오프 제시 |
| 혼란스러운 코드 처리 | 일단 계속 진행 | 즉시 불확실성 표명 |
예시 2: LLM 위키 — RAG 없이 개인 지식 베이스 구축하기
카파시가 2026년 초에 공개한 LLM 위키 아키텍처는 발상이 꽤 단순한데 효과가 강력합니다. RAG(Retrieval Augmented Generation) 파이프라인과 벡터 데이터베이스를 전혀 쓰지 않고, 그냥 마크다운 파일과 긴 컨텍스트 윈도우(모델이 한 번에 처리할 수 있는 텍스트 길이)만으로 구조화된 지식 베이스를 만드는 방식입니다.
직접 써보면서 느낀 건, "관리 포인트가 없다"는 게 생각보다 훨씬 큰 장점이라는 거였습니다. 벡터 DB 세팅, 임베딩 파이프라인 관리, 검색 튜닝 — 이런 인프라 고민 없이 폴더 하나로 시작할 수 있거든요. 카파시 본인이 RAG 대비 70배 효율이라고 언급했는데, 이건 벡터 검색의 오류율과 인프라 복잡도를 제거했을 때의 운영 부담 차이를 가리키는 표현으로 보는 게 맞습니다 — 정밀한 벤치마크 수치라기보다는, 파이프라인 유지 비용 전반을 가리키는 표현입니다.
디렉토리 구조는 이렇게 잡을 수 있습니다:
my-llm-wiki/
├── raw_sources/ # LLM이 읽기만 하는 원본 자료
│ ├── papers/
│ ├── articles/
│ └── meeting_notes/
├── wiki/ # LLM이 생성·관리하는 마크다운
│ ├── entities/ # 사람, 조직, 제품 등
│ ├── concepts/ # 기술 개념, 용어 정의
│ └── index.md # 자동 생성 인덱스
└── schema.md # 에이전트 행동 규칙 정의schema.md에는 AI가 위키를 어떻게 만들고 갱신할지 규칙을 정의합니다:
# Wiki Schema
## Entity Format
Each entity file should contain:
- **Name**: Official name
- **Type**: person | org | product | concept
- **Summary**: 2-3 sentence description
- **Relations**: Links to related entities
- **Sources**: References to raw_sources/ files
## Update Rules
- Never delete existing content; append or update only
- Cross-link related concepts
- Flag conflicts between sources as `> ⚠️ Conflicting info:`> ⚠️ Conflicting info: 태그는 서로 다른 문서에서 상충하는 정보가 나올 때 AI가 자동으로 표시하는 방식입니다. 실제 출력은 이런 식으로 생성됩니다:
## Karpathy — Software 3.0 정의
LLM을 프로그래밍 런타임으로 사용하는 패러다임.
> ⚠️ Conflicting info: article_2025.md는 "자연어가 소스 코드"라 정의하지만,
> interview_2026.md는 "프롬프트 엔지니어링이 새로운 컴파일 단계"라 표현함.덮어쓰지 않고 충돌 지점을 플래그로 남기는 방식이라, 지식 베이스의 신뢰도가 유지됩니다. AI가 raw_sources/를 읽고 wiki/ 아래에 파일을 자동으로 생성하고 갱신하는 전체 흐름이 이 한 파일로 제어됩니다.
예시 3: 에이전트 도구 스택 계층화
카파시가 공개한 자신의 워크플로는 작업 크기에 따라 도구를 계층적으로 쓰는 방식입니다:
[소규모 — 자동완성]
Cursor Autocomplete
→ 한 줄, 짧은 함수 완성. 타이핑하면서 실시간으로 제안
[중규모 — 편집 지시]
Cursor Highlight & Edit
→ 특정 코드 블록을 선택(하이라이트)한 뒤 자연어로 수정 지시
[대규모 — 에이전트]
Claude Code / OpenAI Codex
→ 파일 여러 개에 걸친 기능 구현, 리팩터링
[복잡한 디버깅 / 리서치]
최고 성능 모델 (Claude Opus, Gemini Ultra 등)
→ 원인 불명의 버그 심층 추적, 아키텍처 분석이 계층화 접근법의 핵심은 모든 작업에 가장 강력한 에이전트를 쓰는 게 아니라, 작업의 범위와 복잡도에 맞는 도구를 선택하는 데 있습니다. 단순 자동완성에 에이전트를 돌리면 속도만 느려지고, 복잡한 리팩터링을 자동완성에 맡기면 컨텍스트가 부족합니다.
실무에서 가장 흔한 실수
개념과 도구를 익히다 보면 이 함정에 빠지기 쉬운데, 솔직히 저도 처음에 세 가지를 다 겪었습니다.
CLAUDE.md없이 에이전트에 모호한 지시를 내리는 것 — 컨텍스트 파일 없이 "이 기능 추가해줘"라고만 하면, AI는 알아서 추측해서 코드베이스를 예상치 못한 방향으로 바꿔놓을 수 있습니다.- 바이브 코딩 결과물을 직접 프로덕션에 올리는 것 — 프로토타입 속도는 탁월하지만, 에러 처리나 엣지 케이스는 빠져 있는 경우가 많습니다. Software 1.0 정제 과정을 거치는 것을 권장합니다.
- 모든 작업에 동일한 에이전트 레벨을 적용하는 것 — 한 줄 수정에 Claude Code를 돌리거나, 반대로 수백 줄짜리 리팩터링을 자동완성에 맡기는 건 둘 다 비효율적입니다. 도구 계층화를 의식적으로 적용해보시면 생각보다 빠르게 워크플로가 달라집니다.
장단점 분석
솔직히 이 부분이 가장 조심해야 할 지점이었는데, Software 3.0의 가능성에 흥분하다 보면 한계를 과소평가하기 쉽습니다.
장점
| 항목 | 내용 |
|---|---|
| 접근성 향상 | 자연어만으로 프로토타입 제작이 가능해 비개발자의 진입 장벽이 낮아집니다 |
| 반복 작업 절감 | 보일러플레이트, CRUD, 설정 코드 등 반복성 높은 작업에서 생산성이 크게 오릅니다 |
| 지식 관리 단순화 | 벡터 DB 없이 마크다운만으로 구조화된 개인 위키를 운영할 수 있습니다 |
| 도구 생태계 성숙 | Claude Code, Cursor 등 실전 도구가 2025~2026년 사이 급격히 안정화됐습니다 |
단점 및 주의사항
| 항목 | 내용 | 대응 방안 |
|---|---|---|
| 신규 설계 한계 | 독창적 시스템 아키텍처 설계는 여전히 LLM이 취약한 영역입니다 | 아키텍처는 사람이 먼저 설계하고, 구현을 AI에 위임하는 방식을 권장합니다 |
| 코드 비대화 | 지시가 모호하면 LLM이 불필요한 기능을 추가하는 경향이 있습니다 | CLAUDE.md로 행동 제약, 요청 범위를 명확히 표현하는 것이 효과적입니다 |
| 에이전트 자율성 과신 | "완전 자율 에이전트"는 아직 데모 수준입니다 | 카파시 본인도 "부분 자율 제품이 현실적"이라고 강조합니다 |
| 컨텍스트 비용 | LLM 위키의 긴 컨텍스트 방식은 문서량에 비례해 토큰 비용이 증가합니다 | 위키 규모에 따라 청크 전략을 별도로 가져가는 것을 권장합니다 |
| 기술 부채 위험 | 바이브 코딩으로 빠르게 만든 코드는 프로덕션 품질 검증이 필요합니다 | AI 생성 코드도 코드 리뷰와 테스트를 거치는 워크플로를 유지하는 게 중요합니다 |
마치며
카파시가 우리에게 보여준 건 AI를 쓰는 방법이 아니라, AI 시대에 개발자가 어떻게 사고를 재구성해야 하는가입니다. Software 3.0은 자연어가 코드가 되는 세계이고, 그 세계에서 가장 중요한 역량은 여전히 "무엇을 만들지" 아는 것, 그리고 AI가 저지르는 실수 패턴을 알고 제어하는 능력입니다.
지금 바로 시작해볼 수 있는 3단계:
-
CLAUDE.md파일을 현재 프로젝트 루트에 추가해보시면 좋습니다 —forrestchang/andrej-karpathy-skills리포지토리에서 파일을 복사한 뒤, Claude Code나 Cursor로 평소 작업을 진행해보시면 됩니다. 모호한 요구사항에서 AI가 먼저 질문하는 경험을 금방 체감하실 수 있을 겁니다. -
작업 크기에 따라 도구를 나눠서 써보시면 좋습니다 — 한 줄 수정은 자동완성으로, 특정 블록 수정은 Cursor Highlight & Edit으로, 파일 여러 개에 걸친 작업은 Claude Code로 분류해보시면 됩니다. 이 계층화를 의식적으로 적용하다 보면 자연스럽게 워크플로가 빨라집니다.
-
작은 규모의 LLM 위키를 개인 노트에 적용해보시면 좋습니다 —
raw_sources/,wiki/,schema.md폴더 구조를 만들고, 최근 읽은 기술 문서 두세 개를raw_sources/에 넣은 뒤 AI에게wiki/concepts/파일을 생성해달라고 요청해보시면 됩니다. RAG 없이도 구조화된 지식 정리가 얼마나 빠르게 이루어지는지 직접 확인하실 수 있습니다.
참고 자료
- andrej-karpathy-skills GitHub (forrestchang)
- Karpathy's CLAUDE.md Skills File: The Complete Guide | antigravity.codes
- Andrej Karpathy on Software 3.0 | Latent Space
- Software 2.0 | Karpathy on Medium
- Neural Networks: Zero To Hero (공식 강의)
- LLM Wiki GitHub Gist (Karpathy 원본)
- Karpathy LLM Wiki | VentureBeat
- Andrej Karpathy Vibe Coding | Klover.ai
- Eureka Labs 발표 | TechCrunch
- 안드레 카파시 "소프트웨어 3.0의 시대" | 바이라인네트워크
- 카파시의 AI 코딩 워크플로 분석 | FastCampus
