---
id: 35
type: blog
title: "What I Learned from Writing a Next.js Guide for Agents"
slug: "what-i-learned-writing-nextjs-guide-agents"
canonical_url: "https://docs.phatysd.me/content/what-i-learned-writing-nextjs-guide-agents"
status: published
revision: 2
published_at: "2026-09-19T16:34:11.292Z"
updated_at: "2026-09-19T16:34:11.292Z"
hierarchy_path: "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
    canonical_url: "https://docs.phatysd.me/content/nextjs-16-agent-first-guide"
  - slug: "nextjs-16-caching-patterns"
    title: "Next.js 16 Caching Patterns"
    type: docs
    canonical_url: "https://docs.phatysd.me/content/nextjs-16-caching-patterns"
---

# 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:

1. What is the rule?
2. What is the smallest correct example?
3. What can go wrong?
4. 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

- [Next.js 16](https://nextjs.org/blog/next-16)
- [Next.js AI Coding Agents](https://nextjs.org/docs/app/guides/ai-agents)
- [Next.js server and client components](https://nextjs.org/docs/app/getting-started/server-and-client-components)
- [Next.js revalidating](https://nextjs.org/docs/app/getting-started/revalidating)
