エンジニアのClaude活用ガイド — claude.ai・Claude Code・APIの使い分け

Claudeを使うエンジニアが最初に迷うのは、モデルの性能ではなく入り口の選び方です。claude.aiのチャット、Claude CodeというCLIエージェント、APIとAgent SDKは、同じClaudeモデルを土台にしながら実行環境も権限設計もまったく別物です。結論を先に書くと、単発の調査や資料整理はclaude.ai、リポジトリに対する自律的な編集はClaude Code、自社プロダクトへの組み込みはAPIとAgent SDKが軸になります。

claude.ai・Claude Code・APIの違い

3形態を分けるのは機能の多さではなく、どこで動き、誰が実行を承認するかです。claude.aiとは、ブラウザーとデスクトップ・モバイルアプリから使う対話型のClaudeで、会話の中で文章やコードを生成し、Artifactsとして保持します。Claude Codeとは、リポジトリを読み書きしコマンドを実行するエージェント型のCLIツールで、ブラウザー版(claude.ai/code)やIDE拡張からも動きます。APIとは、https://api.anthropic.comのRESTエンドポイントで、自社アプリへClaudeを組み込むための窓口です。Agent SDKはこのAPIをラップし、ツール呼び出しとセッション管理を含む自律エージェントを構築するための公式SDKです。

違いは実行環境だけではありません。claude.aiは会話ごとに人が都度確認します。Claude Codeは権限モードとHooksで承認フローそのものを設計できます。APIは呼び出し元のアプリケーションコードが承認ロジックを持ちます。個々の機能の全体像はClaude Code完全ガイドにまとまっています。チャットとの能力比較はClaude AIとClaude Codeの違いにあります。エンジニア以外の職種でどう使われているかはClaudeの使い道まとめの早見表で確認できます。

claude.aiでコードを書き、動かすとき何ができるか

claude.aiは、会話の中でコード生成・実行・保存までを完結させる窓口です。生成したコードはArtifactsとして会話内に残り、ダウンロードして保存できます。エンジニアが見落としがちなのはProjects機能です。

Projectsは、チャット履歴と知識ベースを持つ独立した作業スペースです。仕様書やAPIドキュメント、既存コードをアップロードしておくと、そのプロジェクト内のすべての会話から参照されます。無料プランで作成できるプロジェクトは最大5つまでです。Pro以上の有料プランでは、知識量がコンテキストウィンドウの上限に近づくとRAG(検索拡張生成)が自動で有効になり、収容できる知識量が最大10倍まで拡張されます。

チャットにアップロードできるファイルはPDF・DOCX・CSV・TXT・HTML・ODT・RTF・EPUB・JSONと、画像(JPEG・PNG・GIF・WebP)です。Projectsの知識ベースはテキスト抽出が中心で、1ファイル30MBまでです(マルチモーダルPDFを除く)。XLSXも扱えますが、アカウント側でコード実行とファイル作成をあらかじめ有効にしておく必要があります。TeamやEnterpriseプランでは、プロジェクトを「閲覧のみ」「編集可」の権限で組織内に共有できます。仕様書を溜め込む共有ナレッジベースとして、チームで育てる使い方ができます。

Claude CodeはCLIから何を自動化できるか

Claude Codeは、読み取り専用の操作は無許可で実行し、ファイル編集・シェルコマンド・ネットワークアクセスのような影響の大きい操作で承認を求める権限モデルを採用しています。承認の挙動は6モードから選べます。

• default: 読み取り以外は都度確認する標準モード
• acceptEdits: ファイル編集と、mkdir・mvなどの基本的なファイル操作コマンドを自動承認する
• plan: 読み取りだけに限定する
• auto: バックグラウンドの安全性チェック付きで自動承認する
• dontAsk: 許可済み以外は自動で拒否する
• bypassPermissions: ほぼすべてのプロンプトを飛ばす

v2.1.287のclaude --helpでは、--permission-modeの選択肢にmanualが並び、defaultは出てきません。defaultはCLIでの表示名がManualになったモードの設定値です。manualは別名として使えます(v2.1.200以降)。autoが組み込みの既定になったのはv2.1.228以降(macOS・Linux・WSL)で、ネイティブWindowsではv2.1.233以降です。それ以前の既定はManualでした。

リポジトリの.claude/settings.jsonに書けば、チーム全員に同じ設定を配布できます。ただしdefaultModeにautoやbypassPermissionsを書いても、.claude/settings.jsonと.claude/settings.local.jsonでは効きません。この2つの値は~/.claude/settings.jsonなどユーザー側の設定に書く必要があります。

拡張の軸はMCPとHooksの2つです。MCP(Model Context Protocol)は、JiraやGitHub、Sentry、PostgreSQLのような外部ツールにClaudeを直接触らせる標準規格です。Kafkaのように公式サーバーがないミドルウェアでも、Kafka MCPサーバーでトピックとコンシューマーグループを調べるのような非公式実装で同じことができます。サーバー定義は個人用のlocal、チーム共有のproject(.mcp.jsonをリポジトリにコミット)、全プロジェクト共通のuserという3スコープに分かれます。DatadogやSentry、PagerDutyを組み合わせた障害対応ワークフローの設計はClaudeで監視ツール連携による障害対応ワークフローを設計するで扱っています。

# GitHubのMCPサーバーをチーム共有のproject scopeで追加
claude mcp add --scope project --transport http github \
  https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"
# Added HTTP MCP server github with URL: https://api.githubcopilot.com/mcp to project config
# Headers: { "Authorization": "[REDACTED]" }
 
# 追加した直後の状態(v2.1.287で確認)
claude mcp get github
# github:
#   Scope: Project config (shared via .mcp.json)
#   Status: ⏸ Pending approval (run `claude` to approve)
#   Type: http
#   URL: https://api.githubcopilot.com/mcp/

追加直後の状態は接続済みではなく承認待ちです。作業ディレクトリに作られる.mcp.jsonには、サーバーのtype・url・headersが入ります。headersには入力したトークンの文字列がそのまま書かれるので、リポジトリへコミットする前に${GITHUB_PAT}のような環境変数の参照に書き換えます。.mcp.jsonは${VAR}と${VAR:-default}の展開に対応しています。

claude.aiアカウントでログインしていれば、claude.ai側で設定したコネクタもそのままClaude Codeで使えます。仕組みの詳細はMCP実践ガイドにまとめています。

Hooksは、セッション開始からツール呼び出し前後、応答終了まで、公式の一覧に33イベントが並ぶライフサイクルに割り込める機構です。PreToolUseイベントにrm -rf検知用のスクリプトを登録すれば、危険な操作をツールの実行前に機械的に止められます。ハンドラはシェルコマンドだけでなく、HTTPエンドポイント・MCPツール・LLMによるプロンプト判定・サブエージェントの5種類から選べます。

PreToolUseの判定は、トップレベルのdecisionではなくhookSpecificOutputの中に書きます。トップレベルの旧形式は非推奨になりました。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "rm -rf は止めています"
  }
}

permissionDecisionはallow・deny・ask・deferの4値です。複数のフックが食い違う判定を返したときの優先順位はdeny、defer、ask、allowの順になります。スクリプトが終了コード2で終わっても、denyと同じ経路でstderrの文面がClaudeに渡ります。

APIとAgent SDKで組み込むときの設計軸

APIはhttps://api.anthropic.comのRESTエンドポイントです。Authorizationヘッダー(従来のx-api-keyも使えます)とanthropic-versionヘッダーを付けたリクエストが土台になります。中心はMessages API(POST /v1/messages)です。これに加えてToken Counting API・Models APIが正式提供され、大量のリクエストをまとめて処理しコストを50%削減できるMessage Batches APIも使えます。バッチのほとんどは1時間以内に処理が終わるため、レポート生成や大量分類のような即時応答が不要な用途に向き、非ストリーミングの同期リクエストが10分の壁に当たる長時間処理の回避先としても使えます。

アップロード済みファイルをfile_idで使い回せるFiles APIと、カスタムスキルを管理するSkills APIも通常のAPIとして提供されています。Claude Managed Agentsのクラウドサンドボックスでエージェントを走らせるAgents・Sessions・Environments APIは、ベータの扱いです。

リクエストの大きさにはエンドポイントごとの上限があります。MessagesとToken Countingは32MB、Message Batchesは256MB、Files APIは500MBです。超えるとrequest_too_largeの413エラーが返ります。

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-5-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello"}]}'

エンジニアリング寄りの機能として実務に効くのは構造化出力(structured outputs)です。output_config.formatでJSON出力そのものをスキーマに固定し、strict: trueでツール呼び出しの引数までスキーマ検証できます。対応モデルにはClaude Sonnet 4.5・Haiku 4.5・Opus 4.5以降の現行モデルやClaude Mythos系が並びます。JSON解析失敗やフィールド欠落を前提にした再試行ロジックが要らなくなります。

同じ「スキーマに合った出力」を、Claude Codeの非対話実行とAgent SDKで得る方法もあります。入口が違うだけで、どちらもツールを使った作業の最後に、検証済みのJSONを受け取れます。

CLIの--json-schemaは-pのときだけ使えます。v2.1.205より前は、不正なスキーマを黙って無視して通常のテキストを返していました。スキーマを渡したはずなのに構造化されない、というときはclaude --versionを見る価値があります。Agent SDKの導入手順はClaude Agent SDK入門にあります。

クライアントSDKはPython・TypeScript・C#・Go・Java・PHP・Rubyの7言語が公式提供です。認証ヘッダーの付与やリトライ、ストリーミングをSDK側が肩代わりします。AWS(Amazon BedrockまたはClaude Platform on AWS)・Google Cloud・Microsoft Foundry経由でもClaudeにアクセスできます。既存のクラウド契約や請求体系に統合したい場合の選択肢です。Bedrock経由で使う場合の直接APIとの違いとアクセス手順はAmazon BedrockでClaudeを使うにまとめています。

3形態をどう使い分けるか

機能を全部覚える必要はありません。シーンから逆引きすれば十分です。

MCPは3形態を横断する共通言語になっている

MCPは、claude.aiのコネクタ・Claude Codeのサーバー設定・Agent SDKのカスタムツールという3つの窓口を持つ共通の規格です。claude.ai側でコネクタを設定すれば、同じアカウントでログインしたClaude Codeにもその接続先が引き継がれます。Agent SDKでは、MCPサーバーをアプリケーションのプロセス内に定義してカスタムツールとして渡すことも、外部のMCPサーバーに接続することもできます。

3つの窓口で違うのは、誰が接続の可否を決めるかです。

サーバーを1つ作れば、どの窓口からも同じツールを呼べます。

エンジニアがハマりやすい落とし穴

bypassPermissionsモードは権限プロンプトのほとんどを飛ばし、保護されたパスの.gitや.claudeへの書き込みも素通りします。コンテナやVMのような隔離環境専用のモードです。denyルールはこのモードでも効くので、守りたいパスは先にdenyへ書いておけます。

クローンしたばかりのリポジトリで.mcp.jsonのサーバーが繋がらないときは、接続の不具合ではなく承認の手順が残っています。

v2.1.196以降は、claude mcp listとclaude mcp getも、信頼する前のフォルダーではリポジトリにコミットされていない設定ファイルの承認しか読みません。リポジトリの.claude/settings.jsonにenableAllProjectMcpServersなどを書いても、信頼前のフォルダーでは無視されます。クローンしたリポジトリが自分でサーバーを承認することはできません。

CIでは対話的な承認ができないため、--mcp-configで渡したサーバーだけを使う--strict-mcp-configが選択肢になります。v2.1.246以降は、読み込まない.mcp.jsonのサーバーの承認待ちで止まらなくなりました。

allowルールを足したのにブロックが解けない、というときはdeny規則を疑います。ルールはdeny、ask、allowの順に評価され、最初に当たったものが結果を決めます。Bash(aws *)という広いdeny規則があると、Bash(aws s3 ls)という狭いallow規則が別にあってもブロックされます。許可したい操作を通すには、denyパターン自体を狭める必要があります。

Files APIは、現在はベータヘッダーが要りません。以前のanthropic-beta: files-api-2025-04-14を付け続けても動きますが、応答は旧形式のままです。一覧はdataとhas_moreの形で返り、expires_atは含まれません。ヘッダーを外すと、一覧はnext_pageのカーソル形式に変わり、expires_atが必ず入ります。SDKではclient.beta.filesではなくclient.filesを使います。

よくある質問

claude.aiとClaude Codeは同じアカウント・料金プランで使えますか

同じアカウントで使えます。Claude CodeはPro・Max・Teamのプランに含まれるので、追加契約は不要です。旧Enterpriseプランではシート種別がClaude Code対応かを確かめる必要があります。会話から答えを受け取るならclaude.ai、手元の環境で作業させるならClaude Codeという使い分けになります。

自作のMCPサーバーをclaude.aiのコネクタとして公開できますか

公開できます。MCPサーバー自体の作り方はプロトコル標準の手順に従い、Connectors Directoryへの申請は、claude.ai/directory/manageの開発者ポータルから行います。個人用途ならClaude Codeのローカルスコープ登録だけで十分です。

APIの呼び出し量が急増した場合はどうなりますか

組織は利用量に応じたUsage tierに自動で割り当てられ、月間の支出上限とRPM・TPMのレート制限がかかります。Consoleの上限ページから引き上げをリクエストできます。

HooksとAgent SDKのカスタムツールは何が違いますか

Hooksはセッション開始やツール呼び出し前後といった既存のライフサイクルに割り込み、承認や記録、ブロックを行う仕組みです。カスタムツールはClaude自身が呼び出せる新しい能力を追加する仕組みで、目的が異なります。両方を組み合わせて、独自ツールの呼び出し前にHooksで検証を挟む構成も組めます。

まとめ

迷ったら「誰が実行を承認するか」で選びます。人が張り付けないCIでは、承認を設定とコードに落とせるかが分かれ目です。--strict-mcp-config、denyルール、Hooksがその手段になります。