AI に一括修正を任せて事故った。だから ADR を書く

はい、どうもこんにちは佐藤です！

やられました。

ソースコードに一括修正を入れる修正を AI に頼んだところ、例外的に別の対応をしている箇所にも波及して、予想外の不具合を生んでしまいました。

反省！

今回は個人開発だったので、触っていた時に違和感を覚えてセーブできました。でも、これが本番だと思うと、背筋が凍りますよね。

では、このような事故を減らすには何が良いのでしょうか。

答えの一つとして、私は ADR だと思っています。

その理由を書いていきますね！

なぜ事故ったのか。「ここは合わせない」が消えたから

まず、何が起きたのかを整理させてください。

実際に SI でオーダーメイドのシステムを作っていると、他と一貫性を保てないような仕様変更が多々発生しますよね。

「この画面だけは、旧システムの操作感に合わせてほしい」「この帳票だけは、取引先の様式に従わないと受理されない」

こういうやつです。全体の作法から外れているけれど、外れていることに理由がある箇所。どの現場にも必ずありますよね。

私は昔から、そういう場合は、ソースコードに 「ここは〇〇のために、他と合わせない」というコメントを入れるようなことをしてきました。未来の自分と、次の担当者への手紙みたいなものです。

ところが今回は、AI にソースコードを書かせていたので、どうしてもそちらが抜けてしまっていたんですよ。

そして一括修正をかけたら、その例外まできれいに揃えられてしまった、というわけです。

**AI は「揃っていないもの」を見つける天才です。**揃っていない理由が書かれていなければ、揃えるのが親切だと判断しますよね。至極まっとうな仕事をされてしまったのです。

答えの一つは、マークダウン 1 枚の ADR

そこで ADR です。

やることは大げさではありません。**AI にどのように指示を出して、作業させて、結果どうなったのかをメモするマークダウンを用意するだけ。**これだけで全然違います。

先にお断りしておくと、本来の ADR（Architecture Decision Record）は、アーキテクチャ上の意思決定とその背景を残すものですよね。私の使い方はもう少し広くて、作業ログ寄りです。厳密な定義に照らすと外れているところもあります。

でも、残したいものの本質は同じなんですよ。「なぜそうしたのか」は、コードには書かれない。

設計書ではダメなのか

それ、設計書でも良いんじゃないの？　と思いますよね。

ここは、どちらが優れているという話ではありません。得意なことが違うのです。

**設計書は静的で、どのような経緯でこうなったのかをメモするのが苦手。**最新の姿は正確にわかりますが、「なぜ 3 案の中からこれを選んだのか」は、完成した図面からは読み取れません
逆に、**時系列で作業のたびに追加していく ADR は、まとまったデータを作るのが苦手。**追記が積み上がるほど、全体像は掴みにくくなります

それぞれの長所短所を活かしてコントロールすると良いのかなと。

以前 AI 時代に求められるのは、DB 設計のカードを何枚持てるかだで、AI が判断できるようになっても、人間側がどうしてこういう作りになったのかを理解していないと難しい、という話を書きました。

**その「どうして」を置く場所が、ADR です。**設計書には結論しか書けませんからね。

ADR は、AI のためではなく人のためにも効く

ここが意外と大事なところ。

ADR は AI のためではなくて、人のためにも役に立ちます。

AI が膨大なソースを出してくると、レビューが間に合わん。っていうか、レビューをしたら、それ自体がボトルネックになってしまうんですよ。1 日で 1000 行が出てくる横で、人間が 1 行ずつ追いかけるのは、どう考えても勝負になりません。

そんな時、何をやったのかをこのドキュメントに書かせておけば、見直しも楽になります。

全部のコードを追うのではなく、「何をしたと言っているか」と「本当にそうなっているか」を突き合わせる。読む対象が変わるわけです。

このブログも ADR で管理しています

実例を出しますね。

実際にこのブログも、ADR の管理をしていて、何をする予定なのか、何をしたのかを管理しています。

最終的に、タスク管理と背景情報の記載、AI の報告が混ざって、新型のタスク管理ツールみたいになっていますが……。

でも、これが思いのほか効くんですよ。

AI も関連する情報をこの ADR から引っ張ってきて、私に提案してくれます。「前に同じ判断をしていますが、今回もそれに合わせますか？」という具合に。ADR があるだけで良きパートナーとなるのです。

指示する側が毎回同じ前提を説明しなくて済む。これは地味に効きます。

情報が多いと、ノイズになりませんか

「そんなに書いたら、コンテキストがノイズだらけになるのでは？」と思いますよね。

私も最初はそう思っていました。でも、実際に運用してみると気にならないんですよ。

理由は 2 つあります。

1 つは、AI は優秀で、関連するところだけ綺麗に読んでくれること。全文を等しく重く扱うわけではありません。

もう 1 つ、こちらのほうが本質的です。**ADR には、確定や確度の高い情報しか載らない。**検討中のアイデアや、ボツになった案の残骸は書きません。決まったこと、やったこと、その理由だけです。

だから毒にならない。まとまりのない膨大なコンテキストを毎回投げ込むより、全然マシですよね。

まとめ

というわけで、AI に一括修正を任せるなら ADR を書け！　って話でした！

あ。正確には、AI が何をやったのかを、人間も AI も読める形で残しておこう、って感じですねっ。

今回の事故は、AI が悪いわけではありません。「ここは合わせない」という理由が、どこにも残っていなかっただけです。人間が書いていた頃は、それがコメントとして自然に残っていた。書き手が変わったのに、記録の置き場所を変えていなかった私のミスなんですよ。

まずはマークダウンを 1 枚。AI が何をやったのか、整理するドキュメントを作ってみてはいかがでしょうか？