Claude Code의 구조 - 하네스는 얇게, 지능은 모델에

seunghyun·2026년 4월 1일
AI AgentClaudeclaude codeharness

Agentic Programming

목록 보기
4/5


2026년 3월 31일, Anthropic의 Claude Code 소스코드가 npm 패키지에 .map 파일이 포함된 채 배포되면서 세상에 공개됐다. 해킹이 아니라 빌드 파이프라인의 실수였다.

이 글은 유출된 코드를 포함하진 않고, 그 코드가 드러낸 설계 철학과 아키텍처 인사이트를 정리한다.

코딩 AI 에이전트 최고봉 클로드 구조를 볼 수 있다니.. 이게 만우절 이벤트가 아니라니..

1. 지능은 모델에, 하네스는 얇게

Claude Code의 가장 근본적인 설계 원칙은 이것이다.

Intelligence belongs in the model, not the harness.

에이전트 프레임워크들이 복잡한 오케스트레이션 레이어를 쌓는 것과 반대 방향이다. Claude Code의 핵심 루프(TAOR: Think, Act, Observe, Repeat)는 약 50줄에 불과하다. 계획 수립, 의사결정, 오류 복구 — 이 모든 걸 모델이 직접 한다. 프레임워크가 대신하지 않는다.

여기에 덧붙여지는 원칙이 하나 더 있다.

Delete code when models improve.

모델이 발전하면 하네스 코드를 삭제한다. 실제로 Claude 4.0 모델 출시 때 시스템 프롬프트의 절반 가량을 삭제했다고 한다. 하네스는 모델의 현재 한계를 보완하는 임시 비계(scaffolding) 이며, 모델이 성장하면 걷어낸다.

이건 단순한 미니멀리즘이 아니다. 경제적 판단이다. 에이전트 코드를 복잡하게 쌓으면 유지보수 비용이 모델 성능 개선과 경쟁하게 된다. Anthropic은 하루 60~100회 내부 빌드, 엔지니어 1인당 일 5개 PR을 치는 속도로 움직인다. 그 속도에서 복잡한 프레임워크는 발목을 잡는다.

2. 4개 프리미티브로 모든 것을 합성한다

100개의 전용 인테그레이션을 만드는 대신, Claude Code는 4개의 근본 능력을 조합한다.

프리미티브역할
Read파일, 이미지 읽기
Write/Edit정밀한 텍스트 조작
Execute셸 명령 실행
ConnectMCP 프로토콜로 외부 확장

새로운 기능이 필요하면 전용 도구를 만드는 게 아니라 이 프리미티브들의 조합으로 만든다. 인테그레이션 수가 늘어도 유지보수 비용은 일정하다. 자주 쓰는 작업(Edit, Grep, Glob)은 전용 도구로 승격되어 있지만, 그것도 결국 이 프리미티브 위에 놓인 편의 레이어다.

실제 사용 빈도를 보면 Edit이 가장 많이 호출되는 도구이고, Read, TodoWrite가 뒤를 잇는다.

RAG(Retrieval-Augmented Generation)도 쓰지 않는다. 대신 ripgrep, jq, find 같은 유닉스 도구를 LLM이 직접 구사하는 LLM-native search 방식을 택했다. RAG의 유사도 함수와 청킹 결정에 숨어있는 실패 모드를 회피하면서도, 모델의 코드 이해 능력으로 복잡한 정규식 패턴까지 처리한다.

3. 메모리 아키텍처: 6계층 + 5단계 컴팩션

에이전트가 장시간 작업할수록 컨텍스트가 노이즈로 차면서 품질이 떨어지는 문제를 Anthropic은 '컨텍스트 엔트로피(context entropy)' 라고 부른다. 이걸 해결하기 위해 전통적인 "전부 저장" 방식이 아닌 계층적 메모리 구조를 설계했다.

6계층 메모리

계층내용특징
1조직 관리 정책제외 불가, 최우선
2프로젝트 설정 (CLAUDE.md)팀 공유, VCS 커밋
3사용자 개인 설정전역 작업 스타일
4세션 히스토리현재 대화 맥락
5자동 학습 패턴200줄/25KB 캡
6실시간 트랜스크립트가장 먼저 삭제됨

핵심은 MEMORY.md라는 가벼운 인덱스 파일이다. 메모리 내용 자체가 아니라 메모리를 가리키는 포인터들의 목록이다. 이 인덱스가 항상 컨텍스트에 로딩되고, Sonnet 모델이 턴마다 최대 5개의 관련 메모리를 선택적으로 불러온다. 무한 성장 없이 지속적 학습을 실현하는 구조다.

5단계 컴팩션 전략

컨텍스트 윈도우 고갈을 막는 전략도 단일하지 않다.

  1. Snip Compact — 오래된 메시지 제거 (빠르지만 손실)
  2. Microcompact — 턴 안에서 도구 결과만 압축
  3. Auto-Compact — 모델이 전체 요약 생성 (비동기)
  4. Reactive Compact — API가 prompt-too-long 반환 시 긴급 폴백
  5. Context Collapse — snip과 auto-compact 사이의 지능형 프루닝

조직 정책은 절대 건드리지 않고, 실시간 트랜스크립트부터 먼저 떨어뜨린다. 우선순위 기반 정보 보존이다.

4. 프롬프트가 아닌 구조로 강제한다

"rm -rf 쓰지 마"라고 프롬프트에 적어두면 대부분 따르지만 100%는 아니다. Claude Code는 이 문제를 구조적으로 해결한다.

bashSecurity.ts는 2,592줄짜리 셸 명령 검증 모듈이다. 단일 체크가 아니라 다중 계층 방어를 구현한다.

  1. 정규식 패턴 탐지 — 명령 치환, 위험 패턴 검출
  2. Tree-sitter AST 분석 — 구조적 코드 파싱
  3. Heredoc 추출 — 내장 명령 검사
  4. 경량 모델의 2차 검증 — 정규식으로 못 잡는 의미적 판단
  5. 유니코드 경로 우회 방지 — path traversal 공격 차단

Zsh의 =cmd 확장이 $(which cmd)로 풀리면서 Bash deny rule을 우회하는 케이스까지 처리한다.

각 계층이 다른 계층의 사각지대를 보완하는 defense-in-depth 패턴이다. Hooks 시스템도 이 철학의 연장선에 있다. PreToolUse 이벤트에서 셸 스크립트로 위험 명령을 결정론적으로 차단할 수 있다. 프롬프트가 아니라 exit code로.

5. 서브에이전트! 격리가 핵심이다

Claude Code의 멀티에이전트 구조는 의외로 보수적이다. 깊은 에이전트 계층 대신 최대 1단계 깊이의 서브에이전트만 허용한다. 서브에이전트가 다른 서브에이전트를 생성하는 재귀는 금지된다.

서브에이전트가 받는 것

  • 독립된 컨텍스트 윈도우 (부모 오염 방지)
  • 별도 토큰 예산 (비용 통제)
  • 제한된 도구 접근 (폭주 방지)
  • 격리된 MCP 연결 (깨끗한 리소스 관리)

부모는 요약만 받는다. 코드베이스 탐색 중 수천 토큰의 중간 결과가 생기더라도 메인 대화에는 최종 결론만 들어간다. 복잡한 오케스트레이션보다 컨텍스트 격리를 택한 것이다.

재밌는 점은, 메인 에이전트가 여러 작업을 검증 없이 완료하면 자동 검증 서브에이전트가 트리거된다는 것이다. 자기 점검을 구조에 내장했다.

6. Skills와 Progressive Disclosure

CLAUDE.md에 모든 지침을 넣으면 컨텍스트가 금방 찬다. Skills는 이 문제를 Progressive Disclosure로 해결한다.

  • 세션 시작 시: 각 스킬의 name과 description만 시스템 프롬프트에 올라감
  • 실제 호출 시: 전체 내용이 로딩됨

수십 개의 스킬을 등록해둬도 컨텍스트 부담이 거의 없다. 이건 MCP 서버의 lazy loading과도 같은 철학이다. MCP 서버는 원래 연결 시 모든 description과 args가 dump되어 컨텍스트를 크게 잡아먹었는데, Anthropic은 이를 필요할 때만 로드하도록 바꿨다.

많이 넣는 것보다 필요한 구조를 적절한 계층으로 나눠 넣는 것이 에이전트 품질에 더 중요하다.

7. 모델 선택 전략, 비싼 모델만 쓰지 않는다

Claude Code는 중요한 호출의 50% 이상에 Claude 3.5 Haiku를 사용한다.

  • 파일 읽기, 웹 파싱, git 히스토리 처리, 대화 요약
  • 메모리 관련성 판단 (턴마다 5개 메모리 선택)
  • 보안 검증의 2차 판단

프리미엄 모델 대비 70~80% 비용 절감을 적절한 작업에 적용한다. 모든 작업에 Opus를 쓰는 것이 아니라, 작업의 복잡도에 맞게 모델을 배분하는 경제적 설계다.

8. 피처 플래그가 보여주는 로드맵

유출된 코드에는 아직 공개되지 않은 기능들이 피처 플래그로 숨겨져 있었다. Anthropic이 어떤 방향으로 가고 있는지를 보여준다.

KAIROS — 상시 가동 데몬

150번 이상 참조되는 피처 플래그. 반응형이 아닌 항상 켜져 있는 백그라운드 에이전트. append-only 활동 로그와 능동적 알림을 가진다. CLI 도구에서 상시 동반자로의 전환.

autoDream — 수면 중 기억 정리

세션 사이에 백그라운드 서브에이전트가 메모리 파일을 정리·통합한다. UC Berkeley의 sleep-time compute 연구에서 영감을 받았다. 관찰을 병합하고, 모순을 제거하고, 인사이트를 사실로 변환한다.

ULTRAPLAN — 원격 딥 플래닝

복잡한 계획 수립을 원격 컨테이너에서 Opus로 최대 30분간 돌리는 모드. 로컬 세션의 제약을 벗어난 깊은 사고.

BUDDY — 터미널 속 타마고치

18종의 생물, 가챠 메카닉, 레어리티/샤이니 시스템, 결정론적 절차적 생성, 심지어 치트 방지 메카닉까지. Claude가 성격을 써주는 디지털 반려동물. (이건 이미 공식 공개됐다.)

9. 프롬프트가 아니라 환경을 설계한다

이 모든 것을 관통하는 메타 인사이트가 있다.

에이전트 성능의 병목은 모델이 아니라 구조다.

harness 프로젝트의 실험에 따르면, 프롬프트만 사용한 기준선 대비 구조화된 harness를 적용했을 때 평균 점수가 49.5 → 79.3으로 상승했다. 15개 과제 전부에서 우위, 결과 분산 32% 감소. 그리고 난도가 높을수록 효과가 컸다.

  • Basic: +23.8
  • Advanced: +29.6
  • Expert: +36.2

프롬프트를 더 길게 쓰는 게 아니라, 에이전트가 일할 환경 자체를 설계하는 접근이다. 어떤 역할을 분리할지, 어떤 지식을 고정할지, 어떤 검증 루프를 둘지, 어떤 협업 패턴을 택할지가 결과를 좌우한다.

10. 정리

Claude Code의 코드는 AI 에이전트 시스템에 대한 몇 가지 날카로운 교훈을 남긴다.

  1. 얇은 오케스트레이션이 두꺼운 프레임워크를 이긴다. 모델에게 계획을 맡기고, 하네스는 능력과 제약만 제공하라.

  2. 합성 가능한 프리미티브가 전용 인테그레이션보다 확장성이 좋다. Read/Write/Execute만으로 무엇이든 조합할 수 있다.

  3. 컨텍스트 관리에는 단일 전략이 통하지 않는다. 5단계 컴팩션처럼 상황별 전략이 필요하다.

  4. 안전은 프롬프트가 아니라 구조로 강제해야 한다. 프롬프트 기반 지침은 100%가 아니다.

  5. 축소를 전제로 설계하라. 모델이 발전하면 사라질 임시 비계를 짓는다.

  6. AI 애플리케이션에서 진짜 경쟁력은 모델이 아니라 하네스다. 메모리 시스템, 퍼미션 모델, UX 통합 — 실제 작업의 ~90%는 모델 연동이 아니라 이 애플리케이션 레이어에 있다.

코드 생성기의 다음 단계는 더 영리한 한 명의 에이전트가 아니라, 더 잘 설계된 환경과 구조일 수 있다.

참고 자료

profile
seunghyun
이전 포스트

소소한 Claude Code 사용 근황

다음 포스트

Claude Code | 모델 한계를 보완하는 세 가지 구조적 레이어

2개의 댓글

comment-user-thumbnail
KWONYEONGMIN
2026년 4월 16일

많이 배우고 갑니다

1개의 답글