run-codegen

codegen の実行（build_runner）

決定論的で自由度の低い実行手順です。アノテーション駆動のコードをすべて一度に再生成してから、解析します。固定されたコマンドを記載どおりに実行してください。変更したり、フラグを追加したり、生成ファイルを手動で編集したりしないでください。ソースファイルにコード生成アノテーション（@freezed、@JsonSerializable、@riverpod、@DriftDatabase、drift テーブル）があり、それに対応する *.g.dart／*.freezed.dart／*.drift.dart ファイルがない、または古くなっている場合に適用します。

絶対に守るルール

1. flutter analyze の前にコード生成を実行してください。 新しいクローン、ブランチの切り替え、アノテーション付きファイルの編集直後には、生成ファイルがまだディスク上にありません。その状態で解析すると、「missing part file」や未定義クラスのエラーが誤って表示されます。これらは実際のコードの不具合ではなく、生成ファイルの不足を示しています。まず再生成してから解析してください。
2. 常に --delete-conflicting-outputs を付け、固定されたコマンドをそのまま使用してください。 これを付けないと、build_runner は今回の実行で生成していない出力ファイルを上書きできず、「conflicting outputs」というメッセージが大量に表示されて失敗します。これは古いファイルとの競合であり、バグではありません。原因を探し回らないでください。
3. 生成ファイルを手動で編集しないでください。 次回のビルドで変更が黙って元に戻され、編集内容も失われます。アノテーション付きのソース（drift テーブル、freezed クラス、Notifier、ARB）を変更して、再実行してください。
4. 生成ファイルに対して git add -f を実行しないでください。 生成コードをコミットするか gitignore するかは、codegen-and-toolchain が管理する判断事項です。リポジトリの選択にかかわらず、ignore ルールを無視して成果物を強制追加したり、現在のソースから再生成できないファイルをコミットしたりしないでください。
5. watch はローカル開発用の便利機能であり、CI やコミット前フックでは使用しないでください。 CI と解析前の手順では、常に一度だけ実行する build を使います。
6. まず手書きのソースを修正してください。 ジェネレーターは解決済み AST を読み取ります。解析できないソースからコードを生成することはできません。lib/ 内の無関係なエラーでも、テーブルやプロバイダーの生成が妨げられる場合があります。コード生成を疑う前に、それらを解消してください。

標準コマンド

単一パッケージのアプリではパッケージのルートから、マルチパッケージのリポジトリではワークスペースのルートから実行します。

dart run build_runner build --delete-conflicting-outputs

これは、すべての CI レーンおよび新しいクローンで、フォーマットと解析の前に実行する最初の手順です。

新しいクローン、プル、ブランチ切り替え時の標準手順

1. flutter pub get（依存関係を解決します）。
2. dart run build_runner build --delete-conflicting-outputs（再生成します）。
3. その後で初めて flutter analyze を実行します。

手順 2 を省略することは、コードに問題がないにもかかわらず、クローン上でアナライザーがエラーになる最も一般的な原因です。

開発時の反復作業（任意の watch）

アノテーション付きソースを編集中に繰り返し作業する場合は、一度だけのビルドの代わりにウォッチャーを実行してください。保存時に、影響を受ける出力が再ビルドされます。

dart run build_runner watch --delete-conflicting-outputs

同じツリー上で二つの build_runner プロセスを同時に実行すると出力が競合するため、一度だけの build を実行する前にウォッチャーを停止してください。

マルチパッケージの場合（ワークスペース）

build_runner はパッケージ単位で実行されます。一度の実行で再生成されるのは、現在のパッケージとそのパス依存パッケージであり、ワークスペース内のすべての兄弟パッケージが自動的に対象になるわけではありません。そのため、ワークスペースのルートで単一のコマンドを実行すれば、ルートパッケージとそのパス依存パッケージは一度に処理されますが、すべてのメンバーに依存しているわけではないコーディネーター型のルートでは、兄弟パッケージは再生成されません。マルチパッケージ全体を再生成するには、リポジトリレベルの一括実行ラッパー（例：melos run gen）を使って、すべてのワークスペースメンバーに対してコマンドを実行してください。ワークスペースのブートストラップが完了している場合は、こちらを優先してください。開発時に特定のパッケージだけを対象にするには、そのパッケージのディレクトリから同じコマンドを実行します。各ジェネレーターが読み取るファイルを定めるビルダーのスコープは、各パッケージの build.yaml にあり、codegen-and-toolchain が管理します。

コード生成とアナライザーの結果が食い違う場合

アナライザーはディスク上のファイルを読み込み、build_runner はファイルを書き込みます。食い違いが起きる場合、コードに問題があるのではなく、ディスク上のファイルが更新されていないことがほとんどです。

症状	対応
コード生成されるはずの未定義クラス／ゲッターがアナライザーで指摘される	固定されたビルドを再実行してから、解析サーバーを再起動します。呼び出し側を「修正」してはいけません。
*.g.dart／*.freezed.dart／*.drift.dart ファイル内でエラーが報告される	ファイルが古いか、アナライザーの除外設定に誤りがあります。まず再生成してください。生成済みの出力を手作業で編集してはいけません。
build_runner が手書きのソース内のアナライザーエラーで失敗する	手書きのソースを修正します。ジェネレーターは解析できない AST を解決できません。
「Conflicting outputs」という大量のメッセージが表示される	--delete-conflicting-outputs を付けて再実行します。名前変更／削除されたソースの古い出力が削除されます。

アンチパターン

• 新しいツリーでコード生成前に flutter analyze を実行する — 再生成すれば解消される、実際には存在しない missing-part エラーを追うことになります。
• --delete-conflicting-outputs を省く — 最初の名前変更または削除で、古い出力との衝突が起き、実行全体が失敗します。
• .g.dart／.freezed.dart／.drift.dart を手作業で編集する — 次のビルドで変更が元に戻ります。修正すべきなのは注釈付きのソースです。
• Git で無視されている生成ファイルに git add -f を使う — リポジトリで決められたコミット対象／Git 無視対象の区分を迂回し、古い可能性のある成果物を含めてしまいます。
• CI または pre-commit フックで build_runner watch を実行する — 決定性がありません。CI では一度だけ実行する build を使用する必要があります。

完了の定義

• 固定された dart run build_runner build --delete-conflicting-outputs をパッケージ／ワークスペースのルートで実行し、「conflicting outputs」エラーが発生しませんでした。
• flutter analyze より前に実行し、現在はエラーがありません。
• 生成ファイルを手作業で編集したり、強制追加したりしていません。
• CI またはフックに build_runner watch プロセスを組み込んでいません。

関連スキル

• このランブックの背景知識については、codegen-and-toolchain を参照してください。内容は build.yaml のビルダー適用範囲、生成コードをコミットするか Git で無視するかの判断、SDK の固定、生成ファイルに対するアナライザー／カバレッジの除外設定です。
• drift_dev make-migrations をこのコード生成処理に組み込む、drift のスキーマスナップショットとマイグレーションの手順については、run-migration を参照してください。
• このコマンドを再実行してツリーを比較する、CI の鮮度チェックについては、ci-pipeline-and-gates を参照してください。
• 生成ファイルを lint の対象外にするアナライザーの除外設定については、lint-and-style-config を参照してください。

参考資料

• build_runner：https://pub.dev/packages/build_runner
• Dart ツール — build_runner の使い方：https://dart.dev/tools/build_runner
• drift のコード生成：https://drift.simonbinder.eu/docs/getting-started/
• freezed：https://pub.dev/packages/freezed
• riverpod_generator：https://pub.dev/packages/riverpod_generator