AI Coding Assistant Mistakes and How to Avoid Them

Most AI coding assistant mistakes begin before code is generated: the task is vague, the constraints are hidden, or nobody defines how the result will be validated. The prevention is not to avoid AI. It is to give the assistant a better engineering problem to solve.

Here are the failure patterns that make technically valid changes risky, plus a concrete habit that prevents each one.

1. Asking for a solution without the problem

“Move the button to the sidebar” tells an assistant where to place something, not why the current placement fails.

Prevention: State the user problem and outcome first.

Problem: The topic switcher competes with global navigation, but people use it
while comparing lessons in one course.

Outcome: Make topic switching easy to find near course navigation without
changing the navbar's global actions.

The assistant can now challenge the location choice if a different small-screen pattern is safer.

2. Leaving the scope open-ended

“Clean up the auth flow” invites a large diff. The assistant may touch providers, routes, tests, and API calls because it cannot see a boundary.

Prevention: Name the first boundary and the non-goals.

Inspect the sign-in callback and its direct tests only. Do not change account
linking, billing, or route guards unless the evidence shows the callback cannot
be fixed in isolation.

If the work truly crosses a boundary, the assistant should explain why before it expands.

3. Hiding constraints in your head

An assistant cannot infer every product rule from a component. It may introduce a server-only path into a static app, break a locale-preserving route, or duplicate a state writer.

Prevention: Put essential invariants in the prompt or durable project guidance.

Preserve static export, active-locale navigation, existing analytics event
names, and the current single writer for notification preferences.

Keep the list short and specific. A long wish list is less useful than a few enforceable contracts.

4. Treating generated code as verified code

Generated code can compile and still have the wrong state transition, error path, accessibility behavior, or security boundary.

Prevention: Require a validation plan before implementation.

List the focused tests, type check, and manual scenario that would prove this
change. Explain which behavior each check covers and what remains unverified.

Run the checks. Review the diff. Exercise the user path. AI output is a proposal, not a release criterion.

5. Changing too many files at once

A large diff hides whether the actual bug is fixed. It is difficult to review and almost impossible to roll back safely.

Prevention: Request a sequence of small checkpoints.

First reproduce and explain the failure. Next make only the state fix and add
the regression test. Do not refactor related components until the focused test
passes and the diff is reviewed.

The smaller change may reveal that the planned refactor was not needed.

6. Optimizing before measuring

“Make this page faster” can produce caching, memoization, or code splitting that hides the real bottleneck and creates new invalidation risks.

Prevention: Ask for measurement and alternatives.

Identify whether the slowdown is network, computation, or rendering. State the
measurement, baseline, and expected impact before proposing an optimization.
Do not add persistent caching until freshness and invalidation are defined.

Performance work should change a measured cost, not simply add a familiar technique.

7. Solving the wrong product problem

An assistant may remove a desktop sidebar to improve mobile layout, or simplify a flow that people rely on. The code can be clean while the product gets worse.

Prevention: Name the people, workflow, and behavior that must remain.

Mobile learners need more horizontal space. Desktop learners rely on the
sidebar for course navigation. Improve the mobile layout while preserving the
desktop workflow and its keyboard path.

This turns “remove the sidebar” into an actual design constraint.

8. Asking for a production fix without evidence

Production incidents create urgency, but urgency is not a reason to let an assistant guess from a symptom.

Prevention: Use the evidence-to-validation sequence:

Evidence -> hypotheses -> verification -> smallest fix -> regression test ->
safe rollout check

Include logs with sensitive values removed, reproduction steps, environment, recent changes, expected behavior, and observed behavior. Do not apply generated patches blindly to production.

A pre-send checklist mapped to these mistakes

Before you send a significant AI coding request, confirm:

Problem stated — not only the proposed solution (mistake #1).
Scope bounded — first files or subsystem named; non-goals listed (mistake #2).
Constraints explicit — deployment, locale, security, and ownership rules included (mistake #3).
Validation planned — tests, manual path, or measurement named before code is written (mistake #4).
Change sized for review — one checkpoint, not a sweeping refactor (mistake #5).
Performance claims measured — baseline and expected impact if speed is the goal (mistake #6).
Product behavior protected — affected users and preserved workflows named (mistake #7).
Production evidence attached — logs, repro, environment, and recent changes redacted as needed (mistake #8).

For the full reusable prompt template behind this checklist, read how to write better AI prompts. For day-to-day implementation patterns, use prompt engineering for developers. When an incident is involved, follow the production debugging prompt templates.

Terminal output is evidence too. Practice a command-line workflow in the browser before you encode it into a bug report, test, or automation prompt.