ADR 001: フロントエンドへの Feature-Sliced Design (機能別分割) の採用
- Status: Accepted
- Date: 2026-04-17
- Deciders: Lead Engineer
Context
Section titled “Context”Next.js (App Router) を用いた開発において、従来の「技術的役割に基づくディレクトリ分割」
(例: components/, hooks/, api/ をフラットに配置する構成)は、プロジェクトが
スケールするにつれて変更の影響範囲が不明瞭になり、高い認知負荷を生む。
また、App Router の app/ ディレクトリ内に UI ロジックを詰め込むと、ルーティングと
ビジネスロジックが密結合し、テストやリファクタリングが困難になる問題があった。
Decision
Section titled “Decision”アーキテクチャ手法「Feature-Sliced Design (FSD)」のエッセンスを採用し、ドメイン (機能)単位で関連ファイルをカプセル化する。
具体的には src/features/ 配下に objectives/ や tasks/ といったドメインごとの
ディレクトリを作成し、その中に専用の UI コンポーネント、API 通信(TanStack Query
フック)、型定義を同居(Colocation)させる。app/ ディレクトリはルーティングの
宣言と機能の呼び出しのみを行う薄い層とする。
Alternatives Considered
Section titled “Alternatives Considered”-
従来のレイヤー分割(
components,hooks等のフラット配置): 導入は容易だが、1つの機能を追加・修正する際に複数のディレクトリを行き来する 必要があり、コロケーション(関連するコードを物理的に近くに置く)の原則に反する ため却下 -
厳密な完全版 FSD: Layers / Slices / Segments の3階層を厳格に守る手法だが、現在のチーム規模と プロジェクトの初期フェーズにおいてはルールが過剰に複雑(オーバーエンジニアリング) になり、開発スピードを削ぐと判断し却下
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- 変更の影響範囲が
features/xxx/の中に局所化され、保守性が劇的に向上する - 機能の追加や削除がディレクトリ単位で完結する
- 新規参画メンバーが「どこに何を書くか」の判断に迷わない
Negative
Section titled “Negative”- 「ドメインをまたぐ共有ロジック」の配置場所(例:
features/間でのインポートを どう制御するか、shared/に逃がす基準は何か)について、チーム内で明確なルール 作りと規約の維持が必要になる - FSD の正式規約から外れた「簡易版」である旨を、将来の参画メンバーに向けて ドキュメント化しておく必要がある