Blog · Web Blog / Engineering Journal / Documentation
What I Learned from Writing a Next.js Guide for Agents
What I Learned from Writing a Next.js Guide for Agents
Writing a framework guide for an agent is different from writing a tutorial for a person. A person can fill in context from experience. An agent needs boundaries, evidence, commands, and failure conditions made explicit.
The Server/Client boundary is the first question
The most useful explanation was not “Server Components are faster.” It was: identify which code needs secrets, request APIs, database access, state, browser APIs, or event handlers. Keep server code server-side and put 'use client' on the smallest interactive leaf.
That rule helps an agent choose a file before it writes JSX.
Async request APIs must be visible in examples
Older Next.js examples often show synchronous params. In Next.js 16, examples need to show Promise types and await explicitly. A short example that omits this detail can teach an agent the wrong pattern and create a type error throughout a route tree.
Cache invalidation is part of the feature
Caching documentation that only explains how to cache is incomplete. Every cached query needs its freshness window, visibility scope, tag, and invalidation owner. use cache, cacheLife, cacheTag, revalidateTag, and updateTag are useful only when their relationship to mutations is explained.
Verification-first writing
The guide became more useful when each section answered:
- What is the rule?
- What is the smallest correct example?
- What can go wrong?
- Which command or URL proves the result?
This is also a debugging method. A claim like “deployment works” is weaker than a page status, a JSON contract check, a build result, and a real OAuth redirect.
Source maps build trust
Version-sensitive claims should link to the official source that owns them. Repository-specific claims should point to the code, schema, contract, or command that proves them. Recommendations should be labeled as recommendations instead of being presented as framework requirements.
The practical outcome
An agent-first guide is a small operating system for future work. It reduces guesswork, keeps changes near the correct boundary, and turns a handoff into a verifiable state rather than a confident paragraph.
References
Agent access
Choose a representation.
Both machine-readable links refer to this same published item and preserve its identity, relationships, freshness, and body.