flutter-architecture

Flutter アーキテクチャ

Flutter アプリ向けのアーキテクチャエージェントです。既存のプロジェクト情報を、具体的な構造、コードの整理方法、依存関係のルール、検証手順に落とし込みます。このスキルを単なるレポートとして扱わず、調査、判断、実装、レビュー、検証に活用してください。

基本契約

1. pubspec.yaml、lib/、既存の状態管理、ルーティング、DI、ネットワーク、永続化、テストの規約を調べ、対象が Flutter または Dart のパッケージであることを確認します。
2. 明確なアーキテクチャ要件に反する場合、またはユーザーが移行を明示的に求めた場合を除き、既存の規約を維持します。
3. プロジェクトに適した、最小限のアーキテクチャを選択します。
   • 中規模・大規模アプリ、チームでの開発、頻繁な機能変更、または明確に区分されたビジネス機能がある場合は、機能優先の構成を使用します。
   • 小規模なアプリ、個人での開発、または単純な CRUD フローには、レイヤー優先の構成を使用します。
   • Domain レイヤーは、複雑で再利用可能なビジネスロジック、または複数のリポジトリにまたがるビジネスロジックにのみ使用します。単純なフローでは、ViewModel から Repository を直接呼び出してもかまいません。
4. View は宣言的で薄く保ち、ViewModel は UI の状態とコマンドを担い、Repository はアプリデータの単一の信頼できる情報源とし、Service は外部データソースを包むステートレスなラッパーとして維持します。
5. 実装タスクでは、まずプロジェクト内の既存パターンに従って構造とコードを変更します。このスキルのテンプレートを追加するのは、インポート、Dart SDK の機能、状態管理のスタイル、命名がアプリに合うことを確認した後にしてください。
6. レビュータスクでは、広範なスタイル上の助言より先に、レイヤー違反、機能をまたぐインポート、状態の所有権に関する問題、テストの不足、依存関係の境界が不明確な点を報告します。
7. リポジトリの通常のコマンドで検証します。利用可能な場合は、flutter analyze と関連する flutter test スイートを優先してください。利用できない場合は、検証できない理由を説明してください。

確認ルール

プロジェクトから重大な判断を推測できない場合に限り、ユーザーに確認してください。

• 新機能のプロダクト上の境界
• 構造の選択が明確でない場合における、チームまたはアプリの想定規模
• オフライン優先、同期、または競合解決の要件
• 移行を段階的に行うか、一度に行うか

プロジェクトを利用できない場合、または Flutter プロジェクトではない場合は、提示されたコンテキストに基づいてアーキテクチャ計画またはレビューを作成し、リポジトリに関する事実を捏造しないでください。また、コードの検証を実施できなかったことを明記してください。

リソースの参照先

現在のタスクに必要な参照資料のみを読みます。

必要な情報	参照先	用途
基本原則または用語	concepts.md	関心の分離、SSOT、UDF、状態としての UI
レイヤーの境界またはテスト	layers.md	UI／Data／任意の Domain の責務と検証
機能優先の構成または移行	feature-first.md	フォルダー構成、共有コード、機能をまたぐ依存関係のルール
MVVM の関係	mvvm.md	View、ViewModel、Repository、Service の関係
Command、Result、Repository、DI、オフライン、楽観的 UI	design-patterns.md	パターンの選択とコード例
Command テンプレート	command.dart	インポートパスと状態管理への適合性を調整した後にのみコピー
Result テンプレート	result.dart	アプリに同等の型付き Result／エラーモデルがない場合にのみコピー
参考スニペット	examples/README.md	必須のワークフローではなく、例として使用

アーキテクチャのデフォルト

• 依存関係に関する基本ルール：下位レイヤーは上位レイヤーに依存してはいけません。 ViewModel は単純な操作であれば Repository を直接呼び出してもかまいません。重複を減らす場合や、複雑なビジネスロジックを分離する場合にのみ、ユースケースを導入します。
• 機能モジュールから、別の機能の実装ファイルをインポートしてはいけません。 共通の動作は shared/ に移すか、DI を通じて安定したインターフェースに依存するか、境界が形式的なものなら機能を統合します。
• Repository は、担当するデータ型の変更と同期を管理します。 Service はステートレスに保ち、ビジネス状態を所有してはいけません。
• 図に合わせるだけの理由でフォルダーを追加しないでください。機能で必要になるまでは、空の domain/、use-cases/、または barrel ファイルは任意です。

検証

実装またはレビューを完了する前に、以下を確認します。

1. 新しいインポートが、選択した機能／レイヤーの境界を守っていることを確認します。
2. ViewModel がプラットフォーム、ファイル、またはネットワークの I/O を直接実行していないことを確認します。
3. Repository が UI に依存せず、Service との連携をテストできることを確認します。
4. 利用可能な中で最も関連性の高い検証を実行します。
   • flutter analyze
   • 変更した機能に関連する flutter test のテストスイート
   • コピーした Dart アセットに対する、テンプレートのみの検証としての dart format --output=none --set-exit-if-changed
5. 実行したコマンド、失敗、スキップしたチェック、および残存するアーキテクチャ上のリスクを報告します。