Andrej Karpathy의 CLAUDE.md: 코딩 에이전트 워크플로 원칙
목차
개요
Andrej Karpathy가 자신의 CLAUDE.md 파일에 정리한 코딩 에이전트 워크플로 원칙이 인포그래픽으로 공유되었다. 이 문서는 코딩 에이전트와 함께 일할 때 따르는 작업 방식과 사고방식을 압축해 담고 있다. 크게 코딩 워크플로 원칙, 핵심 원칙, 엔지니어 마인드셋, 계속 던질 질문, 그리고 전체를 요약하는 TLDR로 구성된다. 이 글에서는 각 항목을 순서대로 정리한다.
배경
CLAUDE.md는 코딩 에이전트에게 작업 규칙과 맥락을 전달하는 지침 파일이다. Karpathy는 이 파일에 사소하지 않은 작업을 다룰 때 지켜야 할 절차와 태도를 명시했다. TLDR에 따르면 LLM 에이전트의 역량, 특히 Claude와 Codex의 역량이 2025년 12월경 코헤런스 임계점을 넘었다. 이것은 소프트웨어 엔지니어링의 위상 전이로 묘사된다. 지능은 앞서 있고, 통합과 워크플로와 소프트웨어가 아직 따라잡아야 한다는 진단이다. 그래서 2026년은 업계가 이 새 역량을 대사하면서 에너지 높은 해가 될 것이라고 본다.
코딩 워크플로 원칙
Karpathy는 코딩 작업에서 따르는 여섯 가지 워크플로 원칙을 제시한다.
첫째, 계획 우선이다. 사소하지 않은 작업은 플랜 모드를 사용한다. 상세 스펙을 미리 작성하고, 코딩 전에 모호함을 제거한다. 작은 작업에는 가벼운 계획만 둔다.
둘째, 집요하게 검증한다. 좋은 IDE를 매처럼 주시한다. 가정과 엣지케이스와 트레이드오프를 점검한다. 테스트, diff 리뷰, 정합성 확인을 루프 안에서 실행한다.
셋째, 단순하게 유지한다. 과도한 엔지니어링과 비대한 추상화를 회피한다. 1000줄보다 100줄을 선호한다. 죽은 코드와 군더더기를 정리한다. 더 단순한 방법이 없는지 자문한다.
넷째, 외과적 수정만 한다. 필요한 것만 변경한다. 무관한 코드나 주석은 건드리지 않는다. 망가지지 않은 것을 개선하려 하지 않는다. 부수효과와 churn을 최소화한다.
다섯째, 목표 주도로 실행한다. 명확한 성공 기준을 제시한다. 테스트를 먼저 작성한 뒤 통과시킨다. 브라우저 MCP 같은 도구를 루프에 사용한다. 목표 달성까지 에이전트가 반복하도록 둔다.
여섯째, 서브에이전트로 병렬화한다. 리서치, 탐색, 분석을 오프로드한다. 서브에이전트로 컨텍스트를 깨끗하게 유지한다. 집중을 위해 서브에이전트당 한 작업을 맡긴다. 판단을 더해 결과를 병합한다.
핵심 원칙
세 가지 핵심 원칙은 작업의 기준선을 정의한다.
단순함 우선은 문제를 푸는 최소 코드를 쓰고 투기적 코드를 금지한다. 게으름 금지는 근본 원인을 탐색하고 임시방편을 금지하며 시니어 개발자 기준을 따른다. 최소 영향은 필요한 것만 건드리고 부수효과와 새 버그를 만들지 않는다.
엔지니어 마인드셋
엔지니어 마인드셋은 에이전트와 일하는 태도를 다룬다.
끈기는 에이전트가 지치지 않는다는 점에서 출발한다. 무자비한 반복이 천재성을 이기며, 체력이 force multiplier가 된다.
레버리지는 성공 기준을 주고 지켜보는 방식이다. 명령형보다 선언형을 택하고, 레버리지를 곱한다.
재미는 잡일을 제거하고 창의성에 집중하는 데서 온다. 더 많은 커버리지와 더 적은 블로킹을 추구한다.
위축은 코드를 쓰는 능력과 읽는 능력이 다르다는 경고다. 의도적으로 날카롭게 유지해야 한다.
속도 향상은 단지 빨리가 아니다. 빨리 하는 것만이 아니라 무엇을 만들 수 있는지를 확장해야 한다.
슬로포칼립스는 2026년 AI 슬롭에 대비하라는 경고다. 과장은 빠르게 퍼지고, 신호는 판단을 요한다.
계속 던질 질문
Karpathy는 계속 던져야 할 질문들도 함께 제시한다.
10배 엔지니어 격차는 어떻게 되는가. 제너럴리스트가 LLM으로 무장한 전문가를 점점 능가하는가. 미래에 LLM 코딩은 어떤 느낌일까, 스타크래프트인가 팩토리오인가 뮤직인가. 디지털 지식 노동이 병목에서 풀리면 사회는 얼마나 바뀌는가.
의미와 시사점
이 문서의 원칙들은 코딩 에이전트를 단순한 자동완성이 아니라 협업 대상으로 다룬다. 계획 우선과 집요한 검증은 에이전트의 출력을 신뢰하기 전에 사람의 판단을 루프 안에 유지하라는 요구다. 단순함 우선과 외과적 수정은 에이전트가 만들어내는 변경의 규모와 부수효과를 통제하려는 장치다. 끈기와 레버리지는 에이전트의 지치지 않는 반복 능력을 사람의 성공 기준 설정과 결합하는 전략이다. 위축에 대한 경고는 능력을 에이전트에 위임하더라도 코드를 읽고 판단하는 역량은 유지해야 한다는 균형을 강조한다.
결론
Karpathy의 CLAUDE.md는 코딩 에이전트와 일하는 절차와 태도를 압축한 지침이다. 계획, 검증, 단순함, 외과적 수정, 목표 주도, 병렬화라는 워크플로 원칙과 끈기, 레버리지, 재미를 강조하는 마인드셋이 핵심이다. TLDR은 LLM 에이전트가 코헤런스 임계점을 넘었고 2026년이 이 역량을 대사하는 해가 될 것이라고 전망한다. 지능은 앞서 있고 워크플로와 소프트웨어가 따라잡아야 한다는 진단이 이 문서 전체를 관통한다.