「とりあえず動かしてみよう」とAPIを叩き続けた結果、月末に想定外の請求が届く——Claude APIを本番導入する前に、こうした経験をしたことはないでしょうか。プロンプトの微妙なズレやエラーハンドリングの漏れは、ローカルで丁寧に検証しておくほど後工程がラクになります。この記事では、ローカルテスト環境を整えてコストを抑えながらデバッグ精度を上げる方法を、実装例を交えて紹介します。

ローカルでプロンプトを繰り返し検証する理由

プロンプトエンジニアリングの難しさは、「少し変えただけで出力が大きく変わる」点にあります。本番コードにプロンプトを直接埋め込んでデプロイを繰り返すのは、APIコストだけでなくデバッグサイクルの遅さという問題も招きます。

ローカルに軽量なテストスクリプトを用意しておくと、次の恩恵が得られます。

• 反復速度の向上：プロンプト変更→即実行→結果確認のサイクルをデプロイなしで回せる
• コスト削減：必要な検証だけに絞り、不要なAPI呼び出しを減らせる
• 再現性の確保：同じ入力に対して同じ条件でテストできる

プロンプト検証の段階ではclaude-haikuなど軽量モデルを使い、最終確認だけ本番モデルに切り替える運用がコスト面で効果的です。

プロンプト検証用スクリプトの書き方

Node.jsとPythonそれぞれの基本的な検証スクリプトを見ていきましょう。

Node.js の例

// test-prompt.mjs
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function testPrompt(systemPrompt, userMessage) {
  const response = await client.messages.create({
    model: "claude-haiku-4-5", // ローカル検証は軽量モデルで
    max_tokens: 1024,
    system: systemPrompt,
    messages: [{ role: "user", content: userMessage }],
  });

  const usage = response.usage;
  console.log(`[Usage] input: ${usage.input_tokens}, output: ${usage.output_tokens}`);
  return response.content[0].text;
}

const testCases = [
  {
    label: "正常系: 日本語要約",
    system: "あなたは文章の要約アシスタントです。",
    user: "以下を100字以内で要約してください:\n...",
  },
  {
    label: "異常系: 空文字入力",
    system: "あなたは文章の要約アシスタントです。",
    user: "",
  },
];

for (const tc of testCases) {
  console.log(`\n=== ${tc.label} ===`);
  const result = await testPrompt(tc.system, tc.user);
  console.log(result);
}

Python の例

# test_prompt.py
import os
import anthropic

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

def test_prompt(system_prompt: str, user_message: str) -> str:
    response = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=1024,
        system=system_prompt,
        messages=[{"role": "user", "content": user_message}],
    )
    usage = response.usage
    print(f"[Usage] input: {usage.input_tokens}, output: {usage.output_tokens}")
    return response.content[0].text

if __name__ == "__main__":
    result = test_prompt(
        system_prompt="あなたは丁寧なカスタマーサポート担当です。",
        user_message="返品方法を教えてください。",
    )
    print(result)

トークン使用量を毎回ログに出力するのがポイントです。プロンプトのバリエーションごとに消費トークン数を把握しておくと、本番モデルへ切り替えるタイミングで費用感を予測しやすくなります。

レスポンスをファイルに保存して差分を確認する

プロンプトを少し変えたとき、出力がどう変わったかを目視で確認するのは限界があります。レスポンスをJSONファイルに保存して差分を取る仕組みを作ると、変更の影響を把握しやすくなります。

# save_response.py
import json, hashlib, pathlib, datetime

def save_response(label: str, prompt_hash: str, response_text: str):
    output_dir = pathlib.Path("test_outputs")
    output_dir.mkdir(exist_ok=True)

    filename = output_dir / f"{label}_{prompt_hash[:8]}.json"
    data = {
        "label": label,
        "prompt_hash": prompt_hash,
        "timestamp": datetime.datetime.utcnow().isoformat(),
        "response": response_text,
    }
    filename.write_text(json.dumps(data, ensure_ascii=False, indent=2))
    return filename

def get_prompt_hash(system: str, user: str) -> str:
    return hashlib.sha256(f"{system}\n{user}".encode()).hexdigest()

保存したファイルはgit diffでテキストレベルの差分を確認したり、pytestと組み合わせてスナップショットテストとして活用できます。プロンプト変更前後の出力を記録しておくと、リグレッションの検出が楽になります。

test_outputs/ディレクトリはリポジトリに含めて変更履歴を追うのがおすすめです。ただし、.gitignoreでAPIキーや機密情報を含むファイルが混入しないよう注意してください。

段階的チェックフロー：単体→統合→本番前確認

ローカル検証が整ったら、CI/CDへ組み込む前に段階的なチェックフローを設計します。

ステージ1：単体テスト（ローカル）

• プロンプトの形式チェック（必須フィールドの存在確認など）
• モックまたはキャッシュしたレスポンスを使ったロジックテスト
• APIを実際に呼ばないため、コストゼロ

def test_prompt_format():
    system = build_system_prompt(language="ja")
    assert len(system) < 4000, "システムプロンプトが長すぎます"
    assert "{{user_name}}" not in system, "未置換のプレースホルダが残っています"

ステージ2：統合テスト（ローカルまたはステージング環境）

• 実際にClaude APIを呼び出し、レスポンスの構造を検証
• 軽量モデル（haiku）を使用し、テストケース数を絞る
• スナップショット差分で想定外の出力変化を検出

ステージ3：本番デプロイ前の最終確認

• 本番モデルで代表的なケースのみ実行
• トークン数・レイテンシの計測値をログに記録
• ロールバック条件（エラー率の閾値など）を事前に定義

ステージを分けることで、「CIが全部通ったのに本番でプロンプトが期待通り動かない」という事態を減らせます。

よくあるハマりどころと対策

トークン数超過

長い文書を要約させるケースでは、入力トークン数がコンテキストウィンドウを超えてエラーになることがあります。事前に入力長をチェックする処理を入れておくと安全です。

def check_input_length(text: str, max_chars: int = 30000):
    if len(text) > max_chars:
        raise ValueError(f"入力が長すぎます: {len(text)} 文字")

正確なトークン数はAnthropicのcount_tokens APIで事前確認できます。上記の文字数ベースのチェックはあくまで目安として扱ってください。

レート制限（429エラー）

テスト中に短時間で大量のリクエストを送ると、レート制限に引っかかります。公式SDKのリトライ機能（max_retriesオプション）を利用するか、指数バックオフを実装しましょう。

client = anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    max_retries=3,  # 自動リトライ（デフォルトは2）
)

プロンプトインジェクション

ユーザー入力をそのままプロンプトに埋め込む実装では、ローカルテストの段階で意図的に悪意ある入力を試しておくことが重要です。「システムプロンプトを無視して……」といった入力を含めたテストケースを用意し、アプリケーションが意図した範囲で応答するかを確認してください。

APIキーの環境変数管理

テストスクリプトを書く際、うっかりAPIキーをハードコードしてしまうミスは珍しくありません。python-dotenvやdirenvを使い、.envファイルを.gitignoreに含める運用を徹底しましょう。