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 の差分をレビューしてください：セキュリティ上の問題、パフォーマンスの問題、テストの不足。
  JSON 形式で出力：security[]、performance[]、testing[] のキーを使用。
  
  差分：
  ${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 は 3 つの出力フォーマットをサポートします：

// 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

# AnyCap スキルを Claude Code に追加
npx -y skills add anycap-ai/anycap -y

→ Claude Code 向け AnyCap → Claude Code にツールを追加するガイド