feat(next-codemod): add agents-md command for AI coding agents #88961
+1,019
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Adds a new `agents-md` subcommand to @next/codemod that generates a Next.js documentation index for AI coding agents (Claude, Cursor, etc.). Usage: - `npx @next/codemod agents-md` (interactive) - `npx @next/codemod agents-md --version 15.1.0 --output CLAUDE.md` The command: 1. Downloads Next.js docs from GitHub via git sparse-checkout 2. Builds a compact index of all doc files grouped by directory 3. Injects the index into CLAUDE.md or AGENTS.md between marker comments 4. Adds .next-docs to .gitignore This helps AI agents prefer local documentation over pre-trained knowledge, ensuring answers match the project's Next.js version.
Collaborator
Failing test suitesCommit: ba11280 | About building and testing Next.js
Expand output● segment cache (refresh) › router.refresh() refreshes both cached and dynamic data ● segment cache (refresh) › Server Action refresh() refreshes dynamic data only, not cached |
Collaborator
Stats from current PR✅ No significant changes detected📊 All Metrics📖 Metrics GlossaryDev Server Metrics:
Build Metrics:
Change Thresholds:
⚡ Dev Server
📦 Dev Server (Webpack) (Legacy)📦 Dev Server (Webpack)
⚡ Production Builds
📦 Production Builds (Webpack) (Legacy)📦 Production Builds (Webpack)
📦 Bundle SizesBundle Sizes⚡ TurbopackClient Main Bundles: **432 kB** → **432 kB** ✅ -58 B82 files with content-based hashes (individual files not comparable between builds) Server Middleware
Build DetailsBuild Manifests
📦 WebpackClient Main Bundles
Polyfills
Pages
Server Edge SSR
Middleware
Build DetailsBuild Manifests
Build Cache
🔄 Shared (bundler-independent)Runtimes
|
timneutkens
approved these changes
Jan 23, 2026
Add tests for the core pure functions in agents-md: - injectIntoClaudeMd: marker injection, idempotency, content preservation - buildDocTree: hierarchical grouping, nested subsections, sorting
fz6m
reviewed
Jan 25, 2026
| return sortedSections | ||
| } | ||
|
|
||
| export interface ClaudeMdIndexData { |
There was a problem hiding this comment.
Why all interfaces exported from this file?
This is usually an anti pattern.
Are we intentionally expecting deep path imports like import type { ClaudeMdIndexData } from 'next-codemod/lib/agents-md' ?
Contributor
Author
There was a problem hiding this comment.
good catch this was never meant to be used outside removing the export in a follow up PR thanks for flagging
4 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new
agents-mdsubcommand to@next/codemodthat generates a Next.js documentation index for AI coding agents (Claude, Cursor, GitHub Copilot, etc.).Usage
What it does
.next-docs/(via git sparse-checkout)CLAUDE.mdorAGENTS.mdbetween marker comments.next-docs/to.gitignoreThe index helps AI agents prefer local documentation over pre-trained knowledge, ensuring answers match your Next.js version.
Options
--version <version>package.jsonif not provided)--output <file>CLAUDE.md,AGENTS.md)Output format
The generated index is a single line with pipe separators:
Test plan
--versionand--output--outputonly.gitignoreis updatedEval results
Tested against 19 Next.js-specific agent evals with 100% pass rate:
Legend: ✅✅✅ = Build/Lint/Test