Railsアップデートから学ぶ意思決定に根拠を持ち、残すことの重要性

※この記事は、2025 Speee Advent Calendar15日目の記事です。昨日の記事はこちら

こんにちは。Speeeで不動産一括査定サービス「すまいステップ」の開発を担当している中島です。 Speeeには新卒で入社し、2年目のエンジニアとして少しずつ難しい開発にも取り組んでいます。

私は新卒1年目からすまいステップの開発に携わってきました。この記事では、Rails 6.1から7.1へのメジャーアップデートを担当し、そこから学んだ「意思決定に明確な根拠を持ち、それを残していくことの重要性」の話をします。

Railsのメジャーアップデートは影響範囲が広く工数の見積もりも難しいため、どの開発チームでも優先順位の判断が悩ましいテーマではないでしょうか。すまいステップでもEOLが迫る中、優先度を上げて取り組むことになりました。

LLMを使った調査と、根拠のない意思決定への気づき

Railsのアップデートが初めてであることもあり、チームの助言を得て次のような手順で進めていくことにしました。

Railsガイドに記載の主な変更点を確認しつつ、ガイドに記載の方法でバージョンを少しずつ上げていく
とりあえずgemのバージョンを上げてみて、既存のテストがどの程度失敗するのかを確認する

調査を進めるにあたり、LLMの力を借りることで工数を大きく抑えることができたのは間違いありません。 Railsガイドやリポジトリを読んでもらい、この変更点について影響がありそうかを1つずつ確認しました。また、Gemを上げてみたところ、テストが実行される前に落ちるエラーがあり、その直し方もLLMを使用してあたりをつけることができました。

ところが、修正を始めようとしたとき、一つの壁にぶつかりました。 既存のテストでエラーが出ているため修正したいのですが、どう直すのが良いか判断がつかないのです。

具体的な例を挙げると、gemのアップデートを行った際に以下のようにテストが失敗しました。

Failure/Error: expect(mail[:to].value).to match_array ['test1@example.com']
       expected a collection that can be converted to an array with `#to_ary` or `#to_a`, but got "test1@example.com"

メッセージを見れば、配列で来ていたものが文字列で来るようになって、メソッドが呼べなくなったというエラーであることはわかります。しかし、ここから実装を修正するのか、テストを修正するのか、どちらの選択肢を取れば良いのかパッとわかりませんでした。

とりあえず実装を変えずとも動作はしていて、LLM上も問題なさそうだったので、テストの形式が変わったと解釈し、テストを修正しました。

この状態でレビュー依頼を出したところ、「なぜこの変更をしたのか？」というレビューをもらいました。動作確認で問題なく、LLM上も問題がなさそうであることを伝えたところ、「自分がなぜ動いているかわかっていない状態でコードに変更を加えている」ため、公式ドキュメントやリポジトリから理由を調べた方が良いというフィードバックを受けました。

つまり、自分がコードに加えた変更について根拠を持てていないことで、本当に正しい変更かを評価できていませんでした。そして、レビュワーも正しい変更かを評価できないため、そのままリリースすると予期せぬトラブルになる可能性があるという課題がありました。

チームからのフィードバックを経た改善

公式ドキュメントやリポジトリからコードを調査することに慣れていなかったのですが、LLMに次のような指示を与えました。

エラーの原因を探るときは、ファイルや公式ドキュメントを参照してください。特に公式ドキュメントを参照することは一次情報を得ることになるので重要です。
各情報は出所を ref: {location} の形で明らかにしてください。推測が挟まる場合は裏どりをしてください。

この指示を与えたことで、LLMが動作変更の核心に近い部分の情報を抽出し、refからその箇所を自分で見て、これは間違いない、と判断できるようになりました。

先ほどのエラーの場合、rails gemのアップデートの際に一緒に上がったmailというgemの返す型が変わったために起きたエラーということがわかりました。また、テストの書き方がgemで推奨されている書き方ではないことがわかり、合わせて修正することができました。

結果的には当初の見立て通り「テストを修正する」という対処でしたが、公式ドキュメントを用いて裏取りが行えていることで、意思決定の自信度は非常に高いものになり、コードとしても良いものになりました。

さらに、このように修正した背景や根拠を残しておく、ということにも取り組みました。意思決定の背景が残っていないことで、なぜこのような実装になっているかわからず直しにくかった経験があったためです。根拠がしっかりしていればすぐに記載できるため、この動きも意思決定に根拠を持たせる（不十分なら調べさせる）動きにつながっていきました。

この後も様々なエラーに対応することになりましたが、この2つを徹底したことで、ver6.1台から7.1台へのバージョンアップを約1ヶ月で完遂することができました。

その後の開発に活かせたこと

Railsアップデートによって、意思決定に根拠を持ち、残すことが重要だと学びましたが、これはその後の開発にも活きていると感じます。

例えば、Rails 7.1のEOLがすぐに訪れたため、もう一度Railsをアップデートする際には最初からこの動きを徹底していました。また、過去の意思決定の記載が残っていたため、どのような粒度で意思決定を残していけば良いかがわかりやすかったです。結果として、このアップデートは想定より早く、障害も出さずに進めることができました。

Railsアップデート以外にもこの動きが広がっています。オペレーションの効率化の開発を行っている際は、「このテーブル構造にしたのはなぜか？」「ログをこの方法で残すと決めた背景を記載したい」というレビューが出てくるなど、チームの文化として意思決定に根拠を持ち、残すことが根付いてきています。