How Claude Code Works

Prompt Layer의 Jared Zoneraich가 발표한 'How Claude Code Works'를 통해 Claude Code의 내부 작동 방식과 설계 철학을 깊이 있게 살펴보자.

 

코딩 에이전트의 진화

코딩 에이전트는 빠르게 발전해왔다:

 

1. 1단계: ChatGPT에서 코드 복사/붙여넣기
2. 2단계: Cursor 초기 버전 (VS Code 포크 + Command K)
3. 3단계: Cursor 어시스턴트 (에이전트와 대화)
4. 4단계: Claude Code (헤드리스 방식, 코드를 직접 건드리지 않음)

 

성공의 핵심 요인

Claude Code가 폭발적으로 성장한 이유는 두 가지 혁신의 결합이다:

 

• 단순한 아키텍처(Simple Architecture)
• 더 나은 모델(Better Models)

 

설계 철학: 도구를 주고 간섭하지 말라

"Give it tools and then get out of the way"
- 도구를 제공하고, 방해하지 않는 것

 

복잡한 패러다임의 배제

Claude Code는 다음을 모두 배제했다:

 

• RAG (검색 증강 생성)
• 임베딩
• 분류기(Classifier)
• 복잡한 DAG 구조

 

대신 더 나은 모델을 만들고 툴 호출에만 집중했다.

 

Python의 선(Zen of Python)

"Simple is better than complex,
Complex is better than complicated"

단순함이 복잡함보다 낫고,
복잡함이 복잡하게 얽힌 것보다 낫다

 

이 원칙이 Claude Code의 모든 설계에 적용되었다.

 

핵심 아키텍처: 단순 마스터 루프

Claude Code와 대부분의 최신 코딩 에이전트의 핵심은 단 하나의 while 루프다. 내부적으로 N0라고 불린다.

 

이 구조의 핵심은 모델의 유연성에 있다:

• 모델은 언제 계속 도구를 호출해야 하는지 안다
• 모델은 실수를 수정하는 데 매우 뛰어나다
• 모델이 스스로 탐색하도록 맡길수록 시스템은 더 강력해진다

 

Constitution: 마크다운 파일 하나

리포지토리를 이해하기 위해 복잡한 벡터 DB를 만드는 대신, Claude Code는 단순한 마크다운 파일(agents.md 또는 claude.md)을 사용한다.

 

• 프롬프트 엔지니어링/컨텍스트 엔지니어링의 가장 단순한 답변
• 범용 모델을 사용자의 용도에 맞게 조정하는 방법
• 필요할 때 사용자나 에이전트가 변경 가능

 

핵심 도구들

이 도구들은 인간이 터미널에서 문제를 해결할 때 하는 작업을 모방한다.

 

Read

• 토큰 제한이 있어 파일이 너무 클 경우를 대비한 도구
• 별도로 구축할 가치가 있음

 

Grep, Glob

• 벡터 기반 RAG와 대치되는 접근
• 범용 에이전트에서는 grep이 RAG보다 낫다는 판단

 

Edit

• 파일을 재작성하는 대신 Diff(차이점) 사용
• 훨씬 빠르고 컨텍스트를 적게 사용
• 실수 방지에 자연스러운 방식 (종이를 덧쓰는 것보다 지우개로 지우는 것이 쉬움)
• Unified Diffing은 모든 에이전트에서 사용을 강력히 권장

 

Bash: 가장 중요한 도구

"Bash is all you need"
다른 모든 도구를 제거해도 Bash만 있으면 된다

 

왜 Bash가 핵심인가?

1. 단순함과 강력함: 모든 것을 수행할 수 있다
2. 압도적인 훈련 데이터: 사람들이 Bash를 가장 많이 사용했기 때문에 모델이 가장 잘 이해한다

 

Bash의 우아함:

Claude Code는 Python 파일을 생성하고 실행한 후 삭제하는 방식으로 작동한다:

 

# Claude Code가 내부적으로 하는 일
1. Python 스크립트 생성
2. bash로 실행
3. 결과 확인
4. 파일 삭제

 

Bash를 통해 수천 개의 도구를 사용할 수 있으며, 모델에게 시도(try)해 볼 기회를 준다.

 

Web Search, Web Fetch

• 더 저렴하고 빠른 모델로 이동시키는 데 사용
• 비용 관점에서 유용

 

To-Dos

• 모델의 진행 상황 추적 및 제어
• 제어 가능성(Steerability) 향상

 

Tasks

• 컨텍스트 관리 도구
• 컨텍스트가 가득 차면 모델이 멍청해지는 것을 방지

 

To-Do 리스트: 비결정적 구조화

To-Do 리스트는 "구조화되어 있지만 구조적으로 강제되지는 않는(Structured but not structurally enforced)" 형태다.

 

특징

• 결정적으로 강제되지 않고 순수하게 프롬프트 기반
• 모델의 지시 이행 능력에 의존 (1~2년 전에는 불가능했던 방식)
• 시스템 프롬프트 상단에 도구 설명이 주입됨
• ID, 제목, 증거(evidence) 등이 포함될 수 있음

 

4가지 이점

1. 계획 수립 강제: 모델이 계획을 세우도록 함
2. 충돌 후 재개: Resume after crashes 가능
3. UX 향상: 사용자는 40분 동안 루프만 도는 것이 아니라 진행 상황을 알 수 있음
4. 제어 가능성: Steerability 향상

 

컨텍스트 관리: 가장 큰 난제

컨텍스트 관리는 에이전트 분야에서 끊임없이 피하려는 유령이며, 인간과 대화하는 한 항상 한계가 있다.

 

H2A (Async Buffer)

H2A는 IO 프로세스를 추론(reasoning)과 분리하여 컨텍스트를 관리하는 비동기 버퍼다.

 

• 터미널에서 보는 모든 것과 응답을 모델에 모두 채워 넣는 것을 방지
• 컨텍스트 용량 관리 (약 92%에 도달 시 작동)

 

컨텍스트 압축기(Context Compressor)

H2A가 컨텍스트 관리를 하지만, 실제 압축은 Compressor가 담당한다:

 

• 모델이 용량 한계에 도달하면 중간 부분을 삭제
• 머리(Head)와 꼬리(Tail) 부분을 요약
• 압축된 컨텍스트로 계속 작업 진행

 

샌드박싱과 장기 저장소

• Bash와 샌드박스는 장기 저장소에 유리
• 컨텍스트가 짧을수록 모델이 더 빠르고 똑똑해짐
• 마크다운 파일 저장을 통한 컨텍스트 절약
• 가까운 미래에 모든 ChatGPT나 Claude 창에 샌드박스가 포함될 것으로 예측

 

서브 에이전트 (Sub-Agents)

서브 에이전트는 긴 컨텍스트로 인해 모델이 "멍청해지는" 문제의 해결책이다.

 

특징:

• 자체 컨텍스트를 가짐
• 결과만 메인 에이전트에 피드백
• 메인 컨텍스트를 어지럽히지 않음
• 병렬로 실행 가능

 

역할 예시:

• 연구원(Researcher)
• 문서 리더(Docs Reader)
• 테스터 러너(Tester Runner)
• 코드 리뷰어(Code Reviewer)

 

호출 구조:

• 설명(Description): 사용자가 보게 될 내용
• 프롬프트(Prompt): 긴 문자열로, 코딩 에이전트가 자체 에이전트에게 프롬프트 제공
• 오류 발생 시 더 많은 정보를 주입하여 모델이 해결하도록 하는 유연한 방식

 

시스템 프롬프트

시스템 프롬프트에는 다음과 같은 넛지(nudge)가 포함되어 있다:

 

• 간결한 출력 지시
• 텍스트 설명 대신 도구 사용을 더 많이 푸시
• 기존 코드와 일치하도록 수정 (주석 추가 금지)
• 명령을 병렬로 광범위하게 실행
• To-Dos 활용 지시

 

시스템 프롬프트를 통해 어떤 도구를 언제 사용할지 지시할 수 있으며, 이는 DAG 대신 루프를 사용하는 이유와도 연결된다.

 

스킬(Skills) 시스템

스킬은 확장 가능한 시스템 프롬프트(Extendable system prompt)로 생각할 수 있다.

 

정의와 역할

• 컨텍스트를 어지럽히지 않으면서 모델이 더 많은 정보에 접근할 수 있도록 제공
• 필요할 때만 정보를 가져옴

 

활용 예시

• 문서 업데이트: 발표자의 글쓰기 스타일과 제품 정보 포함
• Microsoft Office 편집: Word 및 Excel 작업 (디컴파일 방식)
• 디자인 스타일 가이드: 디자인 참조용
• 심층 연구(Deep Research): GitHub 리포지토리 등을 분석하여 Skills로 재구축

 

현재의 한계

• 이론적으로는 Skills마다 설명(oneliner)이 제공되어 모델이 항상 선택해야 함
• 현실적으로 수동으로 Skill을 호출해야 하는 경우가 많음
• 아직 완벽하지 않은 기능

 

샌드박싱과 보안

샌드박싱은 가장 지루한 부분이지만 매우 중요하다.

 

주요 보안 위협

• 인터넷에서 프롬프트 주입(in-prompt injection)이 큰 문제
• 쉘 접근 권한과 웹 가져오기(web fetch)가 결합되면 큰 공격 벡터가 됨

 

보안 대책

• URL 차단
• 하위 에이전트로의 격리
• Bash 명령 게이트(gate)를 위한 파이프라인
• 접두사에 따라 샌드박싱 환경을 통과하는 방식이 다름
• 컨테이너화 및 권한 관리

 

DAG 구조의 종말

복잡한 DAG(Directed Acyclic Graph) 구조가 더 이상 필요하지 않다.

 

과거의 DAG

• 지난 2년 동안 고객 지원 에이전트 등에 수백 개의 노드를 가진 DAG 구축
• 환각이나 부적절한 환불 등을 보장하는 데 유용했음
• 하지만 엔지니어링 광기(web of engineering madness)를 초래

 

현재의 접근

• 개발이 10배 쉬워짐
• 유지보수가 용이
• 모델이 좋아져서 실제 성능도 더 좋음

 

DAG가 여전히 유용한 경우

• 여행 일정처럼 결과물이 항상 같은 문제(Deliverable)
• 순차적 실행을 강제해야 하는 경우 (예: 고객 서비스 순서)
• 목적에 따라 혼합(mix and match) 가능

 

AGI Pill: 모델을 신뢰하라

"의심스러울 때는 모델에 의존하고,
모든 엣지 케이스를 생각하려 하지 말고
모델이 탐색하도록 두어야 한다"

 

핵심 원칙

• 오늘날 모델의 결함을 우회하려고 과도하게 엔지니어링하는 것은 시간 낭비
• 모델 자체가 나아질 것이므로 신뢰하는 것이 중요
• 툴 호출은 JSON 형식화의 새로운 추상화
• 모델 성능은 지속적으로 향상
• 과도한 최적화를 피하고 단순함 유지

 

Happy Middle Ground

현재 한계를 해결하기 위한 균형점:

 

• 마스터 while 루프와 도구 호출 패러다임 사용
• 도구 호출을 매우 엄격하게(rigorous) 구성
• 엣지 케이스는 구조화된 도구(structured tool)에 넣고 버전 관리 및 평가
• 탐색 단계(exploration phase)에서는 모델에 맡기거나 시스템 프롬프트 사용

 

다른 코딩 에이전트와의 비교

에이전트	핵심 특징
Claude Code	• 사용자 친화성과 단순성 우세 • Git 사용, PR 생성 등 인간 상호작용이 많은 작업에 최적 • 컨텍스트 관리가 강력함 • 단순 마스터 while 루프 사용
Cursor IDE	• 모델 독립적(Model-agnostic) • Composer는 증류된(distilled) 모델 사용으로 속도 극대화 • 파인 튜닝을 통한 데이터 기반 방어벽 구축 • 상태 최신(state-of-the-art) 모델 선택 가능 • Factory 팀 운영, Droid 서브 에이전트 전문화
AMP (Sourcegraph)	• Free Tier 제공 (잉여 토큰 활용, 광고 표시) • 모델 선택 불가 → 개발 속도 향상 (기대치 낮아짐) • Handoff 방식: 새 스레드 시작, 필요한 정보 전달 • Compaction(요약)보다 빠름 • Fast, Smart, Oracle 세 가지 모델 단계 • 에이전트 친화적 환경 구축이 비전
CodeX (OpenAI)	• Claude Code와 유사한 마스터 while 루프 • Rust 코어, 오픈 소스 • 이벤트 기반 IO 처리 • 커널 기반 샌드박싱 • 속도는 느리지만 코딩 에이전트에 최적화
Devon	• 엔드투엔드 자율성 • 자기 성찰(Self-reflection) 초점 • 모델 독립적

 

AMP의 Handoff 방식

Compaction(요약)은 느리고 최악이라는 평가를 받는다. AMP의 Handoff는:

 

• 새로운 스레드를 시작하고 필요한 정보를 전달
• 비유: Call of Duty에서 무기 전환 - 리로드보다 빠름
• 승리 전략일 수 있음

 

평가(Eval) 방법론

벤치마크의 한계

벤치마크는 모델 제공업체의 마케팅 수단이 되었으며, 모든 모델이 벤치마크를 통과한다고 말한다. 유용성이 낮다.

 

에이전트 평가 방식

단순한 while 루프 아키텍처는 모델 유연성에 더 의존하므로 평가를 어렵게 만든다.

 

1. 통합 테스트(Integration Test)
   • 문제를 해결하는지 확인하는 E2E 테스트
   • 높은 수준에서 모델이 도구를 몇 번 호출했는지 통계 확인
2. 시점별 스냅샷(Point-in-time snapshots)
   • 특정 도구 호출이 실행되어야 할 시점의 컨텍스트 제공하고 테스트
3. 백테스트(Backtest) - 가장 추천
   • 모델이 도구를 얼마나 자주 변경하는지 기록하고 재실행
   • 기록 데이터를 캡처하고 다시 실행
4. 에이전트 스멜(Agent Smell)
   • 표면적인 지표로 에이전트의 비정상적 동작 확인
   • 툴 호출 횟수, 재시도 횟수, 소요 시간 등

 

도구 자체의 엄격한 테스트

• 도구를 함수처럼 취급하여 입력과 출력을 테스트
• 모델의 결정론(determinism) 부담을 덜어줌
• 서브 에이전트라면 재귀적으로 E2E 테스트 필요

 

결정론적 결과가 필요한 경우

매우 구체적인 출력 형식이 필요할 때 (예: 특정 목소리의 이메일, SEO 블로그 포스트):

 

• 모델 탐색에만 의존하지 말고 엄격하게 테스트 가능한 도구 구축
• LLM 어설션(Assertion)을 통해 기준 충족 확인
• LLM Judge를 활용한 평가 (가장 쉬운 테스트 방법)
• 기준에 맞으면 수정, 아니면 누락된 헤더 등을 추가
• 유연성이 낮을수록 테스트가 쉬워짐

 

미래 전망

도구 호출 수의 논쟁

• 첫 번째 학파: 수백 개의 도구 호출을 가진 마스터 루프 (도구 호출 기능이 좋아질 것)
• 발표자의 견해: 도구 호출 수를 줄이고 Bash로 회귀 (하나의 메가 도구 호출)

 

적응형 예산(Adaptive Budgets)

다음 개척지(frontier)는 모델 혼합 및 매칭이다:

 

• 추론 모델을 도구로 사용하는 패러다임
• 트레이드오프: 20배 빠른 모델 vs 약간 멍청한 결과
• 플래너(Planner)에는 강력한 모델 (GPT-5, 새로운 Opus)
• 나머지는 혼합하여 사용
• 트리거 구문 활용: think, think hard, think harder, ultra-think

 

새로운 1급 패러다임

To-Do 리스트나 Skills와 같은 새로운 1급 패러다임을 계속 구축할 여지가 많으며, 이는 새로운 발견으로 이어질 수 있다.

 

AI 치료사 문제(AI Therapist Problem)

가장 흥미로운 AI 문제는 전역 최댓값(Global Maximum)이 존재하지 않는다는 것이다.

 

• 예시: 뉴욕의 치료사 - 명상, CBT, 아야와스카 등 다양한 전략 존재
• 취향(taste)과 설계 아키텍처가 중요
• 특정 사용 사례에 따라 다른 철학의 에이전트가 승리
• Mixture of Experts 접근이 필수
• 방어벽(defensibility) 구축: 도메인 전문가(PM, SME) 참여

 

Headless Claude Code SDK

더 높은 수준의 추상화에서 에이전트 구축:

 

• 단순한 프롬프트를 제공하면 파이프라인의 일부로 사용 가능
• GitHub Action 예시: 매일 커밋 읽고 → cloud.md 확인 → 문서 업데이트 여부 결정 → PR 생성
• 클로드 코드가 오케스트레이션 및 허들링 수행
• 워크플로우의 일부로 헤드리스 에이전트 활용

 

기타 지양하는 패러다임

• ML 기반 의도 감지: 배제
• ReAct: 배제
• 분류기(Classifiers): 비용 문제가 크지 않다면 덜 유용 (토큰 당 금융 엔지니어링 덕분에 비용 감소 중)

 

Spec/Test-Driven Development (TDD)

• 좋은 엔지니어링 원칙으로 돌아가라
• 코딩 에이전트의 경우, 좋은 테스트를 구축하면 에이전트 성능이 향상 (AMP의 철학)
• 단순한 편집 작업에서는 단계를 건너뛸 수 있음

 

핵심 교훈

1. 모델을 신뢰할 것: 의심스러우면 모델에 의존
2. 단순한 설계가 승리함: Simple is better than complex
3. Bash가 전부: 도구를 단순하게 (40개가 아닌 5~10개)
4. 컨텍스트 관리는 항상 가장 큰 난제: 끊임없이 피하려는 유령
5. 다양한 관점(Mixture of Experts)이 중요: 문제 해결에는 여러 방법 존재

 

보너스: 슬라이드 덱 구축에 Claude Code 활용

발표자는 Claude Code를 사용하여 이 발표의 슬라이드 덱을 구축했다:

 

• 슬라이드 개발 Skill 생성 → Slidev(라이브러리) 연구
• 심층 연구 Skill 생성 → 다른 에이전트 연구
• 디자인 Skill 생성 → 디자인 개선(박스 스타일, 악센트 색상 등)