코드를 공개하지 않고도
설계의 뼈대는 보인다

Claude Code 공개 분석서로 읽는 에이전트 제품의 구조

한 줄 요청이 들어오면 모델은 바로 답하지 않는다. 도구를 고르고, 권한을 확인하고, 안전하게 실행하고, 결과를 다시 모델에게 돌려준다. 이 반복 루프가 실행형 AI의 본체다.

1,884

TS+React 파일

~800KB

main.tsx 단일 시작 경로

45+

도구·스키마·권한 인터페이스

▼ SCROLL

실행형 AI는 답변기가 아니라 작은 운영체제에 가깝다

규모

1,884개 파일이 말하는 것

분석 대상은 TypeScript와 React 기반 파일 약 1,884개다.
Ink TUI, 상태 관리, 인증, 설정, 플러그인, MCP가 한 제품 안에서 맞물린다.
중요한 건 파일 수가 아니라 자연어 요청을 실제 작업으로 바꾸는 경계의 수다.

시작 성능

큰 main.tsx가 우연이 아니었다

main.tsx는 약 800KB로 크지만, 시작 성능을 위해 단일 경로를 택한 설계로 해석된다.
MDM subprocess read와 macOS Keychain prefetch를 무거운 import와 병렬화해 약 65ms를 줄였다는 분석이 나온다.
에이전트 CLI에서 첫 응답 전 지연은 기능보다 먼저 체감되는 품질이다.

핵심 루프

query.ts는 대화가 아니라 실행 엔진이다

약 68KB 규모의 query.ts는 스트리밍 응답을 비동기 제너레이터로 처리한다.
tool_use가 발생하면 도구 실행 결과를 다시 API 입력으로 넣고 루프를 반복한다.
사용자는 대화한다고 느끼지만 내부에서는 판단, 실행, 관찰, 재판단이 돈다.

도구 계약

45개 이상의 도구가 같은 문법을 쓴다

각 도구는 이름, 설명, 입력 스키마, 실행 함수, 렌더링, 결과 크기 제한 같은 공통 인터페이스를 가진다.
Zod 기반 입력 검증과 checkPermissions가 도구 호출 전에 경계를 만든다.
도구가 많아질수록 중요한 것은 기능 목록보다 호출 계약의 일관성이다.

안전과 속도

읽기는 병렬, 쓰기는 순차

Read, Grep, Glob 같은 안전 도구는 최대 10개까지 병렬 실행된다.
Edit, Bash, Write처럼 위험도가 있는 도구는 하나씩 순차 실행된다.
성능 최적화와 사고 방지는 반대말이 아니라 같은 스케줄러 안의 정책이다.

확장

MCP, 코디네이터, 브리지는 제품의 바깥을 연다

MCP 도구는 built-in 우선, 이름 중복 제거, prompt caching 안정성까지 고려된다.
Coordinator는 leader와 workers 구조로 작업을 나누고, Bridge는 local CLI와 cloud 사이를 잇는다.
확장성의 payoff는 더 많은 버튼이 아니라 더 안전한 위임이다.

겉으로 보이는 기능과 실제 설계의 차이

관점	표면	실제 설계
대화	질문하면 답한다	스트리밍 응답 중 tool_use를 감지하고 실행 결과를 다시 모델에 넣는다
성능	빠르게 켜진다	큰 main.tsx, 병렬 prefetch, bun 빌드와 tree-shaking으로 시작 지연을 줄인다
안전	위험하면 묻는다	도구별 권한 확인, 입력 검증, 병렬 가능 여부, read-only 여부를 계약으로 둔다
확장	플러그인을 붙인다	MCP, built-in 우선순위, 이름 중복 제거, 코디네이터와 브리지로 경계를 관리한다
복구	에러가 나면 재시도한다	413은 context collapse/reactive compact, 출력 한계는 8K에서 64K로 escalation/retry한다

공개 분석서에서 확인되는 장면들

🧭

자연어 요청이 도구 실행으로 바뀌는 순간

request → tool judgment → permission → execution → observation

⚡

시작 성능을 위해 무거운 import와 prefetch를 겹치는 장면

startup optimization

🧰

45+ 도구가 Zod 스키마와 권한 확인을 공유하는 장면

tool contract

🛡️

safe tools는 병렬, unsafe tools는 순차로 나뉘는 장면

safety scheduler

🌉

MCP·Coordinator·Bridge가 로컬과 외부 시스템을 잇는 장면

extension boundary

실행형 AI의 경쟁력은
모델보다 경계 설계에서 드러난다

이 분석은 소스 코드를 공개하지 않는다. 대신 구조를 본다. 편리한 에이전트일수록 권한, 로그, 복구, 병렬성, 확장 경계가 제품의 본체가 된다.

원문 분석서 보기

코드를 공개하지 않고도설계의 뼈대는 보인다

실행형 AI는 답변기가 아니라 작은 운영체제에 가깝다

겉으로 보이는 기능과 실제 설계의 차이

공개 분석서에서 확인되는 장면들

실행형 AI의 경쟁력은모델보다 경계 설계에서 드러난다

코드를 공개하지 않고도
설계의 뼈대는 보인다

실행형 AI의 경쟁력은
모델보다 경계 설계에서 드러난다

Claude Code 분석서에서 보인 실행형 AI의 진짜 설계

Reference Links

Comments (0)