AGENTS.md · Next.jsAGENTS.md and CLAUDE.md examples for Next.js
Of 355 actively developed open-source products built with Next.js, 217 (61%) keep instruction files for coding agents: AGENTS.md in 167, CLAUDE.md in 133. The typical file is 1,033 words, and most cover commands to build, run and test (78%) and pointers to other docs (74%).
Real files to read
From the best-known open-source Next.js products whose file is a real one (not a pointer to another), 200 to 4,000 words, covering at least three of the usual topics and naming Next.js. Each opens on GitHub.
| Project | File | Stars | Words | Covers |
|---|---|---|---|---|
| Significant-Gravitas/AutoGPT | AGENTS.md | 187,527 | 943 | CommandsTestingDoc pointersStructureCode styleGit |
| bytedance/deer-flow | AGENTS.md | 83,703 | 1,785 | CommandsTestingDoc pointersCode style |
| calcom/cal.diy | AGENTS.md | 48,959 | 1,317 | CommandsTestingDoc pointersStructureGit |
| MHSanaei/3x-ui | CLAUDE.md | 47,834 | 1,905 | CommandsTestingDoc pointersCode styleGit |
| lfnovo/open-notebook | AGENTS.md | 40,079 | 501 | CommandsTestingDoc pointersGit |
| MODSetter/SurfSense | AGENTS.md | 16,374 | 1,263 | CommandsTestingDoc pointersStructureGit |
| superset-sh/superset | AGENTS.md | 15,083 | 2,054 | CommandsTestingDoc pointersStructure |
| elie222/inbox-zero | AGENTS.md | 12,451 | 1,328 | CommandsTestingDoc pointersCode style |
| tambo-ai/tambo | AGENTS.md | 11,187 | 3,996 | CommandsTestingDoc pointersStructureCode styleGit |
| katanemo/plano | CLAUDE.md | 7,085 | 575 | CommandsTestingDoc pointersStructureCode style |
| ethereum/ethereum-org-website | AGENTS.md | 5,981 | 2,115 | CommandsTestingDoc pointersStructureCode style |
| vercel/eve | AGENTS.md | 5,529 | 2,036 | CommandsTestingDoc pointersStructureGit |
What Next.js projects put in them
Share of the 190 files that cover each topic, against all 641 files we read.
How they talk to the agent: 81% say “never” or “do not” somewhere (all files: 80%), 25% shout a rule in capitals like IMPORTANT or MUST (24%), and 21% tell it to ask before some changes (20%).
The tools they name
Package managerspnpm (58 files), npm (36 files), uv (25 files)
Tests and lintersPlaywright (41), Vitest (39), ESLint (36), pytest (34), Prettier (29), Biome (24)
Named more than in files generallyTailwind CSS (31), Zod (31), Redis (30), Biome (24), Turborepo (23), Vercel (20), MDX (19)
What they tell the agent
Instructions that recur across files, in our words; open one for the Next.js projects whose file says it.
About Next.js
Named as the web frontend, dashboard or docs site app inside a monorepo.13 files
Use App Router conventions.5 files
Read the Next.js docs bundled in node_modules before framework work; remembered knowledge may be outdated.4 files
Keep backend and server logic in separate packages; Next.js is only the web frontend or dashboard.4 files
About Tailwind CSS
Tailwind is the styling layer, typically paired with shadcn/ui and Radix components.10 files
Style with Tailwind utility classes as the main approach, using plain CSS only when utilities cannot express it.3 files
Tailwind v4 uses CSS-first configuration in a stylesheet.3 files
About Zod
Validate all external or untrusted input, such as requests and payloads, with Zod schemas at the boundary.7 files
Keep Zod schemas in one dedicated shared location rather than inline in pages or routers.4 files
Forms pair React Hook Form with Zod for validation.5 files
Infer TypeScript types from Zod schemas instead of declaring duplicate interfaces.3 files
About Redis
Named as the queue broker, cache or pub/sub layer, usually next to Postgres and a background worker.8 files
Start Redis through Docker Compose or a test service script before running the app or integration tests.6 files
Redis is optional: when it is unset the app falls back to in-memory caching or disables rate limits.5 files
Use Upstash Redis for serverless rate limiting and caching.2 files
About Biome
Code style such as indentation, quotes, and semicolons is dictated by the Biome config, so follow it.5 files
Run Biome through package scripts such as lint, format, check, or fix, optionally with auto-fix.3 files
Biome is used through the Ultracite preset, which sets the lint and format rules.6 files
Biome handles both linting and formatting, replacing ESLint and Prettier, so don't add those.1 files
About Turborepo
Turborepo orchestrates build, test, and lint tasks across a pnpm or Bun workspace monorepo.14 files
Asymmetric-al/coreChatbotXIO/ChatbotXactionbook/actionbookcrbnos/carbondatabuddy-analytics/Databuddydeadlock-mod-manager/deadlock-mod-managerdmno-dev/varlockever-works/ever-worksgiselles-ai/gisellellm-ring/lmringrobotostudio/turbo-start-sanitysuperserve-ai/superservethedaviddias/llms-txt-hubuptimekit/uptimekitTurborepo caching speeds up repeated typecheck, test, lint, and build runs, so rely on it.5 files
Task pipeline and cache settings live in turbo.json.3 files
Turborepo behavior varies by version, so read the docs bundled in the installed turbo package before changing config.3 files
About Vercel
Named as the hosting platform where the app deploys.5 files
Build AI features with the Vercel AI SDK.6 files
Environment variables and secrets live in the Vercel project settings.1 files
About MDX
Documentation site content is written as MDX pages, often with Fumadocs.12 files
Never hand-edit generated MDX files; update the source and regenerate them.3 files
A starting AGENTS.md for Next.js
The sections these files cover most, the package manager and checks Next.js projects name most, and the stack Next.js makers' products chose most often. Fill in the <placeholders>.
# AGENTS.md <What this product does and who it is for, in a sentence or two.> ## Stack - Frontend Framework: Next.js - Hosting: Vercel - Transactional Email: Resend - Database: Supabase - Payments: Stripe - LLM API: OpenAI API - Authentication: Clerk - Web Analytics: Google Analytics ## Commands - Install: `pnpm install` - Run locally: `<command>` - Test: `pnpm exec vitest run` - End-to-end tests: `pnpm exec playwright test` - Lint: `pnpm exec eslint .` ## Testing Run `pnpm exec vitest run` and `pnpm exec playwright test` before calling a change done, and add a test with each fix or feature. ## Project structure - `<folder>/`: <what lives there> - More in <docs/…> ## Conventions - <Naming, patterns and style the code does not show> - Commits and pull requests: <your rules> ## Boundaries - Ask before: <changes you want to approve first> - Never: <files or actions that are off-limits> <!-- Started from https://howmakersbuild.com/agents-md/nextjs — point CLAUDE.md here with a line: @AGENTS.md -->
- pnpm: named in 58 of 190 instruction files from open-source projects built with Next.js.
- Vitest: named in 39 of 190 instruction files from open-source projects built with Next.js.
- Playwright: named in 41 of 190 instruction files from open-source projects built with Next.js.
- ESLint: named in 36 of 190 instruction files from open-source projects built with Next.js.
Questions
What should an AGENTS.md for a Next.js project include?
In 190 files from open-source Next.js products: commands to build, run and test (78%), pointers to other docs (74%), testing (65%), project structure (58%), code style (55%), git, commits and pull requests (49%). The package manager they name most is pnpm (58 files).
AGENTS.md or CLAUDE.md?
Among these Next.js products, 167 keep an AGENTS.md and 133 a CLAUDE.md. Across every product we checked, 320 keep both, and in 170 of those the CLAUDE.md only points to the AGENTS.md (a symlink or a line like @AGENTS.md), so there's one file to maintain. Codex, Cursor, Copilot and others read AGENTS.md; Claude Code reads CLAUDE.md.
How long is a typical Next.js AGENTS.md?
The median is 1,033 words in these 190 files; across all 641 files we read, half are between 425 and 1,665 words.
How this is counted: the GitHub repos of open-source products built with Next.js, pushed to in the 180 days before 2026-10-12. We read each repo's AGENTS.md, CLAUDE.md and other agent files; what's published here is counts and links, not their text. All files, by the numbers.