# Cursor Agent Next.js: practical agent workflow

URL: https://agentvera.dev/en/blog/cursor-agent-for-nextjs/ · Published: 2026-11-01

Learn how to run Cursor Agent on a Next.js project: AGENTS.md rules, prompt loops, testing, and App Router or Pages Router pitfalls.

**In short:**

- Cursor Agent works best in a Next.js repo when AGENTS.md encodes build, lint, and test commands plus server and client component boundaries.
- Use small, verifiable steps and run next build, lint, and targeted tests after each change to catch hydration and routing issues early.
- AgentVera can run multiple Cursor Agent instances in parallel worktrees with automatic review and checkpoints, which suits larger Next.js feature work.

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](/en/agents/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:

```markdown
# 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.

| Task type | Good prompt pattern |
|---|---|
| Add an App Router route | "Add a server-rendered page at app/account/settings/page.tsx that uses the existing auth helper and returns the settings form as a client component import. Include metadata export." |
| Move a component to client | "In components/ThemeToggle.tsx, add 'use client' and replace any server-only imports with client-safe equivalents. Keep the parent server component unchanged." |
| Add an API route | "Add a DELETE handler to app/api/items/[id]/route.ts using the existing prisma client. Validate the id with the existing schema and return 204 on success." |
| Update E2E tests | "Update the Playwright test for the product page to match the new URL structure. Only change the test; do not alter the page code." |
| Fix a build error | "Run pnpm build and fix the first error. Show the diff of only the files you changed." |

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](/en/agents/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)](/en/blog/best-tools-parallel-ai-coding-agents/) 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.

## Frequently asked questions

**What is Cursor Agent and how do I start it in a Next.js project?** Cursor Agent is the terminal coding agent from Cursor. Run cursor-agent in the project root after installing it; it reads project instructions from AGENTS.md or .cursor/rules and can edit files and run commands. For Next.js, configure those files with build, test, and lint commands before starting.

**Can Cursor Agent handle both App Router and Pages Router in one Next.js project?** Yes, but you need to tell it which directories use which router. In AGENTS.md, name the app/ and pages/ folders and their conventions, otherwise the agent may import Next.js hooks from the wrong router or use incompatible data fetching. Explicit boundaries make mixed-router work much safer.

**What should I put in AGENTS.md for a Next.js project?** Include exact package manager commands for install, dev, build, lint, typecheck, and tests. Add folder conventions like App Router under app/, client components only where interactivity is needed, and route handler locations. Keep it short and specific, not generic Next.js advice.

**Does Cursor Agent work with Vitest, Jest, and Playwright in a Next.js repo?** It can run any test command you specify, including Vitest, Jest, and Playwright. Make sure the test commands in AGENTS.md match the project’s actual scripts, and ask the agent to run targeted tests first. Review any changes to test configuration files separately.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/