SDK 아키텍처

SDK 아키텍처 개요

Claude Code SDK는 일반적인 라이브러리 API와 다릅니다. claude CLI 프로세스를 서브프로세스로 스폰하고 stdin/stdout을 통해 구조화된 JSON 메시지를 주고받는 방식으로 동작합니다.

호스트 애플리케이션
      │
      │ stdin (JSON 메시지)
      ▼
claude 서브프로세스
      │
      │ stdout (JSON 스트림)
      ▼
호스트 애플리케이션

이 설계의 장점:

장점	설명
언어 독립성	어떤 언어에서도 JSON으로 통신 가능
격리성	서브프로세스 충돌이 호스트에 영향 없음
일관성	CLI와 동일한 동작 보장
업그레이드 용이	SDK 버전과 CLI 버전 독립적 관리

프로세스 스폰 방식

# 원샷 실행 (단일 프롬프트, --print 포함)
claude \
  --output-format stream-json \
  --print \
  --verbose \
  "파일을 분석해 주세요"

# 영속적 세션 (--print 생략, stdin으로 메시지 전송)
claude \
  --output-format stream-json \
  --verbose

옵션	설명
--output-format stream-json	구조화된 JSON 스트림 출력
--print	원샷 모드, 응답 후 종료
--verbose	도구 호출 등 상세 정보 포함
--system-prompt	커스텀 시스템 프롬프트 설정

메시지 스트림 출력 타입

스트림에서 출력되는 메시지의 타입:

타입	설명	예시
system	시스템 초기화 정보	버전, 세션 ID
assistant	Claude의 텍스트 응답	대화 내용
stream_event	스트리밍 토큰 단위 이벤트	실시간 출력
tool_progress	도구 실행 진행 상황	파일 편집 중…
result	최종 결과 요약	비용, 토큰 수

{"type":"system","session_id":"abc-123","version":"1.0.0"}
{"type":"assistant","message":{"role":"assistant","content":"분석을 시작합니다..."}}
{"type":"tool_progress","tool":"Read","status":"running","path":"src/index.ts"}
{"type":"result","subtype":"success","cost_usd":0.012,"duration_ms":3200}

영속적 멀티프롬프트 세션

--print 옵션을 생략하면 세션이 종료되지 않고 stdin으로 계속 메시지를 전송할 수 있습니다.

import { spawn } from 'child_process';

const claude = spawn('claude', ['--output-format', 'stream-json', '--verbose']);

// 메시지 전송
function sendMessage(content: string) {
  const message = JSON.stringify({
    type: 'user',
    message: { role: 'user', content }
  });
  claude.stdin.write(message + '\n');
}

// 첫 번째 메시지
sendMessage('프로젝트 구조를 설명해 주세요');

// 후속 메시지 (같은 컨텍스트 유지)
setTimeout(() => {
  sendMessage('가장 복잡한 파일은 어떤 것인가요?');
}, 5000);

npm 패키지

npm install @anthropic-ai/claude-code

TypeScript SDK는 @anthropic-ai/claude-code 패키지로 제공되며, 서브프로세스 관리를 추상화한 고수준 API를 제공합니다. agentSdkTypes 진입점에서 타입 정의를 임포트할 수 있습니다.

import { query, type SDKMessage } from '@anthropic-ai/claude-code';

현재 @alpha 마킹이 되어 있어 API가 변경될 수 있음을 유의하세요.