【2026年最新】Claude Code Agent SDK｜本番権限設計

この記事の種別：実装パターン解説です。特定企業の成果事例ではなく、2026年8月24日時点で取得したAnthropic公式ドキュメントとClaude Codeの公開CHANGELOGをもとに、本番導入時の設計手順を整理しています。

Claude Codeを業務導入したいエンジニアから、最近いちばん増えている相談は「CLIで便利なのは分かった。では、社内ツールやSaaSの中にどう組み込むのか？」です。ターミナルでclaude -pを動かすだけなら早いのですが、プロダクトに組み込む瞬間に、権限、承認、ログ、費用、MCP接続、ユーザーごとの責任分界が一気に現れます。

正直、ここを曖昧にしたまま「Agent SDKで全部自動化しよう」と進めるのは危険です。AIエージェントは、便利な補助ツールである一方、ファイル編集、コマンド実行、外部APIアクセス、PR作成、チケット更新までつながると、通常のアプリケーション以上に安全設計が必要になります。

この記事では、Claude Code Agent SDKを本番に入れる前に、どの順番で設計すべきかをエンジニア視点でまとめます。公式ドキュメントの記述に寄せつつ、現場でそのまま設計レビューに使えるよう、チェックリスト、設定例、疑似コード、失敗パターンまで含めます。

1. Agent SDKを使う前に決める判断軸

CLI自動化で足りる仕事、SDK化すべき仕事

まず分けたいのは「Claude Codeを呼ぶ」ことと「Claude Codeをプロダクトの責任ある一部にする」ことです。前者ならCLIのヘッドレス実行、GitHub Actions、CI/CD連携で十分な場合があります。後者、つまりユーザーごとのセッション、承認UI、操作履歴、MCP接続、権限境界をアプリ側で制御したい場合に、Agent SDKの出番になります。

たとえば、毎晩の依存関係レビュー、PRコメントの下書き、社内リポジトリのREADME更新案作成は、まずCLIやGitHub Actionsで試せます。一方、ユーザーがWebアプリから「このリポジトリの障害原因を調べて、修正PRまで作って」と依頼する機能は、セッション管理と承認UIが必要です。この差を最初に言語化しておくと、実装範囲が暴れません。

本番で必要になる5つの境界

本番導入で決める境界は、少なくとも5つあります。第一に、どのファイルやデータソースを読めるか。第二に、どの変更を自動で実行できるか。第三に、どの操作に人間承認を挟むか。第四に、外部送信やMCP経由の操作をどこまで許可するか。第五に、費用と利用量をどこで止めるかです。

この5つが曖昧なままSDK実装に入ると、コードは書けても運用で止まります。逆に、境界が明確なら、最初の実装は小さくて構いません。読み取り専用の分析エージェントから始め、次にパッチ提案、最後に承認付きPR作成へ進むほうが、チームの信頼を得やすいです。

この記事で扱う動作環境

本記事の想定環境は、Node.jsまたはPythonで構成された社内Webアプリ、GitHubまたはGitLab上のリポジトリ、CI/CD、MCPサーバーを一部利用する開発チームです。Claude Codeの具体的なバージョンやSDKのAPIは更新されるため、実装時は必ず公式ドキュメントを確認してください。本記事では、2026年8月24日に確認した公開情報に基づき、設計観点を優先して説明します。

公式情報として、Agent SDK overview、settings、hooks、CLI reference、GitHub Actions、公開CHANGELOGを参照しています。特にCHANGELOGには、2026年8月時点の/cost、status line、--max-budget-usd、Remote Control、MCP、hooks、OpenTelemetryなどに関する更新がまとまっています。

2. 公式情報から見るAgent SDKの役割

Agent SDKは「Claude Codeの機能をアプリに持ち込む」層

AnthropicのAgent SDK overviewでは、Agent SDKはClaude Codeのツールと能力を使って本番AIエージェントを構築するための入口として説明されています。ページ上では、セッション、外部ストレージ、ストリーミング、構造化出力、MCP接続、tool search、subagents、skills、plugins、permissions、hooks、OpenTelemetry、todosなどの項目が並んでいます。

ここから分かる重要点は、Agent SDKが単なる「APIラッパー」ではないことです。チャット補完の呼び出しだけではなく、Claude CodeがターミナルやCIで持っている実務機能を、アプリケーションの権限設計と接続するための層として見たほうが自然です。

CLI・GitHub Actions・SDKの使い分け

Claude Code公式ドキュメントでは、ターミナル、IDE、Web、Desktop、Mobile、Remote Control、GitHub Actions、GitLab CI/CDなど複数の利用面が案内されています。GitHub Actionsのページでは、PRレビュー、skills実行、@claudeメンション、schedule実行、認証情報の保護などが扱われています。

このため、いきなりSDKだけで全部作る必要はありません。CLIで操作を検証し、GitHub ActionsでCI上の権限を整理し、最後にユーザー体験や承認UIが必要な部分をSDK化する。これが実務では安全です。Claude Codeヘッドレス自動実行ガイドや既存の二刀流ワークフロー記事と合わせて読むと、段階的に導入しやすくなります。

設定ファイルは「個人・プロジェクト・組織」で分ける

Claude Code settingsの公式ページでは、個人設定、共有プロジェクト設定、プロジェクトローカル設定、managed settingsなど、設定のスコープが整理されています。チーム導入では、このスコープ分離がかなり重要です。個人の好み、チーム共通の権限、組織が強制したい制限を同じファイルに混ぜると、レビューしづらくなります。

Agent SDKでも同じ考え方を持ち込みます。アプリ側のユーザー設定、プロジェクト設定、組織ポリシーを分け、後から監査できる形にしておく。特に、本番データに触れるエージェントでは「ユーザーが許可したから何でもOK」ではなく、組織側の上限を上に置く設計が必要です。

3. 本番権限設計の基本モデル

ツールを4分類する

最初の実装タスクは、Claude Codeに渡すツールを4分類することです。分類は「読み取り」「変更」「外部送信」「秘密情報アクセス」です。読み取りは、リポジトリのファイル一覧、ログ、テスト結果、ドキュメント参照など。変更は、ファイル編集、コマンド実行、PR作成、チケット更新など。外部送信はSlack、メール、Issueコメント、Webhook、顧客向け通知など。秘密情報アクセスは、環境変数、鍵、トークン、顧客データ、個人情報に近い領域です。

この分類をしないままallowedToolsやMCPを追加すると、レビュー時に「結局このエージェントは何ができるの？」という問いに答えられません。エージェントの能力は便利さではなく、失敗時の被害半径で評価します。

許可・承認・禁止を表にする

権限設計は、文章ではなく表に落とすとチームで合意しやすくなります。以下は、最初の設計レビューで使える最小例です。

操作	初期設定	理由	昇格条件
リポジトリの読み取り	許可	調査に必要で、変更を伴わない	機密ディレクトリは除外
テスト実行	承認なし許可	ローカル/CIの検証に必要	外部サービス接続を伴う時は承認
ファイル編集	人間承認	意図しない差分を防ぐ	生成先ディレクトリを限定した時のみ自動化
PR作成	人間承認	レビュー可能な境界にする	botブランチ限定
Slack/メール送信	禁止または承認必須	外部公開・対人送信に該当	下書き保存から始める
秘密情報の読み取り	禁止	漏えい時の被害が大きい	原則昇格しない

権限は「広く許可して監視」ではなく「狭く許可して拡張」

AIエージェントの導入では、最初に広く許可すると、後から絞るのが難しくなります。ユーザーは「昨日までできたのに、なぜ今日から止めるのか」と感じます。だからこそ、初期状態は狭く、明確な成功パターンが見えた操作だけを広げるほうが安全です。

たとえば、最初の2週間は読み取りとレポート生成のみ。次の2週間でパッチ提案まで。さらに運用ログを見て、特定ディレクトリのテンプレート更新だけ自動編集を許可する。こうした段階導入なら、権限拡張の理由を説明できます。

4. 実装アーキテクチャ：セッション、承認、監査ログ

セッションをユーザー単位で分ける

本番アプリに組み込む場合、セッションを誰の操作として扱うかが重要です。単一のbotユーザーですべて実行すると、監査ログで責任分界が見えません。Agent SDK側のセッションID、アプリ側のユーザーID、対象リポジトリ、実行権限、承認者を紐づけて保存します。

最低限、agent_session_id、app_user_id、workspace_id、repo、requested_action、approved_by、approval_at、tool_calls、cost_estimate、final_statusは後から検索できる形にすると便利です。実装時には、個人情報やシークレット値そのものをログに残さないよう注意してください。

承認UIは「実行前に差分を見せる」

承認UIでよくある失敗は、「許可しますか？」だけを表示することです。これでは何を許可するのか判断できません。ファイル編集なら対象ファイル、差分、テスト結果、影響範囲。外部送信なら送信先、本文、添付、公開範囲。コマンド実行ならコマンド、作業ディレクトリ、環境変数の扱い、タイムアウトを出すべきです。

Agent SDKを使う時も、承認は単なるボタンではありません。人間がリスクを評価できる情報を、実行前に揃えるUIが必要です。ここを丁寧に作るほど、エージェントへの信頼は上がります。

監査ログは「成功ログ」だけでは足りない

監査ログには、成功した操作だけでなく、拒否された操作、権限不足で止めた操作、hooksが差し戻した操作も残します。むしろ本番初期は、止めたログのほうが価値があります。どこで人間承認が多すぎるのか、どのMCPツールが危険判定されやすいのか、どのディレクトリで誤操作が出るのかが見えるからです。

Claude Codeの公式ドキュメントでは、OpenTelemetryによる観測やhooks、permissionsが扱われています。アプリ側でも、トレースIDを持たせて、ユーザー操作からエージェントのtool callまで追える状態にします。これは障害対応だけでなく、セキュリティレビューや利用量分析にも効きます。

5. 最小構成の疑似コード

権限ポリシーをコードにする

実装では、ポリシーを設定ファイルとコードの両方で表現します。以下は概念例です。SDKの正確なAPIはバージョンで変わる可能性があるため、実装時は公式のTypeScript SDKまたはPython SDKリファレンスを確認してください。

type ToolClass = "read" | "write" | "external_send" | "secret";

type ToolPolicy = {
  name: string;
  klass: ToolClass;
  defaultAction: "allow" | "require_approval" | "deny";
  allowedPaths?: string[];
};

const policies: ToolPolicy[] = [
  { name: "repo.read", klass: "read", defaultAction: "allow" },
  { name: "test.run", klass: "read", defaultAction: "allow" },
  { name: "file.edit", klass: "write", defaultAction: "require_approval", allowedPaths: ["src/", "docs/"] },
  { name: "pull_request.create", klass: "write", defaultAction: "require_approval" },
  { name: "slack.post", klass: "external_send", defaultAction: "require_approval" },
  { name: "env.read", klass: "secret", defaultAction: "deny" }
];

ポイントは、ツール名をそのまま許可するのではなく、ツールの性質を分類しておくことです。新しいMCPツールが増えた時も、分類とデフォルト動作を付けない限り有効化しない運用にします。

承認リクエストに必要な情報

次に、承認UIへ渡す情報を定義します。承認者が見たいのは「便利そうか」ではなく「失敗した時に何が起きるか」です。

{
  "action": "file.edit",
  "risk_class": "write",
  "actor": "user_123",
  "workspace": "engineering-platform",
  "target": {
    "repo": "example/api-server",
    "files": ["src/auth/session.ts"]
  },
  "preview": {
    "diff_summary": "認証エラー時のログ出力を1箇所追加",
    "tests_to_run": ["pnpm test src/auth/session.test.ts"]
  },
  "rollback": "git revert またはPRを閉じる",
  "expires_in_minutes": 30
}

この形式にしておくと、承認ログを後から監査しやすくなります。承認期限も重要です。古い差分に対する承認が、翌日に別のコード状態で再利用されると危険です。

hooksで最後の安全網を作る

hooksは、エージェントの行動前後にチェックを入れる安全網として使えます。たとえば、ファイル編集前に禁止パスを検査する、コマンド実行前に危険な引数を拒否する、実行後に差分とテスト結果をログへ送る、といった使い方です。

# 概念例: 変更系コマンドの前に禁止パスを検査する
case "$TOOL_NAME:$TARGET_PATH" in
  file.edit:*\.env|file.edit:*secrets*|file.edit:*private_key*)
    echo "Denied: secret-like path is not editable by the agent" >&2
    exit 1
    ;;
  *)
    exit 0
    ;;
esac

もちろん、hooksだけに頼るのは不十分です。アプリ側のポリシー、Claude Code設定、MCPサーバー側の権限、CIの保護ルールを重ねます。セキュリティは一枚の壁ではなく、薄い壁を何枚も重ねるほうが現実的です。

6. MCP接続は「便利なプラグイン」ではなく権限拡張

MCPは接続先ごとにリスクが違う

MCPは、Claude Codeから外部データや社内ツールへ接続するための強力な仕組みです。公式overviewでも、Google Drive、Jira、Slack、独自ツールのような外部データソースとの接続例が説明されています。ただし、接続できるということは、権限が広がるということでもあります。

たとえば、ドキュメント検索だけのMCPと、Issueを更新できるMCP、Slackへ投稿できるMCP、顧客DBを読めるMCPは、同じ「MCPサーバー」でもリスクがまったく違います。導入レビューでは、MCPサーバー単位ではなく、提供ツール単位で分類します。

headersHelperや認証情報の扱い

2026年8月のClaude Code CHANGELOGでは、plugin marketplacesやMCPのheadersHelper、認証ヘッダー、信頼済みフォルダ、credential envの扱いに関する更新が記載されています。ここからも、MCPやpluginまわりは単なる便利機能ではなく、認証情報と実行権限に直結する領域だと分かります。

実装時は、短命トークン、最小スコープ、監査ログ、信頼済みソースの確認をセットにします。MCPサーバーを増やすたびに、誰が承認したか、どのスコープで、どの環境に有効化したかを記録します。

社内MCPの最小レビュー項目

社内MCPサーバーをAgent SDKから使う場合、最低限以下をレビューします。

• 読み取り専用か、更新系操作を含むか
• ユーザー単位の認可を反映できるか
• 操作ログをサーバー側にも残せるか
• 秘密情報をレスポンスに含めない設計か
• レート制限とタイムアウトがあるか
• 障害時にエージェントがリトライしすぎないか
• テスト環境と本番環境を明確に分けているか

このリストを満たせないMCPは、まずローカル検証か読み取り専用から始めるべきです。特にSlack、メール、CRM、請求、顧客データに触るMCPは、外部送信や個人情報の扱いを明確にします。

7. GitHub ActionsとSDKを組み合わせる

CIで閉じる処理はGitHub Actionsへ寄せる

Claude Code GitHub Actionsの公式ページでは、@claudeメンション、PRレビュー、skills実行、schedule、認証情報の保護、権限設定などが扱われています。リポジトリ内で完結する処理は、SDKアプリで抱え込まずGitHub Actionsに寄せると運用が楽になります。

たとえば、PRが開いたらClaude Codeでレビュー、問題があればinline comment、問題がなければsummary comment。こうした処理はActionsのイベントモデルに自然に合います。SDK側は、ユーザーからの依頼受付、承認、ジョブ作成、結果表示に集中できます。

SDK側は「人間が依頼する入口」にする

一方、SDKが向いているのは、人間がアプリ上で状況を見ながら依頼する場面です。障害調査、複数リポジトリ横断の調査、仕様書とコードの突合、MCPでチケットやドキュメントを参照する作業は、ユーザーの文脈が重要です。

この場合、SDKアプリは「AIに任せるボタン」ではなく、調査範囲、使ってよいツール、承認が必要な操作、予算上限を入力するフォームになります。エンジニア向けには面倒に見えますが、本番ではこの明示性が事故を減らします。

PR作成までの推奨フロー

SDKとActionsを組み合わせるなら、次の流れが扱いやすいです。

1. SDKアプリでユーザーが調査依頼を作成する
2. Agent SDKがリポジトリを読み取り、原因候補と修正方針を提示する
3. ユーザーが対象ファイルと方針を承認する
4. エージェントがbotブランチに差分を作る
5. CIとGitHub Actions上のClaude Codeレビューを走らせる
6. 人間が最終レビューしてマージする

この流れなら、AIが調査と修正を支援しつつ、公開ブランチへの反映は既存の開発統制に乗せられます。いきなりmainへpushするような設計は避けます。

8. 費用・利用量・上限の設計

予算は「月額」だけでなく「1依頼ごと」に見る

AIエージェントの費用管理では、月額の総額だけでなく、1依頼ごとの上限が重要です。大規模リポジトリの全体調査、長いログ解析、複数MCPの横断検索、subagentsの並列実行は、便利な反面、コストが読みにくくなります。

Claude Codeの2026年8月CHANGELOGには、/cost、status line、--max-budget-usdに関するコスト見積もりの更新が記載されています。実装では、CLI側の上限や表示だけに依存せず、アプリ側でもジョブ単位の予算を持つ設計にします。

予算超過時のユーザー体験を決める

予算超過時に、エージェントが途中で止まるだけではユーザーは困ります。止まる前に「ここまで分かったこと」「残りの調査候補」「追加で必要な予算」「低コスト代替案」を返す設計にします。

{
  "status": "budget_paused",
  "spent_estimate_usd": 2.40,
  "budget_usd": 2.50,
  "completed": ["ログ3本の解析", "直近PR差分の確認"],
  "remaining": ["DB slow queryの詳細確認", "修正案の生成"],
  "next_options": ["追加予算を承認", "読み取りだけで要約して終了", "対象範囲を1ファイルに絞る"]
}

こうしておくと、費用上限は単なるブレーキではなく、ユーザーが判断するための情報になります。

OpenTelemetryとアプリログをつなぐ

公式ドキュメントでは、Agent SDKの観測性としてOpenTelemetryが扱われています。アプリ側でも、ユーザー操作、SDKセッション、tool call、MCP呼び出し、CIジョブ、PR番号を同じtraceで追えると、障害調査が楽になります。

たとえば、ユーザーが「このジョブ、なぜ高かったの？」と聞いた時に、どのファイルが大きかったのか、どのMCP呼び出しが多かったのか、どの段階でリトライが発生したのかを説明できます。AI機能はブラックボックスに見えやすいので、費用と挙動を説明できるログが信頼につながります。

9. よくある失敗パターンと回避策

失敗1：全ツールを最初から許可する

❌「社内エンジニアだけが使うから、ファイル編集もコマンド実行もMCPも全部許可する」

⭕「読み取りから始め、変更系は差分プレビューと承認UIを必須にする」

なぜ重要か：社内利用でも、誤ったコマンド、誤ったファイル編集、外部送信の誤爆は起きます。便利さを優先して権限を広げると、事故後に原因を切り分けにくくなります。

失敗2：MCPを接続数で管理する

❌「MCPサーバーは3つだけだから安全」

⭕「各MCPが提供するツールを、読み取り・変更・外部送信・秘密情報アクセスに分類する」

なぜ重要か：危険度はサーバー数ではなく、できる操作で決まります。読み取り専用のMCPが10個あるより、本番CRMを書き換えられるMCPが1個あるほうがリスクは大きいです。

失敗3：承認UIに差分を出さない

❌「Claudeが修正します。許可しますか？」

⭕「対象ファイル、差分、実行コマンド、ロールバック方法、テスト結果を表示して承認する」

なぜ重要か：人間が承認責任を持つには、判断材料が必要です。承認ボタンだけでは、実質的にAIへ丸投げしているのと変わりません。

失敗4：費用上限を後回しにする

❌「利用が増えてから予算管理を考える」

⭕「PoCの時点から1ジョブあたりの上限と、止まった時のユーザー体験を決める」

なぜ重要か：AIエージェントは調査範囲が広がるほど費用が読みにくくなります。予算上限を後から入れると、既存ユーザーの体験を壊しやすくなります。

失敗5：監査ログを成功時だけ残す

❌「成功したPRと回答だけ保存する」

⭕「拒否、承認待ち、hooks差し戻し、予算停止、MCP失敗も保存する」

なぜ重要か：本番運用で改善に効くのは、うまくいかなかったログです。止めた理由を見れば、ポリシーが厳しすぎるのか、ツールが危険すぎるのかを判断できます。

10. 導入ロードマップ：30日で本番候補まで進める

Day 1-7：読み取り専用PoC

最初の1週間は、読み取り専用にします。対象リポジトリを1つに絞り、できることはログ解析、コード理解、影響範囲の説明、テスト候補の提案まで。ファイル編集、PR作成、外部送信は禁止します。

この期間に見るべき指標は、回答の正確さよりも、権限設計の抜けです。エージェントがどのファイルを読みたがるか、どのMCPが必要になりそうか、どの場面で人間の追加情報が必要かを観察します。

Day 8-14：差分提案と承認UI

次の1週間で、ファイル編集の前段として差分提案を作ります。エージェントはパッチを直接適用せず、変更案、理由、対象ファイル、テストコマンドを返します。ユーザーはそれを見て、適用するか却下するかを選びます。

ここで承認UIの原型を作ります。差分表示、リスク分類、ロールバック方法、期限付き承認、承認者ログ。この段階で面倒に感じる部分こそ、本番で事故を防ぐ要素です。

Day 15-21：botブランチとCI連携

3週目は、botブランチ作成とCI連携に進みます。エージェントが差分を作り、テストを実行し、PRを作成する。ただし、マージは人間レビューに残します。GitHub ActionsでClaude Codeレビューを組み合わせる場合も、この段階で動かします。

PRには、エージェントが使った前提、実行したコマンド、失敗した検証、残した懸念をテンプレート化して入れます。人間レビュアーが読みやすいPRを作ることが、AI導入の成否を左右します。

Day 22-30：監査・費用・権限見直し

最後の1週間は、新機能を増やすより、ログを見ます。承認待ちが多すぎる操作、拒否が多いMCP、費用が高い依頼、成功率が低いタスク、ユーザーが中断した場面を集計します。

この結果をもとに、許可する操作を少し広げるか、逆に禁止する操作を増やすかを決めます。Agent SDK導入は、初回リリースで完成ではありません。ログを見てポリシーを育てるプロダクトです。

11. 設計レビューで使うチェックリスト

セキュリティ観点

• 秘密情報を読むツールが初期状態で無効化されているか
• 外部送信は下書きまたは承認必須になっているか
• MCPツールを操作単位で分類しているか
• hooksだけでなくアプリ側にも拒否ロジックがあるか
• ユーザー、承認者、対象リポジトリ、実行時刻を記録しているか

開発運用観点

• CLIで検証済みの作業だけをSDK化しているか
• PR作成後のCIと人間レビューが残っているか
• botブランチ、命名規則、ロールバック手順があるか
• テスト失敗時にエージェントが無限修正しないか
• 大規模リポジトリで対象範囲を絞るUIがあるか

費用・可観測性観点

• 1ジョブあたりの予算上限があるか
• 予算停止時に中間結果を返せるか
• OpenTelemetryまたは同等のtraceでtool callを追えるか
• ユーザー別、リポジトリ別、MCP別の利用量を見られるか
• リトライや長時間実行の上限があるか

このチェックリストは、Claude Code権限設計ガイド、Claude Code Hooks実践ガイド、Claude Code MCP実践ガイドとも接続できます。既存のチーム導入ルールがある場合は、そこへAgent SDK固有の項目を足す形で始めるのが楽です。

12. プロンプトと運用テンプレート

テンプレート1：読み取り専用調査

あなたは社内リポジトリの調査エージェントです。
許可された操作は読み取り、テスト結果の参照、依存関係の確認のみです。
ファイル編集、外部送信、秘密情報の読み取りは禁止です。

目的：この障害ログから原因候補を3つに絞ってください。
出力：根拠ファイル、確認したログ、追加で必要な情報、次の検証コマンド。
不足している情報があれば、最初に質問してから作業を開始してください。

テンプレート2：差分提案のみ

あなたは修正PRの下書きを作るエージェントです。
直接ファイルを編集せず、変更案をunified diff形式で提示してください。

必須：対象ファイル、変更理由、リスク、テストコマンド、ロールバック方法。
禁止：秘密情報の表示、外部送信、mainブランチへの直接反映。
仮定した点は必ず「仮定」と明記してください。

テンプレート3：MCP利用時の前提確認

これからMCPツールを使って調査します。
各ツール呼び出し前に、目的、読み取り/変更の区分、取得するデータの範囲を説明してください。
顧客情報、認証情報、個人情報に該当しそうな値は取得しないでください。
必要な場合は、人間承認を求めてから続行してください。

テンプレート4：予算停止時の返答

予算上限に近づいた場合は、作業を続けずに停止してください。
停止時は、ここまで分かったこと、未確認の仮説、追加で必要な操作、低コスト代替案を返してください。
数字と固有名詞は、根拠または確認元を添えてください。

テンプレート5：PR説明文

PR本文を作成してください。
含める項目：背景、変更内容、確認したファイル、実行したテスト、未確認事項、ロールバック方法。
成果を断定せず、確認済みの事実と仮説を分けてください。
レビュー担当者が最初に見るべきファイルを3つ以内で示してください。

プロンプトは魔法の呪文ではありません。権限、承認、ログ、テスト、ロールバックとセットで使うことで、初めてチーム運用に乗ります。プロンプト単体で本番品質を担保しようとしないことが大切です。

13. FAQ

Claude Code Agent SDKとは何ですか？

Claude Codeのツール、セッション、MCP、hooks、権限制御などを使って、本番向けAIエージェントを組み込むためのSDKです。公式ドキュメントでは、セッション、ストリーミング、構造化出力、MCP接続、subagents、skills、plugins、permissions、OpenTelemetryなどが扱われています。

Claude Code CLIのヘッドレス実行と何が違いますか？

CLIのヘッドレス実行は既存のClaude Codeワークフローを自動化する入口として扱いやすい一方、Agent SDKはアプリケーション側でセッション管理、承認UI、権限、構造化出力、監査を設計したい時に向きます。まずCLIで運用を固め、要件が明確になった部分をSDK化するのが安全です。

本番導入で最初に決めるべき権限は何ですか？

最初に決めるべきなのは、読み取り専用で許可するツール、人間承認を必要にする変更系ツール、最初から禁止する外部送信・削除・秘密情報アクセスです。設定ファイル、managed settings、hooks、アプリ側の承認UIで二重に制御します。

MCPサーバーは自由に接続してよいですか？

いいえ。MCPは外部データや社内ツールへ接続できるため、信頼済みのサーバー、必要最小限のスコープ、ログに残せる承認フローを前提にします。Claude Codeの設定や権限の考え方に沿って、プロジェクト単位でレビューしてから接続するのが安全です。

予算超過を防ぐにはどうすればよいですか？

CLIやSDKの利用形態に応じて、status line、/cost、max budget系の上限、組織側の使用量管理、OpenTelemetryの計測を組み合わせます。2026年8月時点のCHANGELOGでは、/costやstatus line、–max-budget-usdのコスト見積もりに関する更新も記載されています。

この記事の構成は実在案件ですか？

本記事は実装パターン解説です。特定企業の実在案件や成果数値ではなく、Claude Code公式ドキュメントと公開CHANGELOGに基づいて、本番導入時の設計観点を整理しています。

14. 要点の整理と次の一歩

本番導入の結論

Claude Code Agent SDKは、Claude Codeを単に呼び出すための部品ではなく、社内アプリやSaaSの中でAIエージェントを安全に動かすための設計対象です。最初に見るべきは、モデル性能ではありません。何を読めるか、何を変更できるか、どの操作を人間が承認するか、どのログを残すか、どこで費用を止めるかです。

おすすめの進め方は、読み取り専用PoC、差分提案、承認付きPR、CI連携、監査ログ改善の順番です。いきなり「全面自動化」へ飛ぶより、チームが安心して任せられる範囲を増やすほうが、結果的に導入は早く進みます。

今日から始める3アクション

1. 自動化したい作業を、読み取り・変更・外部送信・秘密情報アクセスに分類する
2. Claude Code CLIまたはGitHub Actionsで、読み取り専用のPoCを1つ作る
3. SDK化する前に、承認UIと監査ログの項目を表にする

参考にした一次情報

• Agent SDK overview（2026年8月24日確認）
• Claude Code settings（2026年8月24日確認）
• Hooks reference（2026年8月24日確認）
• CLI reference（2026年8月24日確認）
• GitHub Actions（2026年8月24日確認）
• Claude Code CHANGELOG（2026年8月24日確認）

関連記事: 【2026年最新】Claude Code全社導入のコスト可視化・上限設計ガイド

あわせて読みたい

• ▸ 【2026年最新】Claude Codeセルフホスト実行ガイド｜4ステップ
• ▸ Claude CodeでOpenAPI仕様駆動開発｜APIファースト実践ガイド
• ▸ 【2026年最新】Claude Code×Terraformでインフラコード管理