【ITニュース解説】Sign the Sentences, Not the PR: An Approval Ledger for Model-Drafted Doc Blocks

現代のソフトウェア開発において、人工知能（AI）がドキュメント（説明書や仕様書など）の作成を支援する場面が増えてきた。しかし、AIが生成したドキュメントには、従来の人間による承認プロセスでは見過ごされがちな潜在的な問題が存在する。この問題とは、一度人間が承認したはずのドキュメントの内容が、後でAIによって密かに書き換えられても、その変更が再承認されないまま放置されてしまう危険性である。

多くの開発プロジェクトでは、コードの変更を「プルリクエスト」という単位でレビューし、承認している。プルリクエストの承認は、変更されたコードやドキュメントの差分全体に対して行われるため、ドキュメント内の個々の文章や記述の正確性、そしてその責任の所在までを厳密に追跡することは難しい。例えば、昨年10月に人間が承認したドキュメントがあったとする。そのドキュメントが今年12月にAIによって一部書き換えられたとしても、過去の承認記録は依然として存在し、あたかもその変更内容も承認済みであるかのように見えてしまう。これは、承認記録が実際のテキスト内容から乖離してしまうという、見過ごせない問題を引き起こす。重要な情報、例えばセキュリティ警告や利用料金に関する記述などがAIによって不正確に書き換えられた場合、大きな問題に発展する可能性がある。

この問題に対処するために提案されているのが、「承認台帳」という新しいワークフローである。このアプローチの目的は、人間の承認をドキュメント全体ではなく、ドキュメント内の特定の「ブロック」（文章のまとまり）に厳密に結びつけることにある。具体的には、人間が承認した時点のテキスト内容を「ハッシュ」という、その内容を一意に識別するデジタル指紋に変換し、そのハッシュ値と承認者の署名（名前）をセットで記録する。ハッシュ値は、テキストがたとえ一文字でも変更されれば全く異なる値になるため、これによりテキスト内容と承認記録の整合性を機械的に保証できる。テキストが変更されれば自動的にハッシュ値が変わり、「未承認」状態となるため、再度の人間による承認が必須となる。これは、レビュー担当者の注意深さに頼るのではなく、システムが自動的に再承認プロセスを強制する仕組みだと言える。

この承認台帳システムを導入するための具体的な手順は以下の通りである。

まず、ステップ1として「ソースコード内で所有権の境界をマークする」。ドキュメントのソースファイル内で、各文章のまとまりを特別なHTMLコメントで囲み、そのブロックを一意に識別するIDと、そのブロックの「所有者」がAI（model）なのか人間（human）なのかを明示する。例えば、<!-- doc:block id="install-linux" owner="model" --> のように記述する。owner="human"とマークされたブロックは、人間が責任を持つとみなされ、このシステムのチェック対象外となる。一方、owner="model"のブロックが、AIが生成し、人間の承認が必要な対象となる。これにより、ドキュメント内でAIと人間の責任範囲が明確になる。

次に、ステップ2として「制限された指示でドラフトする」。AIにドキュメントを生成させる際には、その指示を厳しく制限する。AIには、owner="model"のブロックのみを書き換えさせ、owner="human"のブロックは変更しないように指示する。さらに、AIが生成できる内容にも具体的な制約を設ける。例えば、数値、日付、特定のバージョン情報などは、提供されたリリース情報以外のものを勝手に導入しないよう指示することで、AIが誤った情報を生成するリスクを低減し、その責任範囲を明確にする。

ステップ3は「ブロックをハッシュ化し、署名を記録する」ことである。これは、Pythonで書かれた「チェッカーツール」によって実現される。このツールは、ドキュメント内のowner="model"とマークされた各ブロックのテキスト内容を読み込み、不要な空白などを取り除き正規化した上で、SHA256というハッシュアルゴリズムを使って一意のハッシュ値を生成する。人間が特定のブロックを承認すると、そのブロックID、生成されたハッシュ値、そして承認者の名前が、JSON形式の「台帳ファイル」としてリポジトリ内に記録される。この台帳ファイルもコードと同様にバージョン管理システムで管理されるため、いつ誰がどの内容を承認したかという履歴が明確になる。

ステップ4は「pre-commitとCIで強制する」ことである。このチェッカーツールは、開発者の作業フローに組み込まれる。具体的には、コードをコミットする直前に自動的に実行される「pre-commitフック」として設定する。これは、コードをリポジトリに保存する前に、問題がないかを確認する仕組みである。また、コードが共有リポジトリにプッシュされた後、自動的にテストやビルドを行う「CI/CDパイプライン」（継続的インテグレーション・継続的デリバリーの自動化システム）にも組み込む。これにより、開発者が意図せず承認されていない変更をコミットしてしまったり、CIの段階で未承認の変更が検出されたりした場合に、システムがそれを自動的に検知し、問題を指摘する。ローカルでのチェックは高速で、開発の妨げにならない。

そして最後のステップ5は「プログラムの差分ではなく、台帳の差分をレビューする」ことである。従来のプルリクエストレビューでは、ドキュメントの変更内容（テキストの差分）を直接確認していた。しかしこのシステムでは、プルリクエストのレビュー時に、ドキュメント本体の差分に加えて、台帳ファイル（.docprovenance/）の差分を先に確認することが推奨される。台帳の差分を見ることで、どのブロックが変更され、誰によって再承認されたのか（あるいは、削除されたブロックの承認記録が消えたのか）が明確にわかる。これにより、レビューの効率と信頼性が向上する。

AIと人間の役割分担の具体例も重要である。例えば、インストール手順のコマンドはAIがドラフトできるが、そのコマンドが実際にクリーンな環境で動作することの確認は人間が行う必要がある。また、APIのパラメータ名はAIが生成できるが、それが現在のリリースと正確に一致するかどうかは人間が確認する。特に、価格、日付、契約内容、セキュリティ警告などの重要な情報は、AIにドラフトさせるべきではなく、人間が最初から責任を持って作成・管理すべきであるとされている。これはAIの生成品質の問題ではなく、情報が間違っていた場合の「責任の所在」を明確にするためであり、非常に重要な考え方である。

この承認台帳システムは、AIが生成したドキュメントの「承認とテキストの整合性」を強力に保証するが、いくつかの限界も存在する。例えば、レビュー担当者が不注意で誤った内容を承認してしまった場合、その「正確性」までは保証できない。また、管理するブロックの数が増えるほど、承認のプロセスに手間がかかる可能性もある。そのため、まずはコマンド、数値、セキュリティに関する記述など、特に重要性の高いドキュメントブロックから導入を開始することが推奨される。ドキュメントが完全に自動生成される場合や、信頼できる承認者がいないチーム、CIでのフック強制が難しいチームには、このアプローチは適さない場合がある。

この承認台帳システムは、AIがドキュメント作成に貢献する現代において、人間による承認の信頼性と透明性を高めるための実用的な解決策を提供する。テキストと承認を厳密に結びつけることで、AIが生成した内容の管理を強化し、安全で信頼性の高いドキュメント運用を実現するための重要な一歩となる。