Commit 83e515c8 authored by Jude Gao's avatar Jude Gao

Revert "[agents-md] Auto-generate agent files in next dev instead of fatal codemod gate"

This reverts commit c2933977.
parent 6c12a0f8
import fs from 'fs'
import os from 'os'
import path from 'path'
import { ensureAgentRulesForDev } from './app-info-log'
import { checkAgentRulesForDev } from './app-info-log'
const AGENT_RULES_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
......@@ -25,14 +25,18 @@ function clearAgentEnv() {
delete process.env.COPILOT_MODEL
delete process.env.COPILOT_ALLOW_ALL
delete process.env.COPILOT_GITHUB_TOKEN
delete process.env.NEXT_DISABLE_AGENT_RULE_CHECK
}
describe('ensureAgentRulesForDev (auto-generate agent files)', () => {
describe('checkAgentRulesForDev (dev-side fatal gate)', () => {
let tmpDir: string
let originalEnv: NodeJS.ProcessEnv
beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-rules-dev-'))
// `package.json` at the fixture root defines the Next.js project
// root the gate anchors on. `next dev` resolves this via
// `getProjectDir` before calling the gate.
fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "fixture"}')
originalEnv = { ...process.env }
clearAgentEnv()
......@@ -44,99 +48,108 @@ describe('ensureAgentRulesForDev (auto-generate agent files)', () => {
})
it('returns null when no agent is detected', () => {
expect(ensureAgentRulesForDev(tmpDir)).toBeNull()
expect(checkAgentRulesForDev(tmpDir)).toBeNull()
})
it('returns null when the managed block is already in AGENTS.md', () => {
it('returns null when the managed block is installed in AGENTS.md', () => {
process.env.CLAUDECODE = '1'
fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), `${AGENT_RULES_MARKER}\n`)
expect(ensureAgentRulesForDev(tmpDir)).toBeNull()
expect(checkAgentRulesForDev(tmpDir)).toBeNull()
})
it('returns null when the managed block is already in CLAUDE.md', () => {
it('returns null when the managed block is installed in CLAUDE.md', () => {
process.env.CLAUDECODE = '1'
fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), `${AGENT_RULES_MARKER}\n`)
expect(ensureAgentRulesForDev(tmpDir)).toBeNull()
expect(checkAgentRulesForDev(tmpDir)).toBeNull()
})
it('creates both AGENTS.md and CLAUDE.md when neither exists', () => {
it('returns null when NEXT_DISABLE_AGENT_RULE_CHECK is set', () => {
process.env.CLAUDECODE = '1'
const result = ensureAgentRulesForDev(tmpDir)
expect(result).not.toBeNull()
expect(result!.agentsMd).toBe('created')
expect(result!.claudeMd).toBe('created')
const agentsContent = fs.readFileSync(
path.join(tmpDir, 'AGENTS.md'),
'utf-8'
)
expect(agentsContent).toContain(AGENT_RULES_MARKER)
expect(agentsContent).toContain('node_modules/next/dist/docs/')
const claudeContent = fs.readFileSync(
path.join(tmpDir, 'CLAUDE.md'),
'utf-8'
)
expect(claudeContent).toBe('@AGENTS.md\n')
process.env.NEXT_DISABLE_AGENT_RULE_CHECK = '1'
// Neither AGENTS.md nor CLAUDE.md exists — but the bypass env var
// is set, so the gate must respect it and stay silent.
expect(checkAgentRulesForDev(tmpDir)).toBeNull()
})
it('upserts into existing AGENTS.md without the marker', () => {
it('fires when AGENTS.md exists without the managed block', () => {
// File existence alone isn't enough — we care specifically about
// the Next.js directive, so a custom AGENTS.md without the marker
// still counts as "not installed".
process.env.CLAUDECODE = '1'
fs.writeFileSync(
path.join(tmpDir, 'AGENTS.md'),
'# Team rules\n\nUse tabs, not spaces.\n'
)
const result = ensureAgentRulesForDev(tmpDir)
expect(result).not.toBeNull()
expect(result!.agentsMd).toBe('updated')
expect(result!.claudeMd).toBe('skipped')
const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8')
expect(content).toContain('Use tabs, not spaces.')
expect(content).toContain(AGENT_RULES_MARKER)
})
it('upserts into existing CLAUDE.md when AGENTS.md does not exist', () => {
process.env.CLAUDECODE = '1'
fs.writeFileSync(
path.join(tmpDir, 'CLAUDE.md'),
'# My rules\n\nBe concise.\n'
)
const result = ensureAgentRulesForDev(tmpDir)
expect(result).not.toBeNull()
expect(result!.agentsMd).toBe('skipped')
expect(result!.claudeMd).toBe('updated')
const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8')
expect(content).toContain('Be concise.')
expect(content).toContain(AGENT_RULES_MARKER)
expect(checkAgentRulesForDev(tmpDir)).not.toBeNull()
})
it('only checks the Next.js project directory — a marker in an ancestor does not count', () => {
// The gate is strictly anchored on `dir` (the Next.js project
// directory). A marker dropped at a parent directory is
// irrelevant: AI agents read agent-rules files from the package
// they're working in, not from some ancestor. In a monorepo this
// means the marker must live in the app sub-package, never at
// the monorepo root.
process.env.CLAUDECODE = '1'
const appDir = path.join(tmpDir, 'apps', 'web')
fs.mkdirSync(appDir, { recursive: true })
fs.writeFileSync(path.join(appDir, 'package.json'), '{"name": "web"}')
// Marker at the monorepo root — wrong place for apps/web/
// Marker at the monorepo root — wrong place for an `apps/web/`
// invocation.
fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), `${AGENT_RULES_MARKER}\n`)
const result = ensureAgentRulesForDev(appDir)
expect(result).not.toBeNull()
expect(result!.agentsMd).toBe('created')
expect(checkAgentRulesForDev(appDir)).not.toBeNull()
})
it('respects the marker when it is in the sub-package', () => {
it('respects the marker when it is in the sub-package, not the monorepo root', () => {
// Same monorepo layout, but the marker is now in the sub-package
// (where it belongs). The gate must find it.
process.env.CLAUDECODE = '1'
const appDir = path.join(tmpDir, 'apps', 'web')
fs.mkdirSync(appDir, { recursive: true })
fs.writeFileSync(path.join(appDir, 'package.json'), '{"name": "web"}')
fs.writeFileSync(path.join(appDir, 'AGENTS.md'), `${AGENT_RULES_MARKER}\n`)
expect(ensureAgentRulesForDev(appDir)).toBeNull()
expect(checkAgentRulesForDev(appDir)).toBeNull()
})
it('fires with a `Fatal: Dev Server exited.`-prefixed rationale message', () => {
process.env.CLAUDECODE = '1'
const message = checkAgentRulesForDev(tmpDir)
expect(message).not.toBeNull()
// Leads with title-cased `Fatal: Dev Server exited.` — the
// caller will `process.exit(1)` right after, and this wording
// makes it clear in the log that the process terminated
// intentionally.
expect(message!.startsWith('Fatal: Dev Server exited.')).toBe(true)
// States the cause.
expect(message).toContain('AI coding agent')
expect(message).toContain('AGENTS.md')
expect(message).toContain('CLAUDE.md')
// Explains WHY the rules matter in concrete terms. These
// specific phrases are what agents weigh heavily when deciding
// whether to take the codemod path vs the escape path — losing
// any of them significantly weakens the discouragement.
expect(message).toContain('trained on older Next.js versions')
expect(message).toContain('breaking changes')
expect(message).toContain('deprecated APIs')
expect(message).toContain('outdated patterns')
expect(message).toContain('fail at runtime')
// Primary fix — the codemod command.
expect(message).toContain('npx @next/codemod@canary upgrade agents-md')
// Escape hatch — disclosed as an env var (not a CLI flag, since
// agents grab CLI flags more readily), and explicitly framed as
// "Strongly discouraged" with a concrete negative consequence
// attached.
expect(message).toContain('NEXT_DISABLE_AGENT_RULE_CHECK=1')
expect(message).toContain('Strongly discouraged')
expect(message).toContain('last-resort')
expect(message).toContain('far more time than the codemod takes to run')
})
})
import { loadEnvConfig } from '@next/env'
import fs from 'fs'
import * as inspector from 'inspector'
import path from 'path'
import * as Log from '../../build/output/log'
import { bold, purple, strikethrough } from '../../lib/picocolors'
import { bold, cyan, purple, strikethrough } from '../../lib/picocolors'
import type { ConfiguredExperimentalFeature } from '../config'
import { experimentalSchema } from '../config-schema'
import { detectAgent } from '../../telemetry/detect-agent'
import {
hasAgentRulesInstalled,
writeAgentFiles,
type AgentFilesResult,
} from './generate-agent-files'
// Re-export the type for consumers
export type { ConfiguredExperimentalFeature }
......@@ -120,17 +117,80 @@ export function logExperimentalInfo({
}
/**
* When `next dev` detects an AI coding agent but the managed
* agent-rules block is missing from AGENTS.md / CLAUDE.md,
* auto-generate the files so the agent has access to version-matched
* docs. Returns the write result when files were generated, or `null`
* when no action was needed.
* Keep in sync with the marker written by `create-next-app` in
* packages/create-next-app/helpers/generate-agent-files.ts and with the
* codemod in packages/next-codemod/lib/agents-md.ts.
*/
export function ensureAgentRulesForDev(dir: string): AgentFilesResult | null {
const AGENT_RULES_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
function tryReadFile(filePath: string): string | null {
try {
return fs.readFileSync(filePath, 'utf-8')
} catch {
return null
}
}
/**
* Returns true when `AGENTS.md` or `CLAUDE.md` at `dir` contains the
* managed agent-rules marker. `dir` is the Next.js project directory
* (the package.json level) — the same location `upgrade agents-md`
* writes to, so check and codemod stay anchored together.
*/
function hasAgentRulesInstalled(dir: string): boolean {
const agentsMdContents = tryReadFile(path.join(dir, 'AGENTS.md'))
if (agentsMdContents?.includes(AGENT_RULES_MARKER)) return true
const claudeMdContents = tryReadFile(path.join(dir, 'CLAUDE.md'))
if (claudeMdContents?.includes(AGENT_RULES_MARKER)) return true
return false
}
/**
* Escape hatch for the agent-rules hard-exit. Disclosed only inside
* the fatal message itself (not in `--help`) and framed as "strongly
* discouraged" so agents don't grab it off surface area.
*/
const BYPASS_ENV_VAR = 'NEXT_DISABLE_AGENT_RULE_CHECK'
const AGENTS_MD_INSTALL_COMMAND = 'npx @next/codemod@canary upgrade agents-md'
/**
* Returns a fatal message string when `next dev` should exit instead
* of starting — AI coding agent detected, managed block missing, and
* no bypass env var set. Returns `null` when the caller should
* proceed. The caller prints and `process.exit(1)`; anything short
* of a non-zero exit is empirically ignored by agents.
*
* Message length is deliberate: concrete negative consequences and a
* last-resort bypass with stick framing are what actually move agent
* behavior, validated against live Claude Code.
*/
export function checkAgentRulesForDev(dir: string): string | null {
if (detectAgent() === null) return null
if (hasAgentRulesInstalled(dir)) return null
if (process.env[BYPASS_ENV_VAR]) return null
return writeAgentFiles(dir)
const command = cyan(AGENTS_MD_INSTALL_COMMAND)
const bypass = cyan(`${BYPASS_ENV_VAR}=1`)
return (
`Fatal: Dev Server exited. We detected you're running Next.js ` +
`inside an AI coding agent but the managed agent-rules block is ` +
`not installed in AGENTS.md or CLAUDE.md.\n\n` +
`Why this matters: AI coding agents are trained on older Next.js ` +
`versions and don't know about breaking changes, deprecated APIs, ` +
`or new features in your installed version. Without the managed ` +
`block pointing them at the version-matched docs bundled with ` +
`your install, they will write code using outdated patterns that ` +
`fail at runtime or are silently incorrect.\n\n` +
`Run ${command} to install it.\n\n` +
`As a last-resort escape hatch, setting ${bypass} bypasses this ` +
`check. Strongly discouraged — agents will still produce broken ` +
`code, and fixing that will cost far more time than the codemod ` +
`takes to run.`
)
}
/**
......
/**
* Auto-generate AGENTS.md / CLAUDE.md with the managed Next.js agent-rules
* block when `next dev` detects an AI coding agent but the block is missing.
*
* Keep the marker and block content in sync with:
* - packages/create-next-app/helpers/generate-agent-files.ts
* - packages/next-codemod/lib/agents-md.ts
*/
import fs from 'fs'
import path from 'path'
export const AGENT_RULES_START_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
export const AGENT_RULES_END_MARKER = '<!-- END:nextjs-agent-rules -->'
/**
* Markers written by the pre-bundled-docs version of `agents-md`.
* Stripped on upsert so projects that ran the old codemod end up with
* a single current block instead of two stale-and-current blocks.
*/
const LEGACY_AGENT_RULES_START_MARKER = '<!-- NEXT-AGENTS-MD-START -->'
const LEGACY_AGENT_RULES_END_MARKER = '<!-- NEXT-AGENTS-MD-END -->'
function buildAgentRulesBlock(): string {
return `${AGENT_RULES_START_MARKER}
# This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in \`node_modules/next/dist/docs/\` before writing any code. Heed deprecation notices.
${AGENT_RULES_END_MARKER}`
}
const CLAUDE_MD_CONTENT = `@AGENTS.md\n`
export type AgentFileAction = 'created' | 'updated' | 'unchanged' | 'skipped'
export interface AgentFilesResult {
agentsMd: AgentFileAction
claudeMd: AgentFileAction
}
/**
* Returns true when `AGENTS.md` or `CLAUDE.md` at `dir` contains the
* managed agent-rules marker.
*/
export function hasAgentRulesInstalled(dir: string): boolean {
const agentsContent = tryReadFile(path.join(dir, 'AGENTS.md'))
if (agentsContent?.includes(AGENT_RULES_START_MARKER)) return true
const claudeContent = tryReadFile(path.join(dir, 'CLAUDE.md'))
if (claudeContent?.includes(AGENT_RULES_START_MARKER)) return true
return false
}
/**
* Write the agent-rules block into `projectDir`, respecting whichever
* file the user already uses:
*
* - `AGENTS.md` exists → upsert into it, leave `CLAUDE.md` alone.
* - `CLAUDE.md` exists (but not `AGENTS.md`) → upsert into it.
* - Neither exists → create both (`AGENTS.md` + `CLAUDE.md` with
* `@AGENTS.md` import), matching `create-next-app`.
*
* Idempotent: a file already containing the canonical block is
* reported as `unchanged`.
*/
export function writeAgentFiles(projectDir: string): AgentFilesResult {
const agentsMdPath = path.join(projectDir, 'AGENTS.md')
const claudeMdPath = path.join(projectDir, 'CLAUDE.md')
const block = buildAgentRulesBlock()
const agentsMdExists = fs.existsSync(agentsMdPath)
const claudeMdExists = fs.existsSync(claudeMdPath)
if (agentsMdExists) {
return {
agentsMd: upsertFile(agentsMdPath, block),
claudeMd: 'skipped',
}
}
if (claudeMdExists) {
return {
agentsMd: 'skipped',
claudeMd: upsertFile(claudeMdPath, block),
}
}
// Neither file exists — scaffold both, matching create-next-app.
fs.writeFileSync(agentsMdPath, block + '\n', 'utf-8')
fs.writeFileSync(claudeMdPath, CLAUDE_MD_CONTENT, 'utf-8')
return { agentsMd: 'created', claudeMd: 'created' }
}
// ---------------------------------------------------------------------------
// Internal helpers
// ---------------------------------------------------------------------------
function tryReadFile(filePath: string): string | null {
try {
return fs.readFileSync(filePath, 'utf-8')
} catch {
return null
}
}
function upsertFile(filePath: string, block: string): AgentFileAction {
const existing = fs.readFileSync(filePath, 'utf-8')
const updated = upsertAgentRulesBlock(existing, block)
if (updated === existing) return 'unchanged'
fs.writeFileSync(filePath, updated, 'utf-8')
return 'updated'
}
/**
* Detect the predominant line-ending style. Returns `'\r\n'` if any
* CRLF is present, `'\n'` otherwise — avoids mixed EOLs on Windows.
*/
function detectEol(content: string): '\r\n' | '\n' {
return /\r\n/.test(content) ? '\r\n' : '\n'
}
function normalizeEol(s: string, eol: '\r\n' | '\n'): string {
return s.replace(/\r?\n/g, eol)
}
function upsertAgentRulesBlock(existing: string, block: string): string {
const eol = detectEol(existing)
const normalizedBlock = normalizeEol(block, eol)
existing = stripLegacyAgentRulesBlock(existing, eol)
const startIdx = existing.indexOf(AGENT_RULES_START_MARKER)
const endIdx = existing.indexOf(AGENT_RULES_END_MARKER)
if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
const before = existing.slice(0, startIdx)
const after = existing.slice(endIdx + AGENT_RULES_END_MARKER.length)
const replaced = before + normalizedBlock + after
return replaced === existing ? existing : replaced
}
const separator =
existing.length === 0 || /\r?\n$/.test(existing) ? eol : eol + eol
return existing + separator + normalizedBlock + eol
}
function stripLegacyAgentRulesBlock(
existing: string,
eol: '\r\n' | '\n' = '\n'
): string {
while (true) {
const startIdx = existing.indexOf(LEGACY_AGENT_RULES_START_MARKER)
if (startIdx === -1) return existing
const endIdx = existing.indexOf(LEGACY_AGENT_RULES_END_MARKER, startIdx)
if (endIdx === -1) return existing
let cutStart = startIdx
while (cutStart > 0 && /\s/.test(existing[cutStart - 1])) {
cutStart--
}
let cutEnd = endIdx + LEGACY_AGENT_RULES_END_MARKER.length
while (cutEnd < existing.length && /\s/.test(existing[cutEnd])) {
cutEnd++
}
const before = existing.slice(0, cutStart)
const after = existing.slice(cutEnd)
existing =
before.length > 0 && after.length > 0
? before + eol + eol + after
: before + after
}
}
......@@ -27,7 +27,7 @@ import {
PHASE_DEVELOPMENT_SERVER,
} from '../../shared/lib/constants'
import {
ensureAgentRulesForDev,
checkAgentRulesForDev,
getEnvInfo,
logExperimentalInfo,
logStartInfo,
......@@ -374,29 +374,20 @@ export async function startServer(
// Get env info first (fast, doesn't require config)
const envInfo = isDev ? getEnvInfo(dir) : undefined
// Auto-generate AGENTS.md / CLAUDE.md when an AI coding agent
// is detected but the managed agent-rules block is missing.
// Agent-rules gate: hard-fail dev startup when an AI coding
// agent is driving but the managed block isn't installed in
// AGENTS.md/CLAUDE.md. Fires BEFORE the banner and Ready line so
// we never print a success signal the agent could latch onto —
// a non-zero exit is the only signal empirically strong enough
// to override agents' "Ready + exit 0 = succeeded" pattern
// match. The error message itself explains the rationale at
// length and surfaces a last-resort `NEXT_DISABLE_AGENT_RULE_CHECK`
// env var for locked-down environments.
if (isDev) {
const agentFilesResult = ensureAgentRulesForDev(dir)
if (agentFilesResult) {
const generated: string[] = []
if (
agentFilesResult.agentsMd === 'created' ||
agentFilesResult.agentsMd === 'updated'
) {
generated.push('AGENTS.md')
}
if (
agentFilesResult.claudeMd === 'created' ||
agentFilesResult.claudeMd === 'updated'
) {
generated.push('CLAUDE.md')
}
if (generated.length > 0) {
Log.info(
`Generated ${generated.join(' and ')} with Next.js agent rules`
)
}
const agentRulesError = checkAgentRulesForDev(dir)
if (agentRulesError !== null) {
Log.error(agentRulesError)
process.exit(1)
}
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment