Skip to content
vibespell

.cursor/rules/project.mdc

Cursor rules for Flutter

Cursor rules are a markdown file with a short frontmatter header. Cursor attaches them to the agent so it stops guessing how this repo builds, tests, and styles code. 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: project.mdc. Legacy path: .cursorrules

---
description: "Working rules for a Flutter repository"
globs: "**/*"
alwaysApply: true
---

# Project rules

Follow these rules on every task in this Flutter repository.
If the project still uses a root `.cursorrules` file, keep the same rules there.

## 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 Cursor rules on this page, or open the generator if you want different testing, strictness, or comment rules.

  2. 02

    Save it at .cursor/rules/project.mdc

    Save it at `.cursor/rules/project.mdc` in the Flutter repo and create the folders if they are missing. If the project still uses one root rules file, save the body as `.cursorrules`.

  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 Cursor rules in a Flutter repo?

Save it at `.cursor/rules/project.mdc` in the Flutter repo and create the folders if they are missing. If the project still uses one root rules file, save the body as `.cursorrules`.

Which tools read this Cursor rules?

Cursor reads `.cursor/rules/*.mdc` and, on older setups, a root `.cursorrules` file. Other tools ignore the frontmatter, so use AGENTS.md when more than one agent edits the repo.

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

Cursor rules for other stacks