AI Coding Workflow for Next.js

Give the agent one named task, only the context it needs and a check you can rerun. A task shaped this way produces a diff small enough to review and a result you can repeat.

Each move fails in its own way. Without a boundary, the agent edits files you never meant to open, and the diff becomes hard to read. Thin context fails more quietly: the code compiles and the tests pass, but the change ignores patterns the rest of the repo follows. Without a check you can rerun, you are taking the agent's word that the work is done.

Asking for a plan before the agent writes code is the easiest step to skip. It means a short wait while nothing visible happens, and the price of skipping it shows up later, in review.

If the plan names files you didn't expect, you learn that before any code exists. If it names the right files, you have a list to check the diff against. Once four hundred lines of diff are on screen, changing the approach means throwing that work away.

The habit that matters most for a team is leaving a trail the next reviewer can follow. The steps below keep the prompt and its proof attached to the change.

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.

Match the effort to the change. A one-file fix needs a clear done state and a typecheck, and a plan adds little. A change across several files is where a plan pays for itself, and where the check should include tests and a reviewer who knows that code.

Keep whatever lets someone rerun the work or pick it up later. A finished task is the merged code plus a short trail that shows 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.

The last item pays off over time. A rule or template saved from one good run means the next run starts from what already worked, not from a blank prompt.

Because app-router conventions change faster than any model's training snapshot, and a route file written to an older convention still compiles. Give the agent the docs for the Next.js version you are on before you ask for code. That is the cheapest step on this page and the one most likely to get skipped.

Cursor's @ menu no longer lists @Docs, the old way to index a docs site. Attach a local copy of the docs with an @ mention of its folder, or open the page in Cursor's browser and attach it with @Browser.

The failure is not a crash. A wrong API is the kind of mistake review catches. An outdated convention produces 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 after the diff that caused it.

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

A "use client" at the top of a file that didn't have one. It is a single line, it rarely makes it into a summary, and it changes where the rest of that tree renders. Agents add it for a real reason: a hook won't 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 that states the preference, such as preferring server components and marking client files explicitly, scoped to .tsx files. The rule won't stop the edit. It does mean the agent has read the preference before it makes the edit, which changes how often the edit shows up at all.

Sometimes moving the boundary is the right answer. That is why this belongs in a review habit, not in a lint rule that fails the build.

By loading the route, not just compiling it. Cursor prompts the agent to detect running development servers and use the correct port instead of starting a duplicate or guessing. That removes a common way for a verification step to fail for reasons unrelated to the change.

For cloud agents that use a committed .cursor/environment.json, the same information lives in that file. Each entry under terminals takes a description that is shown to the agent, so "Next.js dev server on port 3000" tells it both what is already running and where to look. ports declares the port itself. The file reads like documentation and works as a prompt.

For pages that exist to be found, check the rendered HTML instead of the browser view. You can't count on a crawler running your JavaScript. A page that looks correct in a screenshot can still be empty to the crawler you built it for.

On a small team with one app, this is one habit you can carry in your head. Past a handful of apps, write the verification step into the repo, because the person reviewing in six months won't be the person who agreed to the habit. Where that line falls is a judgment about scale, not a number anyone has published.