AIと育てる型定義 Part 2:『唯一の真実の源』の確立

著者: ClaudeMix Team |

関連しているが少しずつ内容が違う型定義(元データ・詳細ページ用・一覧ページ用・部分セット)が、それぞれ独立して定義されていた。「唯一の真実の源(Single Source of Truth)」という設計原則を導入し、基底型から派生型を自動生成する一方向の依存関係に再構築した。

① やったこと

Before: 同じドメインの型が、用途ごとに4つ独立して定義されていた。

  • ビルド時に生成される元データ(すべての情報を持つ)
  • 詳細ページで必要とされるフルセット
  • 一覧ページで使われる要約版
  • コンポーネントが表示に使う部分セット

元データに新しいプロパティを追加すると、他の3つの関連型を手動で更新する必要があり、修正漏れのリスクが高かった。どの型が「最新」で「正しい」情報源なのかも不明確だった。

After: すべての情報を持つ基底型を1つ定義し、TypeScriptのUtility Types(Pick/Omit)で他の3つを基底型から自動的に派生させる、一方向の依存関係(基底型→派生型)に再構築した。

② 設計判断

  • 【優先した価値】: 基底型を変更すれば派生型に自動反映される構造にし、「どの型が情報源か」を一意にすること
  • 【犠牲にした価値】: 各用途の型を独立に自由な形で定義できる柔軟性。派生型は基底型の制約を受けるため、基底型にないプロパティを派生型だけで自由に追加することはできなくなった

③ 技術的負債

  • 【解消した負債】: 独立して定義されていた4つの型(元データ・詳細用・一覧用・部分セット)を、基底型1つ+そこから派生する3つの型に再構築した。独立した情報源の数は4箇所→1箇所に減った
  • 【新たに生まれた負債】: 基底型がすべての派生元になるため、基底型の設計を誤ると影響がプロジェクト全体の4箇所すべてに波及する

④ 経営翻訳

同じ案件について、4つの部署(元データ・詳細ページ・一覧ページ・表示コンポーネント)がそれぞれ独自に台帳を作っていた。本部の台帳(基底型)を更新しても、他の3部署の台帳は手作業で追従させる必要があり、どの台帳が正本か分からなくなっていた。本部の台帳から各部署の台帳を自動的に生成する仕組みに切り替えた。

「型からSSOTを確立する」のと並行して、UIラベル・バリデーション・テストIDを含むすべての設定値をYAMLの階層型マージで一元管理するアーキテクチャも整備した。型定義のSSOTとYAML定義のSSOTが両輪として機能することで、「コードが仕様を語る」状態が完成する。同じSSOT思想をE2Eテストデータに適用したspec.yamlでテストデータを一元管理して記事追加でテストが壊れなくなった記録も参照してほしい。

このシリーズの記事

同じ案件について、4つの部署がそれぞれ独自に台帳を作っていた。 本部の台帳を更新しても、他の部署の台帳は手作業で追従させる必要があり、 どの台帳が正本か分からなくなっていた。

独立した台帳(情報源)の数: 4箇所