Claude Code 소스 코드 유출에서 배우는 하네스 패턴 10선

2026년 3월 31일, Claude Code의 소스가 통째로 유출되었다. 다만 진짜 흥미로운 지점은 유출 사건 자체가 아니라, 그 안에서 작동하던 Claude Code 하네스 패턴이 전부 드러났다는 사실이다. 512,000줄 규모의 TypeScript 원본과 1,906개 파일이 난독화 이전 상태 그대로 IPFS에 4시간 만에 퍼졌다. DMCA 삭제 요청도 확산 속도를 따라잡지 못했다.

 

각설하고, "유출됐다더라" 수준의 팩트 나열은 이미 넘쳐난다. 정작 "그래서 내 에이전트에 무엇을 적용할 것인가"에 답하는 글은 드물다. 이 글은 10개 패턴 전부를 실전 적용 관점에서 분해한다. 말미에는 CLAUDE.md에 곧바로 붙일 수 있는 체크리스트도 제공한다. 모델은 교체되어도 하네스는 경험의 결정체다. Anthropic이 실제 운영을 통해 녹여낸 노하우이므로 교과서로 삼을 만하다.

 

 

출처: Adobe Stock

 

이번 Claude Code 유출, 무엇이 유출되었는지 팩트 정리

 

원인은 .npmignore 실수와 Bun 런타임 버그의 결합이다

 

발단은 허무할 정도다. .npmignore 설정에서 .map 파일을 걸러내지 않은 채 배포가 진행되었다. 여기에 Bun 런타임 이슈 #28001이 겹쳤다. 본래라면 난독화된 번들만 배포되어야 하지만, sourcemap이 원본 TypeScript를 그대로 끌고 나왔다. 결과적으로 Anthropic 엔지니어들이 수년간 축적한 하네스 설계가 통째로 공개되었다.

 

규모를 보면 결코 가볍지 않다

 

• TypeScript 원본 512,000줄
• 파일 1,906개
• 권한 툴 19개
• 미출시 기능 플래그 44개
• 컨텍스트 압축 엔진만 46,000줄
• MCP 트랜스포트 6종

 

이 정도 규모라면 단순 CLI 래퍼가 아니라 에이전트 운영체제에 가까운 수준이다. UI 층(Ink + React)은 비트마스크 스타일로 치밀하게 구성되어 있으며, 하네스 층이 중간에서 툴·메모리·퍼미션을 전부 중계하고, 모델 층은 맨 아래에서 추론만 담당한다.

 

하네스를 해부하는 일이 의미 있는 이유

 

LLM 앱을 구축해 본 개발자라면 공감할 것이다. 진짜 어려운 것은 모델이 아니라 하네스다. 추론만으로는 풀 수 없는 다섯 과제 — 툴 사용 안정성, 상태 유지, 비용 통제, 보안, UX 일관성 — 이 모두가 하네스의 몫이다. 이번 유출은 "Anthropic이 이 문제를 어떻게 풀었는가"를 통째로 보여준 사건이다.

 

패턴 1~3: 모델과 분리된 하네스의 뼈대

 

패턴 1 — 하네스 패러다임: 추론으로는 풀 수 없는 다섯 과제

 

Claude Code 하네스의 제1 원칙은 "모델에 기대지 말고 하네스에 박아라" 이다. 유출 코드를 살펴보면 모델은 오로지 추론만 담당한다. 툴 호출 검증, 오류 회복, 상태 관리, 비용 모니터링, 보안 체크는 전부 하네스 레이어에 하드코딩되어 있다. 왜일까? 모델은 매 버전마다 행동이 미묘하게 달라지고, LLM 추론에 "안전"을 위임하는 순간 재현성이 증발하기 때문이다.

 

바로 적용할 포인트: 에이전트 설계에서 "모델이 알아서 판단하겠지"라는 표현이 나오는 순간 의심해야 한다. 그 지점은 하네스에 박는 것이 맞다.

 

패턴 2 — 툴 컨트랙트: Zod 스키마로 통일된 19개 툴

 

19개 권한 툴이 모두 buildTool 팩토리를 경유해 생성된다. 입력 검증은 전부 Zod 스키마이며, 출력 파싱 역시 Zod이다. 이것이 왜 중요한가? 툴 컨트랙트가 깨지는 순간 에이전트가 무너지기 때문이다. "이 파라미터 없어도 되리라 가정했다"와 같은 상황을 Zod이 컴파일 타임에 차단한다.

 

// 유출 코드 기준 개념 스케치 (실제 Anthropic 내부 명칭과 다를 수 있음)
const tool = buildTool({
  name: "Read",
  input: z.object({ file_path: z.string() }),
  output: z.object({ content: z.string() }),
  handler: async (input) => { /* ... */ }
});

 

바로 적용할 포인트: MCP 툴을 구성할 때 Zod 같은 런타임 스키마로 입출력 모두를 검증한다. 한쪽만 해서는 충분하지 않다.

 

패턴 3 — 쿼리 엔진: "continue sites"와 5단계 회복 전략

 

쿼리 엔진에는 continue_sites라는 개념이 존재한다. 모델이 중간에 이탈할 수 있는 지점을 미리 표시해 두고, 문제가 발생하면 5단계로 회복한다: 폴딩 → 리액티브 컴팩션 → 토큰 에스컬레이션 → 모델 에스컬레이션 → 안전 정지. 즉, "우선 저렴한 모델로 시도하고 실패하면 Opus까지 끌어올린다"와 같은 그라데이션 전략이다.

 

바로 적용할 포인트: 에이전트 실패 시 재시도 로직을 단일 분기가 아닌 다층 에스컬레이션으로 설계해야 한다.

 

패턴 4~6: Claude Code 하네스 패턴이 잡은 안전·상태·비용

 

패턴 4 — 퍼미션 파이프라인: 5단 방어 아키텍처

 

툴 호출이 발생할 때마다 다음 5단을 거친다.

 

1. 정적 Allow/Deny 리스트 — settings.json에 박아둔 화이트/블랙
2. 툴 고유 체크 — 각 툴이 자체 검증 룰 보유
3. 동적 분류기 — LLM이 명령 위험도 스코어링
4. 유저 승인 — 필요 시 프롬프트
5. 감사 로그 — 전부 기록

 

이것이 퍼미션 파이프라인 설계의 정석이다. 단층 방어는 쉽게 뚫리지만, 다섯 층이 쌓이면 프롬프트 인젝션 공격도 쉽사리 뚫지 못한다.

 

바로 적용할 포인트: 자체 에이전트 역시 "유저가 승인했으니 안전하다"는 가정에만 의존하지 말고, 정적 룰과 동적 분류기까지 최소 3중으로 쌓아야 한다.

 

패턴 5 — 컨텍스트 엔트로피 관리: 3층 메모리와 Strict Write Discipline

 

컨텍스트 엔트로피 관리야말로 이번 유출의 진짜 하이라이트다. 메모리가 3층으로 분할되어 있다.

 

• 단기 컨텍스트 — 현재 턴 작업 메모리
• 세션 영속 — 인덱스 파일 + 토픽별 분리 파일
• 장기 메모리 — 유저 정보, 피드백, 프로젝트 맥락

 

그리고 "Strict Write Discipline"이라는 규칙이 존재한다. 모든 메모리 저장은 한 번에 한 파일에, 명확한 분류 아래, 중복 없이 수행한다. 이 규칙이 없다면 메모리는 순식간에 쓰레기통이 된다. 46,000줄에 달하는 컨텍스트 압축 엔진이 존재하는 이유 역시 이를 보조하기 위함이다.

 

 

바로 적용할 포인트: 메모리 파일을 날짜별로 쌓지 말고 토픽별로 분리한다. 인덱스 파일은 별도로 관리한다.

 

패턴 6 — 프롬프트 캐시 최적화: DYNAMIC_BOUNDARY 경계선의 힘

 

프롬프트 캐시 최적화는 비용과 직결되는 주제다. Claude Code 하네스는 SYSTEM_PROMPT_DYNAMIC_BOUNDARY라는 마커를 통해 시스템 프롬프트를 정적 부분과 동적 부분으로 분할한다. 정적 부분은 캐시에 고정되어 매 요청마다 재사용되고, 동적 부분만 새롭게 토큰 계산된다.

 

여기에 14개 캐시 브레이크 벡터를 추적하여, 캐시를 깨뜨리는 변수(모델 스위치, 툴 리스트 변경, 시간대 변경 등)를 전부 모니터링한다. Anthropic API에서 프롬프트 캐시를 사용할 때 적중률이 50%인 경우와 95%인 경우의 비용 차이는 상당하다.

 

바로 적용할 포인트: 시스템 프롬프트를 "절대 변하지 않는 쪽"과 "턴마다 변하는 쪽"으로 물리적으로 분리한다. 앞쪽을 먼저 전송하고 뒤쪽을 나중에 붙이면 캐시 적중률이 급상승한다.

 

패턴 7~10: Anthropic이 감춰둔 방어막

 

패턴 7 — 반추출 메커니즘: fake_tools와 CONNECTOR_TEXT

 

이 지점이 진정 흥미로운 발견이다. 유출 코드에는 fake_tools 배열이 존재한다. 모델 프롬프트에 실재하지 않는 가짜 툴 정의를 섞어 넣어, "이 모델을 다른 환경으로 증류(distill)하려는 시도"를 감지하는 장치다. 또한 CONNECTOR_TEXT라는 요약 레이어가 툴 호출 체인을 외부에 노출하기 전에 한 번 더 가공한다.

 

즉, 반추출(anti-distillation) 설계가 하네스 안에 박혀 있다. 단순 보안이 아니라 IP 보호 차원의 엔지니어링이다.

 

바로 적용할 포인트: 자체 에이전트가 외부에 API를 제공한다면, 내부 동작을 그대로 노출하지 말고 요약 레이어를 한 층 삽입하는 방안을 검토할 가치가 있다.

 

패턴 8 — 프러스트레이션 탐지: "wtf", "awful" 정규식의 의미

 

유저 메시지에 wtf, awful, terrible 같은 키워드가 등장하면 정규식으로 포착하여 감정 스코어를 가산한다. 포인트는 이것을 LLM 외부에서 처리한다는 사실이다. 이유는 두 가지다.

 

1. 매 턴마다 LLM에게 "지금 유저가 분노했는가"를 묻는다면 비용이 폭발한다
2. LLM이 간혹 "유저는 분노하지 않았다"라고 거짓말을 한다

 

정규식과 스코어링을 하네스 쪽에 박아놓고, 점수가 임계치를 넘어서면 유저에게 "사과 모드"를 적용하거나 "다른 모델로 교체"하는 트리거를 발동한다.

 

패턴 9 — 언더커버 모드: Anthropic 내부 레퍼런스 자동 제거

 

유출 코드를 보면 Anthropic 내부 코드네임, Slack 채널명, 엔지니어 이름 같은 레퍼런스가 출력에 노출되면 자동으로 마스킹된다. 심지어 "NO force-OFF" 보호까지 존재한다 — 유저가 프롬프트 인젝션으로 이 필터를 끄려 시도해도, 하네스 레벨에서 강제로 다시 활성화한다.

 

바로 적용할 포인트: 사내 에이전트를 구축할 때 민감 단어 필터를 모델에 위임하지 말고 하네스 포스트프로세싱에 박아야 한다.

 

패턴 10 — 네이티브 클라이언트 인증: Bun과 Zig로 구현한 DRM

 

기술적으로 가장 인상적인 패턴이다. cch=00000 같은 플레이스홀더가 요청에 포함되어 있으면, Bun이 Zig로 작성한 저수준 HTTP 스택이 그 자리에 런타임 해시를 주입한다. NATIVE_CLIENT_ATTESTATION 플래그를 통해 "이것이 진짜 Claude Code 클라이언트인가"를 서버에서 검증한다. 웹 레벨 가드레일이 아니라 바이너리 무결성 수준의 DRM이다.

 

정리하면, Anthropic은 Anthropic 에이전트 아키텍처를 단순 JS 코드로 지킨 것이 아니라 언어 런타임 레벨까지 내려가서 보호막을 쳤다. 오픈소스를 베껴 그대로 복제하려는 시도에 대응하는 구조다.

 

덤으로, 아직 출시되지 않은 KAIROS와 ULTRAPLAN

 

44개 미출시 플래그 중 두 개가 시선을 끈다.

 

KAIROS — 야간에 작동하는 autoDream 상주 에이전트

 

KAIROS는 4층 구조로 되어 있다: 관찰(observe) → 탐지(detect) → 트리거(trigger) → 증류(distill). 쉽게 표현하자면 프로액티브 상주 에이전트다. 유저가 로그아웃한 이후에도 백그라운드에서 지속적으로 작동하며 "아까 유저가 고민하던 그 버그의 해결책을 찾아두었다"와 같은 결과물을 준비한다. autoDream이라는 야간 모드도 포함되어 있다.

 

ULTRAPLAN — 30분짜리 Opus 계획 오프로딩

 

ULTRAPLAN은 Cloud Container Runtime 위에서 Opus에 30분에 달하는 장시간 계획 작업을 위임하는 기능이다. 로컬 Claude Code가 아니라 클라우드 컨테이너에서 장기간 구동한다. 계획 단계와 실행 단계를 물리적으로 분리함으로써, 장기 추론이 로컬 세션 UX를 얼리지 않도록 설계한 것이다.

 

둘 다 아직은 베타 플래그라 출시 시점은 미정이다. 다만 방향성은 명확하다 — 에이전트가 유저 옆에 앉아 있지 않을 때도 일하는 쪽이다.

 

Claude Code 하네스 패턴, CLAUDE.md에 무엇부터 적용할 것인가

 

10개 전부를 욕심내면 1년도 부족하다. ROI 기준으로 우선순위를 정리해 보았다.

 

우선순위	패턴	이유
1순위	패턴 5, 6	컨텍스트 엔트로피 + 프롬프트 캐시. 즉시 품질·비용 개선
2순위	패턴 1, 4	하네스 패러다임 + 퍼미션 파이프라인. 안정성 기반
3순위	패턴 3, 8	쿼리 엔진 회복 + 프러스트레이션 탐지. UX 고급화
4순위	패턴 2, 7, 9, 10	툴 컨트랙트·반추출·언더커버·DRM. 규모 확장 시

 

바로 실행 가능한 체크리스트는 다음과 같다.

 

• [ ] 시스템 프롬프트를 정적/동적 부분으로 물리적 분리 (패턴 6)
• [ ] 메모리 파일을 토픽별로 분할하고 인덱스 파일을 별도 관리 (패턴 5)
• [ ] "Strict Write Discipline" — 한 번에 한 파일, 중복 없이 (패턴 5)
• [ ] 툴 입출력 전부를 Zod나 JSON Schema로 검증 (패턴 2)
• [ ] 위험 툴은 정적 화이트리스트와 동적 분류기로 2중 체크 (패턴 4)
• [ ] 실패 시 재시도 로직을 다층 에스컬레이션으로 설계 (패턴 3)
• [ ] 민감 키워드 필터를 LLM 외부 포스트프로세싱에 배치 (패턴 9)

 

3줄 요약

 

• 모델보다 하네스가 본체다. Claude Code 하네스 패턴 10개는 전부 "추론에 맡기지 말고 코드에 박아라"는 주장이다.
• 가장 먼저 손댈 대상은 패턴 5와 6이다. 컨텍스트 엔트로피 관리와 프롬프트 캐시 최적화. 이 두 가지가 품질과 비용을 동시에 잡는다.
• 나머지는 규모를 보면서 천천히 쌓아가면 된다. 19개 권한 툴 풀세트를 처음부터 구축할 필요는 없다.

 

Claude Code 하네스 패턴은 결국 "LLM 앱을 진지하게 운영하다 보면 이러한 레이어들이 필연적으로 필요해진다" 는 증명서다. 본인의 CLAUDE.md나 에이전트 설계 문서를 공개한 글이 있다면 댓글에 공유해 주길 바란다. 이 10개 중 몇 개를 이미 커버하고 있는지 함께 점검해 보면 흥미로울 것이다.

 

---

 

참고 자료

 

• 원 분석 글 (Qiita, 일본어): Claude Code 소스 코드 유출 분석
• Bun 런타임 이슈: GitHub Bun issue #28001
• Anthropic 엔지니어링 블로그: Anthropic Engineering

 

본문의 내부 용어(fake_tools, CONNECTOR_TEXT, NATIVE_CLIENT_ATTESTATION 등)는 유출된 코드 기준 명칭이며, Anthropic 공식 명칭과는 다를 수 있다.