Claude Code SDK + AnyCap: 검색, 미디어, 퍼블리싱 워크플로

Claude Code SDK는 코드 중심 자동화에 강력합니다. 웹 검색, 미디어 생성, 퍼블리싱, 더 넓은 에이전트 워크플로에 AnyCap 에이전트 CLI를 언제 추가해야 하는지 알아보세요.

Claude Code SDK + AnyCap 히어로 이미지

최종 업데이트: 2026년 6월 4일

Claude Code SDK는 작업이 여전히 대부분 코드일 때 훌륭합니다. 예를 들어 CI 검사, 코드 리뷰, 구조화된 출력, MCP 인식 자동화가 그렇습니다. 하지만 워크플로에 검색, 미디어, 퍼블리싱 또는 기타 비코드 기능이 필요해지는 순간, Claude Code SDK만으로는 충분하지 않습니다.

이때 AnyCap이 필요합니다. AnyCap은 에이전트 CLI로, 코딩 에이전트를 코드 실행 너머로 확장합니다. 덕분에 같은 워크플로가 코드 추론에서 출발해 조사, 자산 생성, 결과 전달까지 이어질 수 있습니다.

한눈에 보기

코드 중심 자동화에는 Claude Code SDK를 사용
워크플로에 검색, 미디어, 퍼블리싱, 전달이 필요하면 AnyCap을 추가
Claude Code SDK는 코딩 런타임으로 간주
AnyCap은 코드 밖의 기능 계층으로 간주

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}의 모든 export 함수에 대해 포괄적인 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: "설치 방법, API 참조, 예제를 포함한 이 프로젝트의 포괄적인 README를 생성해줘",
    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는 세 가지 출력 형식을 지원합니다.

형식	사용 사례
`text`	기본, 사람이 읽기 쉬운 출력
`json`	프로그래밍 처리용 — 결과, 비용, 세션 정보 포함
`stream-json`	UI와 대시보드를 위한 실시간 출력

// 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에 도구 추가 가이드

Claude Code SDK + AnyCap: 코드만으로는 부족할 때