[PR #604] [MERGED] docs: strengthen Next.js parity verification in agent guidelines #705

New issue

Closed

opened 2026-05-06 13:09:40 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 13:09:40 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/vinext/pull/604
Author: @southpolesteve
Created: 3/20/2026
Status: ✅ Merged
Merged: 3/20/2026
Merged by: @southpolesteve

Base: main ← Head: docs/strengthen-nextjs-parity-checks

📝 Commits (1)

56b1649 docs: strengthen Next.js parity verification in agent guidelines

📊 Changes

2 files changed (+68 additions, -2 deletions)

View changed files

📝 .gitignore (+3 -0)
📝 AGENTS.md (+65 -2)

📄 Description

Summary

Strengthens the AGENTS.md guidelines to prevent shipping fixes that diverge from Next.js behavior.

Motivation

During recent security remediation work, we repeatedly shipped fixes that didn't match Next.js behavior:

Changed config header has/missing evaluation to use post-middleware context, when Next.js evaluates them pre-middleware (headers run before middleware)
Added javascript: URI blocking to router.push(), when Next.js intentionally does not block these (developer responsibility, documented in their docs)
Added query params to ISR route handler cache keys, when Next.js handles this differently (dynamic detection skips caching entirely)

In each case, the fix was written and PRed before discovering the divergence. The verification step happened too late.

Changes

Local Next.js clone (.nextjs-ref/, gitignored): instructions for cloning and searching the Next.js repo locally with ripgrep, much faster and more reliable than gh search code
Mandatory verification for bug fixes: 4-step checklist (search tests, search issues/PRs, search source, document findings) added to the Fixing Bugs section
Document what Next.js does: require linking to Next.js tests/issues/docs when creating PRs or closing issues
Explicit permission to diverge: if vinext should differ from Next.js, that's OK, but it must be deliberate and documented

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/vinext/pull/604 **Author:** [@southpolesteve](https://github.com/southpolesteve) **Created:** 3/20/2026 **Status:** ✅ Merged **Merged:** 3/20/2026 **Merged by:** [@southpolesteve](https://github.com/southpolesteve) **Base:** `main` ← **Head:** `docs/strengthen-nextjs-parity-checks` --- ### 📝 Commits (1) - [`56b1649`](https://github.com/cloudflare/vinext/commit/56b1649e4d20968c74a90050fed174bbd9243c33) docs: strengthen Next.js parity verification in agent guidelines ### 📊 Changes **2 files changed** (+68 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `.gitignore` (+3 -0) 📝 `AGENTS.md` (+65 -2) </details> ### 📄 Description ## Summary Strengthens the AGENTS.md guidelines to prevent shipping fixes that diverge from Next.js behavior. ## Motivation During recent security remediation work, we repeatedly shipped fixes that didn't match Next.js behavior: - Changed config header has/missing evaluation to use post-middleware context, when Next.js evaluates them pre-middleware (headers run before middleware) - Added javascript: URI blocking to router.push(), when Next.js intentionally does not block these (developer responsibility, documented in their docs) - Added query params to ISR route handler cache keys, when Next.js handles this differently (dynamic detection skips caching entirely) In each case, the fix was written and PRed before discovering the divergence. The verification step happened too late. ## Changes - **Local Next.js clone** (`.nextjs-ref/`, gitignored): instructions for cloning and searching the Next.js repo locally with ripgrep, much faster and more reliable than `gh search code` - **Mandatory verification for bug fixes**: 4-step checklist (search tests, search issues/PRs, search source, document findings) added to the Fixing Bugs section - **Document what Next.js does**: require linking to Next.js tests/issues/docs when creating PRs or closing issues - **Explicit permission to diverge**: if vinext should differ from Next.js, that's OK, but it must be deliberate and documented --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>