Skip to main content

Working with a coding agent

Every generated app has a guide for the coding agents that work on it, at the root of the app:

FileWhat it holds
AGENTS.mdThe guide: what the code of the app does not show.
CLAUDE.mdOne line, @AGENTS.md, which gives the same guide to the agents that read CLAUDE.md instead.

The guide is for an agent to read before it changes anything. It tells the rules of this app, so that you do not have to explain them in each session.

What the guide says​

The code of an app shows what it does, and an agent can read it. The guide holds what the code does not show: a rule that holds across files, an order, what not to do and what to do instead, a placeholder, a step that needs a person. Setup that needs a person or an account, such as a Firebase project, stays in the README.md of the app.

The guide starts with a short introduction and has a section for each part of the app that has notes for agents. The section of the app entry comes first, and the others follow in the order of their headings. This is the section "Preferences" of an app with shared_preferences:

  • AppPreferences in lib/core/preferences/app_preferences.dart remembers the settings of the app between its launches, such as the theme mode. It is not encrypted: never save a token, a password, an API key or an encryption key in it.
  • To remember a setting, write a function that takes the AppPreferences and add it to _restorers in that file. In it, read the setting, put it into the state that the widgets listen to, and keep the preferences in that state for its writes. The function awaits nothing, and keeps the current value when nothing is saved.
  • Name a key <owner id>.<setting>, such as theme.mode, where the owner is the feature or the concern whose code keeps the setting.
  • In the code of the app, do not call createAppPreferences() or initPreferences(). bootstrap() opens the preferences, and code gets them as the argument of its function in _restorers, or, with a DI container in the app, from the container. Widgets use the state and do not touch the preferences. A test may call both: initPreferences() opens the preferences again, as the next launch of the app does, and createAppPreferences() returns them.

With shared_preferences:

  • In lib/, only lib/core/preferences/shared_app_preferences.dart imports the package. Other code uses AppPreferences.
  • A number is read only as the type that it was saved as: getDouble() returns null for a key with an int, and getInt() for a key with a double.
  • In a test that runs bootstrap(), first set SharedPreferencesAsyncPlatform.instance = InMemorySharedPreferencesAsync.empty(). Without it, opening the preferences throws. Both names are from the package shared_preferences_platform_interface: add it as a dev dependency.
  • pubspec.yaml keeps shared_preferences_android at 2.5.2 or later. With 2.5.0 and 2.5.1, a release build fails to open the preferences on Android, because R8 renames Kotlin classes that the package looks up by name. Before you change the constraint, check that a release build of the app starts on Android.

The section of a role has two parts. First comes what holds whichever module provides the role, such as how code remembers a setting. Then the module that provides the role adds what comes with it, here after the line "With shared_preferences:". Replace the module with another provider of the role, and only the second part changes.

The sections of an app​

A section is in the guide only when the app has what it describes. The table names the built-in module that brings each section:

SectionIn an app withWhat it tells
App entryevery appThe order of main(), the phases of bootstrap(), where shared code and features go, that StatusBarIcons asks for the icons of the status bar around every screen, and what a flutter command builds without --flavor. In an app with steps by hand, also that only you do them: an agent points you to the section "Finish the setup" of the README instead of trying them. flutter_core adds where each flavor is in the native projects, and the commands to run after a change, the root widget with the one MaterialApp of the app, where the test of a file goes, and where the entitlements of the iOS app are.
Analyticsfirebase_analyticsThat code records what users do through AnalyticsService and never through the SDK of a provider, where it gets the service, and how to add a provider. In an app with a router, the module adds that screen views need no code.
App iconlauncher_iconsWhich images the icon comes from, and that an agent changes those and not what is made from them. The module adds the command, and what an agent does not run or add.
Authenticationfirebase_authThat code signs in, up and out only through appSession, how it shows a failure, that the mode gates nothing on its own and which guard keeps a user from what, and where the data of a guest moves. It also tells where the ways to sign in with an identity provider are listed, what a tap on one of their buttons does with appSession.signInWith, what a deletion asks of them, and what AccountSession.issuers lists. The module adds which file is on Firebase Authentication, where a code of Firebase gets its reason, that the ways to sign in are enabled in the Firebase project, and that an agent runs the script that enables them only when asked. In an app with Google sign-in, it adds what its script does for Google, and with Sign in with Apple, that the key of Apple never goes into the app.
CIgithub_actionsThat CI runs the commands of the section "Continuous integration" of the README, so an agent keeps them passing and runs them before it finishes a change, and what tool/write_env.dart does. The module adds where the jobs are, how a new key reaches a build, how a value reaches a command, and how the actions are pinned.
Crash reportingfirebase_crashlyticsWhich function reports the errors that nothing handles, how code reports an error that it catches, and how to add a provider. The module adds that tool/configure_firebase.dart keeps the build phase working for flutter build ipa, and what to run after flutterfire configure by hand.
Dependency injectionget_itWhat a service is, where the services are registered, and that only the composition file of a feature resolves them. The module adds how its file registers a service.
Eventsevent_busWhat an event is, where code gets the one event service of the app, and what events are for. The module adds when a listener gets an event.
Firebasefirebase_coreThat lib/firebase_options_of_flavor.dart picks the options by the flavor of the build, that the options of a flavor are a placeholder until tool/configure_firebase.dart writes them, that an agent runs that script only when asked and never flutterfire configure, and what a test that starts the app needs.
Google sign-ingoogle_sign_inWhich file asks Google and how it starts the package, which errors become which reason, what the icon shows, and what a test replaces to sign in with Google.
HomehomeWhat the start screen is for, and where the image that it shows is declared.
Layoutbottom_tabsWho creates the shell of the main navigation, what a destination is, how its label follows the language, how to add one, and how code reaches a destination from a page shown over the main navigation. The module adds that it draws its bar itself, when the bar is hidden, how many destinations it should have, where the bar takes its colors from, and what a tab says to a screen reader.
Localizationgen_l10nHow code reads a text, where the languages of the app are, how code changes the language, and what a new language needs. The module adds where the texts are, how to add one, and the command to run after a change.
Notificationslocal_notificationsHow code shows and schedules a notification and which ids it takes, how it asks for the permission and where the app asks, how it handles a tap, and the small icon of Android. The module adds which file is on flutter_local_notifications, how to add a channel, why a scheduled notification is inexact, and what its native files and a test need.
OnboardingonboardingThat no code navigates to the onboarding or away from it, where its pages and its steps are and what the screen keeps around them, that the animations of a page end, how code finishes the onboarding and starts it again, and what a test of another screen does first.
Onboarding screenonboardingWhat a step of the onboarding is, how to add one, how a step that shows a screen of its own pushes it over the onboarding, and that skipping the onboarding skips its steps.
PaywallpaywallWhere the paywall and the screen of the subscription are and which guard shows them, that no screen closes itself or navigates after a purchase or a restore, how to sell from a button and keep a screen for users with premium access, which files are the look and which the state, where the plans get their words and a failure its text, what the links need in .env, whose a purchase before a sign-in is, and what a widget test minds while a call is on its way. By the state manager of the app, it adds where the state of a screen is and how a widget reads the access, and in an app with an onboarding, how its step shows the paywall and who closes it.
Preferencesshared_preferencesWhat the preferences are for, what never goes into them, and how code remembers a setting. The module adds how it reads numbers, what a test that runs bootstrap() needs, and why pubspec.yaml keeps shared_preferences_android at 2.5.2 or later.
PurchasesrevenuecatWhat the access of the user is and where a widget reads it, how code gets the plans, buys, restores and shows a failure, what a screen that sells shows, how a screen is kept for users with premium access, what the app does while purchases are not set up, and which functions are not for the code of the app. In an app with sign-in, also whose the purchases are, and in an app with a settings screen, where the restore is. The module adds which file is on purchases_flutter, that the premium access is the entitlement premium, which API key a build takes and why, that nothing calls RevenueCat before it is configured, how a grant made on the dashboard reaches the app, and what a test answers in place of the package.
REST APIdioHow code makes a request through appRest and turns the body into a type, how it shows a failure, what repeats, how a call ends, and what a test needs. In an app with sign-in, which requests carry the token and what a 401 does. The module adds where an interceptor goes and what it may do.
Push messagesfirebase_messagingWhere the address of the device is and what to do with it, how a message shows in the foreground, how code handles a tap, and what the app does not handle. The module adds which file is on firebase_messaging, where the address comes from, why it sets the presentation options of iOS, and that the app never asks for the permission through the package.
Routergo_routerHow code navigates with context.nav, the three places that a route is in, and the types of its values. In an app with guards, also where the guards are, what tells a gate from a guard for some routes, how code adds either, and that a screen neither closes itself nor navigates after it changed a guard. The module adds how its file writes a route and, in an app with a layout, where a destination of the main navigation goes and that the router creates the main navigation anew.
Settings screensettingsWhat an entry of the screen is and how to add one. The module adds where its screen is, what it shows with entries and without, and how code opens it in an app without a main navigation.
Sign in with Appleapple_sign_inWhich file asks Apple and what it returns, that Apple gives the name only at the first sign-in, which errors become which reason, the entitlement, and what a test sets to sign in with Apple.
Sign-insign_inWhere the screens of the sign-in are and which guards show them, that a screen neither closes itself nor navigates after a sign-in or a sign-out, which files are the look and which the state, where a failure gets its text, what a widget test minds while a call is on its way, where the buttons of the ways to sign in come from, and where the screen of the account and its entry are. By the state manager of the app, it adds where the state of a screen is and how a widget reads who uses the app.
Splash screennative_splashWhich images the screen comes from, and that an agent changes those and not what is made from them. The module adds the command and what it rewrites.
State managementbloc or riverpodHow a screen with state is written with the state manager of the app: where its state is, how the screen passes it on to a view, where state that several screens read goes, what the state checks after a call that it awaited, and that a widget talks only to that state, never to a service or a DI container.
Themematerial_themeWhere the look of the app is, how code changes and reads the theme mode, and where a screen takes its colors from. The module adds how its file creates both themes, where their colors and their font are, where a text field takes its look from, and what a change of the file must keep.
Values in .envdart_defineHow code reads a value of .env through AppEnv and handles null, that no secret goes into .env, and what a new key needs. The module adds the commands with --dart-define-from-file=.env, the run configurations that pass it, that flutter run starts again after an edit of .env, and how the getter of a new key reads its value.

Where the sections come from​

The app entry role generates both files in every app, whichever module provides the role. The roles and the modules of the app contribute the sections, as they contribute start-up code: a module knows nothing of the notes of the other modules, and smf create puts the sections together. So the guide of an app covers only what that app has.

SMF checks the paths that a guide names. In its tests, each file or directory that a note names in backticks below a top-level directory of a Flutter project, such as lib/ or android/, and each path to a Dart file, must be in the app of that guide. A module author reads more in Notes for coding agents.

Keep it true​

The guide is a file of your app, like the rest of the code. Nothing writes it again, so it is right only as long as you keep it so, and its first paragraph asks the agent to do its part: "When you change what a section describes, change the section too."

  • When you change how a part of the app works, such as where its files are or which function code must call, change the section of that part.
  • When you add a part of your own with a rule that the code does not show, add a section for it under a heading of its own.
  • Keep to what the code does not show. A note that repeats the code makes the other notes harder to find.

The documentation for your agent​

Every page of this documentation is also in Markdown, at its URL with .md, such as https://doc.saymyframe.com/guides/theme.md. llms.txt lists the pages with a line about each, and llms-full.txt has all of them in one file. An agent may know SMF from an older version, or not at all. Give it one of these before it picks the modules of an app or writes the command of smf create.