안드레이 카파시의 Claude Code 활용법 분석: 마크다운으로 만드는 AI 세컨드 브레인
안드레이 카파시(Andrej Karpathy)는 OpenAI 창립 멤버이자 테슬라 AI 디렉터를 지낸 인물이다. 2025년부터 그가 공개적으로 사용 패턴을 보여주고 있는 "마크다운 + Claude Code" 워크플로는 단순한 코딩 도구 사용법이 아니라, 지식과 실행을 같은 평면에 두는 세컨드 브레인 설계에 가깝다. 그의 공개 자료를 분석하고 본인 6주 적용 결과를 정리했다.
1. 카파시가 공개한 핵심 패턴
카파시가 X(@karpathy) 계정과 자신의 GitHub 노트에서 반복적으로 강조하는 것은 세 가지다.
- AGENTS.md를 첫 파일로 — 에이전트가 처음 보는 문서가 모든 결과를 결정
- 자연어 = 코드 — 마크다운으로 의도를 적고, 코드는 그 결과물로 둠
- 세션 → 메모로 응결 — 끝난 작업은 짧은 마크다운 메모로 압축해 다음 세션이 읽도록
2. 카파시 패턴이 일반 가이드와 다른 점
흔한 "AI 코딩 잘 쓰기" 글과 카파시 패턴을 비교하면 차이가 명확해진다.
| 비교 항목 | 일반 가이드 | 카파시 패턴 |
|---|---|---|
| 출발점 | 프롬프트 엔지니어링 | AGENTS.md(시스템 컨텍스트) |
| 지식 저장소 | 대화 히스토리 | 마크다운 메모 디렉터리 |
| 세션 종료 시 | 요약 없음 | 5-10줄 메모로 응결 |
| 주요 스킬 | "좋은 프롬프트 쓰기" | "좋은 문서 쓰기" |
카파시가 강조하는 것은 결국 프롬프트 엔지니어링이 문서 엔지니어링으로 이동했다는 점이다. AI에게 잘 시키는 기술이 아니라, AI가 잘 읽도록 쓰는 기술이다.
3. 카파시 패턴을 4가지 원칙으로 정리
원칙 1모든 프로젝트에 AGENTS.md를 둔다
카파시는 자신의 모든 사이드 프로젝트에 AGENTS.md(또는 CLAUDE.md)를 첫 파일로 둔다. 그 안에는 (1) 변경 원칙, (2) 흔한 함정, (3) 검증 방법이 들어간다. 코드가 0줄이어도 이 문서가 먼저 있다.
원칙 2마크다운이 1차 자료다
대화·코드 주석이 아니라 독립된 마크다운 파일이 1차 자료다. 같은 정보가 대화에만 있으면 다음 세션에서 사라진다. 마크다운으로 적으면 검색 가능하고, 다른 에이전트도 읽을 수 있다.
원칙 3세션 끝에 메모로 응결
한 작업이 끝나면 5-10줄짜리 마크다운으로 응결한다. "오늘 무엇을, 왜, 어떻게 결정했고, 다음 세션이 알아야 할 것은 무엇인가." 이게 카파시가 말하는 "compression for the next agent"다.
원칙 4대화는 휘발, 문서는 영구
중요한 결정은 대화 속에 두지 않는다. 즉시 마크다운으로 옮긴다. 카파시가 "코드 리뷰는 대화로, 의사결정은 문서로"라고 표현하는 게 이 원칙이다.
4. 본인 6주 적용 결과
본인 사이드 프로젝트 2개에 카파시 패턴을 적용한 6주(2026-03-18 ~ 2026-04-29) 측정 데이터.
| 지표 | 적용 전(이전 6주) | 적용 후(6주) |
|---|---|---|
| 같은 실수 반복 횟수 | 11회 | 2회 |
| 세션 시작 컨텍스트 재설명 시간 | 평균 8분 | 평균 1분 |
| 완료 PR 수 | 14건 | 22건 |
| 마크다운 메모 누적 | 3개 | 41개 |
가장 큰 변화는 "같은 실수 반복" 지표다. AGENTS.md에 사고 사례를 박제하기 시작하니 동일 실수가 사실상 0에 수렴했다. 컨텍스트 재설명 시간이 8분 → 1분으로 줄어든 것도 누적 효과가 크다.
5. 어떤 메모를 적어야 하는가
카파시 본인이 자주 사용하는 메모 유형은 다음 4가지다.
- incident.md — 사고 사례. "왜 망했는가, 다음에 무엇을 다르게 해야 하는가"
- design-decision.md — 의사결정. "왜 A를 선택하고 B를 버렸는가"
- runbook.md — 반복 작업 절차. "이 작업은 매번 이렇게 한다"
- open-question.md — 미해결 질문. "지금은 답이 없지만 답을 알아야 할 것"
흔한 오해: "메모를 다 적으면 토큰 비용이 폭발한다"는 걱정. 실제로는 메모를 잘 분리해 두면 에이전트가 필요한 메모만 골라 읽기 때문에 토큰이 줄어든다. 모든 정보가 대화 히스토리에 쌓이는 쪽이 훨씬 비싸다.
본인 6주 적용 후 확정한 메모 작성 규칙 5가지
카파시 패턴을 6주 적용하면서 본인이 자체로 추가한 규칙들이다. 일반 가이드에는 없지만 실무에서 자주 부딪히는 문제를 풀어준다.
- 규칙 1: 메모 1개당 한 가지 결정만 — 복잡한 결정을 한 메모에 묶으면 retrieval 시 한쪽만 필요할 때도 양쪽이 끌려와 컨텍스트가 흐려진다. 결정마다 별도 파일이 정답이었다.
- 규칙 2: 결정의 이유와 대안 후보를 함께 기록 — 6주 뒤에 다시 봐도 추적 가능하려면 "왜 그렇게 결정했나"가 필요하다. 대안 후보를 같이 적어두면 다음 작업에서 재고할 때도 빠르다.
- 규칙 3: 본문에 코드 스니펫보다 의도를 기록 — 코드는 git에 있다. 메모에는 "왜 이 코드가 있는지"만 적는다. 코드를 복사해 두면 코드 변경 시 메모와 어긋나는 일이 자주 생긴다.
- 규칙 4: 매주 최소 한 번은 메모 정리 — 메모가 30개를 넘어가면 retrieval 자체가 무너진다. 매주 정리하면서 중복 통합·이미 적용된 결정 아카이브를 한다. 주 30분 정도 투자가 가장 효율 좋았다.
- 규칙 5: 폴더 구조 대신 명시적 파일명 — 폴더로 묶으면 검색이 흐려진다. flat 구조 +
YYYYMMDD-주제-결정-키워드.md형식의 명시적 파일명이 더 잘 작동했다. 파일명만으로도 grep 가능하다.
주의: 이 5가지 규칙은 본인 1인 작업 패턴 기준이다. 팀 협업에서는 메모 공유·동시 편집·리뷰 흐름이 추가되어야 한다. 1인 패턴을 그대로 팀에 가져가면 메모가 빠르게 깨진다.
6. 결론: 마크다운 = 사람과 AI의 공용 언어
카파시 패턴의 본질은 단순하다. 마크다운은 사람도 읽고 AI도 읽는 유일한 매체다. 한쪽만 읽는 코드 주석이나 대화는 둘 사이의 공용 자산이 되지 못한다. 코드를 잘 짜는 시대에서, 코드와 메모를 같이 잘 짜는 시대로 옮겨가고 있다는 게 그의 메시지다.
1차 자료
- Andrej Karpathy, X(@karpathy) 공개 게시글 시리즈 (2025-2026)
- AGENTS.md 표준 제안 저장소
- Anthropic, "Claude Code Best Practices" 공식 문서
- Karpathy 본인 GitHub: github.com/karpathy
- 본인 6주 측정 데이터 (2026-03-18 ~ 2026-04-29)
카파시 인용은 공개 트윗·노트의 의미를 요약한 것으로, 직접 인용이 아닌 부분은 의역입니다.
댓글
댓글 쓰기