【ITニュース解説】Separate Captured Commands from Model-Written Troubleshooting Prose

現代のソフトウェア開発において、トラブルシューティング（問題解決）のドキュメントは非常に重要だ。しかし、最近はAIモデルが文章生成に広く使われるようになり、この種のドキュメント作成においても、AIの利用が検討されている。ここで問題となるのが、AIが生成するトラブルシューティングページが、しばしば「もっともらしいが、事実と異なる情報」を含んでしまう危険性である。

具体的には、AIが失敗したコマンドの実行結果をあたかも成功したかのように修正したり、実際には行われていない再試行の手順を勝手に付け加えたりすることがある。このようなAIが「スムーズに」修正した情報は、後からドキュメントを見た人間が正しい手順だと誤解し、本来のトラブルシューティングをかえって難しくしてしまう可能性がある。なぜなら、一度生成されたドキュメントは完成しているように見え、元のコマンド実行時の状況は既に失われていることが多いからだ。

この問題を解決し、AIモデルの利点を活かしつつ、ドキュメントの正確性を保つための方法が提案されている。それは、ドキュメントを構成する要素を「人間が責任を持って管理するもの」と「AIモデルが生成するもの」に明確に分ける、という考え方だ。

この役割分担の核心は、トラブルシューティングの「証拠」となる部分、つまり実際に実行されたコマンドとその出力結果は、必ず人間が管理し、AIモデルにはその内容を改変させないという点にある。この「コマンドの実行ログ（トランスクリプト）」を人間が所有することで、レビュー担当者は、AIが生成した説明文と、実際の実行ログを照らし合わせて、情報が正確かどうかを容易に確認できる。

より具体的に、ドキュメントの各要素の役割分担は以下のようになる。 まず、「トランスクリプト（transcript.log）」は、実際に実行されたコマンド、その時の標準出力、エラー出力、そしてコマンドの終了ステータスをそのまま記録したログファイルで、これは人間が管理する。AIモデルがここに成功したかのように編集したり、失敗を隠蔽したりすることは許されない。 次に、「ファクト（facts.yml）」は、再試行が可能かどうか、そのページの責任者、特定の測定値（例えば、許容される再試行回数など）といった、事実に関するデータが記述されたファイルで、これも人間が管理する。AIモデルがここに数値を書き加えたり、根拠のない許容値を記述したりすることは禁止されている。 そして、「ナラティブ（narrative.md）」は、トラブルシューティングの手順の順序、その意図、読者への補足説明など、トランスクリプトの内容を説明する文章で、これはAIモデルが生成する。モデルは新しいコマンド、未定義のフラグ、存在しないエラーコード、割り当て量などを発明してはならない。あくまで人間が管理するトランスクリプトとファクトの情報に基づいた説明にとどめる。 最後に、「レビューノート（review.md）」は、人間がそのドキュメントを承認したか、拒否したか、または編集に関するメモを記録するファイルで、これも人間が所有する。未レビューの主張がこのページにコピーされることはない。

この仕組みを運用する手順は、以下の通りだ。 まず、実際にコマンドを実行し、その出力と終了ステータスをすべてキャプチャして、人間が管理するログファイルに保存する。次に、再試行の許容値やサポートIDなどの数値的な情報を、AIモデルに頼らずに確認できる情報源とともに、ファクトファイルに登録する。そして、ナラティブファイルだけをAIモデルが書き込めるパスとして指定し、プロンプト（AIへの指示）では、人間が管理するトランスクリプトを基に説明するよう限定する。

その後、「チェッカー」と呼ばれる自動プログラムを実行する。これは、トランスクリプトの内容が変更されていないか（ハッシュ値でチェック）、ナラティブに含まれる数値がファクトに登録されているかなどを検証し、問題があればエラーを報告する。このチェックを通った後で、人間がナラティブをトランスクリプトと照らし合わせてレビューし、問題がなければ承認する。最終的に、トランスクリプト、ファクト、承認されたナラティブをまとめてコミットし、トランスクリプトやファクトが変更された場合には、ナラティブを再生成する。

この自動チェッカーは非常に重要で、AIが生成したドラフトが、人間が管理する事実から逸脱していないかを機械的に確認する役割を果たす。例えば、ナラティブの中に「この処理には30秒かかる」という記述があった場合、その「30秒」という数値がファクトファイルに根拠とともに登録されていなければ、チェッカーはエラーを出す。これにより、AIが勝手に数値をでっち上げたり、事実と異なる情報を記述したりすることを防ぐ。

AIモデルをドキュメント生成に利用する際には、プロンプトの設計にも注意が必要だ。モデルには、トランスクリプト、許可された数値、そして出力先のパスを明確に指示し、不明な点があれば「推測せずに空白のままにする」よう指示すべきである。コマンドの改善、タイムアウトの選択、欠落した終了コードの補完などをモデルに求めることは、所有権の侵害にあたる。モデルが登録されていない数値を返してきた場合は、人間が管理する情報源に基づいてファクトを更新するか、その文章を削除する必要がある。

すべてのページに対して、以下の4つのレビューチェックを行うことを推奨している。

1. トランスクリプトのハッシュ値がファクトに記録されたものと一致するか、そしてそのセッションが指定された環境で再現可能であるかを人間が確認する。
2. ナラティブ内のすべての数値（終了コード、再試行制限、許容値など）がファクトに値として存在するかを確認する。
3. モデルのドラフトをコミットする際に、トランスクリプトやファクトが誤って編集されていないことを確認する。
4. 人間がレビューノートでナラティブを承認し、チェッカーの出力もその承認の隣に記録されていることを確認する。

ただし、このアプローチがすべての場合に適切というわけではない。セキュリティ勧告、価格ページ、法的条件、インシデントレポートなど、文章そのものが重要なコミットメントとなるようなページには適用すべきではない。また、チームの誰もがトランスクリプトを再キャプチャできない場合も、このゲートウェイをスキップすべきだ。なぜなら、古くなった事実（ピン）は、明らかな情報の欠落よりも危険だからである。

もしチームがAI生成された出力を人間のレビューなしで公開しているのであれば、このスクリプトは意図した保護を提供しない。スクリプトは、説明の明確さや、アドバイスの安全性、実行環境外でそのアドバイスが適用可能かなどを判断するものではない。また、ページセットが小さく、ほとんど変更されない場合、この自動化の導入コストは、それが取り除くリスクよりも大きくなる可能性がある。

そのような小規模なケースでは、スクリプトや定期的なジョブなしでも、同じ所有権ルールを維持できる。人間がトランスクリプトとファクトを編集し、AIモデルにはそれらのファイルへの書き込みアクセスを与えない。これらの事実が変更された場合にのみ説明文を再生成し、新しい測定値を含むドラフトは破棄する。この手動のバージョンは時間がかかるが、チェッカーが自動化しようとしているのと同じ境界を維持できる。

最終的に、この方法の有効性を確認するためには、まず一つのトラブルシューティングページを選び、そのトランスクリプトを固定し、未登録の数値を導入した最初のドラフトを拒否するテストを行うのが良い。この失敗こそが有益な結果となり、許可リストが実際にページが書かれている方法と一致しているかを示すからだ。