Claude Code SDK v2.0.1 - 종합 심층 분석

통합 지점 및 미공개 기능 전체 정리

분석 일자: 2025-09-30 SDK 버전: @anthropic-ai/claude-code@2.0.1 소스: /usr/local/share/nvm/versions/node/v20.19.0/lib/node_modules/@anthropic-ai/claude-code

📊 SDK 아키텍처 개요

파일 구조

@anthropic-ai/claude-code/
├── cli.js (9.36MB - minified executable)
├── sdk.mjs (511KB - main SDK module, 14,157 lines)
├── sdk.d.ts (417 lines - TypeScript definitions)
├── sdk-tools.d.ts (272 lines - Tool input schemas)
├── package.json (32 lines)
├── README.md
├── yoga.wasm (WASM layout engine)
└── vendor/
    ├── claude-code-jetbrains-plugin/
    └── ripgrep/

🎯 핵심 SDK Export (sdk.d.ts 기준)

주요 함수

// 주요 query 함수 - 스트리밍 메시지 생성기
export function query({
  prompt: string | AsyncIterable<SDKUserMessage>,
  options?: Options
}): Query;

// MCP 도구 생성
export function tool<Schema>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args, extra) => Promise<CallToolResult>
): SdkMcpToolDefinition<Schema>;

// 인프로세스 MCP 서버 생성
export function createSdkMcpServer(options: {
  name: string;
  version?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
}): McpSdkServerConfigWithInstance;

// 사용자 정의 오류 타입
export class AbortError extends Error {}

🔌 통합 지점

1️⃣ Hook 시스템 (이벤트 9개)

export const HOOK_EVENTS = [
  "PreToolUse",       // 모든 도구 실행 이전
  "PostToolUse",      // 도구 실행이 완료된 후
  "Notification",     // 시스템 알림
  "UserPromptSubmit", // 사용자 입력이 제출될 때
  "SessionStart",     // 세션 초기화
  "SessionEnd",       // 세션 종료
  "Stop",             // 사용자 중단
  "SubagentStop",     // 하위 에이전트 종료
  "PreCompact"        // 컨텍스트 압축 이전
] as const;

interface HookCallback {
  matcher?: string;  // 선택적 패턴 매칭
  hooks: HookCallback[];
}

type HookJSONOutput =
  | { async: true; asyncTimeout?: number }
  | {
      continue?: boolean;
      suppressOutput?: boolean;
      stopReason?: string;
      decision?: 'approve' | 'block';
      systemMessage?: string;
      reason?: string;
      hookSpecificOutput?: {
        hookEventName: 'PreToolUse';
        permissionDecision?: 'allow' | 'deny' | 'ask';
        permissionDecisionReason?: string;
      } | {
        hookEventName: 'UserPromptSubmit' | 'SessionStart' | 'PostToolUse';
        additionalContext?: string;
      }
    };

Claude-Flow 매핑:

• pre-task → PreToolUse
• post-task → PostToolUse
• session-start → SessionStart
• session-end → SessionEnd
• notify → Notification

2️⃣ 권한 시스템 (도구 거버넌스)

type PermissionBehavior = 'allow' | 'deny' | 'ask';

type PermissionMode =
  | 'default'           // 대화형 프롬프트
  | 'acceptEdits'       // 파일 수정을 자동 승인
  | 'bypassPermissions' // 모든 프롬프트 생략
  | 'plan';             // 계획 모드

interface CanUseTool {
  (toolName: string,
   input: Record<string, unknown>,
   options: {
     signal: AbortSignal;
     suggestions?: PermissionUpdate[];
   }): Promise<PermissionResult>;
[... omitted 393 of 649 lines ...]

          permissionDecisionReason: 'Swarm policy check'
        }
      };
    }]
  }],

  PostToolUse: [{
    hooks: [async (input, toolUseID, { signal }) => {
      // 도구 실행 결과를 swarm 메모리에 저장합니다
      await this.swarmMemory.recordToolExecution({
        tool: input.tool_name,
        input: input.tool_input,
        output: input.tool_response,
        timestamp: Date.now()
      });

      return { continue: true };
    }]
  }],

  SessionEnd: [{
    hooks: [async (input, toolUseID, { signal }) => {
      // 세션 종료 시 swarm 메트릭을 집계합니다
      await this.aggregateSwarmMetrics(input.session_id);
      return { continue: true };
    }]
  }]
};

6단계: 인프로세스 MCP 서버 (신규)

// 오버헤드 없는 swarm 조정
import { createSdkMcpServer, tool } from '@anthropic-ai/claude-code/sdk';

const claudeFlowSwarmServer = createSdkMcpServer({
  name: 'claude-flow-swarm',
  version: '2.5.0-alpha.130',
  tools: [
    tool('swarm_init', 'Initialize multi-agent swarm', {
      topology: { type: 'string', enum: ['mesh', 'hierarchical', 'ring', 'star'] },
      maxAgents: { type: 'number', minimum: 1, maximum: 100 }
    }, async (args) => {
      const swarm = await SwarmCoordinator.initialize(args);
      return {
        content: [{ type: 'text', text: JSON.stringify(swarm.status) }]
      };
    }),

    tool('agent_spawn', 'Spawn specialized agent in swarm', {
      type: { type: 'string', enum: ['researcher', 'coder', 'analyst', 'optimizer'] },
      capabilities: { type: 'array', items: { type: 'string' } }
    }, async (args) => {
      const agent = await SwarmCoordinator.spawnAgent(args);
      return {
        content: [{ type: 'text', text: JSON.stringify(agent) }]
      };
    }),

    // ... IPC 오버헤드가 전혀 없는 40개 이상의 도구
  ]
});

// Claude-Flow에서 사용
const response = query({
  prompt: 'Deploy a 5-agent swarm to analyze this codebase',
  options: {
    mcpServers: {
      'claude-flow-swarm': {
        type: 'sdk',
        name: 'claude-flow-swarm',
        instance: claudeFlowSwarmServer.instance
      }
    }
  }
});

📈 성능 벤치마크

✅ 실행 항목

1. 즉시: @anthropic-ai/claude-code를 의존성으로 설치합니다
2. 3단계: SDK 세션 영속성을 사용하도록 메모리 시스템을 리팩터링합니다
3. 4단계: 병렬 에이전트를 위해 세션 포크를 구현합니다
4. 5단계: 커스텀 hook을 SDK 기본 hook으로 교체합니다
5. 6단계: 인프로세스 MCP 서버 claude-flow-swarm을 생성합니다
6. 테스트: ./claude-flow로 포괄적인 통합 테스트를 수행합니다
7. 문서화: 모든 통합 가이드를 업데이트합니다

🎯 전략적 포지셔닝 (최종)

"Claude Agent SDK는 단일 에이전트 실행을 훌륭하게 처리합니다." "Claude-Flow는 오버헤드 없는 조정으로 심포니를 지휘합니다."

SDK가 제공하는 기능:

• ✅ 단일 에이전트 라이프사이클 (재시도, artifact, 세션)
• ✅ 도구 권한 거버넌스
• ✅ 확장을 위한 hook 시스템
• ✅ MCP 통합 기본 요소
• ✅ 세션 관리 및 포크

Claude-Flow가 추가하는 기능:

• 🚀 멀티 에이전트 swarm 오케스트레이션 (mesh, hierarchical, ring, star)
• ⚡ 인프로세스 MCP 서버 (stdio 대비 10-100배 빠름)
• 🤖 분산 합의 (Byzantine, Raft, Gossip)
• 🧠 에이전트 간 neural pattern 학습
• 📊 swarm 수준 성능 최적화
• 🔄 에이전트 간 메모리 조정
• 🎯 SPARC 방법론 통합

이 분석은 소스 코드 검토를 통해 발견된 Claude Code SDK v2.0.1 아키텍처, 통합 지점, 미공개 기능에 대한 완전한 이해를 제공합니다.