複雑なワークフローのために、単一のエージェントとマルチエージェントのスウォームのどちらを選ぶか。
単一のエージェントとツールから始めます。タスクの境界が明確な場合、コンテキストウィンドウがオーバーフローする場合、またはサブタスクごとに異なるモデルティアが必要な場合にのみ、複数のエージェントに分割します。
理由: マルチエージェントは、レイテンシ、エラー発生源、オーケストレーションコストを増加させます。ほとんどの運用ワークロードは、適切にツール化された単一のエージェントで成功します。
最終確認：2026年5月
CCA-F 試験で問われるアーキテクチャパターンのスキャン可能なリファレンス。上から順に読むか、セクションへジャンプ。
複雑なワークフローのために、単一のエージェントとマルチエージェントのスウォームのどちらを選ぶか。
単一のエージェントとツールから始めます。タスクの境界が明確な場合、コンテキストウィンドウがオーバーフローする場合、またはサブタスクごとに異なるモデルティアが必要な場合にのみ、複数のエージェントに分割します。
理由: マルチエージェントは、レイテンシ、エラー発生源、オーケストレーションコストを増加させます。ほとんどの運用ワークロードは、適切にツール化された単一のエージェントで成功します。
エージェントは、再度行動する前に観測について推論する必要があります。
ReAct (Reason + Act) ループを実装します。モデルが思考を生成し、ツールを選択し、結果を受け取り、停止条件が満たされるまで繰り返します。
理由: ReAct は中間推論を可視化し、デバッグのしやすさを向上させ、思考の連鎖を監査できるようにします。
エージェントが外部システム（API、データベース、ファイルシステム）と対話する必要がある。
tool_use API を介してツールを定義します。モデルは tool_use ブロックを出力し、コードがそれを実行して tool_result を返します。その後、モデルが処理を続行します。
オーケストレーターが異種サブタスク（コードレビュー、ウェブ検索、データ分析）をディスパッチする必要がある。
目標を分解し、専門のサブエージェントに委任し、結果を集約するスーパーバイザーエージェントを使用します。各サブエージェントは独自のシステムプロンプトとツールセットを持ちます。
複数のサブエージェントが直接のピアツーピア通信なしで連携する必要がある。
すべてのエージェント間メッセージをスーパーバイザー経由でルーティングします。スーパーバイザーは次にどのサブエージェントを実行するかを決定し、コンテキストを渡し、順序付けの制約を強制します。
理由: 直接のピアメッセージングはサイクルを生み出し、状態の追跡を困難にします。中央のスーパーバイザーは、実行 DAG を明示的に維持します。
エージェントが複数ターンのセッション全体でコンテキストを記憶する必要がある。
メッセージ配列で会話履歴全体（システムプロンプトと以前のユーザー/アシスタントのターン）を渡します。長いセッションの場合は、コンテキストウィンドウ内に収まるように古いターンを要約します。
エージェントがセッション間またはユーザー間で永続性を必要とする。
事実を外部メモリレイヤー（ベクトルDB、キーバリューストア、ファイル）に保存します。RAG を介して関連するメモリを取得し、各ターンでシステムプロンプトに注入します。
チームがすべての LLM 機能に対してエージェントアーキテクチャをデフォルトとしている。
単一のプロンプトと構造化出力で十分な場合は、エージェントを使用しないでください。エージェントはレイテンシ、コスト、および障害モードを増加させます。反復またはツール使用を必要とするタスクのために、エージェントループを予約してください。
複雑な推論タスクにおいて、回答前にさらなる内部検討が必要である。
budget_tokens パラメータで拡張思考を有効にします。モデルは応答前に思考ブロックを使用し、多段階問題の精度を向上させます。
理由: 拡張思考はレイテンシと品質を交換します。budget_tokens をタスクの複雑さに比例して設定し、コストを制御するために上限を設けます。
ツール呼び出しがエラーを返した場合、エージェントは適切にリカバリする必要がある。
エラーを is_error: true とした tool_result として返します。モデルは失敗を認識し、修正されたパラメータで再試行したり、別のツールを試したり、ユーザーに失敗を説明したりできます。
エージェントループ中の断続的な API 障害（429、529）。
ジッター付き指数バックオフを実装します。429（レート制限）の場合は、retry-after ヘッダーを尊重します。529（過負荷）の場合は、より長くバックオフします。400クラスのエラーを盲目的に再試行しないでください。
エージェントシステムが時間とともに実際に改善されているかを測定する。
評価スイートを構築します。入出力ペアを定義し、エージェントを実行し、出力を評価します（完全一致、LLM-as-judge、人間によるレビュー）。リリースごとに合格率を追跡します。
理由: 評価がなければ、プロンプトの調整は当てずっぽうになります。回帰検出には、自動化された再現可能なスコアリングが必要です。
エージェントが最初のパスで低品質な出力を生成する。
自己反省ステップを追加します。回答を生成した後、モデルに自身の出力を批判させ、修正するように促します。別のメッセージターンまたは拡張思考を使用します。
エージェントワークフローが不可逆的なアクション（リソースの削除、メール送信）を実行する。
破壊的な操作の前にチェックポイントを挿入します。計画されたアクションをユーザーに提示し、承認を待ってから実行します。監査のために決定をログに記録します。
モノレポ内に複数の CLAUDE.md ファイルがあり、どれが優先されるか不明。
3つの階層があります。~/.claude/CLAUDE.md（ユーザー）、プロジェクトルートの CLAUDE.md（プロジェクト）、ワークスペースの子の CLAUDE.md（ワークスペース）です。これらはすべてマージされ、ワークスペースがプロジェクトを、プロジェクトがユーザーをオーバーライドします。
チームが /my-command として呼び出される再利用可能なプロンプトを求めている。
プロンプトテンプレートを含む .claude/commands/<name>.md ファイルを作成します。/<name> で呼び出します。ユーザー入力には $ARGUMENTS を使用します。プロジェクトスコープのコマンドはリポジトリに存在します。
Claude がファイルを編集した後、自動的にリンターを実行する。
settings.json で Write/Edit ツールに一致する PostToolUse フックを構成します。フックスクリプトはツールが完了した後に実行され、ゼロ以外の終了コードは変更をブロックします。
Claude Code がすべてのシェルコマンドで許可を求め、イテレーションを遅くしている。
settings.json の permissions.allow に許可リストパターンを使用します。3つのモードがあります。default（各コマンドでプロンプトを表示）、allowlist（一致するパターンを自動承認）、yolo（すべて自動承認 - 本番環境では非推奨）です。
開発者がリポジトリにコミットされない個人用のオーバーライドを求めている。
settings.json はコミットされます（チームのデフォルト）。settings.local.json は gitignore されます（個人のオーバーライド）。ローカル設定はプロジェクト設定の上にマージされます。
インタラクティブなターミナルなしで CI パイプラインで Claude Code を実行する。
ヘッドレスモードで `claude -p "prompt" --output-format json` を使用します。stdin 経由で入力をパイプし、構造化された出力を解析します。ANTHROPIC_API_KEY を CI シークレットとして設定します。
Claude Code がカスタム MCP サーバー（データベース、内部 API）へのアクセスを必要とする。
settings.json の mcpServers にコマンドと引数でサーバーを追加します。Claude Code は MCP サーバーを子プロセスとして起動し、起動時にツールを検出します。
メインブランチで開発中に、Claude Code がフィーチャーブランチで作業している。
git worktrees を使用します。Claude Code はワークツリーディレクトリで操作され、メインチェックアウトは変更されません。インデックスの衝突やスタッシュのやりくりを回避します。
Claude Code が変更を生成したが、クリーンなアトミックコミットをしたい。
Claude Code はファイルの変更を追跡し、メッセージ付きのコミットを作成できます。コミットする前に差分を確認してください。機密情報の漏洩を防ぐために、`git add -A` よりも特定のファイルをステージングすることを推奨します。
VS Code または JetBrains から Claude Code を使用する。
Claude Code 拡張機能をインストールします。これは CLI を IDE 内のパネルとして組み込み、同じ CLAUDE.md、フック、設定を共有します。ターミナルベースと IDE ベースのセッションは交換可能です。
複数のセクションを持つ長いプロンプトで、モデルが指示とデータを混同する。
セクションを <instructions>、<context>、<examples> のような XML タグで囲みます。Claude は XML の境界を構造的な区切り文字として尊重するようにトレーニングされています。
すべてのターンで永続的な動作（トーン、制約、ペルソナ）を定義する。
システムプロンプトに不変の指示を配置します。役割、制約、出力形式を簡潔に保ちます。ユーザーメッセージはターンごとのコンテキストを運び、システムプロンプトはセッション全体のルールを運びます。
モデルに特定のプレフィックス（例：JSON の開始ブレース）で応答を開始させる。
messages 配列の最後に部分的なアシスタントメッセージを追加します。Claude は中断したところから続行します。これは出力形式を強制するのに役立ちます。
詳細な指示にもかかわらず、モデルの出力形式が一貫しない。
実際のクエリの前に、ユーザー/アシスタントのターンペアとして2～3個の少量の例を追加します。例は、散文の指示よりも確実に形式、トーン、推論スタイルを定着させます。
モデルが多段階論理問題の推論ステップをスキップする。
「Think step by step」というプロンプトを使用するか、拡張思考を使用します。本番環境では、出力をきれいに保つために、可視化された思考の連鎖を促すのではなく、拡張思考（budget_tokens）を使用します。
決定論的な出力と創造的な出力のどちらかを選択する。
決定論的なタスク（分類、抽出）には temperature=0 を使用します。創造的なライティングには temperature=0.5-0.7 を使用します。最大の多様性には temperature=1.0 を使用します。注意：拡張思考には temperature=1 が必要です。
モデルから確実に有効な JSON 出力が必要である。
目的の JSON スキーマを input_schema として持つツールを定義します。tool_choice を設定してそのツールを強制的に使用させます。モデルは tool_use ブロックで構造化された JSON を返し、スキーマに対して検証されます。
ユーザー向けアプリケーションが低い Time-To-First-Token を必要とする。
Messages API で stream=true を使用します。サーバー送信イベントを増分的に処理します。content_block_start、content_block_delta、message_stop。トークンが到着するにつれて表示します。
レイテンシが重要ではない数千のプロンプトを処理する。
Message Batches API を使用します。バッチあたり最大10万件のリクエストを送信できます。結果は24時間以内に届き、コストは50%削減されます。完了のためにポーリングまたはウェブフックを使用します。
スキャンされたドキュメントや画像からデータを抽出する。
ユーザーメッセージで画像を base64 コンテンツブロック（type: image）または PDF ページ（type: document）として渡します。Claude はリクエストあたり最大20 MBを処理します。テキストの多いドキュメントには、スクリーンショットよりもネイティブ PDF を推奨します。
ワークロードに対して Opus、Sonnet、Haiku のいずれかを選択する。
Opus：最高の機能、複雑な推論、エージェントタスク。Sonnet：パフォーマンスとコストのバランスが取れており、一般的な本番環境での使用。Haiku：最速かつ最も安価で、分類、ルーティング、簡単な抽出に適しています。
繰り返される呼び出しが同じ長いシステムプロンプトを共有しており、コストを削減したい。
キャッシュ可能なコンテンツを cache_control: { type: "ephemeral" } でマークします。キャッシュされたプレフィックスは、最大5分間（ヒット時に自動延長）呼び出し間で再利用されます。書き込みコストは25%増、読み取りコストは90%減です。
Claude Messages API のツールを定義する。
各ツールには名前、説明、input_schema（JSON スキーマ）があります。説明は Claude にいつそのツールを使用するかを伝え、スキーマはパラメータを検証します。説明はアクション指向で簡潔に保ちます。
ツールが正常に実行され、結果を Claude に返す必要がある。
role: "user" と tool_result コンテンツブロックを含むユーザーメッセージを送信します。関連付けのために tool_use_id を含めます。データをテキストまたは構造化コンテンツとして返します。ペイロードは10万トークン未満に保ちます。
エージェントが3つの独立したソースから同時にデータをフェッチする必要がある。
Claude は単一の応答で複数の tool_use ブロックを出力できます。それらを並行して実行し、すべての tool_result ブロックを1つのユーザーメッセージで返します。これによりラウンドトリップが削減されます。
Model Context Protocol のコンポーネントモデルを理解する。
3つの役割があります。Host（Claude Code のようなアプリケーション）、Client（サーバーごとのプロトコルハンドラー）、Server（ツール/リソース/プロンプトを公開）。クライアントはサーバーと1対1の接続を維持します。
MCP クライアントがサーバーに接続する方法を選択する。
stdio：ローカルプロセス、最も簡単なセットアップ。SSE：HTTPベース、レガシー。Streamable HTTP：リモートサーバーの現在の標準、再開可能でサーバー開始メッセージをサポート。
どの MCP プリミティブを公開するかを決定する。
リソース：クライアントがプルする読み取り専用データ（ファイル、DB 行）。ツール：モデルが呼び出すアクション（書き込み、計算、クエリ）。プロンプト：ユーザーが選択する再利用可能なプロンプトテンプレート。ツールはモデル制御、リソースはアプリケーション制御です。
内部 API を公開するためのカスタム MCP サーバーを作成する。
MCP SDK（TypeScript または Python）を使用します。入力スキーマを持つツールハンドラーを実装します。server.tool() を介して登録します。トランスポート：ローカルには stdio、リモートには streamable HTTP を使用します。
エージェントが GUI アプリケーション（クリック、タイピング、スクリーンショット）と対話する必要がある。
コンピューター使用ツールを有効にします。computer_20250124（スクリーンショット＋マウス＋キーボード）、text_editor_20250124、bash_20250124。モデルはスクリーンショットを受け取り、座標ベースのアクションを出力します。
モデルがテキストで応答するのではなく、常に特定のツールを呼び出す必要がある。
tool_choice を { type: "tool", name: "my_tool" } に設定します。モデルはそのツールを強制的に呼び出します。何らかのツール呼び出しを必須にするには type: "any" を使用し、モデルに決定させるには type: "auto"（デフォルト）を使用します。
アプリケーションが会話中にコンテキスト制限に達する。
Claude モデルは20万トークンをサポートします。response.usage を介して使用量を監視します。制限に近づいたら、古いターンを要約するか、切り捨てます。決してメッセージをサイレントにドロップしないでください。
コンテキストウィンドウのほとんどを占める150ページのドキュメントを処理する。
ドキュメントをプロンプトの早い段階（システムプロンプトの後）に配置します。質問を最後に置きます。フォローアップで再送信を避けるためにプロンプトキャッシュを使用します。複数ドキュメントのタスクには、RAG を使用して関連するチャンクを選択します。
ナレッジベースが大きすぎてコンテキストに収まらないため、クエリ時にモデルがアクセスする必要がある。
ドキュメントをベクトルストアに埋め込み、インデックス化します。クエリ時に上位 k 個のチャンクを取得し、ユーザーメッセージに挿入します。トレーサビリティのために出力にソースドキュメントを引用します。
モデルが自信を持って誤った事実を述べる。
提供されたコンテキスト（RAG）に基づいて応答を根拠づけます。証拠が不十分な場合は「I don't know」と答えるようモデルに指示します。引用を使用します。事実の主張をソースドキュメントとプログラム的に照合して検証します。
アプリケーションが 429（レート制限）または 529（過負荷）の応答を受け取る。
429：ティアのレート制限に達しました。バックオフして再試行し、retry-after を尊重します。529：Anthropic API が過負荷です。より長くバックオフします。どちらも一時的なものです。400または401は決して再試行しないでください。
月額の API 費用が予想よりも高い。
繰り返されるプレフィックスにはプロンプトキャッシュを使用します（読み取り割引90%）。単純なタスクは Haiku にルーティングします。非同期ワークロードには Batch API を使用します（50%割引）。エンドポイントごとのトークン使用量を監視します。不要なコンテキストを削減します。
リクエストごとのトークン消費量を可視化する必要がある。
すべての Messages API レスポンスには、usage.input_tokens、usage.output_tokens、および（キャッシュされている場合）usage.cache_read_input_tokens が含まれます。これらを呼び出しごとにログに記録し、エンドポイントごとに集計し、予算アラートを設定します。