Next.js: What Running Every Play at Once Looks Like

The lesson: Next.js doesn't just publish agent docs. It takes over the agent's whole working environment. Docs ship inside the npm package. AGENTS.md and CLAUDE.md get written by default at scaffold time. Markdown is served to any non-browser fetcher. There's even a public benchmark. Anyone can copy the mechanics. But the #1 position also rests on a training-data head start that you can't copy.

At a glance

What they built

Next.js goes all in. It's the only product we found running a serious version of every play at once. It wins all four stages: found, selected, obeyed, and installed.

The instruction layer rides inside the environment layer. The generated rules file counter-programs the model's own memory:

"Your training data is outdated. The docs are the source of truth." AGENTS.md / CLAUDE.md generated by default by create-next-app (per nextjs.org/docs/app/guides/ai-agents, observed 2026-06-11)

That sentence goes into every new project by default. It's the whole strategy in one line. The #1 product in agent training data tells agents not to trust their training data, then points them at surfaces Next.js controls.

The content negotiation is the gold standard of the retrieval layer. Most products that serve markdown make the agent know the .md convention. Next.js detects the non-browser fetcher and serves markdown at the canonical URL. No convention to guess. No empty bodies. Full content to a plain HTTP GET.

The npm-package move closes the loop from the other side. The docs sit in node_modules before the agent's first network call. An agent working in a Next.js project has current reference material on disk, matched to the installed version. That means no retrieval latency and no fetch failures.

All figures observed 2026-06-11; single-day Context7 snapshot, ±10% error bars (we watched one product's snippet count read 130 and 207 on the same day).

The ranking. /vercel/next.js: 10.97% of all Context7 library traffic. That's #1, vs 4.59% for #2 (Better Auth) and 2.57% for React's docs. 30-day momentum: +16%.

The cluster. Vercel-ecosystem entries in the same top 50:

Roughly one in five agent doc fetches lands on a Vercel-ecosystem surface. No other org in the data comes close.

The index entry. 587,985 tokens, 2,550 snippets, trust 10, benchmark 84.9, updated 1 day. That's a high quality score on a moderate corpus. It fits our audit-wide finding that corpus mass buys little (log-tokens vs benchmark ρ≈0.30, n=17, correlational). Next.js wins on density and freshness, not volume.

The fetch test. In our markdown probes, Next.js served complete markdown to a non-browser HTTP client on canonical URLs without the .md suffix. It was the only product in the audit doing user-agent content negotiation. It's the model for the "Fetchable" property in our agent-grade docs definition (report §7).

The environment default. create-next-app writes AGENTS.md + CLAUDE.md by default, not behind a flag. That move made scaffolder injection a category norm. Our pilot E1 (single model, n=3 per arm, 2026-06-11) measured the generic rules-file mechanism at a 100% selection flip (3/3 vs 0/3). Next.js installs that mechanism in every new project, plus a codemod for old ones.

The public benchmark. nextjs.org/evals publishes how well models and agents perform on Next.js tasks. It's one of only two public agent-eval boards we found among audited products (Convex's llm-leaderboard is the other).

What to copy

• Stamp versions into your llms.txt (@doc-version) and ship per-version files plus llms-full.txt (Play 5).
• Put machine-readable frontmatter (url, version, lastUpdated, prerequisites) on every .md mirror (Play 6).
• Implement content negotiation: detect non-browser fetchers and serve markdown at canonical URLs. This is the gold standard for agent fetch (Play 1, Play 6).
• Ship docs inside your package so agents have current reference material with zero network calls (Play 6).
• Write AGENTS.md + CLAUDE.md at scaffold time, with a retrofit codemod for existing repos. Disclose it and follow the ethics rules (Play 9).
• Publish an agent benchmark for your product once the internal eval harness exists (Play 11).

What NOT to over-copy

• Maximum training-data head start. Next.js is everywhere in every model's memory. Its #1 retrieval share sits on top of a default position most products start without. You can copy the mechanics above. You can't copy the head start.
• The ecosystem cluster. About 18.5% of all retrieval flows to Vercel-ecosystem surfaces. The AI SDK, hosting platform, and framework all promote one another's agent surfaces. A standalone product can copy the plays, but not the gravity.
• Resourcing. Content negotiation, an in-package docs pipeline, a maintained codemod, a framework MCP, and a public eval board take a platform team. For everyone else, the order is: index and mirrors first, scaffolder and evals later (see the playbook overview).
• Point-in-time, one index. All numbers are a 2026-06-11 Context7 snapshot with ±10% error bars. Retrieval share is a flow metric that moves in weeks (another top-10 entry fell −50% in the same 30 days).
• "By default" carries obligations. People accepted default injection from Next.js without visible backlash. But the move that drew sustained anger, an undisclosed insertion with no opt-out, is one design decision away (Play 9's ethics box).

FAQ

Why is Next.js the #1 documentation source for AI agents? Two things matter. It carries the largest training-data head start in its category. It also runs the most complete agent surface we audited: versioned llms.txt, content negotiation to markdown, docs inside the npm package, default AGENTS.md/CLAUDE.md at scaffold time, a framework MCP, and a public benchmark. As of 2026-06-11 it held 10.97% of all Context7 retrieval, more than double #2.

Does create-next-app really write CLAUDE.md by default? Yes. As of 2026-06-11, create-next-app writes AGENTS.md and CLAUDE.md by default. They contain "Your training data is outdated. The docs are the source of truth" (nextjs.org/docs/app/guides/ai-agents). Existing projects can be retrofitted with npx @next/codemod agents-md.

What is content negotiation for AI agents? It means serving different versions of the same URL based on the client. Browsers get HTML. Non-browser fetchers get markdown, at the canonical URL, with no .md suffix needed. Next.js was the only audited product doing this. It's the gold standard because agents get full content without knowing any convention.

---

Snapshot date 2026-06-11; single-day metrics carry ±10% error bars. Part of Case Studies · The Complete Playbook to Agentic Discovery.

Stay ahead of the agents. We re-test this playbook quarterly and publish what changed: new data, busted myths, ranking shifts. Get the update digest →

Want this done for you? Synscribe runs agentic-discovery programs for B2B SaaS and developer platforms. Talk to us →