Skip to content
vibespell

AGENTS.md

AGENTS.md for Flutter

AGENTS.md is a plain markdown file at the root of a repo. Coding agents from Cursor, Codex, Copilot, and others read it before they edit. This copy is written for a Flutter project. This repository is a Flutter app. Widgets stay small, state management matches the package the repo already uses, and `flutter analyze` stays clean.

The example uses a balanced, readable style, pragmatic tests, and comments only where the intent is not obvious. Open the generator to make the agent stricter, switch to test-first, quiet the comments, or pick a different file.

The example assumes Flutter with Dart. It does not assume Riverpod, Bloc, or a particular router. Use the state library already in pubspec.yaml.

Customize in the generatorBrowse the library

Example file

Balanced strictness, readable style, pragmatic tests. Download name: AGENTS.md

# AGENTS.md

Instructions for coding agents working in this Flutter repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Flutter app. Widgets stay small, state management matches the package the repo already uses, and `flutter analyze` stays clean.

## Layout

- Screens live with the feature. Reusable widgets live in a shared widgets folder the repo already has.
- Side effects stay out of `build`. `build` returns a widget tree.
- Platform channels stay isolated. Do not sprinkle method channels through UI files.

## Commands

- Analyze: `flutter analyze`
- Tests: `flutter test`
- Run: `flutter run`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Prefer `const` constructors when the widget's inputs are constant.
- Do not call `setState` after the widget is disposed.
- Keys are stable when a list can reorder.
- Add a state-management package only if pubspec already depends on it.
- Handle loading and error in the UI the screen already uses.
- Run the formatter the repo uses (`dart format`).

## Testing

Add or update tests when behavior changes.

Add a widget or unit test with `flutter_test`. Assert on text and finders, not on private fields.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Surface a recoverable error in the widget. Do not swallow a failed future.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not do network or disk work directly inside `build`.
- Do not ignore `BuildContext` across an async gap.
- Do not use `print` for errors the user can hit. Use the project's logger.
- Do not fork a widget into a platform file unless the behavior actually differs.

## Done when

- The requested behavior works.
- `flutter analyze` is clean and `flutter test` passes for the widget you touched.
- The diff stays inside the task.
- You list anything you could not run.

Add it to the project

  1. 01

    Copy a starting file

    Copy the example AGENTS.md on this page, or open the generator if you want different testing, strictness, or comment rules.

  2. 02

    Save it at AGENTS.md

    Save it as `AGENTS.md` at the root of the Flutter repo. A nested AGENTS.md can override these rules inside one directory later.

  3. 03

    Start a fresh agent session

    Rules files are read when a session starts. A chat that is already open may still be using the old instructions.

  4. 04

    Give it one small task

    Ask for one change a Flutter agent often gets wrong, such as a widget test that finds a labeled control and taps it. If it ignores the file, confirm the path and start a new session.

Questions about this file

Where do I put AGENTS.md in a Flutter repo?

Save it as `AGENTS.md` at the root of the Flutter repo. A nested AGENTS.md can override these rules inside one directory later.

Which tools read this AGENTS.md?

AGENTS.md is the shared file. Cursor, OpenAI Codex, and a growing set of coding agents read it from the repository root. Nested copies can narrow the rules for one folder.

What does the Flutter example assume?

The example assumes Flutter with Dart. It does not assume Riverpod, Bloc, or a particular router. Use the state library already in pubspec.yaml.

Does VibeSpell upload my repository?

No. Recipe pages are static, and the generator builds the file in your browser from the options you pick. Your source code never leaves the machine.

Other files for Flutter

AGENTS.md for other stacks