Cursor Agent Next.js: practical agent workflow

Cursor Agent is the terminal coding agent from Cursor. In a Next.js project you start it by running cursor-agent in the repo root, and it reads project instructions from AGENTS.md or .cursor/rules. The most reliable pattern is to give it explicit Next.js-specific context, work in small verifiable steps, and run build, lint, and tests after each change. Cursor Agent has the agent basics.

Why a terminal agent fits Next.js patterns

Next.js work is mostly file-level and command-verifiable, which suits a terminal agent. A single feature often touches a page, a server helper, a route handler, a client component, and tests. Cursor Agent can read those files in one session, perform the edits, then run the project’s lint, typecheck, and test commands to catch mismatches. It is especially useful when the repo has clear conventions in AGENTS.md or .cursor/rules because the agent can apply those rules instead of guessing. In a mixed App Router and Pages Router repo, give the agent an explicit map of which directories belong to which router; otherwise it may import next/navigation into a Pages Router file or use getServerSideProps in an App Router component. Typical tasks where Cursor Agent saves time include adding a route with loading and error states, converting a server component to a client component only for a small interactive part, writing route handlers with validation, and updating Playwright tests after a route changes. Those tasks require coordinated edits across files, which is exactly where a terminal agent with repo access is stronger than copy-paste generation. The risks are the same as with any AI coding agent: over-editing, invalid server/client imports, and ignoring route-level caching, so the setup below is important.

Give the agent a project map in AGENTS.md

Create an AGENTS.md at the project root, or add files under .cursor/rules if you prefer per-topic rules. The file should give commands, folder conventions, and Next.js-specific constraints. Keep it short enough that the agent actually reads and follows it. For a mixed repo, put both app/ and pages/ conventions in the same file and label them clearly. A realistic example for a Next.js repo using pnpm, ESLint, TypeScript, Vitest, and Playwright:

# AGENTS.md for a Next.js app

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Lint: `pnpm lint`
- Typecheck: `pnpm typecheck`
- Tests: `pnpm test`
- E2E: `pnpm test:e2e`

## Conventions
- App Router under `app/`, legacy Pages Router under `pages/` if present.
- Prefer Server Components for data fetching; add `'use client'` only for interactivity.
- Keep route handlers in `app/api/` or `pages/api/` with typed responses.
- Colocate tests in `__tests__/` or next to files using the project's pattern.

## Rules
- Never mix server-only imports into client components.
- Do not use `next/router` in App Router components; use `next/navigation`.
- Run `pnpm lint && pnpm typecheck` after every change.
- Do not edit generated files such as `next-env.d.ts`.

Also tell the agent where App Router and Pages Router code lives, how data fetching is done, and what test patterns exist. If the project has route groups or private folders, name them. If ESLint is configured with strict rules like no-unused-vars or no-explicit-any, note it so the agent does not introduce lint errors. You can also create a separate .cursor/rules/nextjs.md with the same content, plus rule files for testing or API conventions. One common mistake is putting too much generic advice in AGENTS.md. The agent will spend attention on noise. Keep it to commands, folders, and hard rules. For example, if the project uses the src/app directory and route groups like (marketing) and (dashboard), name them; otherwise the agent may create a new route outside the group and break the URL structure. The goal is to make the agent’s first guess match the repo, not merely produce valid Next.js code.

Plan, edit, run checks, review the diff

Start each task by asking the agent to inspect the relevant files and state a plan before editing. A useful loop is:

1. Ask it to read the route, component, and test files that are involved.
2. Have it write a short plan in the terminal. Correct any wrong assumptions before it edits.
3. Let it make one logical change.
4. Ask it to run targeted lint, typecheck, and tests.
5. Review the diff for accidental moves of client boundaries or route handlers.

Do not ask it to refactor an entire route tree at once. Review the diff for changes to app/layout.tsx, middleware.ts, or test setup files, because those can affect the whole app. Typical prompts that fit this loop:

• In this App Router project, add a server-rendered product listing at app/products/page.tsx that calls the existing listProducts helper from lib/data.ts. Include loading.tsx and error.tsx using the existing shared components. Run pnpm lint and pnpm typecheck.
• Convert components/CartButton.tsx to a client component that posts to /api/cart with optimistic state. Keep the server component above it unchanged. Add or update the Vitest test for the optimistic behavior.
• Add a GET and POST route handler under app/api/orders/route.ts. Validate the POST body with the existing zod schema in lib/schemas.ts and return JSON errors with the correct status codes. Add Playwright coverage for the success and validation paths.
• Fix the failing Playwright checkout test: run pnpm test:e2e --grep checkout, identify whether the failure is in the page or the test, and make the smallest change that passes without disabling the test.
• Review app/dashboard/layout.tsx and middleware.ts for server/client boundary problems and any accidental use of client-only hooks in the server tree. Explain each finding before changing code.

These prompts are deliberately constrained to one feature or one failure. The agent can also propose the plan itself, but it should show the plan before touching files. If the plan includes moving a server component to a client component, ask why and confirm that interactivity requires it; often the better fix is to extract only the interactive subtree. Keep prompts in English and specific to the codebase.

Where Cursor Agent shines and where to verify carefully

Cursor Agent handles many routine Next.js changes well when given the correct context. The table below lists common tasks and a focused prompt that usually works.

Where to watch closely: page-level caching, server/client boundaries, Route Handlers, and middleware. If the agent adds export const revalidate = 0 or changes a component to a client component without a clear reason, review it manually. It may also forget that a server component cannot use hooks from next/navigation on the server side, or that a client component cannot import server-only code. Another common mistake is editing next.config.js or tsconfig.json without being asked; those files affect the whole build and should be reviewed line by line. In Pages Router, watch for accidental use of App Router features like generateMetadata or loading.js. If the repo has a mix, keep the rules extremely clear.

Run the right checks after every change

Always have the agent run at least lint and typecheck after a change. For unit tests, ask it to run only the tests that cover the changed files, not the whole suite. For a Next.js project, next build is the strongest static check, but it can be slow; run it after a batch of related changes. Playwright tests should run after the build, and only the affected spec files. A typical verification sequence for a feature change is:

1. pnpm lint
2. pnpm typecheck
3. pnpm test -- changed-test.spec.ts
4. pnpm build
5. pnpm test:e2e --grep feature-name

If the agent reports a test failure, ask it to show the exact error and the file:line. It should not edit tests to make them pass unless the test was already incorrect; better to fix the source. When working with Playwright, watch for selectors that are too generic or tied to text that changes. If the agent modifies test files, ask for the test diff separately and check for test.skip or test.only. In a Next.js repo, Vitest is often used for unit and component tests, while Playwright covers E2E. Make sure the agent knows which one to run for a given change. A common failure is running npm test when the project uses pnpm test, or running Playwright without building first. The AGENTS.md commands solve most of that.

Parallel work with AgentVera

AgentVera runs multiple coding agents, including Cursor Agent, side by side in one desktop app with each in its own real terminal panel. For Next.js work, the most valuable pieces are parallel git worktrees, automatic code review with file:line links, and checkpoints you can undo with a click. Parallel worktrees let several Cursor Agent instances edit different features without overwriting each other, which fits a Next.js repo where one agent works on a route while another updates tests. Automatic review catches server/client boundary mistakes after each turn, linking directly to the exact line in a component or route handler. Checkpoints allow you to roll back an agent’s turn if it made a bad change to middleware.ts or next.config.js. Token budgets also help, because a long refactor of route groups can otherwise consume a large budget. Best tools to run AI coding agents in parallel (2026) has more details on parallel agent workflows.

Keep the loop tight

Cursor Agent is useful for everyday Next.js work if you treat it as a capable but fallible pair programmer. Encode the project’s commands and router conventions in AGENTS.md, keep prompts to one logical change, and always run lint, typecheck, and a build or targeted test before accepting the diff. The main risks are accidental server/client boundary violations and route handler mistakes, so review those files manually. With a tight loop and the verification steps above, the agent can handle a meaningful share of the work without introducing regressions. If you run many features in parallel, AgentVera gives you the worktree and review infrastructure to keep several agents productive on the same repo.