ankuro.dev
← ブログ一覧に戻る
【CCA Foundations対策 / Claude Code実践編 #5】Claude Code SDK——プログラムからClaude Codeを操作する
2026-04-03#Claude Code#AI#SDK#CI/CD#自動化#Claude Certified Architect

【CCA Foundations対策 / Claude Code実践編 #5】Claude Code SDK——プログラムからClaude Codeを操作する

Anthropic Academyの「Claude Code in Action」コースをもとに解説しています。

Claude Code SDKを使うと、Claude Codeをプログラムから操作してより大きなワークフローに組み込める。CI/CDパイプライン・gitフック・自動コードレビューなど、開発プロセスのあらゆる場所にAI処理を埋め込める。

この記事でわかること：

  • SDKの3形態（TypeScript / Python / CLI）の使い分け
  • -p / --print フラグでCIがハングする問題を解決する
  • --output-format json と --json-schema で構造化出力を制御する
  • デフォルトのread-only権限と allowedTools での拡張
  • 独立レビューインスタンスとして使う設計パターン

SDKの3形態

Claude Code SDKには3つのインターフェースがある。

形態 用途
TypeScript SDK Node.jsアプリ・TypeScriptスクリプトへの組み込み
Python SDK Pythonスクリプト・データパイプラインへの組み込み
CLI シェルスクリプト・GitHub Actions・gitフックへの組み込み

どの形態でも、ターミナルで使っているClaude Codeと同じツール・同じ設定が使われる。プロジェクトの .claude/ ディレクトリの設定を自動で継承する。

CLI：-pフラグでCI/CDに組み込む

なぜCIでハングするのか

Claude Codeはデフォルトで対話的（インタラクティブ）に動作する。ユーザーの入力を待ち続けるため、CI/CDパイプラインで通常通り実行するとジョブがハングして終了しない。

# NG：CIでハングする
claude "このPRのセキュリティ問題を分析して"

-pフラグで非インタラクティブモードに切り替える

-p（または --print）フラグを付けるとClaude Codeが非インタラクティブモードで動作する。プロンプトを処理して結果をstdoutに出力し、ユーザー入力を待たずに終了する。

# OK：CIで正常に動作する
claude -p "このPRのセキュリティ問題を分析して"

これがCI/CDでClaude Codeを使う際の基本的な設定。GitHub Actionsのカスタム custom_instructions や allowed_tools と組み合わせて使う。

--output-format jsonで構造化出力

claude -p "src/api以下の未使用エクスポートを列挙して" --output-format json

JSON形式で出力されるため、後続のスクリプトで jq などを使って処理できる。

--json-schemaで出力スキーマを指定

claude -p "以下のコードを分析して" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"issues":{"type":"array","items":{"type":"string"}},"severity":{"type":"string","enum":["high","medium","low"]}}}'

スキーマを指定すると、Claudeはそのスキーマに従ったJSONを返す。CIパイプラインで後続処理が決まった形式のデータを期待している場合に有効。

📋 試験ガイドより
公式試験ガイドのTechnologies and Conceptsに「Claude Code CLI — -p / --print flag for non-interactive mode, --output-format json, --json-schema for structured CI output」が明記されている。また試験のシナリオ問題では「pipeline script runs claude without -p flag and the job hangs indefinitely」のケースが取り上げられており、-p フラグの不使用がCIジョブのハングの原因として問われる。

TypeScript SDK：プログラムから操作する

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

const prompt = "./src/queries ディレクトリで重複しているクエリを探して";

for await (const message of query({ prompt })) {
  console.log(JSON.stringify(message, null, 2));
}

query() はメッセージのストリームを返す。for-awaitでメッセージを順に受け取れる。最後のメッセージにClaudeの完成した回答が含まれる。

デフォルトはread-only

SDKはデフォルトでread-only権限で動作する。ファイルの読み取り・ディレクトリの検索・grepは可能だが、ファイルの書き込み・編集・作成はできない。

// read-onlyではできない
for await (const message of query({
  prompt: "src/utils/helper.ts のドキュメントを更新して",
})) {
  console.log(message);
}
// → Editツールが使えないためエラー

書き込み権限を付与するには allowedTools を指定する。

for await (const message of query({
  prompt: "src/utils/helper.ts のドキュメントを更新して",
  options: {
    allowedTools: ["Edit"],
  },
})) {
  console.log(message);
}

最小権限の原則に従い、タスクに必要なツールだけを許可する。

独立レビューインスタンスとして使う

SDKの重要な使い方が、別のClaudeインスタンスを独立したレビュアーとして起動するパターン。

#4のクエリ重複防止フックでもこのパターンを使った。PostToolUseフックからSDKを呼び出し、別インスタンスに「この変更に既存の重複がないか」を判断させる。

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

async function reviewForDuplicates(changedFile: string): Promise<string> {
  let review = "";

  for await (const message of query({
    prompt: `
      ${changedFile} に加えられた変更を確認して。
      ./src/queries ディレクトリに同じ機能のクエリが既にあれば報告して。
      重複が見つかった場合は既存のクエリ名と場所を示して。
    `,
  })) {
    if (message.type === "result") {
      review = message.result;
    }
  }

  return review;
}

独立インスタンスの優位性：

  • メインの会話コンテキストを持ち込まない——先入観なしにレビューできる
  • 並列で複数インスタンスを起動できる——独立した視点でレビュー精度が上がる
  • メインの会話が長くなってもレビュアーはクリーンな状態を保てる

#4のTypeScript型チェックフックと組み合わせると、「型エラーをClaudeが修正 → 修正後のコードを別インスタンスがレビュー」という二段階の品質チェックが自動で動く。

実用的なユースケース

gitフック（pre-commit）：コミット前にステージされた変更をClaudeがレビューし、問題があれば警告する。

#!/bin/bash
CHANGED=$(git diff --cached --name-only)
claude -p "以下のファイルの変更にセキュリティ上の問題がないか確認して: $CHANGED" \
  --output-format json

CI/CDパイプライン：PRのセキュリティ分析・技術的負債レポートの自動生成。

コードメンテナンス：定期的な未使用エクスポートの検出・ドキュメントの自動更新。

よくある誤解まとめ

誤解 実際
CIで-pフラグなしで動く インタラクティブ入力待ちになってジョブがハングする。-pフラグは必須
SDKはターミナルのClaude Codeより機能が少ない 同じClaude Codeが動く。ツール・設定ともにターミナル版と同じ
SDKはデフォルトでファイルを書き込める デフォルトはread-only。allowedToolsで明示的に権限を追加する
--output-format jsonは常に使ったほうがいい 後続処理でJSONを解析する必要があるときに使う。不要な複雑さを加えない
独立インスタンスはコストが増えるだけ メインコンテキストとは独立した視点でのレビューが品質を上げる。トレードオフで判断する

設計の判断基準

場面 やりがちな選択 正しい選択 判断の根拠
GitHub ActionsでClaude Codeを実行する -pフラグなしで実行 claude -p "プロンプト" で実行 -pなしではインタラクティブ入力待ちになってジョブがハングする
SDKで変更レビューをしたい allowedTools: ["Read", "Edit"] allowedTools: ["Read"] のみ レビューだけならreadで十分。不必要な書き込み権限を与えない
技術的負債レポートを毎晩生成する リアルタイムのClaude APIで実行 -pフラグで非インタラクティブ実行 または Message Batches API 翌朝確認するレポートはブロッキング不要。バッチ処理が適切

まとめ

  • Claude Code SDKはTypeScript / Python / CLIの3形態がある。どれもターミナル版と同じClaude Codeが動く
  • CIで使うときは -p / --print フラグが必須。なしだとジョブがハングする
  • --output-format json で後続処理が解析しやすい形式で出力できる。--json-schema でスキーマを指定するとより構造化された出力になる
  • デフォルトはread-only。ファイル書き込みが必要な場合のみ allowedTools で追加する
  • 独立レビューインスタンスとして起動すると、メインコンテキストとは独立した視点でレビューできる

← #4：HooksでClaude Codeを自動化する ｜ 【振り返りクイズ】Claude Code実践編 →

← ブログ一覧に戻る