Harness-Engineering on ICE-ICE-BEAR-BLOG

Claude Code 하네스 해부학 #1 — 진입점에서 응답까지, 요청 하나의 여정

Mon, 06 Apr 2026 00:00:00 +0900

개요

Claude Code의 소스 구조를 27세션에 걸쳐 체계적으로 해부하는 시리즈의 첫 번째 글이다. 이 포스트에서는 사용자가 터미널에 “hello"를 입력했을 때, 응답이 화면에 출력되기까지 거치는 11개 TypeScript 파일의 전체 콜스택을 추적한다.

분석 대상: 11개 핵심 파일

#	경로	줄 수	역할
1	`entrypoints/cli.tsx`	302	CLI 부트스트랩, 인자 파싱, 모드 라우팅
2	`main.tsx`	4,683	메인 REPL 컴포넌트, Commander 설정
3	`commands.ts`	754	커맨드 레지스트리
4	`context.ts`	189	시스템 프롬프트 조립, CLAUDE.md 주입
5	`QueryEngine.ts`	1,295	세션 관리, SDK 인터페이스
6	`query.ts`	1,729	핵심 턴 루프 — API + 도구 실행
7	`services/api/client.ts`	389	HTTP 클라이언트, 4개 프로바이더 라우팅
8	`services/api/claude.ts`	3,419	Messages API 래퍼, SSE 스트리밍, 재시도
9	`services/tools/toolOrchestration.ts`	188	동시성 파티셔닝
10	`services/tools/StreamingToolExecutor.ts`	530	스트리밍 중 도구 실행
11	`services/tools/toolExecution.ts`	1,745	도구 디스패치, 권한 검사

총 15,223줄을 추적한다.

1. 진입과 부트스트랩: cli.tsx -> main.tsx

cli.tsx는 302줄에 불과하지만, 놀라울 정도로 많은 패스트-패스(fast-path) 분기가 존재한다:

cli.tsx:37 --version -> 즉시 출력, import 0개
cli.tsx:53 --dump-system -> 최소 import
cli.tsx:100 --daemon-worker -> 워커 전용 경로
cli.tsx:112 remote-control -> 브릿지 모드
cli.tsx:185 ps/logs/attach -> 백그라운드 세션
cli.tsx:293 기본 경로 -> main.tsx 동적 import

설계 의도: --version 하나를 위해 main.tsx의 4,683줄을 로딩하지 않겠다는 것이다. CLI 도구의 체감 응답성에 직접 영향을 미치는 최적화다.

기본 경로에서는 동적 import로 main.tsx를 로드한다:

// cli.tsx:293-297
const { main: cliMain } = await import('../main.js');
await cliMain();

main.tsx가 4,683줄인 이유는 다음을 모두 포함하기 때문이다:

사이드 이펙트 import (1-209행): profileCheckpoint, startMdmRawRead, startKeychainPrefetch — 모듈 평가 시점에 병렬 서브프로세스를 시작하여 약 65ms의 macOS keychain 읽기를 숨긴다
Commander 설정 (585행~): CLI 인자 파싱, 10+개 모드별 분기
React/Ink REPL 렌더링: 터미널 UI 마운트
헤드리스 경로 (-p/--print): UI 없이 QueryEngine 직접 사용

2. 프롬프트 조립: context.ts의 dual-memoize

context.ts는 189줄의 작은 파일이지만 시스템 프롬프트의 동적 부분을 전담한다. 두 개의 메모이즈된 함수가 핵심이다:

getSystemContext() (context.ts:116): git 상태(branch, status, 최근 커밋)를 수집
getUserContext() (context.ts:155): CLAUDE.md 파일들을 탐색/파싱

왜 분리했는가? Anthropic Messages API의 프롬프트 캐싱 전략과 직결된다. 시스템 프롬프트와 사용자 컨텍스트의 캐시 수명이 다르므로 cache_control을 서로 다르게 적용해야 한다. memoize로 감싸서 세션 내 한 번만 계산한다.

context.ts:170-176에서 setCachedClaudeMdContent()를 호출하는 것은 순환 의존성을 끊기 위한 장치다 — yoloClassifier가 CLAUDE.md 내용을 필요로 하지만, 직접 import하면 permissions -> yoloClassifier -> claudemd -> permissions 순환이 발생한다.

3. AsyncGenerator 체인: 아키텍처의 척추

Claude Code의 전체 데이터 플로우는 AsyncGenerator 체인으로 구성된다:

QueryEngine.submitMessage()* -> query()* -> queryLoop()* -> queryModelWithStreaming()*

모든 핵심 함수가 async function*이다. 이는 단순한 구현 선택이 아니라 아키텍처적 결정이다:

Backpressure: 소비자가 느리면 생산자도 대기
취소: AbortController와 결합하여 즉각적인 취소 가능
합성: yield*로 제너레이터 체인을 자연스럽게 연결
상태 관리: 루프 내 로컬 변수가 턴 간 상태를 자연스럽게 유지

QueryEngine.submitMessage() (QueryEngine.ts:209)의 시그니처를 보면:

async *submitMessage(
 prompt: string | ContentBlockParam[],
 options?: { uuid?: string; isMeta?: boolean },
): AsyncGenerator<SDKMessage, void, unknown>

SDK 모드에서 각 메시지는 yield로 스트리밍되며, Node.js의 backpressure가 자연스럽게 구현된다.

4. 핵심 턴 루프: query.ts의 while(true)

query.ts(1,729줄)의 queryLoop()가 실제 API+도구 루프다:

// query.ts:307
while (true) {
 // 1. queryModelWithStreaming() 호출 -> SSE 스트림
 // 2. 스트리밍 이벤트를 yield
 // 3. 도구 호출 감지 -> runTools()/StreamingToolExecutor
 // 4. 도구 결과를 메시지에 추가
 // 5. stop_reason == "end_turn" -> break
 // stop_reason == "tool_use" -> continue
}

State 타입(query.ts:204)이 중요하다. messages, toolUseContext, autoCompactTracking, maxOutputTokensRecoveryCount 등 루프 상태를 명시적 레코드로 관리하여, continue 사이트에서 한 번에 갱신한다.

5. API 통신: 4개 프로바이더와 캐싱

client.ts:88의 getAnthropicClient()는 4가지 프로바이더를 지원한다:

프로바이더	SDK	동적 import 이유
Anthropic Direct	`Anthropic`	기본, 즉시 로딩
AWS Bedrock	`AnthropicBedrock`	AWS SDK 수 MB
Azure Foundry	`AnthropicFoundry`	Azure Identity 수 MB
GCP Vertex	`AnthropicVertex`	Google Auth 수 MB

claude.ts(3,419줄)의 핵심 함수 체인:

queryModelWithStreaming() (claude.ts:752)
 -> queryModel()
 -> withRetry()
 -> anthropic.beta.messages.stream() (SDK 호출)

캐싱 전략은 getCacheControl() (claude.ts:358)이 1시간 TTL 여부를 사용자 유형, 피처 플래그, 쿼리 소스에 따라 결정한다.

6. 도구 오케스트레이션: 3-tier 동시성

flowchart TD
 TC["도구 호출 배열<br/>[ReadFile, ReadFile, Bash, ReadFile]"]
 P["partitionToolCalls()<br/>toolOrchestration.ts:91"]
 B1["Batch 1<br/>ReadFile + ReadFile<br/>isConcurrencySafe=true"]
 B2["Batch 2<br/>Bash<br/>isConcurrencySafe=false"]
 B3["Batch 3<br/>ReadFile<br/>isConcurrencySafe=true"]
 PAR["Promise.all()<br/>최대 10개 동시"]
 SEQ["순차 실행"]
 PAR2["Promise.all()"]

 TC --> P
 P --> B1
 P --> B2
 P --> B3
 B1 --> PAR
 B2 --> SEQ
 B3 --> PAR2

 style B1 fill:#e8f5e9
 style B2 fill:#ffebee
 style B3 fill:#e8f5e9

StreamingToolExecutor(530줄)는 이 배치 파티셔닝을 스트리밍 컨텍스트로 확장한다. API 응답이 스트리밍되는 도중에 도구 호출을 감지하면 즉시 실행을 시작한다:

addTool() (StreamingToolExecutor.ts:76) — 큐에 추가
processQueue() (StreamingToolExecutor.ts:140) — 동시성 확인 후 즉시 실행
getRemainingResults() (StreamingToolExecutor.ts:453) — 모든 도구 완료 대기

에러 전파 규칙: Bash 에러만 형제 도구를 취소한다 (siblingAbortController). Read/WebFetch 에러는 다른 도구에 영향을 주지 않는다. 이는 Bash 명령 간의 암묵적 의존성(mkdir 실패 -> 후속 명령 무의미)을 반영한 설계다.

전체 데이터 플로우

sequenceDiagram
 participant User as 사용자
 participant CLI as cli.tsx
 participant Main as main.tsx
 participant QE as QueryEngine
 participant Query as query.ts
 participant Claude as claude.ts
 participant API as Anthropic API
 participant Tools as toolOrchestration
 participant Exec as toolExecution

 User->>CLI: "hello" 입력
 CLI->>Main: dynamic import
 Main->>QE: new QueryEngine()
 QE->>Query: query()
 Query->>Claude: queryModelWithStreaming()
 Claude->>API: anthropic.beta.messages.stream()
 API-->>Claude: SSE 스트림

 alt stop_reason == end_turn
 Claude-->>User: 응답 출력
 else stop_reason == tool_use
 Claude-->>Query: tool_use blocks
 Query->>Tools: partitionToolCalls()
 Tools->>Exec: runToolUse()
 Exec->>Exec: canUseTool() + tool.call()
 Exec-->>Query: 도구 결과
 Note over Query: while(true) 다음 반복
 end

Rust 갭 지도 미리보기

동일한 요청을 Rust 포트에서 추적한 결과, 31개 갭을 식별했다:

우선순위	갭 수	핵심 예시
P0 (치명적)	2	동기 ApiClient, StreamingToolExecutor 부재
P1 (높음)	6	3-tier 동시성, 프롬프트 캐싱, Agent 도구
P2 (보통)	7	멀티 프로바이더, 노력 제어, 샌드박스
구현 완료	11	자동 압축, SSE 파서, OAuth, 설정 로딩

구현 완료율: 36% (11/31). 다음 포스트에서 이 갭들의 핵심인 대화 루프를 깊이 파고든다.

인사이트

AsyncGenerator가 아키텍처의 척추다 — 단순한 구현 기법이 아니라 backpressure, 취소, 합성을 한 번에 해결하는 설계 결정이다. Rust에서는 Stream trait이 대응하지만 yield* 합성의 인체공학이 크게 다르다.
main.tsx 4,683줄은 기술 부채다 — Commander 설정, React 컴포넌트, 상태 관리가 한 파일에 혼재. 역사적 성장의 결과로, 모듈 분리의 기회가 된다.
도구 동시성이 단순하지 않다 — “전부 병렬” 또는 “전부 직렬"이 아닌 3계층 모델(읽기 배치, 쓰기 순차, Bash 형제 취소)은 실전 에이전트 하네스의 핵심 설계 요소다.

다음 포스트: #2 — 대화 루프의 심장, StreamingToolExecutor와 7개의 continue

Claude Code 하네스 해부학 #2 — 대화 루프의 심장, StreamingToolExecutor와 7개의 continue

Mon, 06 Apr 2026 00:00:00 +0900

개요

시리즈 첫 번째 글에서 “hello” 한마디가 11개 파일을 관통하는 여정을 추적했다. 이번 포스트에서는 그 여정의 심장부인 query.ts 1,729줄의 while(true) 루프를 완전 해부한다. 7가지 continue 경로가 만드는 탄력적 실행 모델, StreamingToolExecutor의 4단계 상태 머신, 그리고 partitionToolCalls()의 3계층 동시성 모델을 분석한 뒤, Rust 프로토타입에서 이를 어떻게 재현했는지 대조한다.

분석 대상: 10개 핵심 파일

#	경로	줄 수	역할
1	`query/config.ts`	46	이뮤터블 런타임 게이트 스냅샷
2	`query/deps.ts`	40	테스트 가능한 I/O 경계 (DI)
3	`query/tokenBudget.ts`	93	토큰 예산 관리, 자동 연속/중단 결정
4	`query/stopHooks.ts`	473	Stop/TaskCompleted/TeammateIdle 훅
5	`query.ts`	1,729	핵심 – while(true) 턴 루프
6	`QueryEngine.ts`	1,295	세션 래퍼, SDK 인터페이스
7	`toolOrchestration.ts`	188	도구 파티셔닝 + 동시성 제어
8	`StreamingToolExecutor.ts`	530	SSE 중 도구 파이프라이닝
9	`toolExecution.ts`	1,745	도구 디스패치, 권한 검사
10	`toolHooks.ts`	650	Pre/PostToolUse 훅 파이프라인

총 6,789줄의 핵심 오케스트레이션 코드를 해부한다.

1. queryLoop()의 7가지 continue 경로

query.ts의 queryLoop() 함수(query.ts:241)는 단순한 API 호출 루프가 아니다. 7가지 continue 사유를 가진 탄력적 실행기다. 각 경로는 고유한 장애 시나리오를 처리한다:

사유	행	설명
`collapse_drain_retry`	1114	컨텍스트 축소 드레인 후 재시도
`reactive_compact_retry`	1162	반응형 압축 후 재시도 (413 복구)
`max_output_tokens_escalate`	1219	8k -> 64k 토큰 에스컬레이션
`max_output_tokens_recovery`	1248	“이어서 작성하라” 넛지 메시지 주입
`stop_hook_blocking`	1303	Stop 훅이 블로킹 에러 반환
`token_budget_continuation`	1337	토큰 예산 미달로 계속
`next_turn`	1725	도구 실행 완료 후 다음 턴

State 타입이 핵심이다 (query.ts:204-217). 루프 상태를 10개 필드의 레코드로 관리한다. 왜 개별 변수가 아닌 레코드인가? continue 사이트가 7곳이며, 각각 state = { ... }으로 한 번에 갱신한다. 9개 변수를 개별 할당하면 하나를 빠뜨리는 실수가 발생하기 쉽다. 레코드 갱신은 타입 시스템이 누락을 잡아준다.

루프 한 반복의 전체 흐름

1. 전처리 (365-447): snip 압축, 마이크로 컴팩트, 컨텍스트 축소
2. 자동 압축 (454-543): 성공 시 메시지 교체 후 continue
3. 블로킹 한도 검사 (628-648): 토큰 임계값 초과 시 즉시 종료
4. API 스트리밍 (654-863): SSE 이벤트를 for await로 소비
5. 도구 없는 종료 경로 (1062-1357): 413 복구, max_output 복구, stop 훅
6. 도구 있는 계속 경로 (1360-1728): 나머지 도구 실행 -> next_turn

2. StreamingToolExecutor의 4단계 상태 머신

StreamingToolExecutor.ts(530줄)는 Claude Code에서 가장 정교한 동시성 패턴이다. 핵심 아이디어: API 응답이 아직 스트리밍되는 동안 이미 완성된 도구 호출의 실행을 시작한다.

모델이 [ReadFile("a.ts"), ReadFile("b.ts"), Bash("make test")]를 한 번에 호출하는 경우, 파이프라이닝 없이는 세 도구 블록이 모두 도착한 후에야 실행이 시작된다. 파이프라이닝에서는 ReadFile("a.ts") 블록이 완성되는 즉시 파일 읽기가 시작된다.

stateDiagram-v2
 [*] --> queued: addTool()
 queued --> executing: processQueue()<br/>canExecuteTool() == true
 queued --> completed: 사전 취소<br/>getAbortReason() != null

 executing --> completed: 도구 실행 완료<br/>또는 sibling abort

 completed --> yielded: getCompletedResults()<br/>순서대로 yield

 yielded --> [*]

 note right of queued
 processQueue()는 addTool()
 + 이전 도구 완료 시 자동 트리거
 end note

 note right of completed
 Bash 에러 시
 siblingAbortController.abort()
 형제 도구만 취소
 end note

동시성 결정 로직 (canExecuteTool, line 129)

실행 가능 조건:
 - 현재 실행 중인 도구가 없음 (executingTools.length === 0)
 - 또는: 이 도구가 concurrencySafe이고 실행 중인 모든 도구도 concurrencySafe

read-only 도구끼리는 병렬 실행이 가능하지만, write 도구가 하나라도 있으면 그 도구가 끝날 때까지 다음 도구는 대기한다.

siblingAbortController – 계층적 취소

siblingAbortController(line 46-61)는 toolUseContext.abortController의 자식이다. Bash 도구가 에러를 발생시키면 siblingAbortController.abort('sibling_error')를 호출하여 형제 도구만 취소한다. 부모 컨트롤러는 영향을 받지 않으므로 전체 쿼리는 계속 실행된다.

왜 Bash 에러만 형제를 취소하는가? mkdir -p dir && cd dir && make에서 mkdir이 실패하면 후속 명령은 무의미하다. ReadFile이나 WebFetch 실패는 독립적이므로 다른 도구에 영향을 주지 않아야 한다.

3. partitionToolCalls – 3계층 동시성 모델

toolOrchestration.ts(188줄)는 도구 실행의 동시성 모델 전체를 정의한다.

flowchart TD
 TC["도구 호출 배열<br/>[ReadFile, ReadFile, Bash, ReadFile]"]
 P["partitionToolCalls()<br/>toolOrchestration.ts:91"]
 B1["Batch 1<br/>ReadFile + ReadFile<br/>isConcurrencySafe=true"]
 B2["Batch 2<br/>Bash<br/>isConcurrencySafe=false"]
 B3["Batch 3<br/>ReadFile<br/>isConcurrencySafe=true"]
 PAR["Promise.all()<br/>최대 10개 동시"]
 SEQ["순차 실행"]
 PAR2["Promise.all()"]

 TC --> P
 P --> B1
 P --> B2
 P --> B3
 B1 --> PAR
 B2 --> SEQ
 B3 --> PAR2

 style B1 fill:#e8f5e9
 style B2 fill:#ffebee
 style B3 fill:#e8f5e9

규칙은 단순하다: 연속된 isConcurrencySafe 도구는 하나의 배치로 묶고, 그렇지 않은 도구는 각각 독립 배치가 된다. 이 결정은 도구 정의 자체에서 나온다 – tool.isConcurrencySafe(parsedInput) 호출로 결정된다. 같은 도구라도 입력에 따라 동시성 안전성이 달라질 수 있다.

컨텍스트 수정자와 경쟁 조건

왜 배치 완료 후 순서대로 적용하는가? 병렬 실행 중 컨텍스트 수정자를 즉시 적용하면 경쟁 조건이 발생한다. A가 먼저 완료되어 컨텍스트를 수정하면, 아직 실행 중인 B는 수정 전 컨텍스트로 시작했지만 수정 후 컨텍스트를 보게 된다. 배치 완료 후 원래 도구 순서대로 적용하면 결정론적 결과를 보장한다 (toolOrchestration.ts:54-62).

4. 도구 실행 파이프라인과 훅

toolExecution.ts(1,745줄)의 runToolUse()(line 337)가 개별 도구 호출의 전체 생명주기를 관리한다:

runToolUse() 진입점
 1. findToolByName() -- deprecated 별칭으로 재시도 (345-356)
 2. abort 체크 -- 이미 취소되었으면 CANCEL_MESSAGE (415)
 3. streamedCheckPermissionsAndCallTool() -- 권한 + 실행 + 훅 (455)
 -> checkPermissionsAndCallTool():
 a. Zod 스키마로 입력 유효성 검사 (615)
 b. tool.validateInput() 커스텀 검증 (683)
 c. 투기적 분류기 (Bash 전용, 740)
 d. runPreToolUseHooks() (800)
 e. resolveHookPermissionDecision() (921)
 f. tool.call() 실제 실행 (1207)
 g. runPostToolUseHooks() 결과 변환

resolveHookPermissionDecision의 핵심 불변식

resolveHookPermissionDecision()(toolHooks.ts:332)에서 훅의 allow가 settings.json의 deny/ask 규칙을 바이패스하지 않는다 (toolHooks.ts:373). 훅이 allow해도 checkRuleBasedPermissions()를 통과해야 한다. 이것은 “훅은 자동화 도우미이지 보안 우회가 아니다"라는 설계 원칙을 반영한다.

훅 결과가 allow일 때:
 -> checkRuleBasedPermissions() 호출
 -> null이면 통과 (규칙 없음)
 -> deny이면 규칙이 훅을 오버라이드
 -> ask이면 사용자 프롬프트 필요

5. Rust 대조 – 152줄 vs 1,729줄

Rust의 ConversationRuntime::run_turn()은 152줄의 단일 loop {} (conversation.rs:183-272)로 구성된다. TS의 7가지 continue 경로 중 Rust에 존재하는 것은 next_turn(도구 실행 완료 후 다음 턴) 딱 하나뿐이다.

TS continue 사유	Rust 상태	이유
`collapse_drain_retry`	미구현	컨텍스트 축소 없음
`reactive_compact_retry`	미구현	413 복구 없음
`max_output_tokens_escalate`	미구현	8k->64k 에스컬레이션 없음
`max_output_tokens_recovery`	미구현	멀티턴 넛지 없음
`stop_hook_blocking`	미구현	Stop 훅 없음
`token_budget_continuation`	미구현	토큰 예산 시스템 없음
`next_turn`	구현됨	도구 결과 후 API 재호출

가장 치명적인 갭: 동기적 API 소비

Rust의 ApiClient 트레이트 시그니처가 모든 것을 말해준다:

fn stream(&mut self, request: ApiRequest) -> Result<Vec<AssistantEvent>, RuntimeError>;

반환 타입이 Vec<AssistantEvent>다. 스트리밍이 아니다. SSE 이벤트를 모두 수집한 후 벡터로 반환한다. 이로 인해 모델이 5개 ReadFile을 호출할 때, TS는 첫 번째 ReadFile이 스트리밍 중에 실행 완료될 수 있지만, Rust는 5개 모두 스트리밍이 끝난 후에야 순차 실행을 시작한다. 레이턴시 차이가 도구 수에 비례하여 증가한다.

6. Rust 프로토타입 – 갭 브릿지

S04 프로토타입에서 P0 갭 3개를 브릿지하는 오케스트레이션 레이어를 구현했다:

flowchart LR
 subgraph TS["TS 스트리밍 파이프라인"]
 direction TB
 ts1["SSE 이벤트 스트림"]
 ts2["StreamingToolExecutor<br/>4-state machine"]
 ts3["getCompletedResults()<br/>yield 순서 보장"]
 ts1 --> ts2 --> ts3
 end

 subgraph Rust["Rust 프로토타입"]
 direction TB
 rs1["EventStream<br/>tokio async"]
 rs2["StreamingPipeline<br/>tokio::spawn + mpsc"]
 rs3["MessageEnd 후<br/>채널 수집 + 정렬"]
 rs1 --> rs2 --> rs3
 end

 subgraph Bridge["핵심 매핑"]
 direction TB
 b1["yield -> tx.send()"]
 b2["yield* -> 채널 전달"]
 b3["for await -> while let recv()"]
 end

 TS ~~~ Bridge ~~~ Rust

 style TS fill:#e1f5fe
 style Rust fill:#fff3e0
 style Bridge fill:#f3e5f5

프로토타입의 3가지 구현

1. 비동기 스트리밍: ApiClient 트레이트를 비동기 스트림으로 확장. MessageStream::next_event()가 이미 비동기이므로 소비 측만 변경하면 된다.

2. 도구 파이프라이닝: ToolUseEnd 이벤트 수신 시 누적된 입력으로 ToolCall을 조립하고 tokio::spawn으로 즉시 백그라운드 실행을 시작한다. mpsc::unbounded_channel로 완료 순서로 수집하고 나중에 원래 순서로 정렬한다.

3. 3-tier 동시성: ToolCategory enum(ReadOnly/Write/BashLike)에 따라 파티셔닝. ReadOnly 배치는 Semaphore(10) + tokio::spawn으로 최대 10개 병렬. BashLike는 순차 실행 + 에러 시 나머지 중단.

프로토타입 커버리지

TS 기능	프로토타입	상태
`partitionToolCalls()` 3-tier	`partition_into_runs()` + `ToolCategory`	구현
`runToolsConcurrently()` max 10	`Semaphore(10)` + `tokio::spawn`	구현
`siblingAbortController`	BashLike에서 `break`	단순화
`StreamingToolExecutor.addTool()`	`ToolUseEnd` 시 `tokio::spawn`	구현
PreToolUse hook deny/allow	`HookDecision::Allow/Deny`	구현
PostToolUse output transform	`HookResult::transformed_output`	구현
4-state machine (queued->yielded)	spawned/completed 2-state	미완성
413 복구 / max_output 에스컬레이션	–	미구현
`preventContinuation`	–	미구현

정지 조건 비교

조건	TS	Rust
도구 없음 (end_turn)	`handleStopHooks()` 실행 후 종료	즉시 `break`
토큰 예산 초과	`checkTokenBudget()` 3가지 결정	없음
max_output_tokens	에스컬레이션 + 멀티턴 복구	없음
413 prompt-too-long	컨텍스트 축소 + 반응형 압축	에러 전파
maxTurns	`maxTurns` 파라미터 (query.ts:1696)	`max_iterations`
수확 체감	3회 이상 + 500토큰 미만 증가	없음

tokenBudget.ts(93줄)의 checkTokenBudget()은 프롬프트 크기가 아닌 응답 연속 여부를 제어한다. COMPLETION_THRESHOLD = 0.9(전체 버짓의 90% 미만이면 계속), DIMINISHING_THRESHOLD = 500(연속 3회 이상 매번 500토큰 미만 생성 시 수확 체감으로 중단). nudgeMessage가 명시적으로 “do not summarize"를 지시한다.

설계 결정의 핵심 – 왜 AsyncGenerator인가

전체 파이프라인이 async function* 체인이다:

QueryEngine.submitMessage()* -> query()* -> queryLoop()* -> deps.callModel()*
runTools()* -> runToolUse()* -> handleStopHooks()* -> executeStopHooks()*

이 선택의 핵심 이점: 제어 흐름의 반전 없이 복잡한 상태 기계를 구현할 수 있다. 7가지 continue 경로에서 state = { ... }로 상태를 명시적으로 구성하고 continue하면 된다. 콜백 기반이었다면 상태 관리가 분산되어 7가지 복구 경로의 정합성을 보장하기 어려웠을 것이다.

Rust에서는 yield 키워드가 안정화되지 않았으므로, tokio::sync::mpsc 채널로 대체한다. yield -> tx.send(), yield* -> 채널 전달, for await...of -> while let Some(v) = rx.recv().

인사이트

query.ts의 7가지 continue는 “에러 처리"가 아니라 “탄력성 엔진"이다 – 413 에러에서 컨텍스트를 축소하고, max_output에서 토큰을 에스컬레이션하며, stop 훅 블로킹에서 에러를 모델에 피드백한다. 이 복구 파이프라인이 장시간 자율 작업의 안정성을 보장한다. Rust에서 이를 재현하려면 단순한 loop {} 이상의 상태 관리가 필요하다.
StreamingToolExecutor는 성능 최적화가 아니라 UX 결정이다 – 도구 5개를 직렬로 실행하면 사용자가 체감하는 대기 시간이 직렬 합산이 된다. 파이프라이닝은 벤치마크 수치가 아니라 “응답을 기다리는” 시간을 줄이는 사용자 경험 요소다. Rust 프로토타입에서 tokio::spawn + mpsc 채널로 이를 20줄 이내에 구현할 수 있었다.
정적 파티셔닝 + 런타임 동시성의 이중 구조가 안전성과 성능을 양립시킨다 – partitionToolCalls()가 컴파일 타임에 배치를 나누고, canExecuteTool()이 런타임에 실행 가능 여부를 판단한다. 이 이중 구조 덕분에 비스트리밍 경로(runTools)와 스트리밍 경로(StreamingToolExecutor)가 동일한 동시성 의미론을 공유한다.

다음 포스트: #3 – 42개 도구의 설계 철학, BashTool부터 AgentTool까지

Claude Code 하네스 해부학 #3 — 42개 도구의 설계 철학, BashTool부터 AgentTool까지

Mon, 06 Apr 2026 00:00:00 +0900

개요

Claude Code에는 42개의 도구가 존재한다. 이 포스트에서는 Tool.ts의 30+ 멤버 인터페이스가 구현하는 “도구가 자신을 알고 있다” 패턴을 해부하고, 42개 도구를 8개 패밀리로 분류한다. 그 중 가장 복잡한 BashTool(12,411줄)의 6계층 보안 체인, AgentTool(6,782줄)의 4가지 스폰 모드, FileEditTool의 문자열 매칭 전략, MCPTool의 빈 껍데기 프록시 패턴, Task 상태 머신을 심층 분석한다.

1. Tool 인터페이스 – “도구가 자신을 알고 있다”

Tool.ts(792줄)는 도구 시스템의 계약서다. 모든 도구가 구현하는 Tool 타입(Tool.ts:362-695)은 30개 이상의 멤버로 구성되며 네 영역으로 나뉜다:

영역	핵심 멤버	역할
실행 계약	`call()`, `inputSchema`, `validateInput()`, `checkPermissions()`	도구의 핵심 로직
메타데이터	`name`, `aliases`, `searchHint`, `shouldDefer`, `maxResultSizeChars`	검색과 표시
동시성/안전성	`isConcurrencySafe()`, `isReadOnly()`, `isDestructive()`, `interruptBehavior()`	오케스트레이션 결정
UI 렌더링	`renderToolUseMessage()` 등 10개+	터미널 표시

왜 이렇게 많은 멤버가 한 인터페이스에? 오케스트레이터(toolExecution.ts)가 도구를 호출할 때 외부 매핑 테이블 없이 도구 객체 자체에서 모든 메타데이터를 읽을 수 있다. 새 도구 추가가 한 디렉토리 안에서 완결되는 플러그인 아키텍처의 근간이다.

ToolUseContext – 42개 필드의 실행 환경

ToolUseContext(Tool.ts:158-300)는 도구 실행 시 주입되는 환경 컨텍스트다. 142줄에 걸쳐 42개 필드가 정의되어 있다:

abortController: 3-tier 동시성 모델의 취소 전파
getAppState()/setAppState(): 전역 상태 접근 (권한, todo, 팀)
readFileState: LRU 캐시 기반 변경 감지
contentReplacementState: 대용량 결과를 디스크에 저장하고 요약만 반환

도구는 격리된 함수가 아니라 하네스의 전체 상태에 접근해야 한다. FileReadTool은 캐시로 변경 여부를 판단하고, AgentTool은 서브에이전트 상태를 등록하며, BashTool은 형제 프로세스를 중단한다.

buildTool()의 fail-closed 기본값

buildTool()(Tool.ts:783)은 ToolDef를 받아 기본값을 채운 완전한 Tool을 반환한다. 기본값은 fail-closed 원칙(Tool.ts:757-768):

isConcurrencySafe -> false (안전하지 않다고 가정)
isReadOnly -> false (쓰기한다고 가정)

새 도구를 만들 때 동시성/읽기전용을 명시적으로 선언하지 않으면 가장 보수적인 경로(순차 실행, 쓰기 권한 요구)를 탄다. 실수로 안전하지 않은 도구를 병렬 실행하는 버그를 구조적으로 방지한다.

2. 42개 도구의 8개 패밀리

flowchart LR
 subgraph safe["isConcurrencySafe: true (10개)"]
 direction TB
 R1["FileReadTool"]
 R2["GlobTool / GrepTool"]
 R3["WebFetchTool / WebSearchTool"]
 R4["ToolSearchTool / SleepTool"]
 R5["TaskGetTool / TaskListTool"]
 R6["LSPTool"]
 end

 subgraph unsafe["isConcurrencySafe: false (32개)"]
 direction TB
 W1["BashTool 12,411줄"]
 W2["FileEditTool / FileWriteTool"]
 W3["AgentTool 6,782줄"]
 W4["MCPTool / SkillTool"]
 W5["Task 5개 / Todo"]
 W6["Config / PlanMode / Worktree"]
 end

 subgraph orch["오케스트레이터"]
 O["partitionToolCalls()<br/>toolOrchestration.ts"]
 end

 O -->|"병렬 배치"| safe
 O -->|"순차 실행"| unsafe

 style safe fill:#e8f5e9
 style unsafe fill:#ffebee

패밀리	도구 수	대표 도구	핵심 특징
파일시스템	5	FileReadTool (1,602줄)	PDF/이미지/노트북 지원, 토큰 제한
실행	3	BashTool (12,411줄)	6계층 보안, 명령 의미론
에이전트/팀	4	AgentTool (6,782줄)	4가지 스폰, 재귀적 하네스
태스크 관리	7	TaskUpdateTool (484줄)	상태 머신, 검증 넛지
MCP/LSP	5	MCPTool (1,086줄)	빈 껍데기 프록시
웹/외부	2	WebFetchTool (1,131줄)	병렬 안전
상태/설정	5	ConfigTool (809줄)	세션 상태 변경
인프라/유틸	11	SkillTool (1,477줄)	커맨드-도구 브리지

42개 중 10개(24%)만 병렬 실행 가능하지만, 이 10개가 가장 빈번하게 호출되는 도구(Read, Glob, Grep, Web)이므로 실제 체감 병렬성은 비율보다 높다.

3. BashTool – 6계층 보안 체인

BashTool은 단순한 셸 실행기가 아니다. 임의 코드 실행이라는 본질적 위험 때문에 12,411줄의 절반 이상이 보안 레이어다.

flowchart TB
 A["모델: Bash 호출"] --> B{"validateInput"}
 B -->|"sleep 패턴 차단"| B1["에러 반환"]
 B -->|"통과"| C{"6계층 보안 체인"}

 subgraph chain["보안 체인"]
 C1["1. bashSecurity.ts<br/>2,592줄 -- 명령 구조 분석"]
 C2["2. bashPermissions.ts<br/>2,621줄 -- 규칙 매칭"]
 C3["3. readOnlyValidation.ts<br/>1,990줄 -- 읽기전용 판단"]
 C4["4. pathValidation.ts<br/>1,303줄 -- 경로 기반 보안"]
 C5["5. sedValidation.ts<br/>684줄 -- sed 전용 보안"]
 C6["6. shouldUseSandbox.ts<br/>153줄 -- 샌드박스 결정"]
 C1 --> C2 --> C3 --> C4 --> C5 --> C6
 end

 C --> chain
 chain --> D{"allow / ask / deny"}
 D -->|"allow"| E["runShellCommand()"]
 D -->|"ask"| F["사용자 승인 요청"]
 D -->|"deny"| G["거부"]
 E --> H["결과 처리<br/>interpretCommandResult()<br/>trackGitOperations()"]

 style chain fill:#fff3e0

각 레이어가 다른 위협을 담당한다:

bashSecurity.ts (2,592줄): 명령 치환($(), `), Zsh 모듈 기반 공격 차단. 핵심: unquoted 컨텍스트의 메타문자만 위험으로 분류
bashPermissions.ts (2,621줄): 규칙 기반 allow/deny/ask. stripAllLeadingEnvVars() + stripSafeWrappers()로 래퍼 제거 후 실제 명령 추출
readOnlyValidation.ts (1,990줄): 읽기전용이면 isConcurrencySafe: true – 병렬 실행 허용
pathValidation.ts (1,303줄): 명령별 경로 추출 규칙으로 경로 안전성 판단
sedValidation.ts (684줄): sed의 w, e 플래그는 파일 쓰기/임의 실행 가능 – 별도 차단
shouldUseSandbox.ts (153줄): 최종 격리 결정

명령 의미론 (commandSemantics.ts): grep과 diff는 exit code 1이 에러가 아닌 정상 결과다. COMMAND_SEMANTICS Map으로 명령별 해석 규칙을 정의한다.

Rust 포팅 시사점: 이 6계층을 통째로 재현하거나, 아예 sandbox-only로 단순화해야 한다. 중간 단계 생략은 보안 구멍을 만든다.

4. AgentTool – 4가지 스폰 모드

AgentTool은 “도구"라기보다 에이전트 오케스트레이터다. 핵심: runAgent()는 하네스의 query() 루프를 재귀 호출한다. 자식 에이전트는 부모와 동일한 도구/API/보안 체크를 받는다.

모드	트리거	컨텍스트 공유	백그라운드
동기	기본	없음 (프롬프트만)	X
비동기	`run_in_background: true`	없음	O
포크	`subagent_type` 생략	부모 전체 컨텍스트	O
원격	`isolation: "remote"`	없음	O

포크 서브에이전트 – byte-identical 프리픽스

포크는 부모의 전체 대화 컨텍스트를 상속한다. 프롬프트 캐시 공유를 위해 모든 포크 자식이 byte-identical API 요청 프리픽스를 생성하도록 설계한다:

도구 사용 결과를 플레이스홀더로 대체
FORK_BOILERPLATE_TAG로 재귀 포크 방지
모델 동일 유지 (model: 'inherit') – 다른 모델은 캐시 불일치

메모리 시스템 (agentMemory.ts)

에이전트별 지속 메모리를 3가지 스코프로 관리:

user: ~/.claude/agent-memory/<type>/ – 사용자 전역
project: .claude/agent-memory/<type>/ – 프로젝트 공유 (VCS)
local: .claude/agent-memory-local/<type>/ – 로컬 전용

5. FileEditTool – 부분 대체 패턴

FileEditTool(1,812줄)은 전체 파일 쓰기가 아닌 old_string -> new_string 패치를 수행한다. 모델이 전체 파일을 출력할 필요가 없어 토큰을 절약하고, diff 기반 리뷰를 가능하게 한다.

매칭 전략:

정확한 문자열 매칭: fileContent.includes(searchString)
따옴표 정규화: curly quote -> straight quote 변환 후 재시도, preserveQuoteStyle()로 원본 스타일 보존
고유성 검증: old_string이 파일에서 유일하지 않으면 실패 (또는 replace_all)

동시성 보호: readFileState Map에 파일별 마지막 읽기 타임스탬프를 저장. 편집 시 디스크 수정 시간과 비교하여 외부 변경을 감지한다. 이것이 “Read 후 Edit” 규칙이 프롬프트에서 강제되는 이유다.

6. MCPTool – 빈 껍데기 프록시

MCPTool(1,086줄)은 하나의 도구 정의가 수백 개의 외부 도구를 대표한다. 빌드 시점에는 빈 껍데기이고, 런타임에 mcpClient.ts가 서버별로 복제 + 오버라이드한다:

// MCPTool.ts:27-51 -- 핵심 메서드가 "Overridden in mcpClient.ts" 주석
name: 'mcp', // 런타임에 'mcp__serverName__toolName'으로 교체
async call() { return { data: '' } }, // 런타임에 실제 MCP 호출로 교체

UI 축소 분류(classifyForCollapse.ts, 604줄)는 139개 SEARCH_TOOLS, 280개+ READ_TOOLS 이름으로 MCP 도구의 읽기/검색 여부를 판단한다. 알 수 없는 도구는 축소하지 않는다(보수적).

7. Task 상태 머신 – 에이전트 IPC

TaskUpdateTool(406줄)의 상태 흐름: pending -> in_progress -> completed 또는 deleted.

핵심 행동:

소유자 자동 설정: in_progress 변경 시 현재 에이전트 이름 자동 할당
검증 넛지: 3개+ 태스크 완료 후 검증 단계가 없으면 verification agent 스폰 권고
메시지 라우팅 (SendMessageTool 917줄): 이름, * 브로드캐스트, uds:path Unix 도메인 소켓, bridge:session 원격 피어, 에이전트 ID 재개

Task/SendMessage는 단순한 유틸리티가 아니라 멀티에이전트 시스템의 프로세스 간 통신(IPC) 기초다.

TS vs Rust 비교

측면	TS (42개 도구)	Rust (10개 도구)
도구 정의	`Tool` 인터페이스 + `buildTool()`	`ToolSpec` 구조체 + `mvp_tool_specs()`
입력 스키마	Zod v4 + `lazySchema()`	`serde_json::json!()` JSON Schema 직접
동시성 선언	`isConcurrencySafe(parsedInput)`	없음 – 순차 실행
권한 검사	`checkPermissions()` -> `PermissionResult`	`PermissionMode` enum
UI 렌더링	10+ render 메서드 (React/Ink)	없음
MCP 통합	MCPTool + `inputJSONSchema` 이중 경로	없음
크기 비교	~48,000줄 (도구 코드만)	~1,300줄 (lib.rs 단일)

핵심 격차: Rust 포트는 실행 계약(call 등가물)만 구현하고, 동시성 선언, 권한 파이프라인, UI 렌더링, 지연 로딩 최적화는 모두 없다.

인사이트

보안은 단일 체크포인트가 아니라 체인이다 – BashTool의 6계층은 각 레이어가 다른 위협을 담당한다. bashSecurity는 명령 구조, bashPermissions는 규칙 매칭, pathValidation은 경로 안전성. 이 체인의 어느 한 곳이라도 빠지면 공격 표면이 열린다. fail-closed 원칙과 결합하여 “모르면 차단"이라는 보수적 전략이 전체 시스템을 관통한다.
에이전트는 재귀적 하네스 인스턴스다 – AgentTool의 runAgent()가 하네스의 query() 루프를 재귀 호출한다는 것은, “에이전트"가 별개의 시스템이 아니라 **같은 하네스의 다른 구성(configuration)**이라는 아키텍처 결정이다. 도구 풀만 교체하고 동일한 보안/훅/오케스트레이션을 재사용한다.
42개 도구 중 10개만 concurrency-safe이지만 체감 병렬성은 높다 – 전체의 24%에 불과한 10개 도구(Read, Glob, Grep, Web, LSP)가 가장 빈번하게 호출된다. 이 비대칭이 3-tier 동시성 모델의 실용적 가치를 보여준다. buildTool()의 fail-closed 기본값(isConcurrencySafe: false)이 안전 경계를 형성하여, 새 도구 개발자가 동시성을 잘못 선언하는 실수를 구조적으로 방지한다.

다음 포스트: #4 – 런타임 훅 26+이벤트와 CLAUDE.md 6단계 디스커버리

Claude Code 하네스 해부학 #4 — 런타임 훅 26+이벤트와 CLAUDE.md 6단계 디스커버리

Mon, 06 Apr 2026 00:00:00 +0900

개요

Claude Code에서 “hook"이라는 단어는 두 가지 완전히 다른 시스템을 가리킨다. 런타임 훅(toolHooks.ts + utils/hooks.ts)은 도구 실행 전후에 셸 스크립트를 실행하는 보안/확장 파이프라인이고, React 훅(hooks/*.ts 85개+)은 터미널 UI의 상태 관리 코드다. 이 구분을 놓치면 Rust 재구현 범위를 85배 오판하게 된다. 이번 포스트에서는 런타임 훅의 PreToolUse/PostToolUse 파이프라인과 resolveHookPermissionDecision()의 보안 불변식, 85개 React 훅의 9개 카테고리 분류, 그리고 CLAUDE.md 6단계 디스커버리와 토큰 버짓 관리를 분석한다.

1. 런타임 훅 vs React 훅 – 핵심 구분

차원	런타임 훅 (toolHooks.ts + utils/hooks.ts)	React 훅 (hooks/*.ts)
실행 주체	`child_process.spawn()`	React 렌더 사이클
구성 방법	settings.json `hooks` 필드, 셸 커맨드	소스코드 `import`
실행 시점	도구 사용 전/후, 세션 시작 등 26+ 이벤트	컴포넌트 마운트/업데이트
사용자 정의	가능 – 사용자가 셸 스크립트 등록	불가능 – 내부 코드
결과 형태	JSON stdout (allow/deny/ask/rewrite)	React state 변경
Rust 재구현	필수 – 도구 실행 파이프라인의 핵심	불필요 – TUI 전용

2. PreToolUse 파이프라인 – 7가지 yield 변형

runPreToolUseHooks()(toolHooks.ts:435-650)는 AsyncGenerator로 설계되어 있다. 도구 실행 전에 호출되며 다음 yield 타입들을 방출한다:

message: 진행 상황 메시지 (훅 시작/에러/취소)
hookPermissionResult: allow/deny/ask 결정
hookUpdatedInput: 입력 재작성 (권한 결정 없이 입력만 변경)
preventContinuation: 실행 중단 플래그
stopReason: 중단 사유 문자열
additionalContext: 모델에 전달할 추가 컨텍스트
stop: 즉시 중단

왜 AsyncGenerator인가? 훅은 여러 개가 순차 실행되고, 각 훅의 결과가 다음 처리에 영향을 미친다. Promise 체이닝은 최종 결과만 반환하고, 이벤트 이미터는 타입 안전성이 없다. AsyncGenerator는 호출자가 각 결과를 소비하면서 중간에 중단할 수 있는 유일한 패턴이다.

flowchart TD
 subgraph "PreToolUse 파이프라인"
 A["toolExecution.ts<br/>도구 호출 시작"]
 B["runPreToolUseHooks()<br/>toolHooks.ts:435"]
 C["getMatchingHooks()<br/>utils/hooks.ts:1603"]
 D["settings.json hooks<br/>이벤트+패턴 매칭"]
 E["spawn() 셸 커맨드<br/>stdin: JSON, stdout: 결과"]
 F["HookResult 파싱<br/>allow / deny / ask / rewrite"]
 end

 subgraph "권한 해석"
 G["resolveHookPermission<br/>Decision()<br/>toolHooks.ts:332"]
 H{"훅 결과?"}
 I["allow: checkRule<br/>BasedPermissions()<br/>규칙이 훅을 오버라이드"]
 J["deny: 즉시 거부"]
 K["ask: canUseTool()<br/>사용자 프롬프트"]
 end

 subgraph "도구 실행"
 L["tool.call()"]
 end

 subgraph "PostToolUse"
 M["runPostToolUseHooks()<br/>결과 변환 / 차단"]
 end

 A --> B --> C --> D --> E --> F --> G --> H
 H -->|"allow"| I
 H -->|"deny"| J
 H -->|"ask"| K
 I -->|"규칙 통과"| L
 L --> M

resolveHookPermissionDecision – allow != bypass

resolveHookPermissionDecision()(toolHooks.ts:332-433)의 핵심 불변식: 훅의 allow가 settings.json의 deny/ask 규칙을 바이패스하지 않는다 (toolHooks.ts:325-327).

처리 로직 3단계:

1단계 – allow 처리 (toolHooks.ts:347-406):

hookResult.behavior === 'allow':
 -> checkRuleBasedPermissions() 호출
 -> null -> 규칙 없음, 훅 허용 통과
 -> deny -> 규칙이 훅을 오버라이드 (보안 우선!)
 -> ask -> 사용자 프롬프트 필요

왜 allow가 bypass하지 않는가? 이것은 의도적 보안 결정이다. 외부 셸 스크립트가 {"decision":"allow"}를 반환한다고 해서 settings.json의 deny 규칙을 무시하면, 악의적 훅이 보안 정책을 우회할 수 있다. 규칙은 항상 훅보다 우선한다.

2단계 – deny (toolHooks.ts:408-411): 즉시 거부, 추가 검사 없음.

3단계 – ask/없음 (toolHooks.ts:413-432): canUseTool() 호출로 사용자 프롬프트.

26개 이상의 이벤트 유형

getMatchingHooks()(utils/hooks.ts:1603-1682)이 훅 매칭을 담당한다:

도구 이벤트: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied
세션 이벤트: SessionStart, SessionEnd, Setup
에이전트 이벤트: SubagentStart, SubagentStop, TeammateIdle
작업 이벤트: TaskCreated, TaskCompleted
시스템 이벤트: Notification, ConfigChange, FileChanged, InstructionsLoaded
컴팩트 이벤트: PreCompact, PostCompact
입력 이벤트: UserPromptSubmit, Elicitation, ElicitationResult
중단 이벤트: Stop, StopFailure

매칭된 훅들은 순차 실행되며, 하나가 deny하면 이후 훅은 실행되지 않는다.

3. 85개 React 훅 – 9개 카테고리 분류

mindmap
 root(("TS 훅 시스템"))
 런타임 훅
 toolHooks.ts 651줄
 PreToolUse
 PostToolUse
 PostToolUseFailure
 utils/hooks.ts ~5000줄
 26+ 이벤트 유형
 셸 스폰
 비동기 프로토콜
 React 훅 85+
 권한 3개
 useCanUseTool
 PermissionContext
 UI 입력 11개
 useTextInput
 useVimInput
 useTypeahead
 UI 디스플레이 11개
 useVirtualScroll
 useDiffData
 상태/설정 12개
 useSettings
 useSessionBackgrounding
 통합/원격 12개
 useRemoteSession
 useReplBridge
 기능 20개
 useVoice
 useSwarm
 useTasks
 알림 16개
 notifs/ 디렉토리
 도구/키바인딩 5개
 useMergedTools
 추가 5+개
 fileSuggestions
 useManagePlugins

카테고리	개수	Rust 재구현	대표 훅
권한	3	부분 (브릿지)	`useCanUseTool` (203줄)
UI 입력	11	불필요	`useTextInput` (529줄), `useVimInput` (316줄)
UI 디스플레이	11	불필요	`useVirtualScroll` (721줄)
상태/설정	12	불필요	`useSessionBackgrounding` (158줄)
통합/원격	12	불필요	`useRemoteSession` (605줄)
기능/알림	20	불필요	`useVoice` (1,144줄)
알림/배너	16	불필요	`notifs/` 디렉토리
도구/키바인딩	5	불필요	`useMergedTools` (44줄)
추가	5+	불필요	`fileSuggestions` (811줄)

핵심: Rust가 재구현해야 하는 것은 toolHooks.ts(651줄) + utils/hooks.ts(~5,000줄)의 런타임 파이프라인뿐이다. 85개 React 훅 15,000줄+은 범위 밖이다.

4. CLAUDE.md 6단계 디스커버리

claudemd.ts(1,479줄)의 getMemoryFiles()(L790-1074)는 6단계 계층으로 CLAUDE.md를 로드한다:

단계	소스	경로 예시	우선순위
1. Managed	조직 정책	`/etc/claude-code/CLAUDE.md`	최저
2. User	개인 습관	`~/.claude/CLAUDE.md`, `~/.claude/rules/*.md`
3. Project	프로젝트 규칙	cwd에서 루트까지 `CLAUDE.md`, `.claude/rules/*.md`
4. Local	로컬 오버라이드	`CLAUDE.local.md` (gitignore)
5. AutoMem	자동 메모리	`MEMORY.md` 엔트리포인트
6. TeamMem	팀 메모리	조직 간 동기화	최고

왜 이 순서인가? 파일 주석(L9)이 명시한다: “Files are loaded in reverse order of priority.” LLM은 프롬프트 후반부에 더 주의를 기울이므로, 가장 구체적인 지시(Local > Project > User > Managed)가 마지막에 위치한다. 이것은 CSS specificity가 아니라 LLM 주의 편향을 활용한 설계다.

디렉토리 상향 탐색과 중복 방지

originalCwd에서 파일시스템 루트까지 올라간 뒤 dirs.reverse()로 루트부터 아래로 처리한다 (L851-857). 모노레포에서 상위 CLAUDE.md가 먼저 로드되고 하위 프로젝트의 CLAUDE.md가 그 위에 오는 효과를 만든다.

워크트리 중복 방지 (L868-884): git 워크트리가 메인 레포 내부에 중첩되면 동일 CLAUDE.md가 두 번 로드되는 것을 isNestedWorktree 검사로 방지한다.

@include 지시자 (L451-535): 마크다운 토큰을 렉싱하여 코드 블록 내부의 @path는 무시하고, 텍스트 노드의 @path만 재귀적으로 해석한다. 최대 깊이 5.

5. 시스템/사용자 컨텍스트 분리 – dual-memoize 캐시

context.ts(189줄)는 시스템 프롬프트를 두 개의 독립적인 컨텍스트로 분리한다:

getSystemContext() (L116): git 상태, 캐시 브레이커
getUserContext() (L155): CLAUDE.md 머지 문자열, 현재 날짜

왜 둘로 나누었는가? Anthropic API의 프롬프트 캐싱 전략 때문이다. git 상태(세션 고정)와 CLAUDE.md(파일 변경 시에만 무효화)의 캐시 수명이 다르므로, cache_control을 서로 다르게 적용해야 한다. 두 함수 모두 memoize로 감싸져 세션 내 한 번만 실행된다.

3가지 캐시 무효화 경로

setSystemPromptInjection() (context.ts:29): 양쪽 캐시 모두 클리어
clearMemoryFileCaches() (claudemd.ts:1119): 메모리 파일만 클리어
resetGetMemoryFilesCache() (claudemd.ts:1124): 메모리 파일 클리어 + InstructionsLoaded 훅 발화

이 분리는 워크트리 전환(리로드 불필요)과 실제 리로드(compaction 후)를 구분하기 위함이다.

6. 토큰 버짓 – 응답 연속 결정

tokenBudget.ts(93줄)의 checkTokenBudget()은 프롬프트 크기가 아닌 응답 연속 여부를 제어한다:

COMPLETION_THRESHOLD = 0.9 -- 90% 미만이면 계속
DIMINISHING_THRESHOLD = 500 -- 3회+ 연속, 매번 500토큰 미만 -> 수확 체감

if (!isDiminishing && turnTokens < budget * 0.9) -> continue
if (isDiminishing || continuationCount > 0) -> stop with event
else -> stop without event

왜 0.9인가? 모델이 버짓 근처에서 요약을 시작하는 경향이 있다. 90%에서 멈추면 “마무리 요약"을 하지 않고 작업을 계속하게 만든다. nudgeMessage가 명시적으로 “do not summarize"를 지시한다.

수확 체감 감지는 모델이 반복적 패턴에 빠지는 것을 방지한다. 서브에이전트는 즉시 stop (L51) – 자체 버짓을 갖지 않는다.

Rust 대조

관점	TS	Rust
훅 이벤트 유형	26개+	PreToolUse, PostToolUse 2개
훅 실행	비동기 AsyncGenerator	동기 `Command::output()`
훅 결과	7가지 yield 변형 + JSON	Allow/Deny/Warn 3가지 (exit code)
입력 수정	`hookUpdatedInput`	불가능
allow != bypass	보장됨	미구현 (보안 취약)
CLAUDE.md	6단계 디스커버리	4후보 per dir
@include	재귀적, 깊이 5	미지원
토큰 버짓	`checkTokenBudget()` 3가지 결정	없음
프롬프트 캐시	memoize + 3가지 무효화	매번 빌드

인사이트

“hook"의 이중 의미가 아키텍처의 가장 큰 혼동원이다 – 85개 React 훅은 Rust 재구현 범위에 포함되지 않는다. 런타임 훅(~5,600줄)만이 포팅 대상이다. 그러나 이 런타임 엔진은 26개 이벤트 유형, 비동기 프로토콜({"async":true} 백그라운드 전환), 프롬프트 요청(stdin/stdout 양방향)까지 포함하는 복잡한 시스템이다. “훅"이라는 단어의 범위를 정확히 파악하는 것이 범위 산정의 출발점이다.
CLAUDE.md의 “마지막이 더 강하다” 패턴은 LLM 주의 편향의 의도적 활용이다 – 6단계 계층 로딩(Managed -> User -> Project -> Local -> AutoMem -> TeamMem)에서 가장 구체적인 지시가 프롬프트 끝에 위치하여 가장 강한 영향력을 갖는다. 이것은 아키텍처적 깔끔함이 아니라 API 프롬프트 캐싱 적중률 최적화 + LLM 행동 특성의 교차점에서 나온 설계다.
resolveHookPermissionDecision()의 “allow != bypass” 불변식은 보안의 핵심이다 – 현재 Rust hooks.rs는 exit code만으로 allow/deny를 판단한다. JSON 결과 파싱과 checkRuleBasedPermissions 후속 검사를 구현하지 않으면, 악의적 훅이 deny 규칙을 우회할 수 있는 보안 취약점이 생긴다. 편의 자동화와 보안 정책의 경계를 명확히 하는 것이 훅 시스템의 근본 과제다.

다음 포스트: #5 – MCP 서비스와 플러그인 스킬 확장 생태계

Claude Code 하네스 해부학 #5 — MCP 서비스와 플러그인 스킬 확장 생태계

Mon, 06 Apr 2026 00:00:00 +0900

개요

Claude Code는 42개의 내장 도구 외에 MCP(Model Context Protocol)를 통해 외부 도구를 무제한으로 확장할 수 있다. 이 포스트에서는 client.ts(3,348줄)의 연결 관리 아키텍처, auth.ts(2,465줄)의 OAuth 인증 체계, 4계층 보안 모델, 설정 중복 제거를 분석한다. 이어서 플러그인과 스킬의 구조적 차이, 5계층 스킬 디스커버리 엔진, mcpSkillBuilders.ts의 순환 참조 해결 패턴까지 해부한다.

1. MCP 클라이언트 – 연결 관리가 프로토콜보다 어렵다

메모이제이션 기반 커넥션 풀

connectToServer는 lodash.memoize로 래핑되어 있다. 캐시 키는 name + JSON(config). MCP 서버는 stateful(stdio 프로세스, WebSocket 연결)이므로 매 도구 호출마다 새 연결을 만들면 성능이 치명적으로 나빠진다.

onclose 핸들러가 캐시를 무효화 -> 다음 호출이 자동으로 재연결
fetchToolsForClient, fetchResourcesForClient도 각각 LRU 캐시(20개)

도구 프록시 패턴

MCP 도구는 네이티브 Tool 인터페이스로 변환된다:

name: mcp__<normalized_server>__<normalized_tool> 형식
call(): ensureConnectedClient -> callMCPToolWithUrlElicitationRetry -> callMCPTool
checkPermissions(): 항상 passthrough – MCP 도구는 별도 권한 시스템
annotations: readOnlyHint, destructiveHint 등 MCP 어노테이션 매핑

URL Elicitation Retry: OAuth 기반 MCP 서버는 도구 호출 중간에 인증을 요구할 수 있다(에러 코드 -32042). retry 루프가 사용자에게 URL을 보여주고 인증 완료 후 재시도한다.

연결 상태 머신과 3-strike 터미널 에러

stateDiagram-v2
 [*] --> Pending: 설정 로드됨
 Pending --> Connected: connectToServer 성공
 Pending --> Failed: 연결 타임아웃
 Pending --> NeedsAuth: 401 UnauthorizedError
 Pending --> Disabled: isMcpServerDisabled()

 Connected --> Connected: 도구 호출 성공
 Connected --> Failed: 터미널 에러 3회 연속
 Connected --> NeedsAuth: 401 during callMCPTool
 Connected --> Pending: onclose 캐시 무효화

 NeedsAuth --> Pending: 인증 완료
 NeedsAuth --> NeedsAuth: 15분 TTL 캐시

 Failed --> Pending: reconnectMcpServer()
 Disabled --> Pending: toggleMcpServer()

 note right of Connected
 memoize 캐시에 존재
 fetchTools/Resources도 캐시
 end note

3-strike 규칙: 터미널 에러가 3회 연속 발생하면 Failed 상태로 강제 전환. 이는 죽은 서버에 계속 재시도하는 것을 방지한다.

15분 needs-auth 캐시: 401을 받은 서버를 매번 재시도하면 30개 이상의 커넥터가 동시에 네트워크 요청을 만든다. TTL 캐시로 불필요한 재시도를 방지한다.

2. OAuth – 2,465줄의 현실

auth.ts가 2,465줄인 이유는 현실의 OAuth 서버들이 RFC를 일관성 있게 구현하지 않기 때문이다:

구성 요소	설명
RFC 9728 + 8414 디스커버리	서버가 별도 호스트에서 AS 운영 가능 -> PRM으로 AS URL 탐색
PKCE	공개 클라이언트 – code_verifier/code_challenge 필수
XAA (Cross-App Access)	IdP의 id_token으로 MCP 서버 AS에서 access_token 교환
비표준 에러 정규화	Slack은 HTTP 200에 `{"error":"invalid_grant"}` 반환
Keychain 저장	macOS Keychain 연동 (`getSecureStorage()`)

Rust 포팅 시사점: OAuth는 SDK 의존이 아니라 복잡한 비동기 상태 머신이다. 디스커버리(2단계) -> PKCE -> 콜백 서버 -> 토큰 저장 -> 갱신 -> 폐기 -> XAA. 이 전체를 이식하는 것은 비현실적이므로, stdio MCP + API 키 인증으로 시작하는 것이 현실적이다.

3. 4계층 보안 모델

MCP 보안은 단일 게이트가 아니라 트러스트 레벨의 합성이다:

flowchart TD
 subgraph L1["1. Enterprise"]
 E1["managed-mcp.json<br/>존재하면 다른 모든 소스 차단"]
 E2["denylist / allowlist<br/>이름, 명령어, URL 패턴"]
 end

 subgraph L2["2. Project"]
 P1[".mcp.json 로드"]
 P2["pending -> 사용자 승인 -> approved"]
 end

 subgraph L3["3. Server"]
 S1["OAuth 서버별 독립 토큰"]
 S2["Keychain 저장"]
 end

 subgraph L4["4. Channel"]
 C1["GrowthBook allowlist<br/>tengu_harbor_ledger"]
 C2["구조화된 이벤트<br/>일반 텍스트 매칭 아님"]
 end

 L1 --> L2 --> L3 --> L4

 style L1 fill:#ffcdd2
 style L2 fill:#fff9c4
 style L3 fill:#c8e6c9
 style L4 fill:#e1f5fe

각 레이어가 독립적으로 동작하며, Enterprise가 최우선이다. .mcp.json이 프로젝트에 있어도 enterprise denylist에 걸리면 차단된다.

설정 소스와 중복 제거 (config.ts 1,578줄)

설정 소스 우선순위 (높은 것이 이긴다):

Enterprise managed (managed-mcp.json)
Local (사용자별 프로젝트 설정)
User (글로벌 ~/.claude.json)
Project (.mcp.json)
Plugin (동적)
claude.ai connectors (최저)

왜 중복 제거가 필요한가? 같은 MCP 서버가 .mcp.json과 claude.ai 커넥터 모두에 존재할 수 있다. getMcpServerSignature가 stdio:[command|args] 또는 url:<base> 시그니처를 만들어, CCR 프록시 URL도 원본 벤더 URL로 언래핑한 뒤 비교한다.

환경 변수 확장: ${VAR} 및 ${VAR:-default} 문법 지원. 누락 변수는 에러 대신 경고로 보고하여 부분적 연결 실패를 방지한다.

4. 플러그인 vs 스킬 – 구조적 차이

차원	스킬	플러그인
본질	프롬프트 확장 (SKILL.md = 텍스트)	시스템 확장 (스킬 + 훅 + MCP)
설치	파일 하나 배치	마켓플레이스 git 클론
런타임 코드	없음 (순수 텍스트)	있음 (MCP 서버, 훅 스크립트)
토글	암묵적 (파일 존재 여부)	명시적 (`/plugin` UI)
ID 체계	파일 경로	`{name}@builtin` 또는 `{name}@marketplace`

스킬은 “파일 = 확장"이라는 원칙의 구현이다. SKILL.md 하나가 설치/빌드 없이 즉시 확장으로 작동한다.

플러그인 서비스의 관심사 분리

파일	역할	부작용
`pluginOperations.ts`	순수 라이브러리 함수	없음
`pluginCliCommands.ts`	CLI 래퍼	`process.exit`, console 출력
`PluginInstallationManager.ts`	백그라운드 조정기	AppState 업데이트

pluginOperations의 순수 함수는 CLI와 대화형 UI 양쪽에서 재사용된다.

마켓플레이스 조정: diffMarketplaces()로 선언된 마켓플레이스와 실재 설치를 비교. 신규 설치면 자동 새로고침, 기존 업데이트면 needsRefresh 플래그만 설정. 신규는 “플러그인 못 찾음” 오류 방지가 필요하지만, 업데이트는 사용자가 적용 시점을 선택해야 한다.

5. 5계층 스킬 디스커버리 엔진

loadSkillsDir.ts(1,086줄)의 로딩 소스 우선순위:

flowchart TD
 subgraph Discovery["스킬 디스커버리"]
 A["1. policySettings<br/>managed-settings.json"]
 B["2. userSettings<br/>~/.claude/skills/"]
 C["3. projectSettings<br/>.claude/skills/<br/>프로젝트 루트~홈까지"]
 D["4. --add-dir<br/>추가 디렉토리"]
 E["5. 레거시<br/>/commands/ 디렉토리"]
 end

 subgraph Dedup["중복 제거"]
 F["realpath() 심링크 해소"]
 G["파일 ID 기반 first-wins"]
 end

 subgraph Parse["프론트매터 파싱"]
 H["description, when_to_use"]
 I["allowed-tools"]
 J["model, context, hooks"]
 K["paths, shell"]
 end

 A --> B --> C --> D --> E
 E --> F --> G
 G --> H & I & J & K

 style Discovery fill:#e1f5fe
 style Parse fill:#fff3e0

프론트매터 시스템

SKILL.md의 YAML 프론트매터에서 15개+ 필드를 추출한다:

description, when_to_use: 모델이 스킬 선택에 사용
allowed-tools: 스킬 실행 시 허용 도구 목록
model: 특정 모델 강제 지정
context: fork: 별도 컨텍스트에서 실행
hooks: 스킬 전용 훅 설정
paths: 경로 기반 활성화 필터
shell: 인라인 셸 명령 실행

번들 스킬의 지연 디스크 추출

CLI 바이너리에 컴파일되는 17개 번들 스킬(skills/bundled/)은 files 필드가 있으면 첫 호출 시 디스크에 추출한다:

O_NOFOLLOW | O_EXCL 플래그로 심링크 공격 차단
0o600 퍼미션으로 접근 제한
resolveSkillFilePath()가 .. 경로를 거부하여 디렉토리 탈출 방지

왜 디스크에 추출하는가? 모델이 Read/Grep 도구로 참조 파일을 읽을 수 있게 하기 위해서다. 메모리에만 두면 모델이 접근할 수 없다.

mcpSkillBuilders – 44줄짜리 순환 참조 해결

mcpSkillBuilders.ts(44줄)는 작지만 아키텍처적으로 중요하다.

문제: mcpSkills.ts가 loadSkillsDir.ts의 함수를 필요로 하지만, 직접 임포트하면 순환 참조가 발생한다 (client.ts -> mcpSkills.ts -> loadSkillsDir.ts -> ... -> client.ts).

해법: write-once 레지스트리. loadSkillsDir.ts가 모듈 초기화 시 함수를 등록하고, mcpSkills.ts가 필요할 때 가져간다. 동적 임포트는 Bun 번들러에서 실패하고, 리터럴 동적 임포트는 dependency-cruiser 순환 검사를 트리거하기 때문에 이 방식이 유일한 해결책이다.

의존성 그래프의 리프 모듈이 타입만 임포트하고, 런타임 등록은 시작 시 한 번만 수행한다.

Rust 대조

영역	TS (완성)	Rust (현재)
이름 정규화	`normalization.ts`	`mcp.rs` – 동일 로직
서버 시그니처	`getMcpServerSignature`	`mcp_server_signature` – CCR 프록시 언래핑 포함
stdio JSON-RPC	SDK 의존	`mcp_stdio.rs` – 직접 구현 (initialize, tools/list, tools/call)
OAuth	2,465줄 완전 구현	없음 – 타입만 정의
연결 관리	memoize + onclose 재연결	없음
스킬 로딩	5계층 + 프론트매터 15필드	2 디렉토리, SKILL.md만
번들 스킬	17개 내장	없음
플러그인	빌트인 + 마켓플레이스	없음
보안	4계층 (Enterprise->Channel)	없음

핵심 격차: Rust는 부트스트랩(설정 -> 트랜스포트)과 stdio JSON-RPC까지 구현했다. mcp_stdio.rs의 SDK 없는 JSON-RPC 구현은 의미 있는 진전이다. 그러나 OAuth, 연결 생명주기, 채널 보안, 스킬 디스커버리 전체가 부재한다.

인사이트

MCP는 “프로토콜"이 아니라 “통합 프레임워크"다 – 3,348줄의 client.ts가 말해주는 것은, 어려운 부분이 JSON-RPC가 아니라 연결 생명주기 관리라는 점이다. 메모이제이션, 자동 재연결, 세션 만료 감지, 401 retry, 3-strike 터미널 에러, needs-auth 캐시. 외부 프로세스(stdio)와 원격 서비스(HTTP/SSE)는 예측 불가능하게 죽고, OAuth 토큰은 만료되고, 네트워크는 끊긴다. “한번 연결하면 끝"이 아닌 현실을 반영하는 코드다.
스킬은 “파일 = 확장"이라는 원칙의 구현이다 – SKILL.md 하나가 설치/빌드 없이 즉시 확장으로 작동한다. 이 단순성이 프론트매터를 통한 점진적 복잡성 추가(모델 지정, 훅, 경로 필터)와 결합되어 초보자와 파워 유저를 모두 수용한다. 플러그인은 스킬의 상위 조직 단위로, “스킬 + 훅 + MCP 서버"를 묶는 패키지다.
mcpSkillBuilders.ts는 44줄짜리 아키텍처 교훈이다 – Bun 번들러의 동적 임포트 제약과 dependency-cruiser의 순환 검사를 동시에 만족시키는 유일한 해법이 “write-once 레지스트리"였다. 의존성 그래프의 리프 모듈이 타입만 임포트하고 런타임 등록은 시작 시 한 번만 수행하는 패턴은, 복잡한 모듈 시스템에서 순환 참조를 해결하는 범용적인 접근법으로 기억할 가치가 있다.

다음 포스트: #6 – Claude Code를 넘어서, 7크레이트 독자 하네스 구축 회고

Claude Code 하네스 해부학 #6 — Claude Code를 넘어서, 7크레이트 독자 하네스 구축 회고

Mon, 06 Apr 2026 00:00:00 +0900

개요

Claude Code의 TypeScript 소스를 27세션에 걸쳐 체계적으로 해부한 여정의 마지막 포스트다. Phase 1에서 10만줄+ TS 코드의 아키텍처를 이해하고, Phase 2에서 핵심 패턴을 Rust로 재구현한 뒤, Phase 3에서 발견한 8가지 한계점을 극복하는 독자 에이전트 하네스를 설계-구축했다. 이 포스트에서는 한계점 분석, 5가지 설계 원칙, 7크레이트 아키텍처, 61개 테스트, 그리고 전체 여정의 회고를 정리한다.

1. Claude Code 아키텍처의 8가지 한계점

27세션의 분석에서 발견한 강점과 한계를 구분했다. 강점(AsyncGenerator 파이프라인, 3-tier 동시성, 훅 확장성, CLAUDE.md 디스커버리, MCP 지원, 자기 완결적 도구 인터페이스, 7가지 에러 복구)은 설계의 우수한 면이다. 그러나 다음 8가지 한계가 독자 하네스의 동기가 되었다:

#	한계점	근거 세션	영향
1	React/Ink 의존 – 무거운 TUI	S08	headless 모드에서 불필요한 의존
2	단일 프로바이더 (실질 Anthropic 전용)	S01	OpenAI, 로컬 모델 사용 불가
3	main.tsx 4,683줄 모놀리스	S01	CLI/REPL/세션이 단일 파일에 혼재
4	동기적 도구 실행 (Rust 포트)	S03	스트리밍 파이프라이닝 불가
5	TS 생태계에 묶인 플러그인	S13	언어 중립적 확장 불가
6	85개 React 훅의 UI/런타임 혼재	S08	“hook” 용어의 이중 의미
7	프롬프트 캐싱의 암묵적 의존	S10	3가지 캐시 무효화 경로가 암묵적
8	MCP OAuth 2,465줄의 복잡성	S12	RFC 비일관성이 근본 원인

2. 5가지 설계 원칙

한계점을 극복하기 위해 5가지 핵심 원칙을 정립했다:

원칙 1 – 멀티 프로바이더: Anthropic, OpenAI, 로컬 모델(Ollama)을 단일 추상화로 지원.

#[async_trait]
pub trait Provider: Send + Sync {
 async fn stream(&self, request: ProviderRequest)
 -> Result<EventStream, ProviderError>;
 fn available_models(&self) -> &[ModelInfo];
 fn name(&self) -> &str;
}

ProviderRequest는 프로바이더 중립적 구조체로, 각 구현체가 자신의 API 형식으로 변환한다.

원칙 2 – 네이티브 비동기: tokio 기반 완전 비동기. yield -> tx.send(), yield* -> 채널 전달로 AsyncGenerator 패턴을 대체.

원칙 3 – 모듈 분리: 대화 엔진, 도구, 훅, 프롬프트를 각각 독립 크레이트로 분리. main.tsx 모놀리스를 반복하지 않는다.

원칙 4 – 언어 중립 확장: SKILL.md 호환 + MCP 서버를 플러그인 단위로 활용.

원칙 5 – MCP 통합 활용: 도구뿐 아니라 리소스, 프롬프트, 샘플링까지 전체 스펙 활용.

3. 7크레이트 아키텍처

graph TD
 CLI["harness-cli<br/>REPL 바이너리"] --> CORE["harness-core<br/>대화 엔진 + 턴 루프"]
 CORE --> PROV["harness-provider<br/>LLM 프로바이더 추상화"]
 CORE --> TOOLS["harness-tools<br/>도구 레지스트리 + 내장 도구"]
 CORE --> HOOKS["harness-hooks<br/>훅 파이프라인"]
 CORE --> PROMPT["harness-prompt<br/>CLAUDE.md 디스커버리"]
 CORE --> MCP["harness-mcp<br/>MCP 클라이언트"]
 MCP --> TOOLS

 style CLI fill:#b3e5fc
 style CORE fill:#fff9c4
 style PROV fill:#c8e6c9
 style TOOLS fill:#c8e6c9
 style HOOKS fill:#c8e6c9
 style PROMPT fill:#c8e6c9
 style MCP fill:#e1bee7

핵심 설계: harness-core만 다른 크레이트를 의존한다. 나머지는 서로 독립적이다(harness-mcp -> harness-tools 제외). 이 구조 덕분에:

각 크레이트를 독립적으로 cargo test 가능
프로바이더 추가 시 harness-core 수정 불필요
MCP 도구가 내장 도구와 동일한 Tool 트레이트 구현

크레이트	핵심 책임	테스트 수
`harness-provider`	LLM API 호출, SSE 파싱, 재시도	11
`harness-tools`	도구 레지스트리, 3-tier 동시성	12
`harness-hooks`	셸 훅 실행, deny short-circuit, rewrite 체인	9
`harness-prompt`	6단계 CLAUDE.md, SHA-256 중복 제거	9
`harness-core`	대화 엔진, `StreamingToolExecutor`	6
`harness-mcp`	JSON-RPC, stdio 트랜스포트	14
`harness-cli`	REPL 바이너리	–

Provider 트레이트 – 멀티 프로바이더

기존 Rust 포트의 ApiClient 트레이트는 Anthropic 전용이었다(ApiRequest에 Anthropic 필드). Provider 트레이트는 프로바이더 중립적 ProviderRequest를 받아 각 구현체가 자신의 API 형식으로 변환한다. Box<dyn Provider>로 런타임에 폴백 체인 구현 가능.

ConversationEngine – 턴 루프

pub struct ConversationEngine {
 session: Session,
 provider: Box<dyn Provider>,
 tool_executor: StreamingToolExecutor,
 hook_pipeline: HookPipeline,
 prompt_builder: PromptBuilder,
 budget: TokenBudget,
}

기존 Rust 포트의 ConversationRuntime<C, T> 제네릭 패턴 대신 트레이트 객체를 사용한다. 런타임에 프로바이더를 교체할 수 있어야 하고(모델 폴백), 제네릭은 컴파일 타임에 타입이 고정되므로 유연성이 부족하다.

스트리밍 도구 실행 (파이프라이닝)

기존 Rust 포트의 가장 큰 제약인 “모든 SSE 이벤트를 수집 후 도구 실행"을 해결했다:

EventStream에서 ContentBlockStop(ToolUse) 이벤트 도착 시 즉시 전달
is_concurrency_safe() 검사 후 tokio::spawn으로 병렬 처리
API가 아직 스트리밍 중인 동안 도구 실행 병행

4. Phase 2 회고 – 기존 포트 확장

Phase 3의 독자 하네스 이전에, Phase 2에서 기존 rust/ 프로토타입을 확장했다:

스프린트	성과	핵심 패턴
S14-S15	오케스트레이션 모듈 + 3-tier 동시성	`tokio::JoinSet` 기반 병렬 실행
S16-S17	도구 확장 (19 -> 26개)	Task, PlanMode, AskUser 추가
S18-S19	훅 실행 파이프라인	stdin JSON, deny short-circuit
S20-S21	스킬 디스커버리	`.claude/skills/` 스캔, 프롬프트 주입

Phase 2의 코드 대부분은 Phase 3에서 재작성되었다. 그러나 프로토타입 과정에서 발견한 질문들(“왜 AsyncGenerator인가?”, “왜 도구가 UI를 몰라야 하는가?")이 최종 설계를 결정했다.

5. 61개 테스트와 MockProvider 패턴

모든 크레이트가 독립적으로 테스트 가능하다. MockProvider를 통해 실제 API 호출 없이 대화 엔진의 전체 턴 루프를 검증한다:

harness-provider: 11 테스트 (SSE 파싱, 재시도, 스트림)
harness-tools: 12 테스트 (레지스트리, 동시성, 실행)
harness-hooks: 9 테스트 (deny 단락, rewrite 체인, 타임아웃)
harness-prompt: 9 테스트 (6단계 디스커버리, 해시 중복제거)
harness-core: 6 테스트 (턴 루프, 도구 호출, 최대 반복)
harness-mcp: 14 테스트 (JSON-RPC, 초기화, 도구 목록)

6. Phase 1-2 교훈이 설계에 반영된 방식

flowchart LR
 subgraph Phase1["Phase 1 -- 이해"]
 direction TB
 P1A["S02: AsyncGenerator 체인"]
 P1B["S05: 42개 도구 분류"]
 P1C["S08: 런타임 vs React 훅"]
 P1D["S10: 6단계 CLAUDE.md"]
 P1E["S12: MCP 연결 관리"]
 P1F["S13: 스킬 = 프롬프트"]
 end

 subgraph Phase3["Phase 3 -- 독자 하네스"]
 direction TB
 P3A["EventStream + mpsc 채널"]
 P3B["Tool 트레이트 + 3-tier"]
 P3C["HookPipeline (런타임만)"]
 P3D["PromptAssembler 분리"]
 P3E["harness-mcp stdio"]
 P3F["SKILL.md 호환"]
 end

 P1A -->|"yield -> tx.send()"| P3A
 P1B -->|"fail-closed 기본값"| P3B
 P1C -->|"범위 축소"| P3C
 P1D -->|"캐시 분할"| P3D
 P1E -->|"SDK 없이 구현"| P3E
 P1F -->|"텍스트 주입"| P3F

 style Phase1 fill:#e1f5fe
 style Phase3 fill:#fff3e0

교훈	출처	설계 반영
`StreamingToolExecutor` 4단계 상태 기계	S03	`harness-core`에 async 구현
`QueryDeps` 콜백 DI의 타입 안전성 한계	S03	트레이트 객체 DI
6층 Bash 보안 체인	S06	`check_permissions()` + 훅 분리
에이전트 = 하네스 재귀 인스턴스	S06	`ConversationEngine` 재사용
`ApiClient` 동기 트레이트가 파이프라이닝 차단	S03	`Provider` async 트레이트
Deny 단락 + Rewrite 체이닝	S09	`HookPipeline` 동일 패턴
SHA-256 콘텐츠 해시가 경로 해시보다 우수	S11	`harness-prompt` 콘텐츠 해시

7. 학습한 아키텍처 패턴 TOP 10

27세션에서 추출한 핵심 아키텍처 패턴:

AsyncGenerator/Stream 파이프라인: 스트리밍 LLM 응답의 핵심 추상화
3-tier 도구 동시성: ReadOnly/Write/Dangerous 분류로 안전성과 성능 균형
ToolSpec + ToolResult 이원화: 메타데이터(LLM 전달용)와 실행 결과 분리
훅 체인 실행: deny short-circuit, rewrite 체인, 독립 post-hook 변환
6단계 프롬프트 디스커버리: managed -> user -> project -> local 오버라이드
MCP 어댑터 패턴: 외부 프로토콜 도구를 내부 Tool 트레이트로 통일
Provider 추상화: 동일 인터페이스로 Anthropic/OpenAI 교체 가능
SSE 점진적 파싱: 네트워크 청크를 이벤트 프레임으로 조립
MockProvider 테스트: 사전 정의 이벤트 시퀀스로 엔진 동작 검증
스킬 = 프롬프트: 복잡한 플러그인 시스템 대신 텍스트 주입으로 충분

8. 전체 여정 회고

Phase	세션	핵심 산출물
Phase 1 – 이해	S00-S13	14개 분석 문서, Rust 프로토타입
Phase 2 – 재구현	S14-S21	오케스트레이션, 26 도구, 훅, 스킬
Phase 3 – 독자 하네스	S22-S27	7크레이트 워크스페이스, 61+ 테스트

Claude Code는 프롬프트 엔지니어링 런타임이다. 핵심 루프가 메시지를 조립하고, 도구 시스템이 세상과의 상호작용 능력을 부여하고, 권한 시스템이 경계를 설정한다. CLAUDE.md가 컨텍스트를 주입하고, MCP가 외부를 통합하며, 훅과 에이전트가 자동화/위임을 가능케 하고, 플러그인/스킬이 사용자 확장 플랫폼으로 전환한다.

향후 방향

진정한 스트리밍: SSE 바이트 스트림을 청크 단위로 처리
권한 시스템: 도구별 사용자 승인 워크플로우
MCP SSE 전송: stdio 외에 HTTP SSE 지원
토큰 예산 통합: 컨텍스트 윈도우 예산 자동 관리
멀티턴 에이전트 모드: 자율 반복 + 중단점 시스템

인사이트

좋은 추상화는 경계에서 나온다 – Provider 트레이트, Tool 트레이트, HookRunner 트레이트. 모든 핵심 추상화는 모듈 간 경계를 정의하는 트레이트다. 기존 Rust 포트의 ConversationRuntime<C, T> 제네릭은 컴파일 타임 보장이 강하지만, 런타임에 프로바이더를 교체하거나 MCP 도구를 동적 등록하는 시나리오에서 한계가 있었다. Box<dyn Provider> + Box<dyn Tool> 트레이트 객체가 약간의 vtable 비용으로 런타임 유연성을 확보한다. LLM API 지연시간(수백 ms~수 s) 대비 vtable 비용은 측정 불가능한 수준이다.
프로토타입의 가치는 코드가 아니라 질문이다 – Phase 1-2의 프로토타입 코드 대부분은 Phase 3에서 재작성되었다. 그러나 “왜 AsyncGenerator인가?”, “왜 도구가 UI를 몰라야 하는가?”, “왜 allow가 bypass하지 않는가?” 같은 질문들이 최종 설계를 결정했다. 10만줄 코드를 읽는 행위 자체가 답이 아니라, 읽으면서 발견하는 **설계 의도(왜)**가 진정한 산출물이다.
TS 코드의 복잡성은 대부분 방어선이다 – 권한 계층, 프론트매터 파싱, 중복 제거, symlink 방지. 이것들은 기능이 아니라 방어선이다. Rust는 타입 시스템과 소유권 모델로 일부를 컴파일타임에 보장할 수 있지만, 파일시스템 보안과 사용자 설정 우선순위 같은 런타임 정책은 명시적으로 구현해야 한다. 27세션은 이 방어선의 지도를 그리는 과정이었고, 그 지도가 독자 하네스의 설계를 안내했다.

시리즈 완결. 전체 분석 문서는 claw-code 리포지토리에서 확인할 수 있다.