AIへの指示Versionとテスト結果を一緒に記録し、失敗が戻った変更を追う方法

AIへの指示を少しずつ改善し、変更のたびにテストも残すようになると、次の問題が出てきます。

あるテストが昨日は合格していたのに、今日の指示では失敗した。しかし、どの変更で戻ったのか分からない。指示文は更新されているものの、テスト結果には「合格」とだけ書かれている。逆に、失敗記録はあるのに、当時どの指示を使ったのか残っていない。

これでは、AIの出力が変わった理由を追えません。

そこで私は、指示とテストを別々のメモとして管理せず、次の3点を同じ記録で結びます。

• どの指示Versionを使ったか
• どのテストケースを実行したか
• 期待と実際の結果がどう違ったか

この記事では、AIへの指示を変えたあとに失敗が戻ったとき、変更履歴を総当たりせず、原因候補を小さく絞るための記録方法を整理します。

指示本文を上書きするだけでは追えない

AIへの指示を1つのファイルで管理し、毎回上書きしていると、現在の内容は分かっても、過去のテストを再現できません。

たとえば、次の変更を順番に行ったとします。

v1：資料が不足したら確認を返す
v2：資料が矛盾したら本文を作らず停止する
v3：文章を短くするため、確認項目を3件までにまとめる

v3にしたあと、4件目の矛盾が表示されなくなったとします。現在の指示だけを見ても、もともと表示できていたのか、どの変更から欠落したのか分かりません。

v2で同じ入力が合格し、v3で不合格になった記録があれば、確認項目を3件にまとめた変更を最初の調査対象にできます。

重要なのは、指示の文章を保存することだけではありません。その指示で、どの入力に対して、何を期待し、実際にどう動いたかを結びつけることです。

変更ごとに短いVersionを付ける

指示Versionは、壮大な番号でなくてかまいません。日付と連番、または短い番号で、一意に参照できれば十分です。

instruction-2026-10-30-01
instruction-2026-10-30-02

Versionには、少なくとも次を残します。

項目	内容
Version	一意に参照する識別子
変更日時	いつ有効にしたか
変更した箇所	追加・削除・書き換えた範囲
変更理由	どの誤りや要求に対応したか
期待する変化	進む条件、止まる条件、出力形式
変更しない境界	公開、個人情報、削除など維持する条件
承認	誰が使用開始を確認したか

指示全文も保存します。差分だけでは、後から前提を再現できない場合があるからです。ただし、指示ファイルへ認証情報、個人情報、顧客データを入れません。

変更理由は「改善」だけにせず、何を防ぐためかを書きます。

## instruction-2026-10-30-02
- 変更：矛盾が1件でもある場合は本文を生成しない条件を追加
- 理由：確認一覧を出したあと、本文では片方の日付を採用したため
- 期待：矛盾した値と出典だけを返し、本文生成前に停止
- 維持：正常ケースでは下書きを作成できる

これなら、テストが失敗したとき、変更の目的と実際の結果を比較できます。

テストケースにも変わらないIDを付ける

テスト名だけでは、同じケースか判断できません。「矛盾テスト」という名前を使い回すと、日付の矛盾と公開範囲の矛盾が混ざります。

ケースには固定IDを付けます。

T-001 必須情報が不足したら推測せず停止する
T-002 複数資料の日付が矛盾したら両方を示して停止する
T-003 Human Approvalがなければ公開しない
T-004 条件が揃っているときは確認用下書きを作る

入力を修正した場合は、同じIDを黙って上書きしません。期待する境界が同じで、表現だけを整理したならケースのRevisionを上げます。守る境界や期待する停止位置が変わったなら、新しいケースとして分けます。

T-002 r1：資料Aと資料Bで開催日が違う
T-002 r2：資料名と更新日時を追加。守る境界は同じ
T-005 r1：公式情報と取材メモの優先順位を人が指定した場合

ケースIDとRevisionを分けると、AIの指示が変わったのか、テスト入力が変わったのかを区別できます。

1回の実行を1行で記録する

テスト結果は「全件合格」だけでまとめません。最低限、1ケースにつき1行を残します。

実行ID	指示Version	ケース	期待	実際	判定	外部操作
R-101	2026-10-30-01	T-002 r1	矛盾を示して停止	片方を本文へ採用	不合格	なし
R-102	2026-10-30-02	T-002 r1	矛盾を示して停止	本文前に停止	合格	なし
R-103	2026-10-30-02	T-004 r1	下書きを作る	下書きを作成	合格	なし

可能なら、次も残します。

• 実行日時
• 使用したAIやモデルの識別情報
• 指示ファイルのハッシュまたはコミット
• 入力データのRevision
• 出力の保存先
• 人間の判定者
• 再実行が必要な条件

モデル名だけで結果を説明しないことも大切です。同じモデルでも、指示、入力、利用できるツール、会話の文脈が違えば結果は変わります。再現に必要な条件を、確認できる範囲で残します。

また、テストでは公開API、実在の送信先、削除権限を使いません。外部操作の有無を記録し、「なし」が期待どおりであることを確認します。

合格から不合格へ変わった境界を探す

失敗が戻ったら、最初に現在の出力だけを直そうとしません。同じケースの履歴を、古い順に並べます。

T-003 Human Approvalなしでは公開しない

v5：合格
v6：合格
v7：不合格
v8：不合格

この場合、最初に見るのはv6とv7の差分です。v1から現在までの全指示を読み比べる必要はありません。

次に、v7で変更した箇所がT-003の境界へ影響し得るかを確認します。

• 公開条件を短くまとめた
• 承認済みの定義を変えた
• 「下書き保存は可」という例を追加した
• ツール実行の条件を別の節へ移した

文章上は別の目的の変更でも、AIが参照する優先順位や例示を変えていることがあります。変更理由だけで無関係と決めず、差分と出力を並べます。

原因候補を確かめるときは条件を1つだけ戻す

v6では合格、v7では不合格だったとしても、v7の変更が原因と断定はできません。入力や実行条件も変わっているかもしれません。

確認するときは、一度に全部を書き直さず、条件を1つだけ変えます。

確認A：v6の指示 + 同じケース入力 → 合格
確認B：v7の指示 + 同じケース入力 → 不合格
確認C：v7から疑わしい変更だけ外す + 同じ入力 → 合格

この結果なら、疑わしい変更が原因である可能性は高まります。ただし、1回の出力だけで断定しません。重要な境界は再実行し、正常ケースにも悪影響がないか確認します。

失敗したケースだけを合格させる修正も危険です。たとえば「承認がなければ必ず停止」を強くしすぎると、外部操作を含まない下書き作成まで止まることがあります。

そのため、修正後は少なくとも次を組にします。

• 失敗が戻ったケース
• その境界の直前で進んでよいケース
• 公開、個人情報、削除など影響の大きい共通ケース

停止できることと、条件が揃えば進めることの両方を確認します。

指示変更と実行環境の変更を混ぜない

指示を変えた日と同じ日に、AIのモデル、ツール権限、参照ファイル、入力形式まで変えると、結果が変わった理由を切り分けにくくなります。

記録では、少なくとも次を別の欄にします。

指示変更：矛盾時の停止条件を追加
環境変更：なし
入力変更：なし
ツール変更：なし

複数の変更が必要な場合は、変更単位を分けるか、同時に変えたことを明記します。後から都合よく「指示のせい」「モデルのせい」と決めません。

AIの出力には揺れがあります。そのため、完全な再現を約束する記録ではなく、何を固定し、何が変わったかを人間が追える記録を目指します。

失敗を見つけても、すぐ古いVersionへ戻さない

回帰を見つけたとき、直前Versionへ戻すのが安全に見えることがあります。しかし、直前の変更が別の重大な問題を直している場合、単純な巻き戻しでその問題を復活させます。

戻す前に確認します。

• 変更理由は何だったか
• どのテストを新しく合格させたか
• どの境界を維持する必要があるか
• 一部だけ修正できるか
• 本番利用を一時停止すべきか

公開、更新、削除、外部送信、個人情報、安全に関わる不合格なら、原因調査中はその操作を止めます。AIに代替の指示を書かせ、そのまま本番へ適用しません。

AIは差分整理、候補の抽出、過去結果の一覧化を手伝えます。どのVersionを採用するか、テスト範囲を十分とみなすか、本番利用を再開するかは人間が判断します。

記録を残す場所を1つに決める

指示はファイル、結果はチャット、承認は口頭、という状態では結びつけられません。最低限、参照先を1つの索引へ集めます。

# AI指示テスト実行記録

## 実行情報
- 実行ID：R-103
- 実行日時：2026-10-30 09:20 JST
- 指示Version：instruction-2026-10-30-02
- 指示commit：abc1234
- ケース：T-004 r1
- 入力Revision：input-01
- 外部操作：なし

## 判定
- 期待：確認済み情報だけで下書きを作る
- 実際：下書きを作成し、未確認項目は分離
- 判定：合格
- 判定者：本人

## 関連
- 前回実行：R-099
- 変更理由：T-002の回帰修正後、正常ケースへの影響を確認
- 出力保存先：outputs/R-103.md

指示全文や出力が別ファイルでも、Versionと実行IDからたどれるようにします。公開できない情報を含む場合は、公開リポジトリへ置かず、アクセス範囲を分けます。

AIに任せる部分と人間が決める部分

AIは、履歴が同じ形式で残っていれば、次の補助ができます。

• 同じケースIDの結果を時系列に並べる
• 最後の合格と最初の不合格を探す
• 2つの指示Versionの差分を要約する
• 変更箇所と失敗した境界の関連候補を挙げる
• 修正後に再実行するケース候補を出す

ただし、AIの要約だけで原因を確定しません。記録された指示、入力、実際の出力を人間が確認します。

人間が決めるのは次です。

• どの不合格で本番利用を止めるか
• どの変更を原因候補として検証するか
• 古いVersionへ戻すか、一部を修正するか
• 再テストの範囲が十分か
• 修正版を本番で使い始めてよいか

特に外部操作を伴う再開にはHuman Approvalを置きます。

まとめ

AIへの指示とテストを改善し続けるなら、現在の指示と最新の合否だけでは足りません。

• 指示変更ごとに一意のVersionを付ける
• 変更理由、期待する変化、維持する境界を残す
• テストケースには固定IDとRevisionを付ける
• 1ケースの実行を、指示Versionと結びつけて1行で残す
• 最後の合格と最初の不合格の間から調べる
• 指示、入力、モデル、ツールなど、何を変えたかを分ける
• 原因候補の確認では条件を1つだけ変える
• 修正後は失敗ケースと正常ケースの両方を再テストする
• 重大な境界の不合格中は本番操作を止める
• 採用、巻き戻し、再開は人間が承認する

Version管理の目的は、番号を増やすことではありません。AIの動きが変わったときに、どの変更を確認すればよいかを追えるようにすることです。

次回は、AI指示テストの実行結果を週次で短くまとめ、毎回確認するケースと変更時だけ確認するケースを分ける方法を整理します。