frontend-layered-architecture

フロントエンドのレイヤーアーキテクチャ

概要

フロントエンドのディレクトリ構成を、「ページとそれ以外」に集約してはいけません。components、hooks、models、utils、shared など、型は示していても役割が曖昧なフォルダーには、あらゆるコードが入り込む可能性があります。このスキルは、大規模なアーキテクチャを強制するためのものではありません。実装中に、ビジネスルール、API 呼び出し、URL の状態などのロジックが、適切でないフォルダーに無意識のうちに漏れ出すのを防ぐことを目的としています。

コードは、役割、依存関係、外部データとの境界、オーケストレーションの責任に基づいてレイヤーに分ける必要があります。下位レイヤーのコードが、上位レイヤーのコンテキストを認識するようにしてはいけません。

このスキルは、Feature-Sliced Design や Vertical Slice Architecture など、特定の方法論を強制するものではありません。型ベース、機能ベース、ドメイン駆動型など、さまざまなディレクトリ構成が有効です。重要なのは、プロジェクトが選んだ構成の中で役割と依存の方向が明確であること、外部データの契約が分離されていること、コードの責任とフロントエンドが担うドメインロジックが適切に管理されていることです。

既存のプロジェクトでは、アーキテクチャが文書化されている、ユーザーの承認を得ている、または役割、依存関係、データ境界を通じて一貫して認識できる場合に限り、それが意図的なものとして扱います。それ以外の場合は、繰り返されている配置を正当な根拠とみなさず、新規コードや変更するコードにこのスキルの基本方針を適用してください。

共通基盤

プロジェクトですでにレイヤーの用語が使われている場合は、プロジェクトの用語を優先してください。既存の用語がない場合、または構造を説明する場合にのみ、以下の用語を使用してください。これらの抽象的なレイヤー名はデフォルトのディレクトリ名ではありません。ユーザーが明示的にその名前を選択していない限り、End-User、Domain、Shared、Dataをフォルダーに変換しないでください。

このスキルにおける抽象レイヤーの分類と依存方向は、フロントエンドにのみ適用され、APIサーバーやその他のアプリケーションにそのまま適用されるものではありません。以下の図とルールは、プロジェクト固有の例外を含まないデフォルトの構造を示しています。たとえば、モノレポ内でクライアントがサーバー生成のスキーマを利用するのではなく、サーバーとクライアントがEntitiesのコードを直接共有している場合は、DataがDomain内のEntitiesを参照するように、DomainをDataより下位に配置できます。

flowchart TB
  End-User --> Domain
  Domain --> Shared
  End-User --> Data
  Domain -. schemas/types by default .-> Data

レイヤー	意味
End-User	ユーザーに提供される画面です。ページやルートなど、UIフロー、データ取得、オーケストレーションを扱う最上位のレイヤーです。
Domain	Clean ArchitectureのEntitiesに似た、再利用可能なビジネスルール、バリデーション、計算、機能フラグです。このスキルが推奨するベースラインアーキテクチャでは、DomainにAPI呼び出しや外部サービスへのアクセスは含まれません。
Shared	外部のコンテキストを知らない純粋なコードです。最下位のレイヤーです。
Data	外部データの契約と実行境界です。API関連のソースコードはここに属し、フロントエンド開発者が作成した場合でも、フロントエンドが利用する外部所有のコードとして扱います。

これらの抽象レイヤーは、健全なフロントエンド構造を設計するための最小単位です。実際のプロジェクトではさらに細分化される場合がありますが、少なくとも4つの概念が必要ということです。そのため、これらは抽象レイヤーです。

最小限のガード：

• レイヤー名は抽象的な概念であり、必須のフォルダー名ではありません。
• Sharedかどうかは、汎用的な名前やドメイン用語が含まれないことではなく、コードレベルで独立しているかどうかで判断します。たとえば、注入されたpropsを描画するだけならProductCardはSharedになり得ますが、汎用的に見えるbuildSearchParamsでも、ルーターの状態、APIリクエストのパラメーター、ストアの状態、またはビジネスルールを認識していればSharedではありません。
• ブラウザー、ルーター、フォーム、その他のライブラリプリミティブを汎用的にラップするものは、アプリケーション固有の状態、ポリシー、アクションが注入される場合、Sharedのままにできます。インポートしているパッケージではなく、コードが認識しているアプリケーションのコンテキストを基準に判断してください。
• Dataとは、フロントエンドが外部所有のコードと同様に利用する境界を意味します。ファイルが物理的に外部にあることや、別のチームが作成したことを意味するものではありません。たとえば、OpenAPIで生成されたクライアント／スキーマコードも、手動で作成されたAPIエンドポイント／スキーマコードも、フロントエンドが外部の契約として利用する場合はDataです。
• DomainからDataへのアクセスをスキーマ／型のみに限定するのがデフォルトなのは、宣言的なデータ取得（例：useQueryスタイルのAPI）では、Dataの実行、キャッシュ、同期がEnd-UserのUIオーケストレーションに置かれるためです。別の言語やフレームワークで異なる方向が一般的だからといって、このフロントエンドのデフォルトを変更しないでください。別の方向に従うのは、文書化または承認されたプロジェクトルールで定められている場合、一貫性があり判別可能な既存アーキテクチャですでに採用されている場合、またはユーザーが明示的に決定した場合に限ります。
• Dataがどのプロジェクトモジュールに依存できるかは、普遍的な内向き依存ルールを割り当てるのではなく、実際の実装に基づいて判断してください。
• 同じ抽象レイヤー内であっても、依存関係が妥当かどうかは役割と責任によって異なります。たとえば、プロジェクトがentitiesとwidgetsをどちらもDomainに割り当てていても、entitiesがwidgets内のUIオーケストレーションをインポートすることは禁止される場合があります。
• プロジェクトでフォルダーの役割が文書化または承認されている場合は、まずその役割を使用してください。責任や依存方向に違反があるかを確認する場合にのみ、抽象レイヤーに対応付けてください。承認済みの役割を、現在のファイル名、まばらなフォルダー、または汚染された使用状況で置き換えないでください。

Purpose Router

ユーザーの目的を一文で分類し、最初に一致するドキュメントを読みます。ルーティング先のドキュメントの代わりに、このファイルを使用しないでください。

ユーザーの目的	読むドキュメント
ディレクトリの追加、削除、名前変更、再編成、ファイルの配置、ファイルの切り出し、インポートの方向、依存関係の境界に関する判断を含む、既存プロジェクトの構造の判断または変更	brownfield.md
ディレクトリやレイヤーの構造がまだ決まっていない新しいフロントエンドプロジェクト	greenfield.md
docs/architecture.md、ディレクトリルール、依存関係ルール、Mermaid による概要などのアーキテクチャドキュメント	writing-docs.md
eslint-plugin-boundaries、ESLint、CI、インポート境界、その他のツールを使ったアーキテクチャルールの適用	enforcing-rules.md
メインのルーティング先ドキュメントを適用しても配置またはインポートの方向が解決しない場合、または既存コードベースの広範な監査で補助的なチェックリストが必要な場合	best-practices.md

ルーティングルール：

• 最初に気づいたアーキテクチャ関連のキーワードではなく、ユーザーの実際の目的に基づいてドキュメントを選びます。
• リクエストに複数の目的が含まれる場合は、ユーザーに次に見えるアクションを左右する目的にルーティングします。
• エージェントがフロントエンドのアーキテクチャルールを適用するツールを追加または変更しようとしている場合、ユーザーが適用を依頼していない場合や、アーキテクチャがセッションの主な目的ではない場合でも、enforcing-rules.md を読みます。
• ルーティング先のドキュメントを読んだ後、ユーザーの目的に直接答えているか確認します。答えていない場合は、不足している内容を伝え、スキルに答えが含まれているかのように装うのではなく、次に必要な資料へルーティングします。
• 既存のコードベースでは、構造に関する判断とユーザーが依頼した構造変更のどちらにも、brownfield.md を読みます。新しいディレクトリ構造やレイヤー構造のリクエストを、グリーンフィールド作業として扱わないでください。
• 既存プロジェクトの広範な監査や評価では、まず brownfield.md を読み、その後、補助的なチェックリストとして best-practices.md の「よくある間違い」の表だけを確認します。例をテンプレートとして適用したり、プロジェクト固有のルールを上書きしたりしないでください。
• 配置やインポートの方向に関する具体的な判断、または実装作業では、デフォルトで best-practices.md を読みません。