失敗から学んだ設計判断
「正しかったはず」が壊れるとき

インフラエンジニアとして7年。サーバーの構築、監視、障害対応をひたすらやってきた自分が、「何かを作る側」になりたくて受託開発の世界に飛び込んだ。

転職直後、自分がまずやったのは本を読むことだった。デザインパターン、クリーンアーキテクチャ、SOLID原則。読めば読むほど「正しいやり方」が見えてくる気がした。教科書が示す構造に従えば、良いコードが書けるはずだと信じていた。

現場に入ってすぐ、先輩から衝撃的なことを言われた。「分かっていないのに書くより、分からないから書かないほうがマシだよ」と。当時の自分は「とにかく手を動かさなきゃ」と焦っていたが、先輩は「理解してから書け」と教えてくれた。

振り返ると、転職してすぐの自分は毎日が発見の連続だった。インフラの世界では「設計」といえばネットワーク構成図やサーバースペックの話だったが、Web開発の「設計」はもっと抽象的で、もっと自由度が高かった。

自由度が高いということは、間違える余地も大きいということだ。等身大のコードを書くことの大切さに気づくまでに、いくつかの痛い経験が必要だった。背伸びしたコードは、書いた本人にすら読めなくなる。

学ぶ速度と実践のギャップ。本で知識を入れるスピードに、現場で使いこなす力が追いつかない。そのギャップが、これから話す3つの失敗を生んだ。

最初の失敗は、小規模な受託案件でのことだった。

機能としてはシンプルな業務システム。CRUD操作が中心で、ユーザー数も限られている。にもかかわらず、自分は教科書通りにService層、Repository層を細かく分離した。「将来の拡張に備えて」という理由で。

結果はどうなったか。クラス数が膨れ上がり、ひとつの機能を改修するのに5つも6つもファイルを追う必要が出た。コントローラーからサービスを呼び、サービスからリポジトリを呼び、リポジトリからエンティティを……と、処理の流れを追うだけで疲弊する構造になっていた。

チームメンバーから「どこに何があるかわからない」と言われたときの衝撃は、今でも覚えている。自分は「きれいに分離できた」と思っていたのに、他の人から見ると「迷路」だった。

「資料を書くと管理コストが発生する」——現場で学んだこの教訓は、抽象化にもそのまま当てはまる。レイヤーを増やせば、レイヤー間の整合性を維持するコストが発生する。

YAGNIという原則は知っていた。「You Aren't Gonna Need It」——今必要でないものは作るな。頭では理解していたのに、「将来の拡張に備えて」という免罪符が、YAGNIを無力化していた。

「将来」は来なかった。そのプロジェクトは初期リリース後、大きな機能追加なく安定運用に入った。過剰に分離されたレイヤーは、誰にも使われないまま残り続けた。

2つ目の失敗は、医療系ドメインの在庫管理システムの保守で起きた。

既存の在庫管理ロジックに機能追加を行う担当になった。入出庫の履歴表示や発注データの出力など、新しい機能を実装してテストを書いた。正常系のテストは全部グリーン。自分の追加分は問題ないと安心していた。

ところが、運用中に問題が浮上した。在庫計算ロジックにエッジケースで不正な結果を返す不具合が潜んでいた。自分が追加した機能ではなく、既存のロジックに元々あった問題だった。結果的に既存コードを丹念に読み解いて原因を特定し、修正することになった。

このとき痛感したのは、自分が書いた部分だけテストして安心していたということだ。先輩に言われた言葉が刺さった。「テストを書くということは、データの動きが正しいかどうかを捉えることだ。自分が書いたコードだけでなく、データが通る道全体を見ないといけない」と。

自分のテストは「自分の追加分が動くこと」を証明するためのものだった。「システム全体として壊れないこと」を証明するためのものではなかった。この違いは大きい。

全パターンを網羅するのは現実的に無理だ。だからこそ「枝刈り」の考え方が必要になる。全部テストするのではなく、壊れやすい箇所を見極めて、そこに集中する。

テストケースの優先順位を完全に誤っていた。正常系100本書くよりも、境界値10本のほうが価値がある場面がある。特に金額や数量を扱うロジックでは、ゼロ、マイナス、最大値、同時アクセスといったエッジケースが最も危険だ。

この経験以降、テストを書くときの順番が変わった。まず「どこが壊れやすいか」を考え、そこから書き始める。正常系は後回しでいい。正常系が動くことは実装中にだいたい分かるからだ。

3つ目の失敗は、外部API統合の設計で起きた。

複数の外部サービスからデータを取得し、統一的に扱う必要があった。Adapterパターンを採用した。これ自体は正しい判断だった。各APIの差異をAdapterで吸収し、ビジネスロジック側は統一インターフェースだけを知っていればよい、きれいな設計だ。

最初の2社のAPIはうまくいった。レスポンス形式が似ていたからだ。JSONのフラットな構造で、フィールド名が違うだけ。Adapterのマッピングも単純だった。

問題は3社目のAPIが追加されたときに起きた。レスポンス構造が根本的に異なっていた。ネストされたオブジェクト、ページネーションの仕組みが独自、データの粒度も違う。既存のAdapterの抽象化レイヤーが前提としていた「レスポンスはフラットなJSON」という暗黙の仮定が、完全に崩れた。

「1箇所コードを直すことの恐ろしさ」——現場で痛感した「変更の重み」が、まさにこの瞬間に現実になった。Adapterの共通部分に手を入れると、既存2社の動作にも影響が出る。

自分が暗黙に置いていた前提は「APIのレスポンス形式は、ある程度似ている」だった。最初の2社がたまたま似ていたから、この前提を疑わなかった。しかしそれは偶然であり、3社目が現れた瞬間に崩壊した。

結局、Adapterの設計を見直した。「変換ルール」と「共通インターフェース」を明確に分離し、変換ルール側をAPIごとに完全に独立させる形にリファクタリングした。共通インターフェースは最小限にし、各Adapterが自由に変換処理を書ける余地を残した。

3つの失敗を並べてみると、共通するパターンが見えてくる。

過剰な抽象化では、「将来拡張がある」という前提を疑わなかった。テストの不備では、「正常系が通れば大丈夫」という前提を疑わなかった。API設計では、「レスポンス形式は似ている」という前提を疑わなかった。

どの失敗も、技術力の不足が原因ではなかった。自分が置いた前提を疑わなかったことが原因だった。

現場の先輩から学んだ「仮説思考」の大切さが、ここに繋がる。「動かない」という事実に引っ張られるのではなく、「なぜ動かないのか」「自分は何を前提にしていたのか」を紐解く。この思考の習慣があれば、失敗の芽を早い段階で摘める。

「良い設計は良い数式に通じる。例外がないことが美しい数式の条件だ」——先輩のこの言葉が、後の設計判断を変えた。

StrengthsFinderでいう「慎重さ」は、設計の強みになる。リスクを事前に洗い出し、防御的に構造を作る力だ。しかし、一度「正しい」と信じた設計を疑う方向には、慎重さは働きにくい。自分の慎重さは「新しいリスク」には敏感だが、「自分が作ったもの」には甘い。

だからこそ、意識的に自分の設計を疑う仕組みが必要だった。それが次のセクションで話す「3つの問い」だ。

3つの失敗を経て、設計に取りかかる前に自然と習慣になった問いがある。大げさなフレームワークではない。自分への問いかけだ。

この3つの問いは、「段階的詳細化」の考え方にも通じる。いきなりコードを書き始めるのではなく、まず全体像を俯瞰し、前提を確認し、リスクを洗い出してから詳細に入る。

特別なことではない。ただ、失敗しないと身につかなかった。本で読んだだけでは、自分ごとにならなかった。手を動かし、痛い目を見て、初めて骨身に染みた。