---
title: 本番環境向けチェックリスト
url: https://doc.liz6.com/ja/ai/03-applications-and-production/05-production-checklist
locale: ja
area: ai
tags:
- ai
- applications-and-production
date: 2026-06-30
modified: 2026-07-19
description: これまでの全章を「評価セットの作成」から「グレープリリース」、そして「オンラインでの失敗ごとに回帰テストを追加」というリリースライフサイクルへと結びつけます。これはAIセクションの最終ページであり、いつでも参照できるチェックリストです。
---
# 本番環境向けチェックリスト
> これまでの全章を「評価セットの作成」から「グレープリリース」、そして「オンラインでの失敗ごとに回帰テストを追加」というリリースライフサイクルへと結びつけます。これはAIセクションの最終ページであり、いつでも参照できるチェックリストです。
## 概要
これまでの10数章では、モデル、コンテキスト、エージェント、アプリケーションパターンを個別に解説しました。本章ではその逆で、**LLM/エージェントアプリケーションのリリース順序に従ってそれらを結びつけ**、総括的なまとめとして、かつチェック可能なチェックリストとして機能させます。
一貫して貫かれる2つの核心的な信念があります。
- **評価なしに改善はあり得ない。** プロンプトを変更し、モデルを交換し、ツールを追加したとして、なぜ「良くなった」と言えるのか？——それは勘ではなく、評価（eval）によるものです（[評価と観測可能性](/ai/02-Agent/05-evaluation-and-observability.md)参照）。
- **リリースするかどうかをまず確認し、次に方法について議論する。** [ワークフロー](/ai/02-Agent/01-the-agent-loop-and-tool-use.md) で記述できるものはエージェントにせず、[単一エージェント](/ai/02-Agent/04-multi-agent-orchestration.md) で対応できるものはマルチエージェントにしない——最も安定したシステムは、最もシンプルなものです。
## リリースライフサイクル
```mermaid
flowchart TD
A["① レベルの選択
ワークフロー？エージェント？マルチエージェント？"] --> B["② 評価セットの構築
小さく現実的、境界ケースを含む"]
B --> C["③ プロンプト/モデル/イフェルトの調整
評価セットに対して調整"]
C --> D["④ 保護の導入
サンドボックス/権限/インジェクション/シークレット"]
D --> E["⑤ 観測可能性の接続
トレース + 使用量 + 停止理由"]
E --> F["⑥ グレープリリース
少量トラフィック、ロールバック可能"]
F --> G["⑦ オンラインでの失敗
回帰評価として固定"]
G --> C
```
以下、各段階ごとのチェック項目を示します。各項目は、詳細な解説がある該当章へのリンクを指しています。
## ① レベルの選択：安易にエージェントを使わない
エージェントを導入する前に、[4つの関門](/ai/02-Agent/01-the-agent-loop-and-tool-use.md) を通過してください（いずれかでも「No」であれば、よりシンプルなレベルに戻ってください）。
- [ ] **複雑さ**: タスクが複数ステップに分かれており、事前に完全に規定できないか？（フローをハードコードできる場合 → ワークフローを使用）
- [ ] **価値**: その結果は、より高いコストとレイテンシに見合うか？
- [ ] **実現可能性**: モデルは本当にこの種の仕事が得意か？
- [ ] **エラーのコスト**: 失敗した場合に検知およびロールバックできるか？（テスト/監査/フォールバックがあるか）
マルチエージェントの場合、さらに1つ質問を追加します。**単一エージェント＋良いツールでは解決できない場合にのみ、マルチエージェントを採用する**（[マルチエージェント オーケストレーション](/ai/02-Agent/04-multi-agent-orchestration.md)参照）——マルチエージェントは調整オーバーヘッド、コンテキスト同期、デバッグの複雑さを導入します。
## ② まず評価セットを作り、調整を始める
**最も重要なプラクティス：手を動かす前に、小さく現実的な評価セットを持つこと。** 20件程度の代表性のあるタスク（既知の失敗ケースや境界ケースを含み、ハッピーパスだけでなく）でも、単一の勘に頼るよりもはるかに優れています（[評価と観測可能性](/ai/02-Agent/05-evaluation-and-observability.md)参照）。
- [ ] 評価セットには、順調なシナリオだけでなく**失敗/境界ケース**が含まれている。
- [ ] 採点は信頼性の高い順：**プログラム可能な検証** > LLM-as-judge > 結果スコアリング。`assert` で検証できる場合は審判を呼ばない——[構造化出力](/ai/03-applications-and-production/02-prompt-engineering-and-structured-output.md) を用いることで、この種の検証を安定して実行可能にする。
- [ ] LLM 審判は**テスト対象から分離する**（自己採点を避ける）、**独立して判定可能な**ルーブリックを与える。
## ③ 勘ではなく評価セットに対して調整する
- [ ] **プロンプト**: 「必須」を羅列するのではなく、「いつ/境界」を記述する。正例は反例よりも優れている（[プロンプトエンジニアリング](/ai/03-applications-and-production/02-prompt-engineering-and-structured-output.md)参照）。
- [ ] **イフェルト (effort)**: 最初は `high` で始め、評価セット上で `medium`/`high`/`xhigh` をスキャンして決定する——関係性は単調ではない（[推論と思考](/ai/01-models-and-context/04-reasoning-and-thinking.md)参照）。
- [ ] **サンプリングパラメータ**: 新モデルでは既に削除されている。旧コードの `temperature` は削除し、プロンプトとイフェルトに置き換える。
- [ ] **出力形状**: 下流に渡す場合は `output_config.format` / `strict` を使用する。「JSONを返してください」という頼みに頼らないこと。
- [ ] **知識**: 私有/リアルタイム知識は [RAG](/ai/03-applications-and-production/01-rag-and-retrieval-augmented-generation.md) を通じて処理し、生成を調整する前にまず recall@k を最大化する。
- [ ] **コンテキスト予算**: 安定するまでプレフィックスを固定して[キャッシュ](/ai/01-models-and-context/01-context-engineering.md)を確保し、動的なコンテンツは後続に配置する。長文の会話には圧縮 (compaction) やコンテキスト編集を使用する。
## ④ 保護の導入：モデルの出力は信頼できないものとする
リリース前に、[セキュリティと保護](/ai/03-applications-and-production/04-security-and-protection.md) のゲートをすべて設置する。
- [ ] **bash/ツール**: 隔離された環境 + 許可リスト + タイムアウト + ログ；コマンドは信頼できない出力として扱う。
- [ ] **パス**: 正規化 + 境界検証、`..`/シンボリックリンク/URLエンコードされたトラバーサルを拒否する。
- [ ] **危険な操作**: 不可逆的な操作はヒューマン・イン・ザ・ループとし、可逆性に基づいて階層化し、最小権限を適用する。
- [ ] **インジェクション**: ツールの出力はデータとして扱い、指示として扱わない。オペレータの指示は `role:system` の信頼できるチャネル経由で渡す。
- [ ] **シークレット/PII**: コンテキスト/メモリ/プロンプトに決して含めない。資格情報はプロキシ経由で注入し、マルチテナントを分離する。
- [ ] **出力側**: `content` を読み取る前に `stop_reason` を確認する（拒否処理を行う）。SQL/HTML/shell に出力する前に、パラメータ化されたエスケープを適用する。
## ⑤ 観測可能性の接続：「どのステップで問題が発生したか」に答えられるようにする
観測可能性なしでのリリース＝大惨事。[評価と観測可能性](/ai/02-Agent/05-evaluation-and-observability.md) を接続する。
- [ ] **トレース/スパン**: 各 `tool_use`/`tool_result`/モデル呼び出しごとにスパンを作成し、レイテンシとコストを段階的に帰属させる（本サイトでは構築時にOTelを初期化している）。
- [ ] **使用量**: `input/output_tokens`、`cache_read_input_tokens`（長期間0の場合＝キャッシュが静かに無効化されている）、`cache_creation_input_tokens` を監視する——合計はこれら3つの和であり、1つのフィールドだけを見てはいけない。
- [ ] **stop_reason の分布**: `max_tokens` が高い＝出力が切り捨てられている；`refusal` が異常に高い＝プロンプトが拒否をトリガーしている；`pause_turn` が多い＝サーバー側のツールループが継続している。
- [ ] **コスト/レートリミット**: キャッシュヒット率、429 の頻度をダッシュボードに表示する（[コスト、パフォーマンス、信頼性](/ai/03-applications-and-production/03-cost-performance-and-reliability.md)参照）。
## ⑥ グレープリリース：制御可能、ロールバック可能
- [ ] **ストリーミング**: 長入力/長出力はすべてストリーミングとし、非ストリーミングHTTPタイムアウトを回避する。
- [ ] **リトライ/冪等性**: 429/5xx のみリトライする。副作用のあるアクションには冪等キーと人間の確認を付与する。
- [ ] **帰属**: 並列/Batches の結果は `custom_id`/トレースIDで対応させ、順序に頼らない。
- [ ] **少量トラフィックから開始**: 新しいプロンプト/モデルはまず少量のトラフィックでグレープリリースし、評価セットとオンライン指標を比較してから拡大する。ロールバック経路を残す。
- [ ] **モデル変更時のキャッシュ注意**: モデルを変更すると、該当セグメントのキャッシュは無効化され、トークンのベースラインを再計算する必要がある。メインループ内で中途半端に切り替えない（[マルチエージェント オーケストレーション](/ai/02-Agent/04-multi-agent-orchestration.md)参照）。
## ⑦ 回帰：失敗ごとに防御線を追加する
- [ ] オンラインで失敗を発見するたびに、**それを1つの評価ケースとして固定する**——これこそが、時間が経つにつれて評価セットを強化する方法である（[評価と観測可能性](/ai/02-Agent/05-evaluation-and-observability.md)参照）。
- [ ] ③に戻って再調整し、完全な評価を実行して劣化がないことを確認してから、再度リリースする。
## ベストプラクティス（全セクションの凝縮）
- **まず評価し、その後改善する。** 小さく現実的な評価セットは、すべての変更の審判である。それなしでは、すべての「最適化」は賭け事である。
- **シンプルさを保つ。** ワークフロー > 単一エージェント > マルチエージェント；レベルを上げるごとに発生する調整コストが、リターンに見合う必要がある。
- **ウィンドウを予算として管理する。** キャッシュのプレフィックス固定、検索による無理な埋め込みの回避、イフェルトによる深さの調整——これら3つがコストと品質を管理する。
- **モデルの出力はすべて信頼できないものとする。** セキュリティの境界はホスト側の実行環境に設ける：サンドボックス、パス検証、危険な操作の承認、シークレットをコンテキストに入れない。
- **各ステップを定量化する。** トレース + 使用量 + stop_reason により「どのステップが間違っていたか」が見える化する。観測可能性が欠如していれば、それは闇雲な変更である。
- **作成とレビューは別のレーンで行う。** 実行するエージェント自身を検証しない。別のレビュアー/検証者を独立したコンテキストで評価させる（[マルチエージェント オーケストレーション](/ai/02-Agent/04-multi-agent-orchestration.md)参照）。
- **オンラインでの失敗 → オフラインでの回帰。** 各事故が1つの評価ケースとなり、防御線は増えるだけで減らない。
## トレードオフと失敗パターン
- **評価なしでの調整**: 勘で変更し、「良くなった」のか「別の間違い方に変えただけ」なのか区別できない → まず20件の現実的な評価セットを構築する。
- **反射的なエージェント/マルチエージェントの導入**: 調整オーバーヘッド > リターン、かつデバッグがさらに困難になる → 4つの関門を通過し、ワークフローで済むならエージェントにしない。
- **観測可能性なしでのリリース**: 問題が発生した際にどのステップで起きたか、トークンをどれくらい消費したかがわからない → トレース + 使用量 + stop_reason をまず接続する。
- **キャッシュヒット率の監視漏れ**: コストが気づかないうちに数倍になってから発見する → `cache_read_input_tokens` をダッシュボードに追加する。
- **ハッピーパスのみのテスト**: オンラインで境界ケースに遭遇するとすぐに崩壊する → 評価セットに境界を含め、事故の発生とともに成長させる。
- **実行エージェントの自己評価**: 自己認証となる → レビューは別の独立したレーンで行う。
- **プロンプト/モデルの全量一括リリース**: 回帰での比較ができず、事故発生時にロールバックが困難 → グレープリリース + ロールバック経路の確保 + 完全な評価の実行。
## 参考
- **Anthropic 公式ドキュメント**: Building Effective Agents、Building Evals、Observability、Handling Stop Reasons (platform.claude.com、実装前に公式情報を優先すること)
- **全セクションへのリンク**: [コンテキストエンジニアリング](/ai/01-models-and-context/01-context-engineering.md)、[トークンとサンプリング](/ai/01-models-and-context/02-tokens-and-sampling.md)、[モデルアーキテクチャ](/ai/01-models-and-context/03-model-architecture-dense-vs-moe.md)、[推論と思考](/ai/01-models-and-context/04-reasoning-and-thinking.md)、[エージェントループとツール](/ai/02-Agent/01-the-agent-loop-and-tool-use.md)、[MCPとスキル](/ai/02-Agent/02-mcp-and-skills.md)、[メモリと状態](/ai/02-Agent/03-memory-and-state.md)、[マルチエージェント オーケストレーション](/ai/02-Agent/04-multi-agent-orchestration.md)、[評価と観測可能性](/ai/02-Agent/05-evaluation-and-observability.md)、[RAGと検索拡張生成](/ai/03-applications-and-production/01-rag-and-retrieval-augmented-generation.md)、[プロンプトエンジニアリングと構造化出力](/ai/03-applications-and-production/02-prompt-engineering-and-structured-output.md)、[コスト、パフォーマンス、信頼性](/ai/03-applications-and-production/03-cost-performance-and-reliability.md)、[セキュリティと保護](/ai/03-applications-and-production/04-security-and-protection.md)
*Keywords: 本番化, production checklist, リリースライフサイクル, eval-first, workflow vs agent, グレープリリース, canary, ロールバック, rollback, regression, 回帰, observability, trace, span, OTel, usage, stop_reason 分布, プロンプトキャッシュ, RAG, 構造化出力, 保護, サンドボックス, secret, human-in-the-loop, 冪等性, authoring vs review lane, チェックリスト*