Claude Code SDK活用ガイド｜Python/TypeScriptからAIエージェントをプログラムで制御する

Claude Code SDKを使うと、対話型のターミナル操作を超えて、PythonやTypeScriptのプログラムからAIエージェントを直接呼び出せます。 ヘッドレスモードと組み合わせることで、CI/CDパイプライン、定期バッチ処理、カスタムWebアプリケーションなど、あらゆる自動化シナリオにClaude Codeを組み込めます。

この記事でわかること

Claude Code SDKやヘッドレスモードを使ってAIワークフローを構築したいエンジニアに向けた記事です。

• Claude Code SDKの全体像と基本的な使い方 — TypeScript・Pythonそれぞれのセットアップ方法を解説します
• 対話なしで実行するヘッドレスモードの活用法 — スクリプトから自動的にClaude Codeを呼び出す方法を紹介します
• 自動化パイプラインへの組み込みパターン — プルリクエスト時の自動コードレビューなど、実務での活用例を解説します

Claude Code SDKとは

Claude Code SDKは、Claude Codeの機能をプログラムから呼び出すためのインターフェースです。通常のClaude Codeはターミナルで対話的に操作しますが、SDKを使えばPythonやTypeScriptのコードから直接AIエージェントを起動し、結果を受け取れます。

SDKの種類と特徴

SDKはAnthropicが公式に提供しており、Claude Codeと同じ認証情報・設定ファイルを利用します。既存のClaude Code環境があれば、追加の認証設定なしでSDKを使い始められます。

TypeScript SDKの基本的な使い方

TypeScript SDKは、Node.jsプロジェクトに最も自然に統合できる方法です。

インストールと初期設定

npm install @anthropic-ai/claude-code

基本的な呼び出し

import { claude } from "@anthropic-ai/claude-code";

const response = await claude({
  prompt: "src/ディレクトリのTypeScriptファイルを分析して、型定義の改善点を報告してください",
  options: {
    maxTurns: 10,
  },
});

console.log(response.stdout);

claude() 関数は非同期で実行され、Claude Codeのセッションを1つ起動します。promptに指示を渡すと、Claude Codeがファイルシステムの読み書き、コマンド実行などのツールを使いながらタスクを遂行し、結果を返します。

ストリーミング実行

処理の進捗をリアルタイムで受け取りたい場合は、ストリーミングモードを使います。

import { claude, ClaudeEvent } from "@anthropic-ai/claude-code";

for await (const event of claude({
  prompt: "package.jsonの依存関係を分析して、セキュリティリスクのあるパッケージを特定してください",
  options: {
    maxTurns: 15,
  },
})) {
  if (event.type === "text") {
    process.stdout.write(event.content);
  }
}

ストリーミングモードでは、Claude Codeが思考・ツール実行・テキスト出力を行うたびにイベントが発生します。UIにリアルタイムで進捗を表示したい場合に有効です。

セッション管理

同じコンテキストで複数の指示を送りたい場合は、セッションIDを引き継ぎます。

// 最初の呼び出し
const first = await claude({
  prompt: "プロジェクト構成を分析してください",
  options: { maxTurns: 5 },
});

// 同じセッションで追加の指示
const second = await claude({
  prompt: "先ほどの分析を踏まえて、リファクタリング計画を作成してください",
  options: {
    maxTurns: 10,
    sessionId: first.sessionId,
  },
});

セッションを引き継ぐことで、前回の会話コンテキストが保持されます。複数ステップのワークフローを構築する際に重要な機能です。

Python SDKの基本的な使い方

Python SDKは、データ分析やMLパイプラインとの統合に適しています。

インストール

pip install claude-code-sdk

基本的な呼び出し

import asyncio
from claude_code_sdk import claude, ClaudeOptions

async def main():
    result = await claude(
        prompt="data/ディレクトリのCSVファイルを分析して、異常値を検出してください",
        options=ClaudeOptions(max_turns=10),
    )
    print(result.stdout)

asyncio.run(main())

Python SDKは非同期（asyncio）ベースで動作します。既存の非同期アプリケーションにも自然に統合できます。

ストリーミング実行（Python）

import asyncio
from claude_code_sdk import claude, ClaudeOptions

async def main():
    async for event in claude(
        prompt="テストカバレッジを分析してください",
        options=ClaudeOptions(max_turns=10),
    ):
        if event.type == "text":
            print(event.content, end="", flush=True)

asyncio.run(main())

ヘッドレスモード（CLIの--printフラグ）

--printフラグ）" style="width:100%;max-width:1200px;height:auto;margin:24px 0;border-radius:12px;box-shadow:0 4px 16px rgba(0,0,0,0.08);"/>

SDKを使わずに、CLIから直接非対話型で実行する方法もあります。--print（短縮形: -p）フラグを付けると、Claude Codeはユーザーの入力を待たずにタスクを実行し、結果を標準出力に返します。

基本的な使い方

# 単発実行

**claude -p "このリポジトリのREADME.mdを要約してください"**
claude -p "このリポジトリのREADME.mdを要約してください"

# パイプラインでの利用
cat error.log | claude -p "このエラーログを分析して、根本原因を特定してください"

# JSON出力
claude -p "src/の構成を分析してください" --output-format json

シェルスクリプトからの呼び出し

#!/bin/bash
# 毎朝のコードレビュー自動化
RESULT=$(claude -p "昨日のコミット（git log --since=yesterday）をレビューして、問題点があれば報告してください" --max-turns 15)
echo "$RESULT" > /tmp/daily-review.md

--printモードは、SDKを導入するほどではない軽量な自動化に最適です。シェルスクリプト、cron、GitHub Actionsなど、シェルコマンドを実行できる環境ならどこでも使えます。

実務での活用パターン

パターン1: CI/CDパイプラインでのコードレビュー自動化

プルリクエストが作成されるたびに、Claude Codeが自動でコードレビューを実行するパイプラインを構築できます。

# GitHub Actions例
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: AI Review
        run: |
          claude -p "このプルリクエストの変更をレビューしてください。
          セキュリティリスク、パフォーマンス問題、型安全性の観点で確認してください。" \
          --print --max-turns 20

Anthropicの公開事例によると、GitHubのようなプラットフォーム企業では、CI/CDにAIコードレビューを組み込むことで、レビューサイクルを大幅に短縮しています。

パターン2: 定期バッチ処理によるドキュメント自動更新

コードベースの変更に合わせて、ドキュメントを自動更新するバッチ処理を構築できます。

import { claude } from "@anthropic-ai/claude-code";

async function updateDocs() {
  // Step 1: 変更検出
  const changes = await claude({
    prompt: "git diff HEAD~5 で変更されたAPIエンドポイントを一覧化してください",
    options: { maxTurns: 5 },
  });

  // Step 2: ドキュメント更新
  await claude({
    prompt: `以下の変更に基づいて、docs/api-reference.mdを更新してください:\n${changes.stdout}`,
    options: {
      maxTurns: 15,
      sessionId: changes.sessionId,
    },
  });
}

パターン3: カスタムWebアプリケーションへの統合

社内ツールにAIアシスタント機能を組み込む場合、TypeScript SDKをバックエンドから呼び出します。

import express from "express";
import { claude } from "@anthropic-ai/claude-code";

const app = express();

app.post("/api/analyze", async (req, res) => {
  const { query, projectPath } = req.body;

  const result = await claude({
    prompt: query,
    options: {
      maxTurns: 10,
      cwd: projectPath,
    },
  });

  res.json({ result: result.stdout });
});

この方法なら、非エンジニアのチームメンバーもWebブラウザからAIエージェントの機能を利用できます。

主要オプションリファレンス

SDK・CLIで使える主要なオプションを整理します。

関連コマンドとの組み合わせ

SDKは他のClaude Code機能と組み合わせることで、さらに強力になります。

カスタムコマンドとの連携

プロジェクトに定義したカスタムコマンドは、SDK経由でも利用できます。

const result = await claude({
  prompt: "/review src/components/",
  options: { maxTurns: 15 },
});

MCPサーバーとの統合

MCP（Model Context Protocol）で接続した外部ツールも、SDK経由のセッションで利用可能です。HubSpot、Slack、データベースなどの外部サービスと連携したAI自動化パイプラインを構築できます。こうしたAI活用に関心のある方は、経営データの可視化やコンテンツマーケティングの効率化の詳細もあわせてご覧ください。

Hooksによる前後処理

Hooksを設定しておけば、SDK経由の実行でもツール呼び出し前後にカスタムスクリプトを挟めます。セキュリティチェックやログ記録の自動化に有効です。

セキュリティとベストプラクティス

SDKをプロダクション環境で使う際の注意点を整理します。

認証情報の管理

SDKはClaude Codeと同じ認証情報を使います。CI/CD環境では、環境変数 ANTHROPIC_API_KEY を設定してください。APIキーはシークレットストア（GitHub Secrets、AWS Secrets Managerなど）で管理し、コードにハードコードしないことが鉄則です。

ツール制限の活用

allowedToolsオプションで、エージェントが使えるツールを制限できます。自動化パイプラインでは、必要最小限のツールのみ許可することで、意図しないファイル変更やコマンド実行を防止できます。

const result = await claude({
  prompt: "コードを分析してください",
  options: {
    maxTurns: 10,
    allowedTools: ["Read", "Glob", "Grep"],  // 読み取り専用
  },
});

タイムアウトとコスト管理

maxTurnsを適切に設定し、無限ループを防止してください。バッチ処理では、1タスクあたりのターン数上限を設けることで、APIコストの暴走を防げます。

あわせて読みたい

• Claude Codeカスタムコマンド完全ガイド｜スラッシュコマンドで反復タスクを1コマンドに集約する実践パターン
• Claude Code Dispatch入門｜スマホからデスクトップのAI開発環境を遠隔操作する方法
• Claude Codeの見た目カスタマイズ｜テーマ・カラー・ステータスラインの設定方法

まとめ

Claude Code SDKは、AIエージェントを「対話ツール」から「プログラマブルなインフラ」に昇格させる技術です。TypeScript SDKはWebアプリケーションやCI/CDとの統合に、Python SDKはデータ分析やMLパイプラインに、CLIの--printモードはシェルスクリプトによる軽量自動化に、それぞれ最適です

実践にあたっては、以下のポイントを押さえておくことが大切です。

• まずは--printモードで小さな自動化から始め、ユースケースが広がったらSDKへの移行を検討するのが実務的なアプローチです
• *Claude Codeの全コマンド一覧はClaude Codeチートシートをご覧ください
• AI活用の全体像はAI活用完全ガイドで解説しています

よくある質問（FAQ）

Q1. Claude Code SDKを使うにはAPI keyが必要ですか？

はい、必要です。ローカル環境では通常のClaude Codeの認証情報（claude loginで設定済みのもの）がそのまま使えます。CI/CDなどのサーバー環境では、環境変数 ANTHROPIC_API_KEY にAnthropicのAPIキーを設定してください。Maxプランのユーザーは、ローカル環境であればAPIキーなしでSDKを利用できます。

Q2. SDKとCLIの--printモードはどちらを使うべきですか？

自動化の規模と複雑さで判断してください。シェルスクリプトで完結する単純なタスクなら--printモードで十分です。複数ステップのワークフロー、セッション管理、ストリーミング出力が必要な場合はSDKを選択してください。GitHub Actionsのような既存のCI/CD環境に組み込む場合も、--printモードが手軽です。

Q3. SDK経由の実行でもCLAUDE.mdやカスタムコマンドは有効ですか？

はい、有効です。SDK経由のセッションでも、cwdで指定したディレクトリの.claude/CLAUDE.mdが読み込まれ、カスタムコマンドも利用できます。つまり、対話型セッションで確立したワークフローを、そのまま自動化パイプラインに移行できます。MCP設定もプロジェクトの.claude/settings.jsonから読み込まれます。