A Minimal AGENTS.md and Cursor Rules Setup for Next.js App Router

Coding agents do not know the conventions of a Next.js codebase unless the repository tells them....

Coding agents do not know the conventions of a Next.js codebase unless the repository tells them. Without that context, a new session can introduce a second router, move data fetching into the browser, expose an environment variable, or ignore the project’s existing naming patterns.

A large instruction dump is not the answer. A small set of scoped rules is easier to review, easier to keep current, and more likely to be followed.

This guide shows a practical baseline for Next.js App Router projects using AGENTS.md, CLAUDE.md, and Cursor project rules. The free Vildanden sample contains the complete files described here.

The four-layer setup

1. AGENTS.md: the tool-neutral baseline

Keep the durable engineering decisions in a root AGENTS.md:

• Use the App Router and do not invent a parallel pages/ tree. The important part is not the filename alone. The file should describe the repository’s actual architecture, not an idealized rewrite of it.

2. CLAUDE.md: a short Claude Code pointer

A lean CLAUDE.md can point Claude Code to the baseline and add only tool-specific habits:

# CLAUDE.md

Treat `AGENTS.md` as the source of truth for this repository.

- Scan neighboring files before adding a new pattern.
- Prefer Server Components unless hooks or browser APIs require the client.
- Match the package manager and scripts in `package.json`.
- Validate mutations and run focused checks for changed paths.

Avoid duplicating the entire instruction set in two files. Duplication drifts.

3. Cursor .mdc rules: scope the reminders

Cursor project rules can make the same guidance visible at the right time. A rule for server actions and data access does not need to apply to every Markdown file:

---
description: Server actions, route handlers, and data fetching
globs: "**/app/**/*.{ts,tsx},**/lib/**/*.{ts,tsx}"
alwaysApply: false
---

Use `alwaysApply: true` for genuinely global guidance such as security basics. Use globs for rules that are meaningful only in particular files. If the app uses `src/app`, update the patterns rather than blindly copying them.

### 4. Prompts: make the desired finish state explicit

A prompt template is useful when it asks for more than implementation. For a feature, request loading, empty, and error states, tests for risky behavior, and a final summary of files changed and verification steps. For a bug fix, request a root-cause explanation and a regression test when practical.

These prompts are optional. The project rules are the durable layer; prompts are task-level scaffolding.

## A 60-second install

1. Copy `AGENTS.md` and `CLAUDE.md` into the project root, or merge them with existing files.
2. Copy the three `.mdc` files into `.cursor/rules/`.
3. Adjust globs for `src/` layouts and local conventions.
4. Reopen the project and confirm the rules appear in the tool.
5. Run the project’s normal checks before trusting the result.

The sample has no runtime dependency and does not modify your application. It is a starting point, not a claim that three rules can replace CI, review, or security work.

## Download the sample

The free Next.js + React sample is available from Vildanden:

https://vildanden.gumroad.com/l/xphax

For a deeper pass on conventions, Server Actions, and security, see [Scoped Cursor Rules for Next.js App Router](https://dev.to/vildandenai/scoped-cursor-rules-for-nextjs-app-router-conventions-server-actions-and-security-413l).

For projects that also need Node/TypeScript API, Python FastAPI, and general-fullstack variants, the optional four-stack pack is here:

https://vildanden.gumroad.com/l/daody

**Disclosure:** This article describes a Vildanden sample and links to its free download and optional paid expansion.


# Data and mutations

- Validate mutation payloads at the server boundary.
- Revalidate the specific path or tag after writes.
- Treat request bodies and search parameters as untrusted.
- Do not leak stack traces to production clients.

• Prefer Server Components; use Client Components for hooks, events, and browser APIs.
• Keep shared UI in components/ and domain logic in lib/ (or the project’s existing equivalents).
• Validate external input at server boundaries.
• Keep secrets server-side and document required keys in .env.example.
• Run the narrowest useful typecheck, lint, and tests before finishing.