Executive Summary
Next.js announced findings from a study comparing methods for providing version-specific framework knowledge to AI coding agents. The research revealed that embedding a compressed documentation index directly into a project's `AGENTS.md` file is significantly more effective than using the on-demand "Skills" approach. This passive context method achieved a 100% pass rate in tests by ensuring the agent always has access to accurate API information, solving the problem of AI generating code based on outdated training data. A new codemod has been released to automate this setup for developers.
Key Takeaways
* Core Finding: A static, compressed documentation index in `AGENTS.md` (passive context) vastly outperforms on-demand "Skills" (active retrieval) for guiding AI coding agents.
* Performance Metrics: The `AGENTS.md` method achieved a 100% pass rate on a hardened evaluation suite for Next.js 16 APIs. In contrast, "Skills" only reached a 79% pass rate with explicit instructions and performed no better than having no documentation (53%) without them.
* The Solution: The method involves adding a compressed (8KB) index of the project's specific Next.js documentation version into the `AGENTS.md` file. This tells the agent where to find relevant local documentation files without bloating the context window.
* Problem Solved: This approach prevents AI agents from relying on outdated training data and generating code using incorrect or non-existent APIs for a project's specific framework version.
* Availability: The feature is available immediately via an official codemod. Developers can run `npx @next/codemod@canary agents-md` to automatically detect their Next.js version, download matching docs, and inject the index into `AGENTS.md`.
Strategic Importance
This announcement establishes a simple yet powerful best practice for making software frameworks compatible and reliable with AI coding agents. It provides a direct solution to a critical issue in AI-assisted development, improving the developer experience and giving Next.js an edge in AI-native tooling.