AIアプリの更新履歴は「見分けがつくこと」を書く

自動更新されるAIアプリでは、利用者は不具合が直ったのか古い版を掴んでいるのかを区別できません。8日間で38回更新したアプリで、更新履歴の書き方をどう変えたかを書きます。

更新履歴（チェンジログ）は、開発者が自分の仕事を記録するためのものだと思っていました。実際に自動更新されるアプリを配ってみると、まったく別の役割を持っていることが分かりました。

利用者から届く報告のうち、いちばん扱いにくいのはこれです。

直したと言っていた不具合が、まだ出ます。

このとき起きうることは2通りあります。

そして開発者側からは、どちらなのか分かりません。利用者側からも分かりません。ここを利用者が自分で判断できるようにするのが、更新履歴の一番の仕事でした。

自動更新のアプリでは「バージョン」が伝わらない

配布形式がアプリストアなら、利用者は自分の入れている版番号を見られます。 Webアプリ（PWA）として配ると、更新は裏側で勝手に行われます。親切な設計のつもりでしたが、問題が起きたときに手がかりが何も残らないという副作用がありました。

そこで次の3つを並べて画面に置きました。

3つが揃ってはじめて意味を持ちます。版が表示されていても比べる相手がなければ判断できませんし、判断できても直す手段がなければ問い合わせるしかありません。

以前は「リトライ処理を修正」のように書いていました。これは利用者が自分の症状と照合できません。

いま守っているのは「何ができるようになったか」だけを書く、という一点です。

通信の失敗や利用回数の上限で解けなかったときに、「読み取れませんでした」と表示して撮り直しを促してしまう問題を直しました。何度撮り直しても直らない原因になっていました。

後半の「何度撮り直しても直らない原因になっていました」が重要です。利用者は自分が体験した症状の言葉でしか検索できません。内部の原因ではなく、画面に何が起きていたかを書きます。

生成AIを使うアプリでは、変更が確率的な挙動に影響します。「良くなったはず」と「良くなった」を混同しないために、 適用範囲を限定したこと自体を履歴に残すようにしました。

読み直しは命令表だけで行うようにしました。法則性と暗号では効果が確かめられていないため、そのぶんAPI使用回数を増やさないようにしています。

これは利用者向けの情報であると同時に、自分向けの記録でもあります。 2週間後の自分は「なぜ全部に適用しなかったのか」を忘れます。判断の理由がコミットログの奥ではなく利用者が読む場所にあると、安易に広げてしまう事故が減ります。

8日間で38回。1日平均5回近く更新していました。「まとめて書こう」と思うとまとめる作業自体が負債になり、結局書かなくなります。

区切りは日付ではなく、利用者から見た変化のかたまりにしました。同じ日に「答えの中身も見せる」「読み違えを見抜く」「読み取れない原因を正しく伝える」を別々のエントリにしています。症状と照合するのが目的なので、日付でまとめる意味がありません。

普通のソフトウェアの更新履歴と決定的に違うのは、 利用者が何もしていないのに挙動が変わることです。

このため「昨日はできたのに今日はできない」という報告が構造的に発生します。更新履歴が無いと、この報告は何も切り分けられないまま溜まります。

逆に言えば、更新履歴に日付と内容が並んでいれば、利用者自身が「その日にプロンプトを変えたと書いてある」ところまでたどり着けます。サポート窓口を持たない個人開発では、これが唯一の切り分け手段になります。

自分が何を変えたか説明できる状態になりました。

生成AIに書かせながら開発していると、変更の量が自分の記憶を簡単に超えます。利用者に説明できる言葉で毎回書き出しておくと、「これは何のために入れた分岐だったか」を後から復元できます。

コードのコメントとコミットログでは足りませんでした。どちらも実装の都合で書かれるので、利用者から見た意味が残らないためです。

更新履歴は「直した記録」ではなく、利用者と開発者が同じものを見ているかを確かめる道具です。自動更新される仕組みで配るなら、これが無いと問い合わせが切り分け不能になります。