Claude-Flow v2.5.0-alpha.130 - SDK 통합 단계

핵심 및 높은 우선순위 기능을 포함한 업데이트된 구현 계획

상태: 1-2단계 완료, 3-8단계 계획됨 마지막 업데이트일: 2025-09-30

🎯 단계 개요

예상 총 성능 향상: 스웜 작업 최대 100-600배 속도 향상

Phase 1: 기반 설정 ✅ 완료

상태

• ✅ 완료: 모든 작업 종료
• 기간: 1주
• 코드 감소량: 56% (429라인 제거)

완료한 작업

1. ✅ Claude Agent SDK 설치 (@anthropic-ai/sdk@0.65.0)
2. ✅ SDK 구성 어댑터 생성 (src/sdk/sdk-config.ts - 120라인)
3. ✅ 호환성 레이어 구축 (src/sdk/compatibility-layer.ts - 180라인)
4. ✅ SDK 래퍼 클래스 설정

결과

• 검증 테스트: 10/10 통과 (100%)
• 하위 호환성: 100%
• 회귀: 0건
• 빌드: v2.5.0-alpha.130으로 성공적으로 재빌드

Phase 2: 재시도 메커니즘 마이그레이션 ✅ 완료

상태

• ✅ 완료: 모든 작업 종료
• 기간: 1주
• 성능: 재시도 작업 30% 향상

완료한 작업

1. ✅ Claude client v2.5 리팩터링 (src/api/claude-client-v2.5.ts - 328라인)
2. ✅ 커스텀 재시도 로직 200라인 이상 제거
3. ✅ SDK 기반 작업 실행기 생성 (src/swarm/executor-sdk.ts - 200라인)
4. ✅ SDK 오류 처리 구현

결과

• 기존 클라이언트: 757라인
• 신규 클라이언트: 328라인 (56% 감소)
• 재시도 로직: SDK에 위임(자동 지수 백오프)
• 성능: 재시도 작업 30% 가속

Phase 3: 메모리 시스템 → 세션 영속성 ⏳ 진행 중

우선순위

🟡 HIGH - 상태 관리를 위해 필수

기간

1-2주

개요

커스텀 메모리 관리자를 SDKMessage[] 이력을 사용하는 SDK 세션 영속성으로 교체하고 resumeSessionAt으로 복구합니다.

작업

• [ ] 세션 기반 메모리 아키텍처 설계
• [ ] MemoryManagerSDK 클래스 구현
• [ ] 스웜 상태를 SDKMessage 형식으로 저장
• [ ] 체크포인트 복구에 resumeSessionAt 사용
• [ ] 기존 메모리 데이터 마이그레이션
• [ ] 마이그레이션 테스트 생성

구현

// src/swarm/memory-manager-sdk.ts
export class MemoryManagerSDK {
  private sessions: Map<string, SDKMessage[]> = new Map();

  async saveSwarmState(swarmId: string, state: SwarmState): Promise<void> {
    // 스웜 상태를 SDKMessage 형식으로 변환합니다
    const messages: SDKMessage[] = [
      {
        type: 'system',
        subtype: 'init',
        uuid: randomUUID(),
        session_id: swarmId,
        tools: state.activeTools,
        model: state.model,
        // ... 스웜 메타데이터
      },
      ...this.convertStateToMessages(state)
    ];

    // 세션 기록으로 저장합니다
    this.sessions.set(swarmId, messages);
  }

  async restoreSwarmState(
    swarmId: string,
    messageId?: string
  ): Promise<SwarmState> {
    // SDK의 resumeSessionAt을 사용해 시점 복구를 수행합니다
    const stream = query({
      prompt: 'Restore swarm state from session history',
      options: {
        resume: swarmId,
        resumeSessionAt: messageId  // 선택 사항: 특정 메시지
      }
    });

    // 복구된 세션에서 스웜 상태를 추출합니다
    return this.extractSwarmState(stream);
  }

  private convertStateToMessages(state: SwarmState): SDKMessage[] {
    // 에이전트, 작업, 결과를 SDKMessage 형식으로 변환합니다
    return state.agents.map(agent => ({
      type: 'assistant',
      uuid: randomUUID(),
      session_id: state.swarmId,
      message: {
        id: agent.id,
        role: 'assistant',
        content: JSON.stringify(agent.state)
      },
      parent_tool_use_id: null
    }));
  }
}

성공 기준

• ✅ 모든 스웜 상태를 SDKMessage[]로 저장
• ✅ 시점 복구 동작
• ✅ 이전 메모리 형식에서 마이그레이션 완료
• ✅ 마이그레이션 중 데이터 손실 없음
• ✅ 성능 향상이 측정됨

Phase 4: 세션 포크 & 실시간 제어 🔴 CRITICAL

우선순위

🔴 CRITICAL - 10-20x 성능 향상

기간

2-3주

개요

세션 포크로 병렬 에이전트 실행을 가능하게 하고 실시간 에이전트 제어 기능을 추가합니다.

기능

1️⃣ 세션 포크(에이전트 스폰 10-20배 가속)

// src/swarm/parallel-executor-sdk.ts
export class ParallelSwarmExecutor {
  async spawnParallelAgents(task: Task, count: number): Promise<Agent[]> {
    // 공유 컨텍스트로 기본 세션을 생성합니다
    const baseSession = await this.createBaseSession(task);

    // 병렬 실행을 위해 N개의 세션을 포크합니다
    const agents = await Promise.all(
      Array.from({ length: count }, async (_, index) => {
        const stream = query({
          prompt: this.getAgentPrompt(task, index),
          options: {
            resume: baseSession.id,
            forkSession: true,  // 핵심: 즉시 포크!
            mcpServers: {
              'claude-flow-swarm': claudeFlowSwarmServer
            }
          }
        });

        return this.monitorAgentStream(stream, index);
      })
    );

    return agents;
  }
}

성능: 에이전트 스폰 500-1000ms → 10-50ms (10-20배 가속)

2️⃣ Compact Boundary(자연스러운 체크포인트)

// src/verification/checkpoint-manager-sdk.ts
export class CheckpointManagerSDK {
  async monitorForCheckpoints(swarmId: string): Promise<void> {
    const stream = this.getSwarmStream(swarmId);

    for await (const message of stream) {
      if (message.type === 'system' && message.subtype === 'compact_boundary') {
        // SDK가 컨텍스트를 자동 압축하므로 체크포인트로 활용합니다!
        await this.createSwarmCheckpoint(swarmId, {
          trigger: message.compact_metadata.trigger,  // 'auto' | 'manual'
          tokensBeforeCompact: message.compact_metadata.pre_tokens,
          messageId: message.uuid,
          timestamp: Date.now()
        });
      }
    }
  }

  async restoreFromCompactBoundary(
    swarmId: string,
    checkpointId: string
  ): Promise<SwarmState> {
    // resumeSessionAt으로 압축 경계 지점에서 복구합니다
    const stream = query({
      prompt: 'Restore swarm state',
      options: {
        resume: swarmId,
        resumeSessionAt: checkpointId  // 압축 경계 메시지를 가리킵니다
      }
    });

    // 해당 시점으로 스웜 상태가 자동 복원됩니다!
    return this.extractSwarmState(stream);
  }
}

성능: 체크포인트 복구 = 즉시(SDK가 처리)

3️⃣ 실시간 쿼리 제어

// src/swarm/dynamic-agent-controller.ts
export class DynamicAgentController {
  private activeStreams: Map<string, Query> = new Map();

  async killRunawayAgent(agentId: string): Promise<void> {
    const stream = this.activeStreams.get(agentId);
    if (stream) {
      // 즉시 실행을 중단합니다
      await stream.interrupt();
      console.log(`⚠️  Agent ${agentId} interrupted`);
    }
  }

  async switchAgentModel(agentId: string, model: string): Promise<void> {
    const stream = this.activeStreams.get(agentId);
    if (stream) {
      // 실행 중에 모델을 전환합니다(재시작 없음!)
      await stream.setModel(model);
      console.log(`🔄 Agent ${agentId} now using ${model}`);
    }
  }

  async relaxPermissions(agentId: string): Promise<void> {
    const stream = this.activeStreams.get(agentId);
    if (stream) {
      // 자동 승인 모드로 전환합니다
      await stream.setPermissionMode('acceptEdits');
      console.log(`🔓 Agent ${agentId} permissions relaxed`);
    }
  }

  async tightenPermissions(agentId: string): Promise<void> {
    const stream = this.activeStreams.get(agentId);
    if (stream) {
      // 수동 승인 모드로 전환합니다
      await stream.setPermissionMode('default');
      console.log(`🔒 Agent ${agentId} permissions tightened`);
    }
  }
}

기능: 재시작 없이 실시간 제어

작업

• [ ] 병렬 에이전트를 위한 세션 포크 구현
• [ ] Compact Boundary 모니터링 추가
• [ ] 실시간 쿼리 제어 매니저 생성
• [ ] 병렬 vs 순차 실행을 벤치마크
• [ ] 에이전트 중단 시 내고장성 테스트
• [ ] 신규 API 문서화

성공 기준

• ✅ 에이전트 스폰 시간: <50ms (기존 500-1000ms)
• ✅ 체크포인트 복구: 즉시(수동 처리 대비)
• ✅ 실시간 제어: 응답 시간 <100ms
• ✅ 10-20배 성능 향상 검증
• ✅ 기존 기능 회귀 없음

Phase 5: 훅 매처 & 4단계 권한 🟡 HIGH

우선순위

🟡 HIGH - 2-3x 성능 향상

기간

2주

개요

커스텀 훅을 SDK 네이티브 훅으로 교체하고 패턴 매칭과 4단계 권한 계층을 도입합니다.

기능

1️⃣ 훅 매처(2-3배 가속)

// src/services/hook-manager-sdk.ts
const hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>> = {
  PreToolUse: [
    {
      matcher: 'Bash\\(.*\\)',  // 정규식: Bash 명령만 허용합니다
      hooks: [async (input, toolUseID, { signal }) => {
        // Bash에 대한 스웜 수준 거버넌스를 수행합니다
        const allowed = await this.validateBashCommand(
          input.tool_input.command
        );

        return {
          decision: allowed ? 'approve' : 'block',
          hookSpecificOutput: {
            hookEventName: 'PreToolUse',
            permissionDecision: allowed ? 'allow' : 'deny',
            permissionDecisionReason: allowed
              ? 'Command approved by swarm policy'
              : 'Dangerous command blocked'
          }
        };
      }]
    },
    {
      matcher: 'agent_spawn',  // 에이전트 스폰만 대상으로 합니다
      hooks: [async (input, toolUseID, { signal }) => {
        // 스웜 조정을 위해 에이전트 스폰을 추적합니다
        await this.recordAgentSpawn(input.tool_input);
        return { continue: true };
      }]
    },
    {
      matcher: 'FileWrite\\(.*\\.env.*\\)',  // .env 파일 쓰기를 차단합니다
      hooks: [async (input) => {
        return {
          decision: 'block',
          reason: 'Writing to .env files is not allowed'
        };
      }]
    }
  ],

  PostToolUse: [
    {
      matcher: 'memory_.*',  // 모든 메모리 작업을 대상으로 합니다
      hooks: [async (input, toolUseID, { signal }) => {
        // 스웜 전체에 메모리 작업을 복제합니다
        await this.replicateMemoryOperation(input);
        return { continue: true };
      }]
    },
    {
      matcher: '.*',  // 모든 작업(감사 로깅)
      hooks: [async (input) => {
        await this.logToolExecution(input);
        return { continue: true };
      }]
    }
  ],

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

성능: 불필요한 훅을 건너뛰어 실행 속도가 2-3배 빨라집니다

2️⃣ 4단계 권한 계층

// src/security/swarm-permission-manager.ts
export class SwarmPermissionManager {
  async configurePermissionHierarchy() {
    // 1단계: 사용자 수준(~/.claude/settings.json)
    // 가장 제한적인 규칙으로 모든 프로젝트에 적용됩니다
    await this.updatePermissions({
      type: 'addRules',
      rules: [
        { toolName: 'Bash', ruleContent: 'rm -rf *' },
        { toolName: 'Bash', ruleContent: 'sudo *' },
        { toolName: 'FileWrite', ruleContent: '/etc/*' }
      ],
      behavior: 'deny',
      destination: 'userSettings'
    });

    // 2단계: 프로젝트 수준(.claude/settings.json)
    // 프로젝트별 정책(git에 커밋)
    await this.updatePermissions({
      type: 'addRules',
      rules: [
        { toolName: 'FileWrite', ruleContent: './src/*' },
        { toolName: 'FileRead', ruleContent: './src/*' },
        { toolName: 'Bash', ruleContent: 'npm *' }
      ],
      behavior: 'allow',
      destination: 'projectSettings'
    });

    // 3단계: 로컬 수준(.claude-local.json)
    // 개발자 전용 재정의(gitignore 처리)
    await this.updatePermissions({
      type: 'addRules',
      rules: [
        { toolName: 'Bash', ruleContent: 'npm install *' },
        { toolName: 'FileWrite', ruleContent: './.env.local' }
      ],
      behavior: 'allow',
      destination: 'localSettings'
    });

    // 4단계: 세션 수준
    // 현재 세션에만 적용(스웜에 가장 관대한 설정)
    await this.updatePermissions({
      type: 'addRules',
      rules: [
        { toolName: 'agent_spawn' },
        { toolName: 'swarm_init' },
        { toolName: 'task_orchestrate' }
      ],
      behavior: 'allow',
      destination: 'session'
    });
  }

  async getEffectivePermission(toolName: string, input: any): Promise<PermissionBehavior> {
    // 계층을 순서대로 검사합니다: 사용자 → 프로젝트 → 로컬 → 세션
    // 첫 번째 'deny'가 우선하며, deny가 없으면 마지막 'allow'가 적용됩니다

    const userPerm = await this.checkLevel('userSettings', toolName, input);
    if (userPerm === 'deny') return 'deny';

    const projectPerm = await this.checkLevel('projectSettings', toolName, input);
    if (projectPerm === 'deny') return 'deny';

    const localPerm = await this.checkLevel('localSettings', toolName, input);
    if (localPerm === 'deny') return 'deny';

    const sessionPerm = await this.checkLevel('session', toolName, input);
    if (sessionPerm === 'allow') return 'allow';

    // 기본값은 'ask'입니다
    return 'ask';
  }
}

기능: 4단계에서 세밀한 거버넌스를 제공합니다

작업

• [ ] 모든 커스텀 훅을 SDK 네이티브 훅으로 교체
• [ ] 훅 매처 패턴 구현
• [ ] 4단계 권한 계층 구성
• [ ] 기존 훅 로직 마이그레이션
• [ ] 권한 감사 로그 추가
• [ ] 훅 패턴 라이브러리 생성

성공 기준

• ✅ 훅 실행 오버헤드: -50%
• ✅ 권한 검사: <0.1ms (기존 1-2ms)
• ✅ 2-3배 성능 향상 검증
• ✅ 무단 도구 실행 0건
• ✅ 모든 계층에서 감사 추적 완비

Phase 6: 인프로세스 MCP 서버 🔴 GAME CHANGER

우선순위

🔴 CRITICAL - 10-100x 성능 향상

기간

2-3주

개요

stdio 기반 MCP 전송을 인프로세스 SDK 서버로 교체해 IPC 오버헤드를 제거합니다.

구현

// src/mcp/claude-flow-swarm-server.ts
import { createSdkMcpServer, tool } from '@anthropic-ai/claude-code/sdk';
import { z } from 'zod';
import { SwarmCoordinator } from '../swarm/coordinator';
import { SwarmMemory } from '../swarm/memory';

export const claudeFlowSwarmServer = createSdkMcpServer({
  name: 'claude-flow-swarm',
  version: '2.5.0-alpha.130',
  tools: [
    // 스웜 초기화
    tool('swarm_init', 'Initialize multi-agent swarm', {
      topology: z.enum(['mesh', 'hierarchical', 'ring', 'star']),
      maxAgents: z.number().min(1).max(100),
      strategy: z.enum(['balanced', 'specialized', 'adaptive']).optional()
    }, async (args) => {
      // 직접 함수 호출 - IPC 오버헤드 없음!
      const swarm = await SwarmCoordinator.initialize(args);
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(swarm.status)
        }]
      };
    }),

    // 에이전트 스폰 - <0.1ms 지연
    tool('agent_spawn', 'Spawn specialized agent', {
      type: z.enum(['researcher', 'coder', 'analyst', 'optimizer', 'coordinator']),
      capabilities: z.array(z.string()).optional(),
      swarmId: z.string().optional()
    }, async (args) => {
      // stdio 대비 <0.1ms!
      const agent = await SwarmCoordinator.spawnAgent(args);
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(agent)
        }]
      };
    }),

    // 작업 오케스트레이션 - 인프로세스
    tool('task_orchestrate', 'Orchestrate task across swarm', {
      task: z.string(),
      strategy: z.enum(['parallel', 'sequential', 'adaptive']).optional(),
      priority: z.enum(['low', 'medium', 'high', 'critical']).optional()
    }, async (args) => {
      const result = await SwarmCoordinator.orchestrateTask(args);
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(result)
        }]
      };
    }),

    // 메모리 작업 - <1ms 지연
    tool('memory_store', 'Store data in swarm memory', {
      key: z.string(),
      value: z.any(),
      namespace: z.string().optional(),
      ttl: z.number().optional()
    }, async (args) => {
      await SwarmMemory.store(args.key, args.value, {
        namespace: args.namespace,
        ttl: args.ttl
      });
      return {
        content: [{ type: 'text', text: 'Stored successfully' }]
      };
    }),

    tool('memory_retrieve', 'Retrieve data from swarm memory', {
      key: z.string(),
      namespace: z.string().optional()
    }, async (args) => {
      const value = await SwarmMemory.retrieve(args.key, args.namespace);
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(value)
        }]
      };
    }),

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

// 스웜 코디네이터에서 사용하는 예
export class SwarmCoordinator {
  async initialize() {
    const response = await query({
      prompt: 'Initialize swarm with mesh topology and 5 agents',
      options: {
        mcpServers: {
          'claude-flow-swarm': {
            type: 'sdk',  // 인프로세스!
            name: 'claude-flow-swarm',
            instance: claudeFlowSwarmServer.instance
          }
        }
      }
    });

    // 응답을 파싱해 스웜을 구성합니다
    return this.parseSwarmInitResponse(response);
  }
}

MCP 상태 모니터링

// src/monitoring/mcp-health-monitor.ts
export class McpHealthMonitor {
  async monitorSwarmServers(swarmId: string): Promise<void> {
    const stream = this.activeStreams.get(swarmId);
    if (!stream) return;

    setInterval(async () => {
      const status = await stream.mcpServerStatus();

      for (const server of status) {
        if (server.status === 'failed') {
          console.error(`❌ MCP server ${server.name} failed`);
          await this.handleServerFailure(swarmId, server);
        } else if (server.status === 'needs-auth') {
          console.warn(`⚠️  MCP server ${server.name} needs auth`);
          await this.handleAuthRequired(swarmId, server);
        } else if (server.status === 'connected') {
          console.log(`✅ MCP server ${server.name} healthy`);
        }
      }
    }, 5000);  // 5초마다 확인합니다
  }

  private async handleServerFailure(
    swarmId: string,
    server: McpServerStatus
  ): Promise<void> {
    // 복구를 시도합니다
    console.log(`🔄 Attempting to restart ${server.name}...`);
    await this.restartMcpServer(server.name);

    // 스웜 코디네이터에 알립니다
    await SwarmCoordinator.notifyServerFailure(swarmId, server);
  }
}

작업

• [ ] 인프로세스 claude-flow-swarm MCP 서버 생성
• [ ] 40개 이상의 스웜 조정 도구 구현
• [ ] MCP 상태 모니터링 추가
• [ ] stdio 대비 인프로세스 성능 벤치마크
• [ ] stdio → SDK 전송 마이그레이션 가이드 작성
• [ ] 모든 통합 테스트 업데이트

성공 기준

• ✅ 도구 호출 지연: <0.1ms (기존 2-5ms)
• ✅ 메모리 작업: <1ms (기존 5-10ms)
• ✅ MCP 기반 에이전트 스폰: <10ms (기존 50-100ms)
• ✅ 10-100배 성능 향상 검증
• ✅ MCP 관련 실패 0건
• ✅ 사전 장애 감지(<5s)

Phase 7: 고급 기능 & 테스트 🟢 MEDIUM

우선순위

🟢 MEDIUM - 보안, 모니터링, 테스트

기간

2-3주

기능

1. 네트워크 샌드박싱 - 에이전트별 네트워크 격리
2. React DevTools - 실시간 스웜 시각화
3. 종합 테스트 - 회귀 및 성능 테스트

참고

• /ko-docs/SDK-ADVANCED-FEATURES-INTEGRATION.md 전체 구현 문서

작업

• [ ] 네트워크 정책 매니저 구현
• [ ] React DevTools 대시보드 생성
• [ ] 종합 테스트 스위트 구축(커버리지 98% 이상)
• [ ] 성능 벤치마크 스위트
• [ ] 보안 감사
• [ ] 부하 테스트

Phase 8: 마이그레이션 & 문서화 📚

기간

1주

산출물

• 마이그레이션 스크립트: scripts/migrate-to-v2.5.js
• 변경점 정리: BREAKING_CHANGES.md
• 마이그레이션 가이드: MIGRATION_GUIDE.md
• API 문서 업데이트
• 성능 벤치마크 보고서
• 비디오 튜토리얼

🎯 성공 지표 요약

📅 일정

총 기간: 약 13주(3개월) 목표 출시: 2026년 1분기

Claude-Flow v2.5.0-alpha.130의 핵심 및 높은 우선순위 기능이 반영된 단계 업데이트