{"id":35,"type":"blog","title":"What I Learned from Writing a Next.js Guide for Agents","slug":"what-i-learned-writing-nextjs-guide-agents","canonicalUrl":"https://docs.phatysd.me/content/what-i-learned-writing-nextjs-guide-agents","status":"published","revision":2,"publishedAt":"2026-09-19T16:34:11.292Z","updatedAt":"2026-09-19T16:34:11.292Z","hierarchyPath":"Web Blog > Engineering Journal > Documentation","topics":["Next.js 16","AI agents","Technical writing","Verification"],"tags":["nextjs","agents","documentation","verification","engineering"],"related":[{"slug":"nextjs-16-agent-first-guide","title":"Next.js 16 for Agents: A Verifiable, Production-Ready App Router Guide","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/nextjs-16-agent-first-guide"},{"slug":"nextjs-16-caching-patterns","title":"Next.js 16 Caching Patterns","type":"docs","canonicalUrl":"https://docs.phatysd.me/content/nextjs-16-caching-patterns"}],"body":"# What I Learned from Writing a Next.js Guide for Agents\n\nWriting 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.\n\n## The Server/Client boundary is the first question\n\nThe 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.\n\nThat rule helps an agent choose a file before it writes JSX.\n\n## Async request APIs must be visible in examples\n\nOlder 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.\n\n## Cache invalidation is part of the feature\n\nCaching 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.\n\n## Verification-first writing\n\nThe guide became more useful when each section answered:\n\n1. What is the rule?\n2. What is the smallest correct example?\n3. What can go wrong?\n4. Which command or URL proves the result?\n\nThis 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.\n\n## Source maps build trust\n\nVersion-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.\n\n## The practical outcome\n\nAn 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.\n\n## References\n\n- [Next.js 16](https://nextjs.org/blog/next-16)\n- [Next.js AI Coding Agents](https://nextjs.org/docs/app/guides/ai-agents)\n- [Next.js server and client components](https://nextjs.org/docs/app/getting-started/server-and-client-components)\n- [Next.js revalidating](https://nextjs.org/docs/app/getting-started/revalidating)\n"}