Skip to content

[AI] Ship bundled docs in next and generate AGENTS.md in create-next-app#89850

Merged
timneutkens merged 2 commits intocanaryfrom
create-next-app/agents-md
Feb 11, 2026
Merged

[AI] Ship bundled docs in next and generate AGENTS.md in create-next-app#89850
timneutkens merged 2 commits intocanaryfrom
create-next-app/agents-md

Conversation

@gaojude
Copy link
Contributor

@gaojude gaojude commented Feb 11, 2026 •
edited
Loading

AI coding agents often rely on outdated training data when working with Next.js projects, leading to hallucinated APIs and deprecated patterns. This PR addresses that by shipping version-matched documentation inside the next npm package and generating agent instruction files during create-next-app.

During next build, a new copy_docs task copies docs/ from the repo root into dist/docs/. Since "dist" is already in the package's files array, the docs are automatically published at node_modules/next/dist/docs/.

create-next-app gains a new --agents-md / --no-agents-md flag (defaults to true). When enabled it writes two files:

  • AGENTS.md — instructs agents to read node_modules/next/dist/docs/ instead of relying on training data
  • CLAUDE.md — uses @AGENTS.md import syntax for Claude Code

The option appears in the recommended defaults display and is prompted during the customize flow. Existing tests are updated with --no-agents-md to avoid the new prompt.

@nextjs-bot nextjs-bot added create-next-app Related to our CLI tool for quickly starting a new Next.js application. created-by: Next.js team PRs by the Next.js team. tests type: next labels Feb 11, 2026
@nextjs-bot
Copy link
Collaborator

nextjs-bot commented Feb 11, 2026 •
edited
Loading

Tests Passed

@gaojude gaojude changed the title [create-next-app] Generate AGENTS.md and CLAUDE.md for AI coding assistants [AI] Ship bundled docs in next and generate AGENTS.md in create-next-app Feb 11, 2026
@nextjs-bot
Copy link
Collaborator

nextjs-bot commented Feb 11, 2026

Stats from current PR

🔴 1 regression

Metric Canary PR Change Trend
node_modules Size 467 MB 472 MB 🔴 +4.87 MB (+1%) ▁▁▁▁▁
📊 All Metrics
📖 Metrics Glossary

Dev Server Metrics:

  • Listen = TCP port starts accepting connections
  • First Request = HTTP server returns successful response
  • Cold = Fresh build (no cache)
  • Warm = With cached build artifacts

Build Metrics:

  • Fresh = Clean build (no .next directory)
  • Cached = With existing .next directory

Change Thresholds:

  • Time: Changes < 50ms AND < 10%, OR < 2% are insignificant
  • Size: Changes < 1KB AND < 1% are insignificant
  • All other changes are flagged to catch regressions

⚡ Dev Server

Metric Canary PR Change Trend
Cold (Listen) 455ms 456ms ✓ ▁▁▁▁▁
Cold (Ready in log) 439ms 439ms ✓ ▆▅▂▆▅
Cold (First Request) 1.150s 1.185s ✓ ██▁██
Warm (Listen) 456ms 456ms ✓ ▁▁▁▁▁
Warm (Ready in log) 444ms 443ms ✓ ▁▁▂▁▁
Warm (First Request) 335ms 332ms ✓ ▁▅▅▅▅
📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric Canary PR Change Trend
Cold (Listen) 557ms 558ms ✓ ▁▁▅▁▁
Cold (Ready in log) 514ms 516ms ✓ ▃▄▅▃▄
Cold (First Request) 2.195s 2.202s ✓ ▂▃▆▁▂
Warm (Listen) 559ms 558ms ✓ ▁▁▅▁▁
Warm (Ready in log) 518ms 516ms ✓ ▃▃▅▃▃
Warm (First Request) 2.231s 2.233s ✓ ▂▃▅▂▂

⚡ Production Builds

Metric Canary PR Change Trend
Fresh Build 3.826s 3.792s ✓ ▁▁▃▁▁
Cached Build 3.836s 3.808s ✓ ▁▁▃▁▁
📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric Canary PR Change Trend
Fresh Build 16.734s 16.794s ✓ ▂▃▅▁▁
Cached Build 16.878s 16.933s ✓ ▂▃▅▁▁
node_modules Size 467 MB 472 MB 🔴 +4.87 MB (+1%) ▁▁▁▁▁
📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **437 kB** → **437 kB** ⚠️ +8 B

81 files with content-based hashes (individual files not comparable between builds)

Server

Middleware
Canary PR Change
middleware-b..fest.js gzip 758 B 757 B ✓
Total 758 B 757 B ✅ -1 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 451 B 449 B ✓
Total 451 B 449 B ✅ -2 B

📦 Webpack

Client

Main Bundles
Canary PR Change
5528-HASH.js gzip 5.47 kB N/A -
6280-HASH.js gzip 57 kB N/A -
6335.HASH.js gzip 169 B N/A -
912-HASH.js gzip 4.53 kB N/A -
e8aec2e4-HASH.js gzip 62.5 kB N/A -
framework-HASH.js gzip 59.7 kB 59.7 kB ✓
main-app-HASH.js gzip 256 B 254 B ✓
main-HASH.js gzip 39.1 kB 39.1 kB ✓
webpack-HASH.js gzip 1.68 kB 1.68 kB ✓
262-HASH.js gzip N/A 4.53 kB -
2889.HASH.js gzip N/A 169 B -
5602-HASH.js gzip N/A 5.49 kB -
6948ada0-HASH.js gzip N/A 62.5 kB -
9544-HASH.js gzip N/A 57.7 kB -
Total 230 kB 231 kB ⚠️ +630 B
Polyfills
Canary PR Change
polyfills-HASH.js gzip 39.4 kB 39.4 kB ✓
Total 39.4 kB 39.4 kB ✓
Pages
Canary PR Change
_app-HASH.js gzip 194 B 194 B ✓
_error-HASH.js gzip 183 B 180 B 🟢 3 B (-2%)
css-HASH.js gzip 331 B 330 B ✓
dynamic-HASH.js gzip 1.81 kB 1.81 kB ✓
edge-ssr-HASH.js gzip 256 B 256 B ✓
head-HASH.js gzip 351 B 352 B ✓
hooks-HASH.js gzip 384 B 383 B ✓
image-HASH.js gzip 580 B 581 B ✓
index-HASH.js gzip 260 B 260 B ✓
link-HASH.js gzip 2.49 kB 2.49 kB ✓
routerDirect..HASH.js gzip 320 B 319 B ✓
script-HASH.js gzip 386 B 386 B ✓
withRouter-HASH.js gzip 315 B 315 B ✓
1afbb74e6ecf..834.css gzip 106 B 106 B ✓
Total 7.97 kB 7.97 kB ✅ -1 B

Server

Edge SSR
Canary PR Change
edge-ssr.js gzip 126 kB 126 kB ✓
page.js gzip 249 kB 250 kB ✓
Total 375 kB 376 kB ⚠️ +392 B
Middleware
Canary PR Change
middleware-b..fest.js gzip 613 B 614 B ✓
middleware-r..fest.js gzip 156 B 155 B ✓
middleware.js gzip 33 kB 33.2 kB ✓
edge-runtime..pack.js gzip 842 B 842 B ✓
Total 34.6 kB 34.8 kB ⚠️ +205 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 733 B 735 B ✓
Total 733 B 735 B ⚠️ +2 B
Build Cache
Canary PR Change
0.pack gzip 3.84 MB 3.85 MB 🔴 +10.5 kB (+0%)
index.pack gzip 104 kB 104 kB ✓
index.pack.old gzip 103 kB 103 kB ✓
Total 4.05 MB 4.06 MB ⚠️ +9.86 kB

🔄 Shared (bundler-independent)

Runtimes
Canary PR Change
app-page-exp...dev.js gzip 316 kB 316 kB ✓
app-page-exp..prod.js gzip 168 kB 168 kB ✓
app-page-tur...dev.js gzip 315 kB 315 kB ✓
app-page-tur..prod.js gzip 167 kB 167 kB ✓
app-page-tur...dev.js gzip 312 kB 312 kB ✓
app-page-tur..prod.js gzip 166 kB 166 kB ✓
app-page.run...dev.js gzip 312 kB 312 kB ✓
app-page.run..prod.js gzip 166 kB 166 kB ✓
app-route-ex...dev.js gzip 70.5 kB 70.5 kB ✓
app-route-ex..prod.js gzip 49 kB 49 kB ✓
app-route-tu...dev.js gzip 70.5 kB 70.5 kB ✓
app-route-tu..prod.js gzip 49 kB 49 kB ✓
app-route-tu...dev.js gzip 70.1 kB 70.1 kB ✓
app-route-tu..prod.js gzip 48.8 kB 48.8 kB ✓
app-route.ru...dev.js gzip 70.1 kB 70.1 kB ✓
app-route.ru..prod.js gzip 48.8 kB 48.8 kB ✓
dist_client_...dev.js gzip 324 B 324 B ✓
dist_client_...dev.js gzip 326 B 326 B ✓
dist_client_...dev.js gzip 318 B 318 B ✓
dist_client_...dev.js gzip 317 B 317 B ✓
pages-api-tu...dev.js gzip 43.2 kB 43.2 kB ✓
pages-api-tu..prod.js gzip 32.9 kB 32.9 kB ✓
pages-api.ru...dev.js gzip 43.2 kB 43.2 kB ✓
pages-api.ru..prod.js gzip 32.8 kB 32.8 kB ✓
pages-turbo....dev.js gzip 52.5 kB 52.5 kB ✓
pages-turbo...prod.js gzip 39.4 kB 39.4 kB ✓
pages.runtim...dev.js gzip 52.5 kB 52.5 kB ✓
pages.runtim..prod.js gzip 39.4 kB 39.4 kB ✓
server.runti..prod.js gzip 62.7 kB 62.7 kB ✓
Total 2.8 MB 2.8 MB ✅ -1 B

@gaojude gaojude requested a review from timneutkens February 11, 2026 20:26
@gaojude gaojude marked this pull request as ready for review February 11, 2026 20:42
timneutkens
timneutkens approved these changes Feb 11, 2026
View reviewed changes
Copy link
Member

@timneutkens timneutkens left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔥

@timneutkens timneutkens merged commit b9ec2e4 into canary Feb 11, 2026
160 checks passed
@timneutkens timneutkens deleted the create-next-app/agents-md branch February 11, 2026 20:50
@gaojude gaojude mentioned this pull request Feb 13, 2026
Merged
gaojude added a commit that referenced this pull request Feb 16, 2026
@gaojude
[Docs] Add AGENTS.md and bundled docs guide (#89973)
104f0db 
Adds a guide for configuring AI coding agents to use the version-matched
documentation bundled in `node_modules/next/dist/docs/` (shipped via the
`copy_docs` build task in #89850) instead of stale training data.

The guide covers how the bundled docs work, the `AGENTS.md` and
`CLAUDE.md` files generated by `create-next-app --agents-md`, and how to
add project-specific instructions outside the `<!--
BEGIN:nextjs-agent-rules -->` markers.
icyJoseph pushed a commit that referenced this pull request Feb 18, 2026
@gaojude @icyJoseph
[Docs] Add AGENTS.md and bundled docs guide (#89973)
75cf0ba 
Adds a guide for configuring AI coding agents to use the version-matched
documentation bundled in `node_modules/next/dist/docs/` (shipped via the
`copy_docs` build task in #89850) instead of stale training data.

The guide covers how the bundled docs work, the `AGENTS.md` and
`CLAUDE.md` files generated by `create-next-app --agents-md`, and how to
add project-specific instructions outside the `<!--
BEGIN:nextjs-agent-rules -->` markers.
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Feb 26, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@timneutkens timneutkens timneutkens approved these changes

Assignees

No one assigned

Labels

create-next-app Related to our CLI tool for quickly starting a new Next.js application. created-by: Next.js team PRs by the Next.js team. locked tests type: next

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@gaojude @nextjs-bot @timneutkens