Claude アーキテクチャバリアント

概要

Claude搭載アプリケーション向けの5つのアーキテクチャパターン：チャットボット（ステートレスAPIラッパー）、RAG（検索拡張生成とベクトル検索）、エージェント（ツール使用ループ）、コンテンツパイプライン（バッチ処理）、および評価（Claudeを判定者として使用）。各パターンに完全なコードと比較表が含まれます。

1. チャットボット（ステートレスAPIラッパー）

最もシンプルなパターン — Claudeをシステムプロンプトでプロキシします。

// api/chat.ts
export async function POST(req: Request) {
  const { messages } = await req.json();
  const response = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 2048,
    system: 'You are a helpful assistant for our SaaS product.',
    messages,
    stream: true,
  });
  return new Response(response.toReadableStream());
}

最適な用途： カスタマーサポート、Q&A、シンプルな会話インターフェース。

2. RAG（検索拡張生成）

関連コンテキストを取得して、プロンプトに注入し、根拠のある回答を生成します。

async function ragQuery(question: string) {
  // 1. 質問をエンベッドします（Voyage、OpenAI、またはCohere を使用 — Anthropicではありません）
  const embedding = await embeddingClient.embed(question);

  // 2. ベクトルDBで関連チャンクを検索します
  const chunks = await vectorDb.query(embedding, { topK: 5 });

  // 3. コンテキスト付きでClaudeに送信します
  const message = await client.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 2048,
    system: `提供されたコンテキストに基づいて回答してください。コンテキストに答えが含まれていない場合はそう述べてください。`,
    messages: [{
      role: 'user',
      content: `Context:\n${chunks.map(c => c.text).join('\n---\n')}\n\nQuestion: ${question}`,
    }],
  });
  return message.content[0].text;
}

最適な用途： ドキュメントQ&A、ナレッジベース、ソース引用付きのサポート。

3. エージェント（ツール使用ループ）

Claudeが呼び出すツールを決定し、あなたがそれらを実行して、完了するまでループします。

async function agentLoop(userInput: string, tools: Anthropic.Tool[]) {
  let messages: MessageParam[] = [{ role: 'user', content: userInput }];

  while (true) {
    const response = await client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 4096,
      tools,
      messages,
    });
    messages.push({ role: 'assistant', content: response.content });

    if (response.stop_reason === 'end_turn') {
      return response.content.find(b => b.type === 'text')?.text;
    }

    // ツールを実行します
    const results = [];
    for (const block of response.content) {
      if (block.type === 'tool_use') {
        const result = await executeTool(block.name, block.input);
        results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(result) });
      }
    }
    messages.push({ role: 'user', content: results });
  }
}

最適な用途： データ分析、コード生成、マルチステップワークフロー。

4. コンテンツパイプライン（バッチ処理）

数千のドキュメントを非同期でClaudeを通じて処理します。

const batch = await client.messages.batches.create({
  requests: documents.map((doc, i) => ({
    custom_id: doc.id,
    params: {
      model: 'claude-haiku-4-5-20251001', // 大量処理用の低コスト
      max_tokens: 512,
      messages: [{ role: 'user', content: `Extract entities: ${doc.text}` }],
    },
  })),
});
// 50%安くなり、24時間以内に処理されます

最適な用途： 要約、分類、大規模抽出。

5. 評価／採点

Claudeを使用して他のAI出力または人間作成のコンテンツを評価します。

const evaluation = await client.messages.create({
  model: 'claude-opus-4-20250514', // 最高の判定性能
  max_tokens: 1024,
  system: `あなたは専門家の評価者です。正確性、関連性、完全性について1～5の評点を付けてください。JSON形式で返してください：{ "accuracy": N, "relevance": N, "completeness": N, "reasoning": "..." }`,
  messages: [{
    role: 'user',
    content: `Question: ${question}\nResponse to evaluate: ${candidateResponse}`,
  }],
});

最適な用途： AI出力品質、コンテンツモデレーション、自動採点。

パターン選択ガイド

パターン	レイテンシ	コスト	複雑性
チャットボット	低（ストリーミング）	低	シンプル
RAG	中（エンベッド＋検索＋生成）	中	中
エージェント	高（マルチターン）	高	複雑
パイプライン	高（非同期バッチ）	低（50%割引）	シンプル
評価	中	様々	シンプル

出力

• 要件に基づいて選択されたアーキテクチャパターン
• 選択したパターンの実装コード
• コストとレイテンシ特性の理解
• スケーリング戦略の特定（チャットボットのストリーミング、パイプラインのバッチ）

エラーハンドリング

エラー	原因	解決策
APIエラー	エラータイプとステータスコードを確認	clade-common-errors を参照

例

完全なTypeScriptコード付きの5つのパターンセクション、およびレイテンシ、コスト、複雑性の評点を含むパターン選択ガイド比較表を参照してください。

リソース

• ツール使用ガイド
• プロンプトエンジニアリング

次のステップ

一般的な間違いについては clade-known-pitfalls を参照してください。

前提条件

• clade-install-auth と clade-model-inference が完了していること
• ユースケース要件（レイテンシ、コスト、複雑性）の理解
• RAG の場合：ベクトルデータベースとエンベッディングモデル（Voyage、OpenAI、またはCohere）

説明

ステップ1：以下のパターンをレビューします

各セクションには本番環境対応のコード例が含まれています。ユースケースに合わせてコピーして調整します。

ステップ2：コードベースに適用します

要件に合致するパターンを統合します。各変更を個別にテストします。

ステップ3：検証します

テストスイートを実行して、統合が正しく機能することを確認します。