Claude Code SDK: 에이전트 구축을 위한 개발자 가이드

Claude Code SDK는 Claude Code를 대화형 코딩 어시스턴트에서 완전히 프로그래밍 가능한 에이전트 런타임으로 확장합니다. 지금까지 Claude Code를 대화형으로 사용해왔다면, SDK는 자동화 파이프라인, 커스텀 UI, 멀티 에이전트 오케스트레이션, CI/CD 통합 등 근본적으로 다른 가능성을 열어줍니다.

Claude Code SDK란?

Claude Code SDK는 다음을 가능하게 해주는 프로그래밍 인터페이스입니다:

• 스크립트와 파이프라인에서 Claude Code를 비대화형으로 실행
• 컨텍스트에 포함될 파일, 디렉토리, 도구 제어
• 다운스트림 처리를 위한 구조화된 출력 파싱
• 자동화 워크플로에서 Claude Code를 다른 도구와 연결
• Claude Code의 추론 능력 위에 커스텀 UI 구축

Node.js 패키지로 제공:

npm install @anthropic-ai/claude-code

또는 CLI에서 비대화형 모드로 호출:

claude -p "여기에 프롬프트 입력" --output-format json

SDK 핵심 개념

비대화형 모드

가장 기본적인 SDK 사용 사례: 프롬프트와 함께 Claude Code를 실행하고, 출력을 받으면 끝.

# CLI 비대화형 모드
claude -p "src/auth.ts의 보안 취약점 검토" \
  --output-format json \
  --max-turns 5

// SDK
const { query } = require('@anthropic-ai/claude-code');

const result = await query({
  prompt: "src/auth.ts의 보안 취약점 검토",
  options: {
    maxTurns: 5,
    outputFormat: 'json'
  }
});

도구 설정

SDK 호출에서 Claude Code가 접근할 수 있는 도구를 제어합니다:

const result = await query({
  prompt: "src/utils.ts에 대한 테스트 스위트 생성",
  options: {
    allowedTools: ['Read', 'Write', 'Bash'],
    // 불필요한 도구 비활성화:
    // disallowedTools: ['WebSearch', 'mcp__custom_tool']
  }
});

커스텀 시스템 프롬프트

특화된 동작을 위해 기본 Claude Code 시스템 프롬프트를 재정의합니다:

const result = await query({
  prompt: "이 모듈을 리팩터링하세요",
  options: {
    systemPrompt: `당신은 함수형 프로그래밍 패턴을 전문으로 하는 TypeScript 전문가입니다.
    항상 불변 데이터 구조를 선호하세요. 오류 처리에는 Result 타입을 사용하세요.
    any 또는 unknown 타입은 절대 사용하지 마세요.`,
  }
});

실전 SDK 패턴

1. CI에서의 자동화된 코드 리뷰

// .github/workflows/code-review.js
const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

const diff = execSync('git diff main...HEAD').toString();

const review = await query({
  prompt: `이 PR diff를 검토하세요: 보안 문제, 성능 문제, 누락된 테스트.
  다음 키로 JSON 출력: security[], performance[], testing[].
  
  Diff:
  ${diff}`,
  options: {
    outputFormat: 'json',
    allowedTools: ['Read'],  // CI에서는 읽기 전용
    maxTurns: 3
  }
});

console.log(JSON.parse(review.result));

2. 자동화된 문서 생성

const fs = require('fs');
const { query } = require('@anthropic-ai/claude-code');

async function generateDocs(srcPath) {
  const result = await query({
    prompt: `${srcPath}의 모든 내보내기 함수에 대한 포괄적인 JSDoc 문서를 생성하세요.
    매개변수 설명, 반환 타입, 사용 예시를 추가하세요.
    문서가 추가된 업데이트된 파일을 작성하세요.`,
    options: {
      allowedTools: ['Read', 'Write'],
      cwd: process.cwd()
    }
  });
  return result;
}

3. 외부 기능을 활용한 멀티 에이전트 파이프라인

바로 이 지점에서 AnyCap 통합이 강력해집니다. Claude Code가 코드 추론을 담당하고, AnyCap이 미디어와 퍼블리싱을 처리하는 파이프라인입니다:

const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

async function buildAndPublishDocs(repoPath) {
  // 1단계: Claude Code가 문서 생성
  const docsResult = await query({
    prompt: "이 프로젝트의 포괄적인 README를 설정 안내, API 참조, 예시와 함께 생성하세요",
    options: {
      cwd: repoPath,
      allowedTools: ['Read', 'Write', 'Bash']
    }
  });

  // 2단계: AnyCap이 히어로 다이어그램 생성
  execSync(`anycap image generate \
    --prompt "개발자 도구의 기술 아키텍처 다이어그램, 깔끔하고 미니멀한 스타일" \
    --model nano-banana-2 \
    -o ${repoPath}/docs/architecture.png`);

  // 3단계: AnyCap이 웹 페이지로 배포
  const pageResult = execSync(`anycap page deploy ${repoPath}/docs/`).toString();
  
  return { docs: docsResult, page: JSON.parse(pageResult) };
}

SDK 인증

SDK는 Claude Code와 동일한 인증 방식을 사용합니다. API 키를 설정하세요:

export ANTHROPIC_API_KEY=your_key_here

팀 환경에서는 환경별 설정을 사용하세요:

const { query } = require('@anthropic-ai/claude-code');

// SDK가 ANTHROPIC_API_KEY를 자동으로 읽어옵니다
// 또는 명시적으로 전달:
process.env.ANTHROPIC_API_KEY = await getSecretFromVault('anthropic-api-key');

출력 형식

SDK는 세 가지 출력 형식을 지원합니다:

// JSON 출력에는 메타데이터가 포함됩니다
{
  "result": "이 함수에는 잠재적인 SQL 인젝션 취약점이 있습니다...",
  "is_error": false,
  "session_id": "sess_xxxx",
  "cost_usd": 0.0043,
  "num_turns": 2
}

SDK 워크플로에서의 요청 제한과 비용 관리

SDK 기반 자동화는 대화형 사용보다 토큰을 더 빠르게 소비할 수 있습니다. 내장 안전장치:

const result = await query({
  prompt: "...",
  options: {
    maxTurns: 5,        // 추론 반복 횟수 제한
    timeoutMs: 30000,   // 장시간 작업의 타임아웃
  }
});

// 프로덕션에서는 항상 비용을 확인하세요
if (result.cost_usd > 0.10) {
  logger.warn(`고비용 세션: $${result.cost_usd}`);
}

기능 집약적인 작업(이미지 생성, 동영상 제작, 웹 검색)은 Claude Code가 컨텍스트 내에서 처리하도록 두지 말고 AnyCap에 오프로드하세요. 이렇게 하면 SDK 비용을 예측 가능하게 유지하고, 비추론 작업에서 Claude의 요청 제한에 도달하는 것을 방지할 수 있습니다.

시작하기

# SDK 설치
npm install @anthropic-ai/claude-code

# 기능 확장을 위한 AnyCap 설치
curl -fsSL https://anycap.ai/install.sh | sh

# Claude Code에 AnyCap 스킬 추가
npx -y skills add anycap-ai/anycap -y

→ Claude Code용 AnyCap → Claude Code에 도구 추가 가이드