Flutter Project Structure

Flutter プロジェクト構造

コードベースを理解するためのコンテキストを90％削減できます。 1つのコマンドで、Claude Code、Cursor、CopilotなどのすべてのAIエージェントに、プロジェクトの全体的な構造を提示できます。各ファイルでできること、ファイル同士のつながり、変更した場合に何が壊れるかがわかります。以下の数値は推定ではなく、実際のアプリで測定したものです。

Flutter／DartのコードベースをAI対応にするDartパッケージです。プロジェクト構造を分析、ドキュメント化、可視化し、手間のかかる「コードベースを確認してきます」という段階を置き換えるコンテキストファイルを生成します。

なぜ必要なのか？（コンテキストの課題）

エージェントがリポジトリで役立つ作業を始める前に、次の3つの質問に答える必要があります。

1. これはどのようなプロジェクトか？ — 技術スタック、アーキテクチャ、規約、エントリーポイント
2. このタスクに関係するファイルはどれか？ — それらに依存するファイルはほかにあるか
3. それらのファイルでできることは何か？ — 呼び出す必要のあるクラスやメソッド

ソースを読んでこれらに答えるのはコストがかかり、セッションのたびにやり直す必要があります。実際のFlutterアプリ breeze_buy_app は170ファイルで、Dartコードは 670 KB — 約171,000トークン です。すべてを最初から最後まで読む必要があります。エージェントはすべてを読むことはないため、十分なコンテキストが得られるまで手探りでファイルを開き、翌日にはまた同じコストが発生します。

代わりに得られるもの

一度実行するだけです：dart run flutter_project_structure ai-context

成果物	答えられること	breeze_buy_app での測定値
CLAUDE.md	これはどのようなプロジェクトか？	2.6 KB（約670トークン）。Claude Codeが自動で読み込みます
.ai-context/graph.json	関係するファイルはどれか、変更すると何が壊れるか	170ファイル間に777のエッジ
.ai-context/skeletons.json	各ファイルでできること	ソースコード670 KBに対して63 KB — 90.6％小さくなります

このアプリの構造全体を把握するために必要なのは、ソースを読む場合の約171,000トークンではなく、約17,000トークンです。これが90％削減の根拠です。ご自身のプロジェクトでツールを実行すれば同じ結果を再現でき、圧縮率は skeletons.json に記録されます。

スケルトンの例

lib/core/utils/http_base_interceptor.dart
  class BaseInterceptor extends Interceptor  // base [Interceptor] for [Dio]...
    @override void onRequest(RequestOptions options, RequestInterceptorHandler handler)
    @override void onResponse(Response response, ResponseInterceptorHandler handler)
    @override Future onError(DioException err, ErrorInterceptorHandler handler)
  class RefreshToken
    final String access;
    RefreshToken({required this.access})

ファイルを開かなくても、正しく呼び出すには十分な情報が得られます。ファイル自体を読むのは、変更する必要があるときだけです。

グラフから変更の影響もわかります

get_file_graph(path: "lib/config/colors.dart")
  importedBy   : 108 files
  blastRadius  : 134 of 170 files

これを使うとできること、できないこと

この違いは重要なので、明確に説明します。

できること： プロジェクト全体の構造とインターフェースに関する完全な知識をエージェントに提供します。すべてのファイル、すべてのパブリック API、すべての依存関係を、ソースを読む場合の約10分の1のコストで把握できます。エージェントがどのファイルを開くべきか推測する必要がなくなり、セッションのたびにアーキテクチャを再分析することもなくなります。

できないこと： コードが 何をするか をエージェントに伝えることです。動作はメソッド本体にあり、スケルトンでは定義上、本体が省かれます。インターフェースが意味の大部分を占めるサービス、モデル、ブロック、リポジトリで特に効果を発揮します。一方、Flutter ウィジェットでは意味が build() 本体にあるため、効果は限定的です。スケルトンは目次に近いものです。

また、セッション全体を短縮するわけでもありません。コードの作成、テストの実行、反復作業には影響せず、実際のタスクでは通常、これらのコストのほうがコンテキストより大きくなります。このパッケージが取り除くのは、繰り返しコストをかけているのに、新たな情報を得られていなかった部分です。

機能

コア分析

• Markdown 形式でディレクトリツリーを可視化
• 各 Dart ファイルの先頭にパスコメント（// Path: lib/src/...）を追加します。ファイルをチャンクに分割してインデックス化する際にパスが失われる RAG ベースのツールで特に役立ちます。Claude Code のようなエージェント型ツールでは、すでに各結果にパスが含まれています
• ファイル統計（ファイル総数、コード行数、最大／最小のファイル）
• 行番号付きの TODO／FIXME コメント検索
• パッケージ依存関係の分析（AST ベースのインポート追跡）
• ファイルごとのコード指標（クラス、メソッド、コメント比率）

スケルトン（v3.0.0）

• API スケルトン — 本体を省いたすべての宣言。実際の170ファイルのアプリでは、ソースより90.6％小さくなります
• ドキュメント要約 — 各宣言の作成者による一行の説明を、シグネチャとともに保持します
• エージェントがプロジェクト全体の構成をコンテキスト内に保持し、実際に編集するファイルの完全な本体だけを読み込めるようにします
• サービス、モデル、ブロック、リポジトリで特に効果を発揮します。Flutter ウィジェットでは意味が build() 本体にあるため、スケルトンは要約ではなく目次となります

インポートグラフ（v3.0.0）

• ファイル依存関係グラフ — ノードはファイル、エッジはプロジェクト内で解決された import、export、part ディレクティブです（package:<own_name>/... による自己インポートを含みます）
• 影響範囲 — あるファイルを変更した場合に影響を受ける可能性があるファイルの推移的な集合です。編集前に確認すべき対象がわかります
• 前方閉包 — ファイルの動作に必要なすべての要素
• デッドコード候補 — いずれのエントリーポイントからも到達できないファイル
• ハブ — 最も多く依存されているファイル、つまり変更時のリスクが最も高いファイル

スマート検出（v3.0.0）

• プロジェクトタイプ — monorepo、plugin、flutter_app、dart_package
• 10種類のフレームワーク — GetX、Riverpod、Bloc/Cubit、Provider、Dio、GoRouter、AutoRoute、Freezed、Hive、Drift（pubspec、インポート、AST のスーパークラス照合を使って検出）
• アーキテクチャレイヤー — 依存関係グラフとともに、ディレクトリをレイヤー（モデル、サービス、コントローラー、ウィジェット、ブロックなど）に対応付けます
• エントリーポイント — main.dart、app.dart、および main_development.dart、main_staging.dart、main_production.dart などの環境別バリエーションを検出します
• 命名規則 — ファイルのサフィックスパターン（_model、_service、_bloc）とクラスのサフィックスパターン（Model、Service、Bloc）
• ファイル用途の分類 — すべてのファイルに、ウィジェット、モデル、サービス、ブロック、テスト、生成ファイル、ユーティリティなどの役割を割り当てます
• 集計指標 — 平均、合計、最大のファイル上位5件、コメントのないファイル

AI 出力ジェネレーター

• CLAUDE.md — 概要、アーキテクチャ、規約、依存関係、コードの健全性を含む、AI に最適化されたプロジェクト概要（20KB 未満）
• .ai-context/ — 8個の JSON ファイル：architecture.json、files.json、patterns.json、conventions.json、metrics.json、todos.json、graph.json、skeletons.json
• MCP サーバー — stdio JSON-RPC 経由でライブクエリを実行する8個のツール。オプションで --watch モードを利用できます

シングルパスアーキテクチャ

• FileAnalyzer interface — 各ファイルを一度だけ読み込んで解析し、すべてのアナライザーに配布します
• AnalysisPipeline — シングルパス処理を統括します（アナライザーごとのスキャンと比べて3倍高速です）
• ProjectContext — すべての解析結果を1つのデータクラスにまとめ、ジェネレーターとMCPツールで利用します

インストール

pubspec.yaml に追加します。

dev_dependencies:
  flutter_project_structure: ^3.0.0

次に、以下を実行します。

dart pub get

CLI の使い方

クイックスタート

# Analyze your project — generates project_structure.md with path comments
dart run flutter_project_structure

# Full AI setup — project_structure.md + CLAUDE.md + .ai-context/ JSON files
dart run flutter_project_structure ai-context

# Start MCP server for live AI agent queries
dart run flutter_project_structure mcp-server --watch

コマンド

すべてのコマンドは、基本としてパスコメントと project_structure.md を生成し、その後、各コマンド固有の出力を追加します。

analyze（デフォルト）

中核となるコマンドです。ディレクトリツリーとすべての解析セクションを含む project_structure.md を生成します。すべてのDartファイルに // Path: コメントを追加します。

dart run flutter_project_structure
dart run flutter_project_structure analyze --root-dir=lib --output=structure.md

サブコマンドなしで実行すると、後方互換性のため、デフォルトで analyze が実行されます。

claude-md

CLAUDE.md を生成します。これはコンパクトでAI向けに最適化されたプロジェクトコンテキストファイル（<20KB）です。Claude Code などのAIエージェントは、各セッションの開始時にこれを自動的に読み込みます。

dart run flutter_project_structure claude-md
dart run flutter_project_structure claude-md --output=AI_CONTEXT.md

さらに、パスコメントと project_structure.md も生成します。

ai-context

最も包括的なコマンドです。project_structure.md、CLAUDE.md、および .ai-context/ 内の8つの構造化JSONファイルをすべて生成します。

dart run flutter_project_structure ai-context
dart run flutter_project_structure ai-context --output-dir=.ai-context

作成されるJSONファイル：

• architecture.json — プロジェクトの種類、レイヤー、依存関係グラフ、エントリーポイント
• files.json — すべてのファイルの用途、LOC、クラス、メソッド、コメント比率
• patterns.json — ファイルの根拠とともに検出されたフレームワーク
• conventions.json — 命名サフィックスの数とファイル用途の分布
• metrics.json — 集計されたコード健全性メトリクス
• todos.json — 構造化されたTODO/FIXMEインデックス

さらに、パスコメント、project_structure.md、および CLAUDE.md も生成します。

mcp-server

リアルタイムのAIエージェントからの問い合わせに対応するMCPサーバーを起動します。サーバーは起動時にプロジェクトを解析し、必要に応じてファイルの変更を監視します。

dart run flutter_project_structure mcp-server
dart run flutter_project_structure mcp-server --watch

--watch を指定すると、.dart ファイルの変更時にサーバーが再解析します（2秒のデバウンス）。起動時には、パスコメントと project_structure.md も生成します。

公開される8つのMCPツール：

ツール	説明
get_architecture	プロジェクトの種類、レイヤー、依存関係グラフ、エントリーポイント
get_file_purpose(path)	特定のファイルの用途とメトリクス
get_dependencies(package?)	パッケージの依存関係。必要に応じて絞り込み可能
get_conventions	命名パターンとサフィックスの採用率
get_todos(severity?)	TODO/FIXME項目。必要に応じて絞り込み可能
get_file_skeleton(path?, paths?)	ファイルの宣言部分のみを、本体を除いて取得します。ファイル全体を読む場合の約10%のサイズです。ファイルの呼び出し方を把握するにはこちらを使い、ファイルを変更するにはファイルを読み込みます
get_file_graph(path?, depth?)	ファイルの依存関係グラフです。引数なしの場合、サイズ、最も多くのファイルから依存されているファイル、到達不能なファイルを返します。path を指定すると、そのファイルがインポートするファイル、そのファイルをインポートするファイル、および影響範囲を返します
get_project_structure(section?)	プロジェクト構造の完全なMarkdownです。デフォルトでは概要を返し、特定のセクション（ツリー、フレームワーク、アーキテクチャなど）も指定できます

Claude Code での設定：

{
  "mcpServers": {
    "flutter-project-structure": {
      "command": "dart",
      "args": ["run", "flutter_project_structure", "mcp-server", "--watch"]
    }
  }
}

オプション

Analyze コマンドのフラグ（すべてデフォルトで有効です）：

フラグ	短縮形	説明
--root-dir	-r	解析するルートディレクトリ（デフォルト：lib）
--output	-o	出力ファイルのパス（デフォルト：プロジェクトルートの project_structure.md）
--file-stats	-f	ファイル数・行数のカウント
--todo-comments	-t	TODO/FIXMEのスキャン
--dependency-analysis	-d	パッケージのインポート追跡
--code-metrics	-m	クラス、メソッド、コメント比率
--project-type		プロジェクトの種類の検出
--framework-detection		フレームワーク／ライブラリの検出
--architecture		レイヤーと依存関係の解析
--conventions		命名規則の解析
--file-purpose		ファイルの役割の分類
--metrics-aggregation		集計された健全性メトリクス

--no-<flag> を指定すると、任意の機能を無効にできます（例：--no-framework-detection）。

プログラムからの使用

パスコメント付きの完全な分析

import 'package:flutter_project_structure/flutter_project_structure.dart';

void main() {
  // Omit outputFile to write project_structure.md to the project root
  // (next to pubspec.yaml). Pass one to choose your own path.
  final structure = FlutterProjectStructure(rootDir: 'lib');

  // generate() injects path comments, writes project_structure.md,
  // and returns a ProjectContext for further use
  final context = structure.generate();
  if (context == null) return;

  print('Written to: ${structure.outputFilePath}');
  print('Project type: ${context.projectTypeDetector?.projectType}');
  print('Total files: ${context.fileStatistics.totalFiles}');
  print('Frameworks: ${context.frameworkDetector?.detectedFrameworks.keys}');

  // Generators default to the project root too, and return the path written
  print(ClaudeMdGenerator(context).generate());
  print(AiContextGenerator(context).generate());
}

出力先には次のルールが適用されます。フラグを省略すると、プロジェクトのルート（pubspec.yaml の隣）に出力されます。そのため、コマンドを実行した場所ではなく、分析対象のプロジェクトと一緒に保管されます。明示的なパスを渡すと、ほかの CLI ツールと同様に、現在のディレクトリを基準に解決されたパスがそのまま使用されます。

読み取り専用の分析（ファイルを変更しません）

final structure = FlutterProjectStructure(rootDir: 'lib');
final context = structure.runAnalysis();
// Or get the markdown string without writing to disk:
final markdown = structure.generateMarkdown();

アーキテクチャ

AnalysisPipeline (reads & parses each file once)
  |-- FileStatistics        -- file/line counts, largest/smallest files
  |-- TodoComments          -- TODO/FIXME scanning
  |-- DependencyAnalysis    -- package import mapping (AST-based)
  |-- CodeMetrics           -- classes, methods, comment ratio (AST-based)
  |-- FrameworkDetector     -- framework detection (pubspec + imports + AST)
  |-- ArchitectureAnalyzer  -- layers, entry points, dependency graph
  |-- ConventionAnalyzer    -- file/class naming patterns
  |-- FilePurposeAnalyzer   -- file role classification

Every command produces (baseline):
  |-- Path comments         -- // Path: lib/src/... in every Dart file
  |-- project_structure.md  -- comprehensive directory tree + all analysis

Output Generators (added on top):
  |-- ClaudeMdGenerator     -- CLAUDE.md for AI agents (<20KB)
  |-- AiContextGenerator    -- .ai-context/ (8 JSON files)
  |-- McpProjectServer      -- MCP server with 8 live-query tools

すべてのアナライザーは FileAnalyzer インターフェースを実装しています。カスタムアナライザーを作成できます。

import 'dart:io';
import 'package:analyzer/dart/ast/ast.dart';
import 'package:flutter_project_structure/flutter_project_structure.dart';

class MyCustomAnalyzer implements FileAnalyzer {
  @override
  void analyzeFile(File file, String content, CompilationUnit? compilationUnit) {
    // Your analysis logic here — receives pre-parsed AST
  }
}

例

使用方法の完全な例については、example フォルダーを確認してください。

dart run example/main.dart

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

プロジェクトを応援する

このパッケージがお役に立った場合は、pub.dev で「いいね」をして応援してください。

つながりましょう

• LinkedIn：LinkedIn のプロフィール
• GitHub：GitHub のプロフィール

お仕事の依頼・組織へのお問い合わせ

フリーランスの仕事や大規模なプロジェクトについては、以下をご覧ください。

• Upwork 個人プロフィール：個人プロフィール
• Upwork エージェンシー：エージェンシーのプロフィール

大規模な開発や協業の可能性についてのご相談は、[email protected] までメールでお問い合わせください。

成功事例

さまざまなプロジェクトの成功に貢献できたことを誇りに思います。その中から一つご紹介します。

Abwaab.com

Abwaab は、MENA 地域を代表する EdTech プラットフォームの一つです。何百万人もの学生が質の高い教育を受けられるようにするという Abwaab の使命の実現に向けて、堅牢でスケーラブルなソリューションの開発において重要な役割を果たしました。

Abwaab をご覧ください

私の組織

Increments Inc.

当社のソフトウェアは、レストランの業務を自動化し、エネルギー利用を最適化し、金融を革新し、医療を改善し、教育にイノベーションをもたらし、アパレル業界の業務を効率化し、ペーパーレス化を推進します。 Increments Inc. は、バングラデシュで第 1 位のモバイルアプリ開発エージェンシーです。

Increments Inc. をご覧ください

---

Flutter Project Structure をご覧いただきありがとうございます！開発ワークフローに役立てば幸いです。コーディングをお楽しみください！