Commit bd2383f6 authored by Jude Gao's avatar Jude Gao

[agents-md] Hard-fail `next build` the same way `next dev` does

`warnIfMissingAgentRules` collapses into a single `checkAgentRules(dir, mode)` helper shared between dev and build. Build now aborts with the same rationale-heavy fatal message and exit code 1 as dev, before any bundling work kicks off, so an agent-driven build doesn't burn minutes on artifacts the developer is about to throw away. Safe to fail hard on build because `detectAgent()` only inspects env vars set by AI coding tools — CI pipelines don't set them, so the gate never fires on a real build server, only when a developer is running `next build` from inside an agent session.

`mode` picks the lead label: `Fatal: Dev Server exited.` for dev, `Fatal: Build aborted.` for build. Both are pattern-matched by agents as terminal failures, which is exactly the framing we want.
parent 91b79650
...@@ -4,8 +4,8 @@ import { saveCpuProfile } from '../server/lib/cpu-profile' ...@@ -4,8 +4,8 @@ import { saveCpuProfile } from '../server/lib/cpu-profile'
import { existsSync } from 'fs' import { existsSync } from 'fs'
import { italic } from '../lib/picocolors' import { italic } from '../lib/picocolors'
import build from '../build' import build from '../build'
import { warn } from '../build/output/log' import { warn, error as logError } from '../build/output/log'
import { warnIfMissingAgentRules } from '../server/lib/app-info-log' import { checkAgentRules } from '../server/lib/app-info-log'
import { printAndExit } from '../server/lib/utils' import { printAndExit } from '../server/lib/utils'
import isError from '../lib/is-error' import isError from '../lib/is-error'
import { getProjectDir } from '../lib/get-project-dir' import { getProjectDir } from '../lib/get-project-dir'
...@@ -104,6 +104,19 @@ const nextBuild = async (options: NextBuildOptions, directory?: string) => { ...@@ -104,6 +104,19 @@ const nextBuild = async (options: NextBuildOptions, directory?: string) => {
printAndExit(`> No such directory exists as the project root: ${dir}`) printAndExit(`> No such directory exists as the project root: ${dir}`)
} }
// Agent-rules gate: hard-fail `next build` when an AI coding agent
// is driving the build and the managed block isn't installed in
// AGENTS.md/CLAUDE.md. Fires before any bundling work so the
// developer doesn't burn minutes on a build they're about to throw
// away. Safe to fail hard here because `detectAgent()` only
// inspects env vars set by AI coding tools — CI pipelines don't
// set them, so this gate never fires on a real build server.
const agentRulesError = checkAgentRules(dir, 'build')
if (agentRulesError !== null) {
logError(agentRulesError)
process.exit(1)
}
// Resolve selective build paths // Resolve selective build paths
let resolvedBuildPaths: { app: string[]; pages: string[] } | undefined let resolvedBuildPaths: { app: string[]; pages: string[] } | undefined
...@@ -148,15 +161,6 @@ const nextBuild = async (options: NextBuildOptions, directory?: string) => { ...@@ -148,15 +161,6 @@ const nextBuild = async (options: NextBuildOptions, directory?: string) => {
resolvedBuildPaths, resolvedBuildPaths,
enabledFeatures enabledFeatures
) )
.then((result) => {
// Fire the agent-rules warning as the very last line of `next build`
// output when an AI coding agent is driving the build. Tail-of-log
// recency means agents are much more likely to surface this than a
// warning buried early in the build pipeline. `warnIfMissingAgentRules`
// is already gated on `detectAgent()`, so humans never see it.
warnIfMissingAgentRules(dir)
return result
})
.catch((err) => { .catch((err) => {
if (experimentalDebugMemoryUsage) { if (experimentalDebugMemoryUsage) {
disableMemoryDebuggingMode() disableMemoryDebuggingMode()
......
...@@ -154,13 +154,13 @@ function hasAgentRulesInstalled(dir: string): boolean { ...@@ -154,13 +154,13 @@ function hasAgentRulesInstalled(dir: string): boolean {
} }
/** /**
* The env var an intentional user can set to bypass the dev-side * The env var an intentional user can set to bypass the agent-rules
* agent-rules hard-exit. Named with `DISABLE` rather than `SKIP` so * hard-exit. Named with `DISABLE` rather than `SKIP` so the word
* the word itself carries some behavioral friction — setting this is * itself carries some behavioral friction — setting this is a
* a deliberate acknowledgement that the dev server is running in a * deliberate acknowledgement that Next.js is running in a
* knowingly-degraded state for agent-driven workflows. * knowingly-degraded state for agent-driven workflows.
* *
* Not documented in `next dev --help` and not mentioned in any CLI * Not documented in any `--help` output and not mentioned as a CLI
* flag. The only place it's surfaced is inside the fatal error * flag. The only place it's surfaced is inside the fatal error
* message itself, framed as an explicit "strongly discouraged" escape * message itself, framed as an explicit "strongly discouraged" escape
* hatch for cases where the user genuinely can't run the codemod * hatch for cases where the user genuinely can't run the codemod
...@@ -171,34 +171,7 @@ const BYPASS_ENV_VAR = 'NEXT_DISABLE_AGENT_RULE_CHECK' ...@@ -171,34 +171,7 @@ const BYPASS_ENV_VAR = 'NEXT_DISABLE_AGENT_RULE_CHECK'
const AGENTS_MD_INSTALL_COMMAND = 'npx @next/codemod@canary upgrade agents-md' const AGENTS_MD_INSTALL_COMMAND = 'npx @next/codemod@canary upgrade agents-md'
/** /**
* Print a yellow `⚠` warning at the end of `next build` when an AI * Check the Next.js agent-rules gate for `next dev` and `next build`.
* coding agent is driving the build and the managed agent-rules block
* isn't installed. Non-fatal — the build still completes, so CI
* pipelines aren't broken. Humans never see it.
*
* The dev-side gate (`checkAgentRulesForDev` below) is fatal instead
* of a warning, because warnings attached to a successful process are
* empirically ignored by AI coding agents — the `Ready` + exit-zero
* signal dominates their categorization of the command as succeeded.
* Build is the exception only because failing the build breaks CI for
* legitimate reasons.
*/
export function warnIfMissingAgentRules(dir: string): void {
if (detectAgent() === null) return
if (hasAgentRulesInstalled(dir)) return
const command = cyan(AGENTS_MD_INSTALL_COMMAND)
Log.warn(
`Next.js detected an AI coding agent but the managed agent-rules ` +
`block is not installed in AGENTS.md or CLAUDE.md. Without the ` +
`managed block, code written for this project will be based on ` +
`outdated Next.js API knowledge and is likely to be incorrect. ` +
`Run ${command} to install it before making further code changes.`
)
}
/**
* Check the Next.js agent-rules gate for `next dev`.
* *
* Returns `null` when the caller should proceed normally: no AI * Returns `null` when the caller should proceed normally: no AI
* coding agent is driving, OR the managed agent-rules block is * coding agent is driving, OR the managed agent-rules block is
...@@ -210,8 +183,11 @@ export function warnIfMissingAgentRules(dir: string): void { ...@@ -210,8 +183,11 @@ export function warnIfMissingAgentRules(dir: string): void {
* none of the above apply. The caller should print the message and * none of the above apply. The caller should print the message and
* `process.exit(1)` — warnings attached to a successful process are * `process.exit(1)` — warnings attached to a successful process are
* empirically ignored by agents, so the only reliable way to make * empirically ignored by agents, so the only reliable way to make
* them act on this is to prevent the `Ready`/success signal from * them act on this is to prevent the success signal from firing at
* firing at all. * all. Build is safe to hard-fail alongside dev because CI
* environments don't set the env vars that `detectAgent()` inspects,
* so this gate never fires in automated pipelines — only when a
* developer is running `next build` from inside an agent session.
* *
* The message is deliberately long and rationale-heavy. Agents * The message is deliberately long and rationale-heavy. Agents
* processing tool output weigh concrete negative consequences ("will * processing tool output weigh concrete negative consequences ("will
...@@ -222,17 +198,26 @@ export function warnIfMissingAgentRules(dir: string): void { ...@@ -222,17 +198,26 @@ export function warnIfMissingAgentRules(dir: string): void {
* is disclosed, but framed as a last resort with a concrete negative * is disclosed, but framed as a last resort with a concrete negative
* consequence attached ("agents will continue producing broken code * consequence attached ("agents will continue producing broken code
* that takes more time to fix than the codemod takes to run"). * that takes more time to fix than the codemod takes to run").
*
* `mode` picks the "Fatal: X" label so the lead sentence matches the
* command the user invoked. `Dev Server exited.` and `Build aborted.`
* are both pattern-matched by agents as terminal failures, which is
* exactly the framing we want.
*/ */
export function checkAgentRulesForDev(dir: string): string | null { export function checkAgentRules(
dir: string,
mode: 'dev' | 'build'
): 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 if (process.env[BYPASS_ENV_VAR]) return null
const command = cyan(AGENTS_MD_INSTALL_COMMAND) const command = cyan(AGENTS_MD_INSTALL_COMMAND)
const bypass = cyan(`${BYPASS_ENV_VAR}=1`) const bypass = cyan(`${BYPASS_ENV_VAR}=1`)
const exitLabel = mode === 'dev' ? 'Dev Server exited.' : 'Build aborted.'
return ( return (
`Fatal: Dev Server exited. We detected you're running Next.js ` + `Fatal: ${exitLabel} We detected you're running Next.js ` +
`inside an AI coding agent but the managed agent-rules block is ` + `inside an AI coding agent but the managed agent-rules block is ` +
`not installed in AGENTS.md or CLAUDE.md.\n\n` + `not installed in AGENTS.md or CLAUDE.md.\n\n` +
`Why this matters: AI coding agents are trained on older Next.js ` + `Why this matters: AI coding agents are trained on older Next.js ` +
......
...@@ -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 {
checkAgentRulesForDev, checkAgentRules,
getEnvInfo, getEnvInfo,
logExperimentalInfo, logExperimentalInfo,
logStartInfo, logStartInfo,
...@@ -384,7 +384,7 @@ export async function startServer( ...@@ -384,7 +384,7 @@ export async function startServer(
// length and surfaces a last-resort `NEXT_DISABLE_AGENT_RULE_CHECK` // length and surfaces a last-resort `NEXT_DISABLE_AGENT_RULE_CHECK`
// env var for locked-down environments. // env var for locked-down environments.
if (isDev) { if (isDev) {
const agentRulesError = checkAgentRulesForDev(dir) const agentRulesError = checkAgentRules(dir, 'dev')
if (agentRulesError !== null) { if (agentRulesError !== null) {
Log.error(agentRulesError) Log.error(agentRulesError)
process.exit(1) 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