Next.js 16.2 began shipping its complete documentation as Markdown inside the installed package. create-next-app also creates an AGENTS.md file telling coding agents to consult node_modules/next/dist/docs/ before they write code. In evals published by Vercel, that combination reached a 100% pass rate, while skill-based approaches peaked at 79%.
The score is striking, but the architecture behind it is more useful. The framework placed correct, local, version-matched context directly in the agent's normal path. The tool no longer depends on two fragile assumptions: that the model notices its own uncertainty and that it searches for the right source before answering.
Retrieval can fail before search begins
An on-demand skill saves context while it remains closed. That design works when the agent recognizes that it should open the skill. Many coding errors arrive without an explicit signal of uncertainty. The model knows an older API, produces a plausible answer, and moves forward. From its perspective, there is no obvious reason to research.
The problem is common in fast-moving frameworks. A convention changes between releases, an option receives new behavior, or an old pattern remains syntactically valid while no longer being the recommended route. Training knowledge does not carry the same guarantee as the package recorded in a lockfile.
The AGENTS.md produced by Next.js uses a short rule: read the relevant documentation before working. The heavier content stays in local files and is opened as the task requires. The instruction remains visible without pouring the full manual into the context window.
This separation combines availability with progressive loading. The index says where the source lives; the documents provide detail. A team does not have to copy pages into a parallel wiki or trust an internet search that may return a different release.
Version belongs in the context
Bundled documentation turns package-lock.json or another lockfile into an anchor for the agent's knowledge as well. If a project uses Next.js 16.2, the installed text describes 16.2. Updating the package updates the reference. Reverting a commit restores code and documentation to the same combination.
This matters during maintenance. An agent may work in two repositories on the same day, each with a different version. A generic search for "Next.js cache" does not automatically preserve that distinction. The path inside node_modules does.
There is an operational benefit too: work continues in network-isolated sandboxes. CI environments, restricted runners, and agents without egress can still inspect the reference. Reviewers can also record the exact source used without depending on the current state of an external website.
Documentation increases distribution size. For frameworks, the added weight is usually small beside development dependencies and the value of consistency. The calculation may differ for tiny libraries or environments that ship node_modules in constrained artifacts. Teams should measure the published package rather than treating the repository size as the deployment cost.
One eval does not establish a universal rule
The 100% result belongs to Vercel's test set and evaluated configurations. It shows that the strategy worked in that domain. It does not prove that AGENTS.md always beats skills, RAG, or MCP in every codebase.
These mechanisms solve different problems. Always-visible instructions suit short invariants: supported runtime, required checks, canonical files, and security boundaries. Local documentation suits a stable, versioned reference. Retrieval remains useful when the corpus is large, changes outside the release cycle, or depends on user identity. A skill works when a specialized procedure should consume context only during a matching task.
Treating them as exclusive competitors creates a false choice. A project can keep a small AGENTS.md that points to local docs, load a deployment skill, and query an API for current state. The architecture improves when each mechanism has one explicit role.
Applying the idea outside Next.js
A team can start without building a platform. First, list what an agent must know before any edit: runtime version, test commands, directory architecture, source of truth, and forbidden operations. Put only that index in the instruction file.
Next, keep detailed documents close to the code they describe. Give them predictable names, make them searchable, and update them in the same pull request as the implementation. When a rule needs long examples, the index should link to the file instead of repeating it.
Finally, evaluate the arrangement using real repository tasks. Measure correctness, retries, search calls, and context usage. An aggregate result from another framework supports a hypothesis; it does not replace local evidence.
Next.js also started forwarding browser errors to the terminal and introduced experimental tools for inspecting running applications. Those changes follow the same principle: put evidence where the agent already works. Context supplied before an error is cheaper than repairing code confidently written for a version the project never installed.
If your company is weighing something similar, reach me on LinkedIn or WhatsApp.
