What we put in AGENTS.md for a Next.js starter (and what we left out)

By VibeBoot · 2026-10-19

Short on time? The SaaS Starter already has this wired up: $49 one-time, 14-day money-back guarantee.

Most Next.js starters ship components and a README. Fewer ship the files coding agents actually read. VibeBoot Lite includes AGENTS.md, CLAUDE.md and a Cursor rule so Cursor, Claude Code and similar tools edit the right files on the first try. This is what we put in those files, what we left out, and why.

Why a starter needs agent files

Without project context, every new chat re-decides where copy lives, which button component to use and whether to invent a new layout. That burns tokens and produces inconsistent diffs. A short, checkable AGENTS.md is cheaper than fixing the same mistakes twice.

We keep three files in sync on purpose:

`AGENTS.md` — the cross-tool default many agents look for.
`CLAUDE.md` — Claude Code's project memory.
`.cursor/rules/project.mdc` — Cursor's always-on rule with the same essentials.

If you only maintain one, make it AGENTS.md and point the others at it.

What we put in AGENTS.md

Stack, in one screen

Name the framework versions and the defaults you actually use: Next.js App Router with a src/ directory, React Server Components by default, TypeScript strict, Tailwind CSS v4. Agents stop proposing Pages Router patterns when the stack line is explicit.

Where copy and links live

Lite keeps marketing copy and URLs in src/lib/site.ts. The rule says: change hero text there, not by hardcoding strings into page components. When you ask an agent to "rewrite the hero for my product," it has a single file to open.

Brand tokens

Colors and type live in one Tailwind @theme block. The agent rule says to edit that block for brand changes instead of sprinkling hex values across classNames. Black and neon green (#39FF14) stay consistent that way.

The component set you already have

Lite ships a small set: Button, Badge, Section, Nav, Footer, Terminal, Comparison. Listing them in AGENTS.md matters more than the components themselves. Agents reuse named pieces when they know the names; otherwise they invent parallel ones.

One verify command

npm run check runs lint, typecheck and build. The rule tells agents to run it before claiming they are done. That catches broken imports and type errors without you babysitting every turn.

What we left out

Long essays. Always-on rules cost context on every request. Detail belongs in glob-scoped Cursor rules or linked docs, not a 2,000-line AGENTS.md.
Style guides nobody enforces. If it is not checkable (npm run check, a named file, a forbidden import), we skip it.
Secrets and deploy runbooks. Those change per buyer. The starter stays clone-and-run with no env vars.

A minimal template you can copy

# Agent notes

## Stack
- Next.js App Router (`src/`), React Server Components by default, TypeScript strict, Tailwind CSS v4.

## Edit here first
- Marketing copy and links: `src/lib/site.ts`
- Brand tokens: the Tailwind `@theme` block
- UI: reuse `Button`, `Badge`, `Section`, `Nav`, `Footer` before inventing new components

## Verify
- Run `npm run check` (lint + typecheck + build) before you finish

Adapt the paths to your repo. Keep it short enough that an agent will still see it when the chat is long.

If npm run check fails anyway, paste the error into the free Next.js error fixer. It covers 20 common Next.js 16 errors that agents cause, each with the fix and a ready-to-paste prompt, and it runs in your browser.

Try it

Clone the free VibeBoot Lite Starter, open AGENTS.md, and ask Cursor to rewrite the hero. There is a live preview if you want to see the UI first. The same agent setup ships in the paid SaaS Starter and AI Chatbot Starter, with auth and Stripe already wired.

Want ready-made versions of these files? The free VibeBoot Cursor Rules Pack bundles an AGENTS.md template, a CLAUDE.md and 9 scoped Cursor rules (Next.js, Stripe, Stripe webhooks, access control, database, AI SDK and more) in one zip. MIT license, no signup.