AIが書く「読みづらいADR」に発狂しかけたので、ADRのガイドラインを作った

BRANK

はじめにみなさん、ADR（Architecture Decision Record）は書いていますでしょうか？AIを使ったソフトウェア開発において「意思決定の記録を残す」ことの重要性は、今や多くのエンジニアに周知されているかと思います。僕が率いるチームにおいても、プロジェクト開始初期から様々な技術的な意思決定をADRに記録し、運用してきました。最近では、ADRのドラフト作成もAIに任せるようになっています。ところが、ADRを書くルールを整備しないままAIに書かせていると、 人間が読み返しづらいADR が次々と出てくるようになりました。「人間がじっくり目を通すべきものの代表格」とも言えるADRですが、これが読みづらいと凄まじくストレスフルです。そこで僕は、ADRの文面が意図を汲み取りやすい状態に保たれるよう、ADRに書くべきこと・書くべきでないことを整理したガイドラインを作成する取り組みを実施しました。この記事では、具体的にどのような問題が発生し、どのようなガイドラインを作成したのか、実例も交えながら知見として共有させていただきます。ADRは、2011年にMichael Nygardがブログ記事『Documenting Architecture Decisions』で提唱した、アーキテクチャ上の意…