3段階の階層型スペック・マージでSSOTと疎結合を両立させた設計

著者: ClaudeMix Team |

サービス全体の設定値が各ドメインに個別にハードコードされていた問題を、Shared > Domain > Sectionの3階層YAMLとビルド時の差分抽出によるESモジュール生成で解決した。

① やったこと

Before: カテゴリ名・UIラベル・バリデーション定義が、各ドメインのコードに個別に直接書き込まれていた。

// app/routes/blog._index.tsx(変更前、抜粋)
const categories = ['ガイド', '開発記録', '設計考察', '資料室'];

カテゴリ名を1つ変更するだけで、これを直接書いている全ドメインのファイルを検索して修正する必要があった。

After: 全社共通(Shared)・ドメイン共通(Common)・ページ個別(Section)の3階層でYAML定義を持たせ、下位階層が上位階層を継承・上書きする構造にした。ビルド時に基底スペックとの差分だけを抽出し、差分のみをESモジュールとして書き出す。

// scripts/prebuild/generate-specs.js(差分抽出、抜粋)
function getDifference(target, base) {
  const diff = {};
  for (const key in target) {
    if (base && key in base && target[key] !== base[key]) {
      diff[key] = target[key];
    } else if (!base || !(key in base)) {
      diff[key] = target[key];
    }
  }
  return diff;
}
// app/generated/specs/blog/posts.ts(ランタイムでの復元)
import { data as base } from './common';
import { deepMerge } from '~/lib/utils/deepMerge';

export const data = deepMerge(base, {
  posts_config: { page_title: "Latest Update" },
});

差分だけを転送し、ランタイムでdeepMergeすることで、上位階層の重複データをクライアントへ二重に送らずに済むようにした。

② 設計判断

  • 【優先した価値】: 「設定を1箇所変えれば全体に伝播する」一貫性と、Cloudflare Workersのバンドルサイズを膨らませない疎結合の両立
  • 【犠牲にした価値】: フラットな単一設定ファイルであれば一目で分かった「この値がどこから来ているか」が、階層をたどらないと分からなくなった。差分抽出・マージという中間層が増えた分、認知コストが上がった

③ 技術的負債

  • 【解消した負債】: 設定値が各ドメインに個別にハードコードされ、変更のたびに複数ファイルを手動で同期する必要があった状態
  • 【新たに生まれた負債】: 差分抽出ロジック(基底と対象を比較するマージ処理)自体が、階層が増えるほど複雑になる。新しい階層を追加するたびに、このマージロジックが正しく差分を検出できるかを個別に確認する必要がある

④ 経営翻訳

全社共通の規定・部署ごとの規定・課ごとの規定を、それぞれ独立した分厚い冊子として配っていたため、共通規定を1つ変えると全部署の冊子を作り直す必要があった状況に相当する。共通規定は本部が持ち、各部署・課の冊子には「本部規定と違う部分だけ」を書き、必要なときに合体させて読む方式に変えることにした。

このspec.yamlを唯一の情報源とする設計思想は、コードだけでなくコンテンツにも適用できる。ブログメタデータの必須項目・禁止記法を共有lintエンジンで検証する仕組みも、この階層設計があるからこそ検証ルールをRUNNERSへ登録するだけで済んでいる(ただしカテゴリ・タグの値そのものがspec.yamlの許可リストと一致しているかまでは、まだ検証していない)。また、E2EテストのセレクタIDも同じspec.yamlから動的に取得するextractTestIdパターンを採用することで、UIの文言変更がテストを壊さない構造を実現している。