5 Mistakes When You Let an AI Agent Touch Your Flutter Codebase / Nov 3, 2026

This is part of a short series ahead of my session at FlutterBytes Conference 2026 in Lagos, 6 and 7 November. The five incidents are illustrations, written to show common patterns. They aren't the history of a specific project or team, but you've probably seen at least one.

The incident log

Each one below is a short postmortem in the usual format: what happened, the root cause and the fix. None of them are about the agent being bad at Dart. They're all about what the agent was given, and what happened to its output afterwards.

INC-01: No spec (SEV 2)

What happened: Asked for a login screen. Got a login screen, a new auth service and a second router.

Root cause: The agent had to guess the scope, so it guessed big.

The fix: Write requirements.md first. Five WHEN / SHALL lines is enough to start.

"Build a login screen" doesn't say where the screen stops. Does it include auth? Navigation after login? Error states? With no boundary, a capable agent will often build everything that seems related. A short requirements file draws the boundary:

1.1 WHEN the login screen opens THE APP SHALL show email and password fields.
1.2 WHEN the user taps Log in THE APP SHALL call the existing AuthService.
1.3 IF login fails THEN THE APP SHALL show the error and keep the email filled.

"The existing AuthService" does a lot of work in that second line.

INC-02: No tests (SEV 1)

What happened: The agent fixed the cart. Checkout broke. Nobody noticed until a user did.

Root cause: Nothing checked the old behaviour after the change.

The fix: One widget test per requirement. Run flutter test before every merge.

This is SEV 1 because a user found it. The agent did what it was asked: fix the cart. It had no way to know the change affected checkout, and neither did the reviewer, because nothing was checking checkout.

A widget test per requirement turns "nobody noticed" into a red test run before the merge. Name each test with its requirement ID, so when it fails you know which promise broke.

INC-03: Huge tasks (SEV 2)

What happened: "Build the profile feature." One task, dozens of files, one giant diff.

Root cause: A task that big can't be reviewed, so it wasn't.

The fix: Split it in tasks.md until each diff fits on one screen.

The size of a task sets the size of the diff, and the size of the diff decides whether anyone reads it. "Build the profile feature" is a project, not a task. Break it down until each step is something like "Add ProfileState and ProfileCubit" or "Build the avatar picker", each pointing back to a requirement. There is more on this in Sizing Tasks an AI Coding Agent Can Finish.

If a diff doesn't fit on one screen, the task was too big.

INC-04: No rules (SEV 3)

What happened: Screen 12: Provider. Screen 13: Riverpod. Screen 14: setState and hope.

Root cause: Every session started from zero on how this app is built.

The fix: A rules file the agent reads every time:

# AGENTS.md
- State: Bloc only. No new packages.
- Ask before touching lib/theme/.
- flutter analyze + test before "done".

This is the lowest severity on the list because nothing breaks immediately. It's also the one that compounds. Each screen works on its own, but the codebase gets harder to change with every new state approach.

Where the rules file lives depends on your agent, so check its docs. The content is the same idea everywhere: your architecture, your packages and your no-go files, written once instead of repeated in every prompt.

INC-05: Unread diffs (SEV 1)

What happened: +900 −340. Approved at 1am because the app still ran.

Root cause: Running isn't the same as correct. The diff was too big to read.

The fix: Read the tests first, then the diff. Can't review it? It's too big. See INC-03.

"It still runs" is the weakest possible review. The tests-first order helps: if the tests match the requirements, you know what the code is supposed to do before you read it, and the diff review becomes "does this do that?" rather than "what is all this?"

If you still can't review it, don't approve it. Send it back and split the task. Review is becoming the slow part of building with agents, which is the argument in Code Review Is the New Bottleneck.

How the five fixes fit together

Look at the fixes side by side:

1. Write requirements.md first.
2. One widget test per requirement.
3. Split tasks until each diff fits on one screen.
4. A rules file the agent reads every time.
5. Read the tests first, then the diff.

They aren't five separate tools. They're one workflow: requirements, then tests that prove them, small tasks that produce reviewable diffs, rules that keep every session consistent, and a review order that uses the tests. Each fix also makes the others easier. Small tasks make diffs readable. Tests make diffs checkable. Requirements make tests possible.

At FlutterBytes

At FlutterBytes 2026 in Lagos (6 and 7 November) I'll show how spec, tests, small tasks, a rules file and real reviews fit together on one feature.

Which incident has your team already had?