Give a coding agent three kinds of context before you ask it to change a Next.js app: documentation that matches the installed framework version, repository rules that explain local boundaries, and evidence from the running app. Each solves a different failure mode. Bundled docs reduce stale API advice; AGENTS.md and project Skills reduce architectural drift; browser and runtime diagnostics reveal whether the change actually behaves as intended.
This is more useful than a longer prompt. It gives a capable React and Next.js developer a repeatable way to review agent work without pretending the agent can infer your product, route behavior, or provider boundaries on its own.
Current Next.js agent-tooling matrix
The practical question is not “which agent is best?” It is which evidence source should answer which question. The following matrix is a repository check, not a compatibility guarantee for every editor or agent.
1. Version-matched framework docs
- Use for: Next.js APIs, routing conventions, caching behavior, and migration questions.
- Evidence source: Next.js documents that
node_modules/next/dist/docs/is bundled with the installed package and can be directed from a rootAGENTS.md. - What it prevents: an agent choosing an API pattern from older training data when your project uses a different version.
- What it does not prove: where your business logic belongs, how your auth works, or whether a screen now works in the browser.
2. Repository instructions and Skills
- Use for: local architecture, provider boundaries, verification commands, and repeatable multi-step tasks.
- Evidence source: this Frontend Accelerator repository has a canonical
AGENTS.md, tool-specific entrypoints for Claude Code, Copilot, Cursor, and Windsurf, plus pinned.agents/skills/workflows. - What it prevents: an otherwise plausible feature importing a provider SDK directly, bypassing a feature boundary, or adding a second testing pattern.
- What it does not prove: that an instruction is followed, a command passes, or a page is usable.
3. Runtime and browser evidence
- Use for: build errors, runtime errors, active routes, page metadata, server-action lookups, logs, and browser-visible behavior.
- Evidence source: the current Next.js MCP guide describes the
next-devtools-mcpbridge for Next.js 16+ and lists runtime diagnostic capabilities. - What it prevents: declaring a patch finished when it only type-checks or when the error exists only after rendering a route.
- What it does not prove: that a product decision is right or that a visual flow is accessible. A human still needs to exercise the relevant path.
Repository baseline: the current Frontend Accelerator product repository records Next.js 16.2.3, includes the bundled docs directory, and ships its own agent contract and repo-local Skills. It does not currently include a root .mcp.json, so treat live MCP diagnostics as an intentional setup step—not as a capability that is already configured.
Start with a small evidence ladder
Use the lightest source that can answer the next question. This keeps an agent focused and makes your review easier.
- Read the target route or feature and its closest working neighbor.
- Read the relevant section of
AGENTS.md. For a framework question, locate the matching document undernode_modules/next/dist/docs/. - Load one relevant project Skill only when the task matches it. A testing Skill is useful for a regression; a cache Skill is useful for a cache change. Loading every Skill creates noise rather than safety.
- Ask the agent to name the files it will change, the boundary it must preserve, and the check that could disprove the change.
- Run the change, inspect the route in a browser, and record the observed result before calling the task complete.
That last step matters. A repository rule can tell an agent to default to Server Components; it cannot show whether a submitted form displays a validation message, a redirect lands on the right locale, or a client-only dependency reached the browser bundle.
How the three layers work together
Consider a request to add a profile preference saved from a dashboard page. The bundled Next.js docs answer framework-level questions such as where a Server Action belongs and how mutations interact with rendering. The repository contract answers product-level questions: keep business behavior in the relevant feature, instantiate infrastructure server-side, validate input, and use the local structured-result convention. Browser inspection then answers the only question a static read cannot: does a signed-in user see the right state after the action runs?
The important distinction is evidence ownership. Framework docs are authoritative for framework behavior. Your repository is authoritative for local architecture. A running app is authoritative for the observed result in that environment. Do not let an agent use one layer as a substitute for another.
Recommendation: ask for an implementation plan that cites one item from each layer before asking for code on a sensitive path.
Original asset: a practical agent-task checklist
Use this checklist as the handoff between a developer and an agent. It is deliberately small enough to apply to a single route or feature.
- Task boundary: name the user outcome and the exact feature or route.
- Local rule: quote the relevant
AGENTS.mdconstraint, such as a provider-adapter or feature-boundary rule. - Framework reference: identify the installed-version document that governs the API or convention.
- Skill decision: name one relevant Skill, or explicitly say that none is needed.
- Failure case: state what should happen for invalid input, an unauthorized user, or a provider failure.
- Verification: name the focused test or command and the browser interaction that must be observed.
Example task brief
Goal: add a profile preference on the authenticated dashboard.
Scope: profile feature and its localized dashboard route only.
Local rule: keep provider access behind the existing adapter.
Framework reference: read the installed Server Actions documentation first.
Failure case: invalid input returns the existing structured error shape.
Verify: run the focused test, then save and reload the setting as a signed-in user.
This is not a prompt that asks an agent to be careful. It makes the expected evidence and the failure behavior reviewable.
When to add browser debugging
Start with ordinary browser checks for a visual or interaction change. Add the Next.js DevTools MCP path when the agent needs to correlate a browser symptom with development-server diagnostics, route metadata, logs, or a server action. The official setup is a root MCP configuration that invokes next-devtools-mcp; the bridge discovers a running Next.js instance. Keep that configuration separate from secrets and review it like any other developer tool.
A useful workflow is: start the development server, open the affected page, reproduce one narrow action, then ask for errors or logs tied to that state. If you use browser automation, keep the same boundary: automation verifies an observed flow; it does not replace authorization tests, unit tests, or a human review of the result.
Three failure modes to catch early
Stale framework knowledge
An agent proposes a familiar pattern that no longer matches the installed Next.js release. The fix is not a larger model or a longer conversation; it is reading the version-matched doc before implementation.
Generic instructions that do not name boundaries
“Follow best practices” does not tell an agent whether a feature may import Stripe, Firebase, or a database client. A canonical contract should name the allowed adapter, the expected result shape, and the checks that matter. Keep tool-specific files short and point them back to that contract so the rules do not fork.
Passing tests with a broken route
A focused test can pass while an active route has a runtime error, a missing client interaction, or an unexpected redirect. Open the route after the change. For a high-risk flow, verify both the expected path and one failure path before merging.
Too much context at once
Loading every repository document, every Skill, and a long conversation transcript can make the next decision less clear. Keep the task context bounded: one target feature, the adjacent implementation, the governing rule, one framework reference, and the relevant check. Expand only when that evidence exposes a real dependency. This is especially useful for solo developers because it leaves a short review trail: another person can see what the agent was told, what it changed, and which observation justified accepting the work.
A sensible default for a solo SaaS
Put a concise AGENTS.md at the root, keep the authoritative rules in one place, and add narrowly scoped Skills for workflows you repeat. For Next.js-specific work, direct the agent to the installed docs rather than asking it to recall framework behavior. Add live diagnostics when the work depends on a running app, and make browser verification part of the definition of done.
Frontend Accelerator follows this shape with a feature-first contract, provider adapters, tool entrypoints, and pinned project Skills. That pattern is useful because it gives an agent a readable starting point while leaving the developer responsible for the architecture, tests, and final product judgment. Read the compatibility guide and inspect the AI-ready foundation.
