2026년 3월 31일, Claude Code의 소스 코드가 통째로 유출됐습니다. Anthropic은 사태 직후 공식 문서 「How Claude Code works」에 동작 원리를 정리해 공개했습니다. 이 글은 그 공식 문서를 1차 자료로 Claude Code의 동작 원리를 정리합니다.
코드 유출 원인
Claude Code 배포 과정에서 npm 패키지 @anthropic-ai/claude-code 2.1.88 버전에 소스맵(.map) 파일이 함께 올라갔습니다.
이 파일이 난독화된 배포 코드를 원래 TypeScript 소스로 그대로 되돌리는 열쇠가 됐습니다.
소스맵이란?
소스맵은 빌드 후 압축·난독화된 코드와 원래 소스 코드의 위치를 짝지어 둔 매핑 파일입니다. 브라우저 개발자 도구가 에러 스택을 원래 파일과 줄 번호로 짚어 주는 것도 이 파일이 있기 때문입니다. 개발과 디버깅에는 꼭 필요하지만, 운영 배포에 함께 올리면 압축 코드를 원본 소스로 그대로 복원할 수 있어 보통 외부에는 내보내지 않습니다.
유출 규모와 Anthropic의 입장
그렇게 유출된 코드가 51만 줄, 파일로 약 1,900개에 달합니다. 다행히 고객 데이터나 인증 정보는 섞여 있지 않았다고 합니다.
Anthropic은 이걸 보안 침해가 아니라 사람의 실수로 생긴 패키징 사고라고 선을 그었습니다. 다만 2025년에도 똑같은 실수가 있었다는 걸 떠올리면 마냥 가볍게 넘길 일은 아닌 것 같습니다.
유출된 건 도구 코드, 모델의 '두뇌'는 아니다
유출된 건 Claude Code의 CLI 도구 코드입니다. 모델이 어떻게 추론하는지를 담은 '두뇌'는 처음부터 거기 없었습니다.
공식 문서는 이 도구 코드를 에이전트 하니스(agentic harness)라고 부릅니다. 평범한 언어 모델 하나를 쓸 만한 코딩 에이전트로 바꿔 주는 도구·컨텍스트 관리·실행 환경의 묶음입니다.
마침 사람들이 유출 코드를 뜯어보며 동작 원리를 짐작하던 무렵, Anthropic이 「How Claude Code works」 공식 문서를 내놓았습니다. 유출 때문이라고 밝히지는 않았지만, 타이밍이 묘합니다.
에이전트 루프
Claude Code는 일을 맡기면 세 단계를 반복하며 처리합니다.
- 컨텍스트 수집 — 파일을 뒤지고 코드 구조를 파악
- 실행 — 코드를 고치고 명령을 실행
- 결과 검증 — 테스트·타입 체크로 확인
세 단계는 뚜렷이 나뉘지 않고 서로 포개집니다. 작업이 끝날 때까지 줄곧 도구를 쓰면서 셋을 오갑니다.
루프의 모양은 일감에 따라 달라집니다. 가벼운 질문이면 컨텍스트만 모으고 끝나고, 버그 수정이면 세 단계를 몇 번이고 다시 돕니다. 사용자도 이 루프 안에 들어 있어 진행 중 언제든 끼어들어 방향을 틀 수 있습니다.
두 축 — 모델(머리)과 도구(손)
루프를 굴리는 두 축은 모델과 도구입니다.
모델은 코드를 읽고 무엇을 어떻게 바꿀지 판단하는 '머리'입니다.
Sonnet은 대부분의 코딩 작업에 무리가 없고, 복잡한 설계 판단에는 더 강한 추론을 하는 Opus가 어울립니다.
모델은 사용자가 직접 고릅니다 — 세션 중에는 /model 명령으로 바꾸고, 시작할 때는 claude --model <이름>으로 지정합니다.
도구는 Claude의 '손'입니다. 손이 없으면 Claude가 할 수 있는 일은 텍스트 응답뿐입니다. 파일을 읽고 고치고, 명령을 실행하고, 웹을 뒤지려면 도구가 필요합니다. 내장 도구는 크게 다섯 갈래입니다.
메모리와 컨텍스트
Claude Code는 대화 내용을 ~/.claude/projects/ 아래 JSONL 파일로 적어 둡니다.
덕분에 지난 세션을 되감거나 이어서 열 수 있습니다.
단, 세션끼리는 분리돼 있어 새 세션은 늘 빈 컨텍스트로 출발합니다.
컨텍스트 윈도우에는 대화·파일·CLAUDE.md·메모리가 차곡차곡 쌓입니다.
공간이 꽉 차면 Claude Code가 정리에 들어갑니다.
- 도구 출력 정리오래된 도구 출력부터 차례로 비움
- 대화 요약 압축그래도 모자라면 대화를 통째로 요약해 압축
- 초반 지시 손실이 과정에서 초반에 했던 자잘한 지시는 사라질 수 있음
오래 지켜야 할 규칙이라면 대화가 아니라 CLAUDE.md에 적어 두는 편이 안전합니다.
안전장치 — 체크포인트와 권한
Claude Code의 안전장치는 둘입니다.
체크포인트는 파일 변경을 되돌리는 장치입니다.
Claude는 파일을 건드리기 전에 늘 그 파일의 스냅샷을 떠 두기 때문에, 뭔가 어긋나면 Esc 두 번으로 직전 상태로 되돌릴 수 있습니다.
단, 체크포인트가 책임지는 건 파일 변경까지입니다 — 데이터베이스나 배포처럼 바깥세상에 영향을 주는 일은 되돌릴 수 없어, 그런 명령 앞에서는 Claude가 먼저 물어봅니다.
권한은 Claude가 어디까지 묻지 않고 처리해도 되는지를 정합니다.
Shift+Tab으로 모드를 바꿔 가며 고릅니다.
- Default파일 편집·셸 명령을 매번 물어봄
- Auto-accept edits파일 편집과 mkdir·mv 같은 명령은 알아서, 그 외는 물어봄
- Plan mode읽기 전용 도구만 써서 계획부터 세움
- Auto mode모든 행동을 백그라운드 안전 체크와 함께 실행 (리서치 프리뷰)
자주 쓰는 믿을 만한 명령은 아예 .claude/settings.json에 미리 등록해 둘 수 있습니다.
결국 Claude Code란
에이전트 루프와 내장 도구는 토대입니다. 그 위에 스킬·MCP·훅·서브에이전트를 얹어 기능을 넓힐 수 있습니다. 군더더기를 걷어내면 Claude Code는 한 문장으로 줄어듭니다 — 추론하는 모델에 도구·컨텍스트·실행 환경을 둘러 코딩 에이전트로 만드는 장치.
이번 사건에서 가장 인상적이었던 건 Anthropic의 선택입니다. 소스가 털린 상황에서 택할 수 있는 길은 여럿이었지만, 동작 원리를 더 또렷한 공식 문서로 펴내는 쪽을 골랐습니다. 어차피 드러난 구조라면 추측과 포크가 여기저기 나뒹구는 것보다 한곳에 제대로 정리해 두는 편이 낫다 — 그런 판단이 아닐까 싶습니다.
