# 改善と再検証

失敗した段階から具体的な修正内容を決め、同じタスクをもう一度検証します。

出典: https://flovia.dev/docs/ja/improvement-loop/

## 観測した失敗から修正対象を決める

評価の結果を、何を変えるか、なぜそれが有効そうか、どう確かめるかという判断につなげます。ダッシュボードの指摘から根拠を確認し、対象を絞って修正します。再検証の結果を見て、次の改善を決めます。

出発点は、観測した失敗と、それに影響し得るプロダクト側の変更対象です。Floviaは、チームのコーディングエージェントで実行できる修正プロンプトを生成します。修正案は、タスク、失敗した段階、再検証で確認すべき動作に結び付けられます。

| 観測した失敗 | 確認する箇所 | 再検証で確かめること |
| --- | --- | --- |
| 対象が現れない、または選ばれない | プロダクトの位置付け、ドキュメント、ランディングページ、llms.txt、候補の説明 | 定義した発見条件の下で、対象が現れる、または選ばれるか？ |
| 操作を誤る | APIやMCPのツール名、説明、操作ごとの役割 | 許可した操作を正しく特定できるか？ |
| 引数が無効 | パラメーターの意味、入力制約、具体的な使用例 | リクエストがスキーマと意味の検証を通過するか？ |
| 結果が利用できない、または回答が不完全 | 応答仕様、必須フィールド、単位、結果の解釈方法 | 返されたデータで、すべての完了基準を満たせるか？ |

これらは診断の出発点です。ページを変更しても、モデルがそのページを取得・利用するとは限りません。再検証では、エージェントへの情報の渡し方を維持するか、変える場合はその条件を明示します。

## ダッシュボードで指摘から修正へ進む

専用ダッシュボードでは、評価の概要、根拠となる実行記録、修正ガイダンスをまとめて確認できます。以下は、顧客を識別できる情報を置き換えた実際のダッシュボードの抜粋です。数値は、画面に示した個別のテストの結果です。

この例では、コーディングエージェントに取引履歴を取得するコードを書かせ、ドキュメントを届ける方法を比較しています。CLAUDE.mdから説明を参照できるようにすると、対象APIを選ぶ結果は6回中0回から6回中6回になりました。これは、このタスクと条件で観測したAPI選択の結果です。

次に取り組む改善を選ぶ — 概要画面では、修正候補ごとに観測された変化と、その根拠となるテストを確認できます。まず詳しく調べる項目を選びます。

![概要画面：修正候補と、選択中の項目の比較結果。](https://flovia.dev/docs/images/dashboard-overview.png)

概要画面：修正候補と、選択中の項目の比較結果。

指摘の内容を読む — 改善項目を開くと、エージェントが何につまずいたのか、どの変更が推奨されているのかを確認できます。この例では、起動時に読み込む指示ファイルからドキュメントへのリンクがなく、専用APIや登録方法が見つからないケースがありました。

![指摘画面：見つからなかった導線、推奨する変更、証拠と実装用プロンプトへの入口。](https://flovia.dev/docs/images/dashboard-finding.png)

指摘画面：見つからなかった導線、推奨する変更、証拠と実装用プロンプトへの入口。

根拠を確認し、修正を準備する — 証拠画面で評価条件と実行記録を確認します。実装用プロンプトをコピーしてチームでレビューし、変更を反映します。リリース後に同じテストを再実行し、変更を採用するか、さらに修正するかを判断します。

![証拠画面：説明への導線を変えた条件と、その前後の観測結果。](https://flovia.dev/docs/images/dashboard-evidence.png)

証拠画面：説明への導線を変えた条件と、その前後の観測結果。

## ドキュメント改善の例

あるブロックチェーンデータAPIで、機能の選び方や使い方が伝わるようにドキュメントを更新しました。更新前と更新後の資料に基づくAIの回答を比較し、どの説明が改善し、どこに誤りが残るかを確認しました。

確認したのは、用途に合う機能を選べているか、正しい呼び出し先を示せているか、開発者側で必要な作業を説明できているかです。以下の各項目は、更新後の資料に基づく5回の回答を確認したものです。

| 確認した機能 | 変更前 | 変更後 |
| --- | --- | --- |
| トランザクションIDだけを取得 | 5回中0回。方法を特定できないか、別の用途向けの機能を案内 | 5回中5回、履歴取得機能でIDだけを取得する方法を説明 |
| 取引履歴の取得方法の使い分け | 元の取引データの取得と、解析済みで読みやすい履歴の取得の違いを説明できず | 5回中5回、違いを説明。ただし4回は、元データの取得に使うAPI名を取り違え |
| WebSocketによるリアルタイム監視 | 接続準備用のツールを呼べば監視が始まるのかが不明確 | 5回中5回、ツールは接続情報やサンプルコードを返すもので、監視処理は開発者側で動かす必要があると説明 |
| サーバーでリアルタイムストリームを受信 | 接続情報の参照と、接続設定の生成を正しく区別できず | 5回中5回、接続設定を生成する機能を選び、接続自体は開発者側で確立すると説明 |
| 優先手数料の見積もり・接続情報の取得 | 機能と呼び出し先の対応を誤り | 5回中5回、正しい呼び出し先を示した |

改善が見られたのは、取引履歴の取得方法の案内、リアルタイム配信の接続準備、優先手数料の見積もりなどの呼び出し先です。

開発者にとっては、誤った方法で実装を進めたり、接続の準備だけでサービスが動き始めると誤解したりすることの減少が期待できます。この比較で確認したのはAIの案内の改善であり、実装ミスや問い合わせ件数の減少は測定していません。

ここでの件数は、この比較で確認した回答の数であり、実APIの実行成功率や、他のタスク・モデルでの成功率を表すものではありません。次の再検証では、使い分けの説明とは別に、正しいAPI名を示せるかを個別に確認します。

## 例：過去の為替レートを取得する操作を選びやすくする

シナリオ設計で紹介した架空の為替レートAPIを使い、確認したいことから修正の判断までの流れを説明します。手順を示すための例であり、顧客の評価結果ではありません。

| ステップ | 進め方 |
| --- | --- |
| 問い | 今日のレートではなく、指定日のEURからUSDへのレートを取得できるか？ |
| 評価 | ツール一覧と準備済みの応答を固定したうえでタスクを実行します。選んだ操作、通貨と日付の引数、最終回答を確認します。 |
| 指摘 | 最新レートの操作を選んだとします。最初の失敗は操作の選択なので、二つの操作の説明を確認します。 |
| 修正 | 過去のレートを取得する操作の用途を明記し、日付を指定する使用例を加えます。この比較では、スキーマと応答は変えません。 |
| 再検証 | 同じタスクを同等の条件で再実行します。過去のレートの操作を選べるようになったか、回答まで正しく完了できたかを確認します。 |
| 判断 | テストした動作が改善していれば、新しい説明を採用します。操作は正しく選べても日付の引数を間違えるなら、次は日付の指定方法を検証します。 |

## 修正プロンプトは検証できる形にする

修正プロンプトの例 · 架空の為替API

```text
観測した失敗：日付を指定した依頼に対し、エージェントが
最新レートの操作を選んでいる。

最新レートと過去のレートの違いが伝わるように操作の説明を修正する。
日付形式を記載し、日付を指定したEUR-to-USDの例を一つ追加する。
エンドポイントの動作とスキーマは変更しない。

合格条件：同じ日付付きタスクでget_historical_rateを選び、
正しい日付と通貨を指定する。続けて、返されたレートと日付を
最終回答で使っていることを確認する。
```

チームが修正内容をレビューし、自社環境に実装します。Floviaは診断、修正ガイダンス、検証を提供し、変更と再検証結果を結び付けます。

## 再検証の結果から次の行動を決める

変化した段階と最終結果を併せて読みます。一つの問題を解消すると、次の問題が見えることがあります。既に正しく動いている部分を保ちながら、次に直す箇所を選びます。

| 再検証で分かったこと | 次の行動 |
| --- | --- |
| 選択は改善したが、まだ違う操作が選ばれる | 分かりやすくなったプロダクトの説明は維持し、操作名・説明・使い分けを確認する |
| 正しい操作を選ぶが、引数が不正 | パラメーターの意味を明確にし、タスクの制約を反映した使用例を追加する |
| 結果は利用できるが、回答に必要な情報が足りない | 完了条件と対応する出力フィールドを確認し、その意味と回答での使い方を明確にする |
| モデルやタスクによって結果が異なる、または欠測がある | 修正を選ぶ前に、該当グループと失敗記録を確認する。必要な範囲で比較を補う、または広げる |

過去の為替レートの例では、過去データ用の操作を選べれば、操作の選択ミスは解消します。その後の回答から日付が抜けていれば、完了段階の別の問題として、次の再検証条件にします。

- [完了判定の例を読む](https://flovia.dev/docs/ja/agent-funnel/): レート、通貨の方向、日付をそれぞれどう確認するかを見ます。

## 同じ判断をもう一度検証する

1. 変更した成果物と、介入対象のフィールドを記録します。
2. タスク、要求するモデル、候補条件、実行経路、採点を比較可能な状態に保ちます。
3. 設計どおりに、修正した情報が実際に与えられる、または取得されることを確認します。
4. 段階別の結果と完了を、欠測やカバレッジとともに比較します。
5. 残っている失敗を基に、次の介入を定義します。

モデルの更新と測定期間も重要です。周辺条件が変わった場合は、比較の中で明示します。結果には、検証した段階で何が改善し、何が未解決のままかを示します。