ミニフレームワークは避けましょう。

Japanese Translation:

ミニフレームワーク―確立されたスタックの上に構築される小さく、意見が強いラッパーは、しばしば小規模チームの「魔法的」解決策として始まります。彼らは迅速な成果を約束しますが、通常は隠れた複雑さとリスクを増やします。

著者はGoogleでの経験に大きく基づいています。よくメンテナンスされた内部フレームワークの上に抽象化層を追加した結果、1年間にわたる移行が発生し、最終的にはすべての新しいコードがミニフレームワークを採用せざるを得なくなりました。実際には移行は完全には完了していませんでした。開発者は、新しい層が追加概念を導入し、複雑さを増大させ、日単位の開発から週単位へと遅延させ、作成者への頻繁な助けを必要とすることに気付きました。

ミニフレームワークは通常、実際のユースケースの約80 %しかカバーせず、残り20 %が回避策やパッチングを強いるギャップがあります。これは「Easier To Change」（ETC）原則に違反し、現在のユースケースのみをモデル化し、実装詳細に依存するため、将来の変更が困難になります。作成者のメンタルモデル（時にはエゴ）を反映した過度に意見的な層は他のエンジニアを疎外し、技術スタックの断片化につながります：部分的な移行が積み重ねられ、完全に完了した移行が生まれません。

オリジナルの作成者が離れるとメンテナンスは問題になります。後継者は深い知識や動機を欠くことが多く、ミニフレームワークが広範に採用されない限り放棄につながります。著者は抽象化そのものに反対しているわけではなく、新しい概念（ライブラリ＝新しい概念なし、フレームワーク＝新しい概念あり）の境界を曖昧にする不要な追加を警告しています。

推奨実践： ミニフレームワークよりもスタンドアロンのライブラリ構築を優先してください。真にフレームワークが必要な場合は、その概念を具体的なビジネス要件に直接結び付け、既存スタックをラップするのではなくゼロから構築することを検討し、決定を真剣に扱うべきです。開発者にとっては納品が遅れ、サポートコストが増加します。企業にとっては技術的負債と生産性の損失につながります。ミニフレームワークの広範な誤用は業界エコシステムを分断し、全体的な保守費用を上昇させる可能性があります。

2025年12月24日

ミニフレームワークとは？

ミニフレームワークは、企業が共有している技術スタックの上に構築された、1つまたは数チームによって作られた軽量なフレームワークです。自社の課題を解決するために設計されています。

典型的な特徴：

小規模チームが特定の問題（ボイラープレート、パフォーマンスなど）に対処するために作成。
既存の共有スタックを包み込む形で実装され、独立したライブラリではない。
オリジナルのスタックには存在しない新しい概念を導入。
「魔法のように多くの問題を解決する」と宣伝され、広い採用が促進される。

私の体験

私は4年間Google Adsインフラストラクチャで働いていました。私たちのチームは内部フレームワークを使って分散プログラムを書き、そのコードベースを徐々に移行していきました。そのフレームワークは設計が優れており、メンテナンスもされていましたが、数点気になる癖がありました。

マネージャーから「採用障壁を下げるために、その上に抽象化層を追加し、癖を修正する」と提案されました。私は反対しましたが、決定は進みました。何人かのエンジニアが数ヶ月かけてこの新レイヤーを構築しました。しかし既存コードを移行しようとした際、抽象化層が特定のユースケースに対応できず、度々パッチを当てる必要がありました。結果として移行は予定よりも遥かに長引きました。

新フレームワークが完成すると：

すべてのタスクが難しくなった：1日で済んだ作業が今では数週間かかるようになった。
著者からの助けを常に必要とした。ペアプログラミングセッションを予約し続けた。
自チーム自身も苦労。採用を容易にするという目標は達成されず、むしろ全員が遅くなってしまった。

ミニフレームワークの問題点

理由	何が起こるか
機能セットが不完全	複雑さを隠す一方で、オリジナルフレームワークほど柔軟性がない。カバレッジは80％程度が多く、残りの20％に苛立ちが生じる。
ETC（Easier To Change）原則に違反	• 現在のユースケースのみをモデル化し、将来変更されると壊れる。 • 内部詳細に依存しており、それが変わると保守が困難になる。
一人のメンタルモデルしか反映しない	意見が強い設計は他者の思考と合わず、混乱や抵抗を招く。
スタック分散を引き起こす	部分的な移行により複数レイヤーが生まれ、時間とともに複雑さが増大する。
保守が難しい	通常は元の作成者が所有しており、離脱すると知識が消失し、誰もメンテナンスを継続する動機付けがない。

代わりにすべきこと

ライブラリとフレームワークを区別
- ライブラリ は新しい概念を導入せず、ユーティリティだけを追加。
- フレームワーク は新たなメンタルモデル（READMEの「Glossary」などで明示されることが多い）を提示。
可能ならミニフレームワークの作成は避ける
- ライブラリや共有スタックを直接利用する方が望ましい。
本当にフレームワークが必要な場合、以下のガイドラインに従う
1. 概念を具体的なビジネス要件と結び付ける。内部アイデアだけでなく実際のニーズに基づくこと。
2. ゼロから始める：既存フレームワークをラップするより、最初から構築する方が良い。
3. 重大な意思決定として扱う—ライブラリとフレームワークの違いを理解し、レビュー担当者を巻き込み、長期的な保守計画を立てる。