AI Coding Workflow for Next.js

The working pattern for Next.js AI coding is small enough to review and specific enough to repeat. Give the agent a named task and only the context it needs, then tie the result to a check you can rerun. The table below breaks that into moves.

Each of those moves fails in its own particular way, and the order they come in is doing more work than it looks like it is. Skip the boundary and you get a diff nobody wants to read, because the agent has quietly rewritten files you never meant to open. Thin context fails more quietly: the code compiles, the tests pass, and it ignores every pattern the rest of the repo follows. Then there's the check, which to me is the real one, because it's the whole difference between a result you verified and a result you're taking someone's word for.

The step people skip is the plan. I think it's because it feels like overhead, thirty seconds of nothing visibly happening while you're trying to get work done. Actually, that's not quite the reason. It's that the cost of skipping it lands much later, so it never registers as the mistake it was. If the plan names files you didn't expect, you've learned something for free. If it names the right ones, you've got a reference to check the diff against when it arrives. And once there are four hundred lines on the screen, changing the approach means throwing that work away, which nobody is good at.

Running Next.js AI coding as a team comes down to one habit: leave a trail the next reviewer can follow. The steps below keep the prompt and its proof attached to the change, so nobody has to reverse-engineer what the agent did.

1. 1Pick one real backlog item with a clear owner and expected result.
2. 2Add only the context the agent needs: files, failing output, constraints and done state.
3. 3Ask for a plan before code when the task touches more than one file.
4. 4Run checks that match the risk: unit test, typecheck, visual pass or review checklist.
5. 5Capture the prompt, diff, result and reviewer note so the workflow can be repeated.

Keep whatever lets you rerun the work or hand it to someone else. A finished task is the merged code plus the short trail that explains how it got there.

• The prompt or plan that shaped the work.
• The files changed and the reason each file changed.
• The command, screenshot or review note that proved the result.
• The rule, checklist or template you would reuse next time.

Because app-router conventions move faster than any model's training snapshot, and a route file written to an older convention still compiles. Attach the version you are actually on with @Docs, and index it once through @Docs > Add new doc if it is not there yet. That is the cheapest step on this page and the one most likely to get skipped.

The failure mode is not a crash. I used to describe it as the agent getting an API wrong, which is not really it, because a wrong API is the kind of thing review catches. What happens instead is a file that looks idiomatic, passes review from someone who learned the same older convention, and behaves differently at request time. You find out from a stale page in production, weeks past the diff that caused it.

Rules help here too, scoped with globs so the app-router conventions load for the app directory and not for your migrations or scripts.

The "use client" at the top of a file that did not have one. It is a single line, it rarely survives into a summary, and it changes where the rest of that tree renders. Agents add it for an honest reason. A hook would not work otherwise, and moving the boundary is the fastest way to make the hook work.

So check whether the boundary moved before you check whether the logic is right. The repo-side version of that check is a short rule stating the preference, something close to preferring server components and marking client files explicitly, scoped to .tsx files. It will not stop the edit. It does mean the agent has read the preference before making it, which changes how often the edit shows up at all.

Then again, moving the boundary is sometimes the right answer, which is exactly why this belongs in a review habit rather than in a lint rule you can fail a build on.

By loading the route, not by compiling it. Cursor prompts the agent to detect running development servers and use the correct port instead of starting a duplicate or guessing at one, which removes the most common reason a verification step fails for reasons that have nothing to do with the change.

For cloud agents the equivalent lives in .cursor/environment.json. Each entry under terminals takes a description that is displayed to the agent, so "Next.js dev server on port 3000" tells it both what is already running and where to look, while ports declares the port itself. It reads like documentation and functions as a prompt, which is a genuinely nice property for a config file to have.

For pages that exist in order to be found, the check is the rendered HTML rather than the browser view. The lead answer on this page says as much. What it does not say is why, and the why is that you cannot count on a crawler running your JavaScript, so a page that looks correct in a screenshot can still be empty to the thing you built it for.

Small team, one app, this is all one habit and you can carry it in your head. Past a handful of apps, write the verification step into the repo instead, because the person reviewing in six months will not be the person who agreed to the habit. Where exactly that line sits is a judgement about scale rather than something anyone has measured.