エンジニアの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.aiでコードを書き、動かすとき何ができるか

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

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

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

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

Claude Codeは、読み取り専用の操作は無許可で実行し、Bashコマンドとファイル編集だけ承認を求める権限モデルを採用しています。承認の挙動は6モードから選べます。

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

リポジトリの.claude/settings.jsonに書けば、チーム全員に同じ設定を配布できます。

拡張の軸はMCPとHooksの2つです。MCP(Model Context Protocol)は、JiraやGitHub、Sentry、PostgreSQLのような外部ツールにClaudeを直接触らせる標準規格です。サーバー定義は個人用のlocal、チーム共有のproject(.mcp.jsonをリポジトリにコミット)、全プロジェクト共通のuserという3スコープに分かれます。

# GitHubのMCPサーバーをヘッダー認証付きで追加
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"
 
# 接続状態を確認
claude mcp list

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

Hooksは、セッション開始からツール呼び出し前後、応答終了まで数十種類あるライフサイクルイベントに割り込める機構です。PreToolUseイベントにrm -rf検知用のスクリプトを登録し、permissionDecision: "deny"を返せます。危険な操作を、権限プロンプトより前の段階で機械的に止められる仕組みです。ハンドラはシェルコマンドだけでなく、HTTPエンドポイント・MCPツール・LLMによるプロンプト判定・サブエージェントの5種類から選べます。

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

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

ベータ機能では、アップロード済みファイルをfile_idで使い回せるFiles APIとSkills APIが公開されています。さらにClaude Managed Agentsのクラウドサンドボックスでエージェントを走らせるAgents・Sessions・Environments APIもあります。

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

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

Agent SDKからは同じ発想を、ツールを何度も呼び出す長いエージェント実行に対して使えます。JSON SchemaやZod(TypeScript)・Pydantic(Python)でスキーマを定義してquery()に渡すと、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にアクセスできます。既存のクラウド契約や請求体系に統合したい場合の選択肢です。

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

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

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

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

3つの窓口で違うのは、誰が接続の可否を決めるかです。claude.aiのコネクタはTeam・Enterpriseプランなら管理者が組織単位で追加・制御します。Claude Codeはリポジトリの.mcp.jsonに定義を書けば承認待ちの状態でチームに配布され、各メンバーが個別に承認します。Agent SDKはアプリケーションのコード自体がMCPサーバーの構成を決めるため、承認フローはプロダクト側の設計に委ねられます。エンジニアがMCPサーバーを1つ作れば、3形態のどこからでも同じツールを呼び出せる。これがMCPをエコシステムの土台にしている理由です。

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

bypassPermissionsモードは権限プロンプトのほとんどを飛ばします。.gitや.claudeへの書き込みも素通りするため、コンテナやVMのような隔離環境以外で使うと、意図しない変更を止める手段がなくなります。

クローンしたばかりのリポジトリで.mcp.jsonのサーバーが繋がらない、という報告は珍しくありません。プロジェクトスコープのMCPサーバーは承認待ちの状態で配布され、各メンバーがclaudeを対話的に起動してワークスペースの信頼ダイアログを受け入れるまで接続されません。CIでそのまま動かそうとして接続失敗に気づくことがあります。

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

Files APIはベータ機能です。curlから直接呼ぶ場合はanthropic-beta: files-api-2025-04-14ヘッダーが必須です。公式SDKのbeta.files名前空間経由なら自動で付きますが、素朴に同じクライアントで呼ぶとエラーになります。

応答速度や検索の粒度が変わったと感じたら、まず知識ベースの容量を疑います。ProjectsのRAGモードは手動でオフにできず、知識量がコンテキスト上限に近づけば自動で切り替わり、下回れば自動で戻ります。チーム全員が同じ挙動を体験するとは限りません。

よくある質問

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

同じアカウントで使え、Proプラン以上なら追加契約は不要です。会話から答えを受け取るならclaude.ai、手元の環境で作業させるならClaude Codeという使い分けになります。

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

公開できます。MCPサーバー自体の作り方はプロトコル標準の手順に従い、認証・テスト・Directoryへの申請はAnthropic側が公開しているコネクタ構築ドキュメントに従う必要があります。個人用途ならClaude Codeのローカルスコープ登録だけで十分です。

Claude Codeから構造化出力を直接指定できますか

Messages APIのoutput_config.formatに相当する指定は、Claude Codeの対話利用には用意されていません(CLIの--output-formatは応答の受け渡し形式で、スキーマ制約ではありません)。同じ「型が保証された出力」をアプリに組み込みたい場合は、Agent SDKのoutputFormat(TypeScript)/output_format(Python)を使います。

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

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

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

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

まとめ

3形態の選び方は、モデルの賢さではなく実行環境と承認の主体で決まります。単発の調査や知識の蓄積はclaude.aiのProjects。リポジトリへの自律的な作業はClaude CodeのMCPとHooks。プロダクトへの組み込みはAPIとAgent SDKの構造化出力です。境界線を引く軸さえ持てば、どの窓口から入っても同じClaudeモデルの上で一貫した設計ができます。