%20(%E8%83%8C%E6%99%AF%E3%81%82%E3%82%8A).png?width=130&height=39&name=%E6%9C%80%E7%B5%82Start%20Link%20(500%20x%20150%20px)%20(%E8%83%8C%E6%99%AF%E3%81%82%E3%82%8A).png "StartLink"){kind=logo}
この記事の結論
Claude Code SDKを使うと、対話型のターミナル操作を超えて、PythonやTypeScriptのプログラムからAIエージェントを直接呼び出せます。ヘッドレスモードと組み合わせることで、CI/CDパイプライン、定期バッチ処理、カスタムWebアプリケーションなど、幅広い自動化シナリオにClaude Codeを組み込めます。
Claude Code SDKを使うと、対話型のターミナル操作を超えて、PythonやTypeScriptのプログラムからAIエージェントを直接呼び出せます。ヘッドレスモードと組み合わせることで、CI/CDパイプライン、定期バッチ処理、カスタムWebアプリケーションなど、幅広い自動化シナリオにClaude Codeを組み込めます。
「コードレビューを毎回自分の手でClaude Codeに貼り付けて依頼している」「ドキュメント更新をやる人・やらない人でばらつきが出ている」「ターミナルでの対話操作をチームの自動化基盤に乗せたいが、どこから手をつければいいかわからない」——こうした声は、Claude Codeを個人利用からチーム・組織の自動化へ広げようとする段階でよく聞かれます。
Claude Code SDKとは、Claude CodeのAIエージェント機能をPythonやTypeScriptのプログラムから呼び出すための公式インターフェースです。ターミナルでの対話操作を、CI/CDやバッチ処理に組み込める形に置き換えられる点が最大の特徴です。
この記事でわかること
この記事は、ターミナルでの対話操作をSDKやヘッドレスモードでプログラムから実行できる形に置き換えたいエンジニアに向けて、SDKの基本的な使い方から実務での自動化パターン、運用上の注意点までを順に整理したものです。
- Claude Code SDKの全体像と基本的な使い方 — TypeScript・Pythonそれぞれのセットアップ方法とコード例を紹介します
- 対話なしで実行するヘッドレスモードの活用法 — スクリプトから自動的にClaude Codeを呼び出す方法と、SDKとの使い分け基準を解説します
- 自動化パイプラインへの組み込みパターン — プルリクエスト時の自動コードレビューなど、実務での活用例を紹介します
- 運用時に気をつけたいセキュリティと限界 — 認証情報の管理やツール制限、向かないケースまで率直に整理します
- 自社の開発フローに合わせた導入の進め方 — いきなり全体を自動化するのではなく、どこから始めてどう広げるかの考え方を紹介します
Claude Codeをすでに個人で使っている方はもちろん、チームや自動化基盤への組み込みを検討している方に向けて書いています。最後まで読むと、自社の開発フローのどこにSDKを組み込むべきか判断できるようになります。
Claude Code SDKとは
Claude Code SDKは、Claude Codeの機能をプログラムから呼び出すための公式インターフェースです。通常のClaude Codeはターミナルで対話的に操作しますが、SDKを使えばPythonやTypeScriptのコードから直接AIエージェントを起動し、結果を受け取れます。
個人が手元のターミナルで完結させていた作業を、チームや組織の仕組みとして再利用できる形に変換する技術だと捉えると理解しやすくなります。
SDKの種類と特徴
| SDK | 言語 | インストール | 主な用途 |
|---|---|---|---|
| TypeScript SDK | TypeScript/JavaScript | @anthropic-ai/claude-code（npm） |
Node.jsアプリ、Webサービス、CI/CD |
| Python SDK | Python | claude-code-sdk（PyPI） |
データ分析、バッチ処理、MLパイプライン |
CLI（--printモード） |
任意（シェル経由） | Claude Code本体 | シンプルな自動化、シェルスクリプト |
SDKはAnthropicが公式に提供しており、Claude Codeと同じ認証情報・設定ファイルを利用します。既存のClaude Code環境があれば、追加の認証設定なしでSDKを使い始められます。
どのSDKを選ぶかについては、次のように考えられます。
- 判断基準 ── 既存の開発基盤がNode.jsとPythonのどちらに寄っているかで決めるのが実務的です
- 使い分けも可 ── 無理に片方に統一する必要はなく、CI/CDはTypeScript、データ分析バッチはPythonというように用途ごとに使い分けても問題ありません
認証の仕組み
- ローカル環境 ──
claude loginで設定済みの認証情報がそのまま使えます - CI/CDなどのサーバー環境 ── 環境変数
ANTHROPIC_API_KEYにAnthropicのAPIキーを設定する運用が基本です - Maxプランを契約している場合 ── ローカル環境であればAPIキーなしでSDKを利用できます
ローカルとサーバーで認証方式が異なる点は、後述するセキュリティ設計にも関わるため、SDK導入の初期段階で押さえておきたいポイントです。
TypeScript SDKの基本的な使い方
TypeScript SDKは、Node.jsプロジェクトに最も自然に統合できる方法です。
- 相性が良いケース ── Webアプリケーションのバックエンドや、既存のCI/CDパイプラインにNode.jsが使われている場合
- 導入のハードルが低いチーム ── すでにNode.js製のツールやスクリプトを運用していれば、既存のパッケージ管理・デプロイの仕組みにそのまま乗せられます
インストールと基本的な呼び出し
npmで @anthropic-ai/claude-code パッケージをインストールし、プログラムから呼び出す構成にします。以下は基本的な呼び出しのコード例です。
npm install @anthropic-ai/claude-codeimport { claude } from "@anthropic-ai/claude-code";
const response = await claude({
prompt: "src/ディレクトリのTypeScriptファイルを分析して、型定義の改善点を報告してください",
options: {
maxTurns: 10,
},
});
console.log(response.stdout);この例では、claude()関数を非同期で呼び出し、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,
},
});セッションを引き継ぐことで、前回の会話コンテキストが保持されます。分析→計画→実行のような複数ステップのワークフローを構築する際に重要な機能です。
ここが--printモードとの大きな違いで、単発のタスクで完結するか、前工程の結果を踏まえて次のステップを進めたいかが、SDK導入を検討する分かれ目になります。
Python SDKの基本的な使い方
Python SDKは、データ分析やMLパイプラインとの統合に適しています。既存の分析基盤やバッチ処理がPythonで組まれているチームにとっては、こちらの方が導入コストが低くなります。
インストールと基本的な呼び出し
pip install claude-code-sdkimport 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）ベースで動作する設計です。既存の非同期アプリケーションにも統合しやすい構成になっています。
- オプション名 ── 名前がTypeScript版の
maxTurnsに対してmax_turnsのようにスネークケースになる点以外は、考え方はTypeScript SDKとほぼ共通です - 両方の言語を使うチーム ── 設計の発想を1つ覚えておけばどちらにも応用が効きます
ストリーミング実行（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())TypeScript版と同じく、イベント単位で進捗を受け取れます。分析結果を社内ダッシュボードに逐次反映するような用途に向いています。
ヘッドレスモード（--printフラグ）という選択肢
SDKを使わずに、CLIから直接非対話型で実行する方法もあります。--print（短縮形: -p）フラグを付けると、Claude Codeはユーザーの入力を待たずにタスクを実行し、結果を標準出力に返します。
SDKを導入する前段階として、まずここから自動化を試してみることをおすすめします。いきなりSDKでワークフロー全体を組もうとすると、設計に時間がかかり途中で止まってしまいがちだからです。
基本的な使い方
# 単発実行
claude -p "このリポジトリのREADME.mdを要約してください"
# パイプラインでの利用
cat error.log | claude -p "このエラーログを分析して、根本原因を特定してください"
# JSON出力
claude -p "src/の構成を分析してください" --output-format json以下の画面は、claude --versionの実出力に続けて、本記事で扱うnpm install @anthropic-ai/claude-code・claude login・claude -p・git log --since・git diffのコマンドを並べたものです。
シェルスクリプトからの呼び出し
#!/bin/bash
# 毎朝のコードレビュー自動化
RESULT=$(claude -p "昨日のコミット（git log --since=yesterday）をレビューして、問題点があれば報告してください" --max-turns 15)
echo "$RESULT" > /tmp/daily-review.md--printモードは、SDKを導入するほどではない軽量な自動化に最適です。シェルスクリプト、cron、GitHub Actionsなど、シェルコマンドを実行できる環境ならどこでも使えます。
SDKとヘッドレスモードの使い分け基準
| 状況 | 推奨 |
|---|---|
| シェルスクリプトで完結する単発タスク | --printモード |
| 複数ステップのワークフローやセッション管理が必要 | SDK |
| ストリーミング出力でUIに逐次進捗を表示したい | SDK |
| cronやGitHub Actionsに軽く組み込みたい | --printモード |
ただし、--printモードは1回のプロンプトで完結する設計のため、セッションを跨いだ状態管理には向きません。ユースケースが複数ステップに広がってきたら、SDKへの移行を検討したほうが良いでしょう。
最初から高機能な仕組みを目指すのではなく、「今できている自動化が足りなくなったら次に進む」という順序で考えると、設計にかける時間を最小限に抑えられます。
実務での活用パターン
SDKとヘッドレスモードは、単体の便利機能としてではなく、開発フロー全体のどこに置くかを決めて初めて効果を発揮します。ここでは3つの代表的な組み込み方を紹介します。
- CI/CDパイプラインでのコードレビュー自動化 ── プルリクエストの作成ごとにレビューを実行
- 定期バッチ処理によるドキュメント自動更新 ── コードベースの変更に合わせて更新
- カスタムWebアプリケーションへの統合 ── 社内ツールにAIアシスタント機能を組み込む
いずれも共通しているのは、AIに任せる範囲と、最終的に人が確認する範囲を最初に線引きしておく設計です。
パターン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これは、レビューを「やる人がやる」という属人的な運用から、プルリクエストが作成されるたびに自動で走る仕組みへの転換です。仕組み化しておけば、担当者が変わってもレビューの一次チェックの質を一定に保ちやすくなります。
ただし、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,
},
});
}変更検出とドキュメント更新をセッションで繋ぐことで、「APIが変わったのにドキュメントが古いまま」という状態を防ぎやすくなります。
定期実行のスケジュールに乗せてしまえば、誰かが手を止めてドキュメントを見直すタイミングを待つ必要がなくなる点も、仕組み化のメリットです。
パターン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エージェントの機能を利用できます。
ただし、問い合わせ内容が重要な意思決定に関わる場合は、AIの回答をそのまま実行するのではなく、確認画面を挟んで人がチェックできる設計にすることをおすすめします。
主要オプションリファレンス
SDK・CLIで使える主要なオプションを整理します。どの言語で書いても、押さえるべき考え方は共通しています。
| オプション | TypeScript SDK | Python SDK | CLI（--print） |
説明 |
|---|---|---|---|---|
| 最大ターン数 | maxTurns |
max_turns |
--max-turns |
エージェントの最大行動回数 |
| 作業ディレクトリ | cwd |
cwd |
実行時のカレントディレクトリ | ファイル操作の基準パス |
| セッション継続 | sessionId |
session_id |
--session-id |
前回セッションの引き継ぎ |
| 出力形式 | イベントストリーム | イベントストリーム | --output-format json |
出力のフォーマット |
| 許可ツール | allowedTools |
allowed_tools |
--allowed-tools |
使用可能なツールの制限 |
| システムプロンプト | systemPrompt |
system_prompt |
--system-prompt |
追加のシステムプロンプト |
| モデル指定 | model |
model |
--model |
使用するモデルの指定 |
特に押さえておきたい3つのオプション
自動化パイプラインを設計するうえでは、すべてのオプションを網羅するよりも、maxTurns・allowedTools・sessionIdの3つを最初に理解しておくと運用が安定します。
maxTurns── コストと実行時間の上限を決める設定allowedTools── エージェントに許可する操作範囲を絞る設定sessionId── 複数ステップの文脈を引き継ぐための設定
どれも「AIに何をどこまで任せるか」を仕組みとして明示するためのオプションだと捉えると理解しやすくなります。
ユースケース別のオプションの考え方
- CI/CDでのコードレビューのように、短時間で1回だけ結果を得たい用途 ──
maxTurnsを絞り、allowedToolsも読み取り系に限定する構成が候補になります - ドキュメント更新のように複数ステップを繋ぐ用途 ──
sessionIdで前工程の結果を引き継ぐ設計が前提になります - Webアプリケーションからの都度呼び出し ──
cwdをリクエストごとに切り替えることで、複数のプロジェクトを1つのバックエンドから横断的に扱えます
どの設定が正解ということはなく、自動化の目的に応じてオプションの組み合わせを変えていくものだと考えるのが実務的です。
関連機能との組み合わせで広がる自動化
SDKは単独で使うよりも、Claude Codeの他機能と組み合わせることで、開発フロー全体を一気通貫で自動化できるようになります。
- カスタムコマンド ── 定型タスクの起動
- MCP ── 外部ツールへの接続
- Hooks ── 実行前後のチェック
個々の機能をバラバラに使うのではなく、起動から実行前後のチェックまでを一続きの仕組みとして設計する視点が重要です。
カスタムコマンドとの連携
プロジェクトに定義したカスタムコマンドは、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経由の実行でもツール呼び出し前後にカスタムスクリプトを挟めます。セキュリティチェックやログ記録の自動化に有効です。
カスタムコマンド・MCP・Hooksを組み合わせることで、「起動→ツール接続→実行前後のチェック」までを一連の仕組みとして運用できるようになります。
セキュリティとベストプラクティス
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コストの想定外の増加を防ぎやすくなります。
- 絞りすぎに注意 ──
maxTurnsを絞りすぎるとタスクが途中で打ち切られてしまうこともあります - 調整の進め方 ── まずは余裕のある値で試し、実行ログを見ながら調整していくアプローチが現実的です
自社に合わせたSDK導入のロードマップ
どの粒度で自動化するかは、開発チームの規模や既存のCI/CD基盤によって最適な形が異なります。
企業様によって最適な形は異なりますので、汎用的な手順をそのまま真似るのではなく、自社の開発フローに合わせて段階的に広げていく進め方をおすすめします。
まずは--printモードから始める
まずは1つのユースケース（例えばコードレビューの一次チェックだけ）を--printモードで自動化し、運用に慣れてから対象を広げていくアプローチが実務的です。
- SDKへの移行 ── ユースケースが複数ステップに広がった段階で検討すると無理がありません
- 最初の候補 ── 今すでに手動でClaude Codeに依頼している作業があるなら、それが最初の候補になります
自動送信ではなく人間レビューを挟む設計
AIエージェントに任せてよいのは、次のような提案段階までです。
- コードの一次チェック
- ドキュメントの下書き
- 変更点の要約
マージ判断や本番環境への反映など、影響範囲が大きい操作は、AIの出力を人が確認してから実行する設計にすることをおすすめします。
自動化の目的は人の判断を省くことではなく、判断材料を早く揃えることだと捉えると設計がぶれにくくなります。
仕組み化で属人化を防ぐ
allowedToolsによるツール制限やHooksによる前後処理は、個人の注意力ではなく仕組みでガードレールを作る手段です。
新しくチームに加わったメンバーがいても、パイプラインとして定義されたルールに沿って自動化が動くため、レビューやドキュメント更新の質が担当者によってばらつきにくくなります。
属人的な運用から仕組みへの移行こそが、SDK導入の本質的な価値です。
まずは小さく試し、運用に慣れてから広げるという進め方そのものは、規模を問わず共通して有効だと考えています。
よくある質問
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から読み込まれます。
Q4. どのくらいの規模のチームから導入を検討すべきですか？
チームの規模よりも、「同じ作業を繰り返し手動で呼び出しているかどうか」を基準に考えることをおすすめします。コードレビューやドキュメント更新を毎回誰かが手動でClaude Codeに依頼している状態であれば、規模にかかわらず--printモードでの自動化を検討する価値があります。
まとめ
Claude Code SDKは、AIエージェントを「対話ツール」から「プログラマブルなインフラ」に昇格させる技術です。それぞれ向いている用途は次のとおりです。
- TypeScript SDK ── WebアプリケーションやCI/CDとの統合
- Python SDK ── データ分析やMLパイプライン
- CLIの
--printモード ── シェルスクリプトによる軽量自動化
どれか1つを選ぶのではなく、用途ごとに使い分けるのが現実的な進め方です。
最初の一歩としては、コードレビューやドキュメント更新といった、今すでに手動でClaude Codeに依頼している作業を1つ選び、--printモードで自動化してみることをおすすめします。その上で、次の3ステップで段階的に広げていくと無理がありません。
- 手動で繰り返している作業を1つ選び、
--printモードで自動化する - 複数ステップの処理やセッション管理が必要になった段階でSDKへ移行する
allowedToolsやHooksでツール権限を絞り、属人的な運用から仕組みへ置き換える
CRMを活用した業務効率化やAIとの連携に関するご相談は、CRM特化型コンサルティングのHubSpotゴールドパートナーのStartLinkまでお気軽にお問い合わせください。
あわせて読みたい
記事の内容を、そのまま実務に落とし込みたい方向け
HubSpotゴールドパートナーのStartLinkが、HubSpot導入・AI活用・CRM整備・業務効率化までをまとめて支援しています。記事で気になったテーマを、そのまま相談ベースで整理できます。
次に読む
株式会社StartLinkは、事業推進に関わる「販売促進」「DXによる業務効率化（ERP/CRM/SFA/MAの導入）」などのご相談を受け付けております。 サービスのプランについてのご相談/お見積もり依頼や、ノウハウのお問い合わせについては、無料のお問い合わせページより、お気軽にご連絡くださいませ。
著者情報
