バッチ処理の設計で学んだ、「ハッピーパス」の効能と「設計レビュー」の重要性 #PERSOL CAREER Advent Calender2025

はじめに
全てを考慮しようとして、手が止まった
「まずは正常系だけでいい」というアドバイス
Kaigi on Rails の「ハッピーパス」の話
モブレビューで気づいた、設計レビューの大切さ
おわりに

はじめに

今年のDeveloper&Designer Advent Calendar 2025の8日目を担当する、はたらく未来図構想統括部 JobQ部エンジニアの川村です。私が普段開発している「JobQ Town」では、バックエンド・フロントエンド双方の実装に関わっています。

エンジニア3年目となった最近は、1つのプロジェクトにおいて設計から実装までを一貫して担当することが多いです。
「どう作ればメンテナンスしやすいか」「拡張性はあるか」——。自分の頭でシステムを組み立てていくこの過程に、これまでとは違う楽しさを感じています。

先日、その「設計」という壁の高さに改めて直面し、そこから大きな学びを得る出来事がありました。
今回はバッチ処理の実装を通して学んだ「ハッピーパス」と「設計レビュー」の重要性について、得た気づきを振り返っていきたいと思います。

全てを考慮しようとして、手が止まった

先日、ある定期バッチ処理を作成するタスクがアサインされました。
要件自体はシンプルで、「外部から提供される重ためのZIPファイルを解凍し、中にあるCSVからデータを抽出してDBに保存する」というものです。

エンジニア3年目ともなると、設計時に考えるべきリスクやエッジケースが多く頭に浮かぶようになります。
さらに最近ではAIに壁打ちをすることで、自分では気づけなかった懸念点まで提示されるようになり、考慮事項は増える一方です。

アーキテクチャの懸念：
- 冪等性の担保はできているか
- 定期実行時の二重起動を防ぐためのロック制御は必要か
- ストリーミング処理にした方が安全か
- 途中で落ちた場合、途中から再開できるレジューム処理は必要か
パフォーマンスの懸念：
- 定期的にGCを走らせないとメモリが溢れるか
- マスターデータは事前キャッシュしておかないとDB負荷が高いのか
- 重複チェックはHashでやるべきか、Setでやるべきか？
異常系・エッジケースの懸念：
- ダウンロードしようとしたZIPが存在しなかったら
- ZIPの中にCSVが入っていなかったら？
- CSVのヘッダーや文字コードが想定していないものだったら？
- 失敗時のログ通知レベルや、一時ファイルのクリーンアップ漏れ対策は

……などなど。

考え出すとキリがなく、「あれもやらなきゃ、これもやらなきゃ」とリスクばかりが目につき、思考が発散しすぎて手が全く動かなくなりました。

「まずは正常系だけでいい」というアドバイス

そんなときに、エンジニアリングマネジャーの村松さんからあるアドバイスをもらいました。

まず正常系だけにフォーカスして実装する
その後、想定される異常系の洗い出しをしてからそれを考慮した実装を追加する

そこで、正常系の前提条件を整理してみました。

ZIPファイルは必ず存在する。
ダウンロード時のHTTPステータスは必ず200が返る。
ZIP内には想定通りのCSVファイルが1つだけ含まれている。
CSVの形式（カラム、ヘッダー、文字コード）は全て正しい。
DB、ワーカーが正常に稼働している。
関連するマスターデータが全て揃っている。

これらを前提にすると、やるべきことがシンプルに、実装すべき最小の流れが見えてきました。

Kaigi on Rails の「ハッピーパス」の話

先日、私はKaigi on Rails 2025に参加してきました。参加レポートはこちらです。

実装を進めていたとき、Kaigi on Railsのkeynote、諸橋さんの「dynamic!」を思い出しました。

こちらのkeynoteでは「ハッピーパス」という概念が語られています。

"ふつう"の利用者が期待する最もシンプルな操作ができるところまで実装できている状態。（中略）いわゆる「正常系」のユースケースに近いです。一式すべてでなく、さらにステップを分割できることもあります。 MVPとも違って、もっと小さくスライスします。MVP一式だとこの判断のためには大きすぎる。

セッションを聞いた当時は感銘を受けつつも、自分が直面していた「定期バッチの実装」という文脈では、どこか別物だと感じていました。
しかし今回、村松さんのアドバイスを通じて、ハッピーパスの考え方がバッチ処理の設計にもそのまま応用できることに気づきました。

ハッピーパスを作ることは、単に手を動かしやすくするだけではありません。
動くコードができたことで、ローカル環境や検証環境で実際にデータを流したらどこで詰まるかを早期に確認できるようになります。
また、正常系が動いたという達成感は、精神的な安心材料にもなります。
その後、当初心配していたパフォーマンスやエラー処理を1つずつ追加していったのですが、土台ができているため、迷うことなくスムーズに実装できました。

モブレビューで気づいた、設計レビューの大切さ

実装が一通り完了した後、コードが複雑になってしまっていたこともあり、開発メンバーとモブレビュー会を開催しました。
自分でコードを解説しながら、メンバーからフィードバックをもらう形式です。
（JobQ部のエンジニアメンバーでは現在、定期的にモブプロ会・モブレビュー会を開いています）

レビューの結果、大きな方針が変わることはありませんでしたが、「ここの設計はもっといい方法があったかもしれない」という指摘をいくつかいただきました。

このレビュー会を通じて、もう一つ、Kaigi on Railsのセッションを思い出しました。
大場さんの『Railsによる人工的「設計」入門』です。

このセッションでは、完成形から逆算して設計する重要性と、設計段階でのレビューの大切さが語られていました。印象的だったのは、「設計を体得できていないと、つい最初にコードから考えてしまう」という指摘です。
コードを書き始める前の「作戦」段階——全体の構造や技術要素を決め、手順を考えた時点で、レビューを受けることが推奨されていました。

振り返ってみると、自分はこれまで何度か定期バッチを作った経験から、「コードを書きながら考えよう」という姿勢で臨んでいました。
しかし、今回の経験を通じて、実装前にもう少し時間をかけて設計を固めるべきだったと感じています。
そして「作戦」の段階で、メンバーにレビューしてもらえれば、実装後に気づいた課題を、もっと早い段階で発見できたかもしれません。
今後はこの「作戦」のタイミングを意識的に作っていきたいと思っています。