ドキュメントをLLMで自動同期させたら、担当者交代のコストが変わった話

設計ドキュメントは書いた瞬間がいちばん正確で、そこから先は基本的に劣化していきます。半年運用していたプロジェクトで担当を引き継いだとき、ドキュメントに書かれているAPIの仕様と実際のコードが半分近くずれていて、結局コードを読み直すところからやり直しました。この記事では、そのあとに試した「ドキュメントとコードをLLMで突き合わせて差分を検出する」仕組みと、実際に担当者交代のコストがどう変わったかを書きます。

きっかけ、ドキュメントが古くなっていく過程

ドキュメントが古くなる理由は、だいたいいつも同じです。実装を変更したエンジニアが、レビューには通るがドキュメント更新までは手が回らない。あるいは緊急のバグ修正で仕様が変わり、あとで直すつもりのままリリースされてしまう。1回1回は小さなズレでも、3ヶ月、半年と積み重なると、ドキュメントは「だいたい合っている」から「部分的に間違っている」に変わります。

厄介なのは、ドキュメントが古いこと自体には誰も気づかないという点です。書いた本人はコードの実態を覚えているので、ドキュメントを見返す機会がありません。実際に困るのは、あとから来た人がドキュメントを信じて作業したときです。

試した仕組み、LLMでコードとドキュメントの差分を検出する

やったことは単純です。CIにステップを1つ追加し、プルリクエストごとに変更されたファイルと、対応するドキュメントのセクションをLLMに渡して、内容がずれていないか判定させます。

具体的には次の3種類を対象にしました。

・APIのリクエスト/レスポンス定義と、ドキュメント内のエンドポイント一覧

・DBのマイグレーションファイルと、ドキュメント内のテーブル定義

・環境変数を読み込む箇所と、READMEのセットアップ手順

LLMには一致しているかどうかだけを判定させるのではなく、ズレている箇所と、ドキュメント側の修正案を両方出させるようにしました。判定だけだと結局人が確認して直す手間が変わらないからです。修正案が出てきたプルリクエストには、ドキュメント差分コメントが自動で付き、レビュアーがそのまま採用するか手直しするかを選べます。

運用してみて分かったこと

うまくいったのはAPI定義とテーブル定義です。この2つは構造が機械的なので、LLMがズレを検出する精度もかなり高く、修正案もほぼそのまま採用できるレベルでした。

一方でREADMEのセットアップ手順は、あまりうまくいきませんでした。環境変数が増えているのに気づいても、なぜその変数が必要になったかという文脈まではコードから読み取れないため、修正案が表面的になりがちです。ここは結局、変更した本人が一言添えるほうが早いという結論になりました。

正直に言うと、最初はこの仕組みで人間のドキュメント更新作業をほぼゼロにできると思っていました。実際にはそうならず、機械的に照合できる部分と、文脈が要る部分をはっきり分けて考える必要があると分かったのが、一番の収穫だったかもしれません。

担当者交代のコストがどう変わったか

この仕組みを3ヶ月ほど運用したあと、別のプロジェクトで担当者交代が発生しました。引き継いだ側の感触ですが、以前は「ドキュメントを読む、怪しい箇所をコードで裏取りする、合っているか確認する」という手順をほぼ全ページでやっていました。今回はAPI定義とテーブル定義については裏取りの手間がほとんどなく、READMEなど文脈が必要な部分だけ、担当者に直接聞くという形に絞れました。

引き継ぎにかかった日数を正確に測ったわけではないので、具体的な数字は出せませんが、全部疑ってかかる状態から、ここだけ疑えばいいという状態に変わったことは、体感としてはっきりありました。

おわりに

ドキュメントの陳腐化はどのプロジェクトでも起きる問題ですが、機械的に照合できる部分は思っていたより多く、そこだけでも自動化する価値はあると感じています。文脈が要る部分まで無理にLLMに任せようとせず、役割を分けたのが今回うまくいったポイントでした。

AIを使った開発プロセスについては、会社のブログでも別の角度から書いています。よろしければご覧ください。