From 02a6afd07139116d051b6f025a5ba28d31dad6db Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Wed, 21 Jan 2026 10:40:46 -0800 Subject: [PATCH 1/4] Docs: Clarify native code placement in Flutter modules (#12960) --- .../add-to-app/android/project-setup.md | 23 ++++++++----------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/src/content/add-to-app/android/project-setup.md b/src/content/add-to-app/android/project-setup.md index f3679a2d01..44ee5a2556 100644 --- a/src/content/add-to-app/android/project-setup.md +++ b/src/content/add-to-app/android/project-setup.md @@ -139,20 +139,15 @@ standalone version of your Flutter module via `flutter run` and it's also a wrapper that helps bootstrap the Flutter module an embeddable Android library. -:::note -Add custom Android code to your own existing -application's project or a plugin, -not to the module in `.android/`. -Changes made in your module's `.android/` -directory won't appear in your existing Android -project using the module. - -Do not source control the `.android/` directory -since it's autogenerated. Before building the -module on a new machine, run `flutter pub get` -in the `flutter_module` directory first to regenerate -the `.android/` directory before building the -Android project using the Flutter module. +:::warning +**Do not** edit files in `.android/` to add native functionality. +This folder is generated for testing purposes and **will be overwritten** +whenever you run `flutter pub get` or build the module. + +* To add **module-specific** native code (reusable across apps), create a [Flutter Plugin](/packages-and-plugins/developing-packages#plugin) and depend on it. +* To add **app-specific** native code, add it directly to your existing Android host application. + +The `.android` directory contains a generated Android project that uses Java to bootstrap the Flutter module. This helps you run a barebones standalone version of your Flutter module via `flutter run` and verify basic functionality. The use of Java here does not prevent you from using Kotlin in your host app or plugins. ::: :::note From 9c28f51a5bb5876efe29555b80139efe2fcc2c3e Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 22 Jan 2026 11:58:02 -0800 Subject: [PATCH 2/4] Update src/content/add-to-app/android/project-setup.md Co-authored-by: Camille Simon <43054281+camsim99@users.noreply.github.com> --- src/content/add-to-app/android/project-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/add-to-app/android/project-setup.md b/src/content/add-to-app/android/project-setup.md index 44ee5a2556..d92719dd79 100644 --- a/src/content/add-to-app/android/project-setup.md +++ b/src/content/add-to-app/android/project-setup.md @@ -144,7 +144,7 @@ module an embeddable Android library. This folder is generated for testing purposes and **will be overwritten** whenever you run `flutter pub get` or build the module. -* To add **module-specific** native code (reusable across apps), create a [Flutter Plugin](/packages-and-plugins/developing-packages#plugin) and depend on it. +* To add native code you may use across apps/modules, create a [Flutter Plugin](/packages-and-plugins/developing-packages#plugin) and depend on it. * To add **app-specific** native code, add it directly to your existing Android host application. The `.android` directory contains a generated Android project that uses Java to bootstrap the Flutter module. This helps you run a barebones standalone version of your Flutter module via `flutter run` and verify basic functionality. The use of Java here does not prevent you from using Kotlin in your host app or plugins. From 73c6d2415066fee063618a5f1b396c194e35c916 Mon Sep 17 00:00:00 2001 From: John Ryan Date: Wed, 21 Jan 2026 16:53:26 -0800 Subject: [PATCH 3/4] Add AI rules limits and compressed files (#12969) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit _Description of what this PR is changing or adding, and why:_ This adds the new compressed rules files to our docs page. (https://github.com/flutter/flutter/pull/179817) _Issues fixed by this PR (if any):_ _PRs or commits this PR depends on (if any):_ ## Presubmit checklist - [x] If you are unwilling, or unable, to sign the CLA, even for a _tiny_, one-word PR, please file an issue instead of a PR. - [x] If this PR is not meant to land until a future stable release, mark it as draft with an explanation. - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style)—for example, it doesn't use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person pronouns). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer. --------- Co-authored-by: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> --- src/content/ai/ai-rules.md | 41 +++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/src/content/ai/ai-rules.md b/src/content/ai/ai-rules.md index b60cf831f3..b5c8f2de87 100644 --- a/src/content/ai/ai-rules.md +++ b/src/content/ai/ai-rules.md @@ -19,28 +19,37 @@ instructions to an underlying LLM. These files help you: design. * Provide critical project context to the AI. +The Flutter project provides several versions of the rules file to accommodate +different tool limits: + +* [`rules.md`](https://raw.githubusercontent.com/flutter/flutter/refs/heads/main/docs/rules/rules.md): + The comprehensive master rule set. +* [`rules_10k.md`](https://raw.githubusercontent.com/flutter/flutter/refs/heads/main/docs/rules/rules_10k.md): + A condensed version (<10k chars) for tools with stricter context limits. +* [`rules_4k.md`](https://raw.githubusercontent.com/flutter/flutter/refs/heads/main/docs/rules/rules_4k.md): + A highly concise version (<4k chars) for limited contexts. +* [`rules_1k.md`](https://raw.githubusercontent.com/flutter/flutter/refs/heads/main/docs/rules/rules_1k.md): + An ultra-compact version (<1k chars) for very strict limits. + Download the Flutter and Dart rules template -## Environments that support rules +## Device & editor specific limits -Many AI environments support rules files to guide LLM behavior. -Here are some common examples and their corresponding -rule file or directory names: +Different AI coding assistants and tools have varying limits for their "rules" +or "custom instructions" files. *Last updated: 2026-01-05.* -| Environment | Rules file or directory | Configuration instructions | -|:---------------------|:----------------------------------|:------------------------------------------------------| -| Copilot-powered IDEs | `.github/copilot-instructions.md` | [Configure instructions for Copilot][copilot] | -| Claude Code | `CLAUDE.md` | [Configure rules for Claude Code][claude] | -| Cursor | `AGENTS.md` | [Configure rules in Cursor][cursor] | -| Firebase Studio | `.idx/airules.md` | [Configure instructions in Firebase Studio][firebase] | -| Gemini CLI | `GEMINI.md` | [Configure context in Gemini CLI][gemini-cli] | -| Google Antigravity | `.agent/rules/.md` | [Configure rules for Antigravity Agent][antigravity] | -| JetBrains IDEs | `.junie/guidelines.md` | [Configure guidelines for Junie][junie] | -| VS Code | `.instructions.md` | [Configure instructions in VS Code][vs-code] | -| Windsurf | `.windsurf/rules/.md` | [Configure rules in Windsurf][windsurf] | +| Tool / Product | Rules file / Feature | Limit (soft / hard) | Documentation | +|:---|:---|:---|:---| +| Antigravity (Google) | `.agent/rules/.md` | 12,000 chars (Hard) | [Configure rules][antigravity] | +| Claude Code | `CLAUDE.md` | No Hard Limit | [Claude Code Docs](https://code.claude.com/docs/en/memory) | +| Cursor | `AGENTS.md` | No Hard Limit | [Cursor Docs](https://cursor.com/docs/context/rules) | +| Gemini CLI | `GEMINI.md` | 1M+ Tokens (Context) | [Gemini CLI Docs](https://cloud.google.com/vertex-ai/generative-ai/docs/long-context) | +| GitHub Copilot | `.github/copilot-instructions.md` | ~4k chars | [GitHub Copilot Docs](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) | +| JetBrains AI (Junie) | `.junie/guidelines.md` | No Hard Limit | [JetBrains AI Docs](https://www.jetbrains.com/help/junie/get-started-with-junie.html) | +| VS Code | `.instructions.md` | Unknown | [Configure instructions][vs-code] | {:.table .table-striped} @@ -55,7 +64,7 @@ the most up-to-date naming conventions and instructions. [cursor]: https://cursor.com/docs/context/rules [firebase]: https://firebase.google.com/docs/studio/set-up-gemini#custom-instructions [gemini-cli]: https://geminicli.com/docs/cli/gemini-md -[antigravity]: https://antigravity.google/docs/rules +[antigravity]: https://antigravity.google/docs/rules-workflows [junie]: https://www.jetbrains.com/help/junie/customize-guidelines.html [vs-code]: https://code.visualstudio.com/docs/copilot/customization/custom-instructions#_use-instructionsmd-files [windsurf]: https://docs.windsurf.com/windsurf/cascade/memories#rules From 315b3f02358ac4c061f2f067edf43a15db04612e Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" Date: Thu, 22 Jan 2026 12:11:13 -0800 Subject: [PATCH 4/4] Tweaking text and incorporating feedback --- .../add-to-app/android/project-setup.md | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/content/add-to-app/android/project-setup.md b/src/content/add-to-app/android/project-setup.md index d92719dd79..0e12504e23 100644 --- a/src/content/add-to-app/android/project-setup.md +++ b/src/content/add-to-app/android/project-setup.md @@ -122,9 +122,9 @@ follow these steps: #### Create a Flutter module -Let's assume that you have an existing Android app at +Assuming that you have an existing Android app at `some/path/MyApp`, and that you want your Flutter -project as a sibling: +project as a sibling, do the following: ```console cd some/path/ @@ -132,10 +132,10 @@ flutter create -t module --org com.example flutter_module ``` This creates a `some/path/flutter_module/` Flutter module project -with some Dart code to get you started and an `.android/` +with some Dart code to get you started and a `.android/` hidden subfolder. The `.android` folder contains an Android project that can both help you run a barebones -standalone version of your Flutter module via `flutter run` +standalone version of your Flutter module with `flutter run` and it's also a wrapper that helps bootstrap the Flutter module an embeddable Android library. @@ -144,10 +144,17 @@ module an embeddable Android library. This folder is generated for testing purposes and **will be overwritten** whenever you run `flutter pub get` or build the module. -* To add native code you may use across apps/modules, create a [Flutter Plugin](/packages-and-plugins/developing-packages#plugin) and depend on it. -* To add **app-specific** native code, add it directly to your existing Android host application. - -The `.android` directory contains a generated Android project that uses Java to bootstrap the Flutter module. This helps you run a barebones standalone version of your Flutter module via `flutter run` and verify basic functionality. The use of Java here does not prevent you from using Kotlin in your host app or plugins. +* To add native code that you can use across apps/modules, + create a [Flutter Plugin](/packages-and-plugins/developing-packages#plugin) + and depend on it. +* To add **app-specific** native code, + add it directly to your existing Android host application. + +The `.android` directory contains a generated Android project that uses Java +to bootstrap the Flutter module, so **do not** add it to source control. +This approach helps you run a barebones standalone version +of your Flutter module (with `flutter run`) and verify basic functionality. +Using Java here doesn't prevent you from using Kotlin in your host app or plugins. ::: :::note