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 fs from 'fs'
import os from 'os' import os from 'os'
import path from 'path' import path from 'path'
import { ensureAgentRulesForDev } from './app-info-log' import { checkAgentRulesForDev } from './app-info-log'
const AGENT_RULES_MARKER = '<!-- BEGIN:nextjs-agent-rules -->' const AGENT_RULES_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
...@@ -25,14 +25,18 @@ function clearAgentEnv() { ...@@ -25,14 +25,18 @@ function clearAgentEnv() {
delete process.env.COPILOT_MODEL delete process.env.COPILOT_MODEL
delete process.env.COPILOT_ALLOW_ALL delete process.env.COPILOT_ALLOW_ALL
delete process.env.COPILOT_GITHUB_TOKEN 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 tmpDir: string
let originalEnv: NodeJS.ProcessEnv let originalEnv: NodeJS.ProcessEnv
beforeEach(() => { beforeEach(() => {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-rules-dev-')) 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"}') fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name": "fixture"}')
originalEnv = { ...process.env } originalEnv = { ...process.env }
clearAgentEnv() clearAgentEnv()
...@@ -44,99 +48,108 @@ describe('ensureAgentRulesForDev (auto-generate agent files)', () => { ...@@ -44,99 +48,108 @@ describe('ensureAgentRulesForDev (auto-generate agent files)', () => {
}) })
it('returns null when no agent is detected', () => { 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' process.env.CLAUDECODE = '1'
fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), `${AGENT_RULES_MARKER}\n`) 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' process.env.CLAUDECODE = '1'
fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), `${AGENT_RULES_MARKER}\n`) 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' process.env.CLAUDECODE = '1'
const result = ensureAgentRulesForDev(tmpDir) process.env.NEXT_DISABLE_AGENT_RULE_CHECK = '1'
// Neither AGENTS.md nor CLAUDE.md exists — but the bypass env var
expect(result).not.toBeNull() // is set, so the gate must respect it and stay silent.
expect(result!.agentsMd).toBe('created') expect(checkAgentRulesForDev(tmpDir)).toBeNull()
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')
}) })
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' process.env.CLAUDECODE = '1'
fs.writeFileSync( fs.writeFileSync(
path.join(tmpDir, 'AGENTS.md'), path.join(tmpDir, 'AGENTS.md'),
'# Team rules\n\nUse tabs, not spaces.\n' '# Team rules\n\nUse tabs, not spaces.\n'
) )
expect(checkAgentRulesForDev(tmpDir)).not.toBeNull()
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)
}) })
it('only checks the Next.js project directory — a marker in an ancestor does not count', () => { 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' process.env.CLAUDECODE = '1'
const appDir = path.join(tmpDir, 'apps', 'web') const appDir = path.join(tmpDir, 'apps', 'web')
fs.mkdirSync(appDir, { recursive: true }) fs.mkdirSync(appDir, { recursive: true })
fs.writeFileSync(path.join(appDir, 'package.json'), '{"name": "web"}') 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`) fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), `${AGENT_RULES_MARKER}\n`)
const result = ensureAgentRulesForDev(appDir) expect(checkAgentRulesForDev(appDir)).not.toBeNull()
expect(result).not.toBeNull()
expect(result!.agentsMd).toBe('created')
}) })
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' process.env.CLAUDECODE = '1'
const appDir = path.join(tmpDir, 'apps', 'web') const appDir = path.join(tmpDir, 'apps', 'web')
fs.mkdirSync(appDir, { recursive: true }) fs.mkdirSync(appDir, { recursive: true })
fs.writeFileSync(path.join(appDir, 'package.json'), '{"name": "web"}') fs.writeFileSync(path.join(appDir, 'package.json'), '{"name": "web"}')
fs.writeFileSync(path.join(appDir, 'AGENTS.md'), `${AGENT_RULES_MARKER}\n`) 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 { loadEnvConfig } from '@next/env'
import fs from 'fs'
import * as inspector from 'inspector' import * as inspector from 'inspector'
import path from 'path'
import * as Log from '../../build/output/log' 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 type { ConfiguredExperimentalFeature } from '../config'
import { experimentalSchema } from '../config-schema' import { experimentalSchema } from '../config-schema'
import { detectAgent } from '../../telemetry/detect-agent' import { detectAgent } from '../../telemetry/detect-agent'
import {
hasAgentRulesInstalled,
writeAgentFiles,
type AgentFilesResult,
} from './generate-agent-files'
// Re-export the type for consumers // Re-export the type for consumers
export type { ConfiguredExperimentalFeature } export type { ConfiguredExperimentalFeature }
...@@ -120,17 +117,80 @@ export function logExperimentalInfo({ ...@@ -120,17 +117,80 @@ export function logExperimentalInfo({
} }
/** /**
* When `next dev` detects an AI coding agent but the managed * Keep in sync with the marker written by `create-next-app` in
* agent-rules block is missing from AGENTS.md / CLAUDE.md, * packages/create-next-app/helpers/generate-agent-files.ts and with the
* auto-generate the files so the agent has access to version-matched * codemod in packages/next-codemod/lib/agents-md.ts.
* docs. Returns the write result when files were generated, or `null`
* when no action was needed.
*/ */
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 (detectAgent() === null) return null
if (hasAgentRulesInstalled(dir)) 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 { ...@@ -27,7 +27,7 @@ import {
PHASE_DEVELOPMENT_SERVER, PHASE_DEVELOPMENT_SERVER,
} from '../../shared/lib/constants' } from '../../shared/lib/constants'
import { import {
ensureAgentRulesForDev, checkAgentRulesForDev,
getEnvInfo, getEnvInfo,
logExperimentalInfo, logExperimentalInfo,
logStartInfo, logStartInfo,
...@@ -374,29 +374,20 @@ export async function startServer( ...@@ -374,29 +374,20 @@ export async function startServer(
// Get env info first (fast, doesn't require config) // Get env info first (fast, doesn't require config)
const envInfo = isDev ? getEnvInfo(dir) : undefined const envInfo = isDev ? getEnvInfo(dir) : undefined
// Auto-generate AGENTS.md / CLAUDE.md when an AI coding agent // Agent-rules gate: hard-fail dev startup when an AI coding
// is detected but the managed agent-rules block is missing. // 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) { if (isDev) {
const agentFilesResult = ensureAgentRulesForDev(dir) const agentRulesError = checkAgentRulesForDev(dir)
if (agentFilesResult) { if (agentRulesError !== null) {
const generated: string[] = [] Log.error(agentRulesError)
if ( process.exit(1)
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`
)
}
} }
} }
......
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