Unverified Commit bd070d06 authored by Jude Gao's avatar Jude Gao Committed by GitHub

Auto-generate AGENTS.md / CLAUDE.md in next dev (#92910)

parent 8ddc1cdb
...@@ -59,9 +59,7 @@ npx create-next-app@canary --no-agents-md ...@@ -59,9 +59,7 @@ npx create-next-app@canary --no-agents-md
### Existing projects ### Existing projects
Ensure you are on Next.js `v16.2.0-canary.37` or later, then add the following files to the root of your project. On Next.js 16.3 or later, just run `next dev`. When an AI coding agent is detected in the environment and no managed block is present, Next.js auto-generates `AGENTS.md` and `CLAUDE.md` at the project root. Existing `AGENTS.md` or `CLAUDE.md` files are upserted — content outside the managed block is preserved:
`AGENTS.md` contains the instructions that agents will read:
```md filename="AGENTS.md" ```md filename="AGENTS.md"
<!-- BEGIN:nextjs-agent-rules --> <!-- BEGIN:nextjs-agent-rules -->
...@@ -73,24 +71,31 @@ This version has breaking changes — APIs, conventions, and file structure may ...@@ -73,24 +71,31 @@ This version has breaking changes — APIs, conventions, and file structure may
<!-- END:nextjs-agent-rules --> <!-- END:nextjs-agent-rules -->
``` ```
`CLAUDE.md` uses the `@` import syntax to include `AGENTS.md`, so [Claude Code](https://docs.anthropic.com/en/docs/claude-code) users get the same instructions without duplicating content:
```md filename="CLAUDE.md" ```md filename="CLAUDE.md"
@AGENTS.md @AGENTS.md
``` ```
<details> ### Opting out
<summary>For earlier versions</summary>
On version 16.1 and earlier, use the codemod to generate these files automatically: We believe leaving auto-generation on is a good default—[benchmark results on nextjs.org/evals](https://nextjs.org/evals) show agents do better when they read the bundled docs. If you really want to opt out, set `agentRules` to `false` in your config:
```bash ```ts filename="next.config.ts"
npx @next/codemod@latest agents-md import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
agentRules: false,
}
export default nextConfig
``` ```
The codemod outputs the bundled docs to `.next-docs/` in the project root instead of `node_modules/next/dist/docs/`, and the generated agent files will point to that directory. ### For earlier versions
On version 16.1 and earlier, use the legacy `agents-md` command, which downloads the docs to `.next-docs/` in the project root:
</details> ```bash
npx @next/codemod@canary agents-md
```
## Understanding AGENTS.md ## Understanding AGENTS.md
......
...@@ -429,6 +429,7 @@ export const experimentalSchema = { ...@@ -429,6 +429,7 @@ export const experimentalSchema = {
export const configSchema: zod.ZodType<NextConfig> = z.lazy(() => export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
z.strictObject({ z.strictObject({
adapterPath: z.string().optional(), adapterPath: z.string().optional(),
agentRules: z.boolean().optional(),
allowedDevOrigins: z.array(z.string()).optional(), allowedDevOrigins: z.array(z.string()).optional(),
assetPrefix: z.string().optional(), assetPrefix: z.string().optional(),
basePath: z.string().optional(), basePath: z.string().optional(),
......
...@@ -1657,6 +1657,17 @@ export interface NextConfig { ...@@ -1657,6 +1657,17 @@ export interface NextConfig {
*/ */
expireTime?: number expireTime?: number
/**
* When `next dev` detects an AI coding agent and no managed
* agent-rules block is present, Next.js auto-generates `AGENTS.md`
* and `CLAUDE.md` at the project root so the agent reads
* version-matched docs from `node_modules/next/dist/docs/` instead
* of stale training data. Set to `false` to disable this behavior.
*
* @default true
*/
agentRules?: boolean
/** /**
* Enable experimental features. Note that all experimental features are subject to breaking changes in the future. * Enable experimental features. Note that all experimental features are subject to breaking changes in the future.
*/ */
...@@ -1954,6 +1965,7 @@ export interface NextConfigRuntime { ...@@ -1954,6 +1965,7 @@ export interface NextConfigRuntime {
distDir: NextConfigComplete['distDir'] distDir: NextConfigComplete['distDir']
cacheComponents: NextConfigComplete['cacheComponents'] cacheComponents: NextConfigComplete['cacheComponents']
agentRules: NextConfigComplete['agentRules']
htmlLimitedBots: NextConfigComplete['htmlLimitedBots'] htmlLimitedBots: NextConfigComplete['htmlLimitedBots']
assetPrefix: NextConfigComplete['assetPrefix'] assetPrefix: NextConfigComplete['assetPrefix']
output: NextConfigComplete['output'] output: NextConfigComplete['output']
...@@ -2106,6 +2118,7 @@ export function getNextConfigRuntime( ...@@ -2106,6 +2118,7 @@ export function getNextConfigRuntime(
distDir: config.distDir, distDir: config.distDir,
cacheComponents: config.cacheComponents, cacheComponents: config.cacheComponents,
agentRules: config.agentRules,
htmlLimitedBots: config.htmlLimitedBots, htmlLimitedBots: config.htmlLimitedBots,
assetPrefix: config.assetPrefix, assetPrefix: config.assetPrefix,
output: config.output, output: config.output,
......
...@@ -4,6 +4,12 @@ import * as Log from '../../build/output/log' ...@@ -4,6 +4,12 @@ import * as Log from '../../build/output/log'
import { bold, purple, strikethrough } from '../../lib/picocolors' import { bold, 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 {
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 }
...@@ -113,6 +119,23 @@ export function logExperimentalInfo({ ...@@ -113,6 +119,23 @@ export function logExperimentalInfo({
Log.info('') Log.info('')
} }
/**
* 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.
*
* Callers gate this on `config.agentRules !== false` — opt-out is
* declarative in next.config, not inside this function.
*/
export function ensureAgentRulesForDev(dir: string): AgentFilesResult | null {
if (detectAgent() === null) return null
if (hasAgentRulesInstalled(dir)) return null
return writeAgentFiles(dir)
}
/** /**
* Gets environment info for logging. Fast operation that doesn't require config. * Gets environment info for logging. Fast operation that doesn't require config.
*/ */
......
/**
* 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
}
}
...@@ -22,6 +22,8 @@ export type ServerInitResult = { ...@@ -22,6 +22,8 @@ export type ServerInitResult = {
experimentalFeatures: ConfiguredExperimentalFeature[] experimentalFeatures: ConfiguredExperimentalFeature[]
// Whether cache components is enabled // Whether cache components is enabled
cacheComponents: boolean cacheComponents: boolean
// Whether AGENTS.md / CLAUDE.md auto-generation is enabled (default true)
agentRules?: boolean
} }
let initializations: Record<string, Promise<ServerInitResult> | undefined> = {} let initializations: Record<string, Promise<ServerInitResult> | undefined> = {}
......
...@@ -930,5 +930,6 @@ export async function initialize(opts: { ...@@ -930,5 +930,6 @@ export async function initialize(opts: {
distDir: config.distDir, distDir: config.distDir,
experimentalFeatures, experimentalFeatures,
cacheComponents: config.cacheComponents, cacheComponents: config.cacheComponents,
agentRules: config.agentRules,
} }
} }
...@@ -25,7 +25,12 @@ import { ...@@ -25,7 +25,12 @@ import {
CONFIG_FILES, CONFIG_FILES,
PHASE_DEVELOPMENT_SERVER, PHASE_DEVELOPMENT_SERVER,
} from '../../shared/lib/constants' } from '../../shared/lib/constants'
import { getEnvInfo, logExperimentalInfo, logStartInfo } from './app-info-log' import {
ensureAgentRulesForDev,
getEnvInfo,
logExperimentalInfo,
logStartInfo,
} from './app-info-log'
import { validateTurboNextConfig } from '../../lib/turbopack-warning' import { validateTurboNextConfig } from '../../lib/turbopack-warning'
import { import {
type Span, type Span,
...@@ -501,6 +506,31 @@ export async function startServer( ...@@ -501,6 +506,31 @@ export async function startServer(
experimentalFeatures: initResult.experimentalFeatures, experimentalFeatures: initResult.experimentalFeatures,
cacheComponents: initResult.cacheComponents, cacheComponents: initResult.cacheComponents,
}) })
// Auto-generate AGENTS.md / CLAUDE.md when an AI coding agent
// is detected but the managed agent-rules block is missing.
// Gated on `agentRules` in next.config (default true).
if (initResult.agentRules !== false) {
const result = ensureAgentRulesForDev(dir)
if (result) {
const generated: string[] = []
if (
result.agentsMd === 'created' ||
result.agentsMd === 'updated'
)
generated.push('AGENTS.md')
if (
result.claudeMd === 'created' ||
result.claudeMd === 'updated'
)
generated.push('CLAUDE.md')
if (generated.length > 0) {
Log.event(
`Generated ${generated.join(' and ')} for AI agents. Set \`agentRules: false\` in next.config to disable.`
)
}
}
}
} }
handlersReady() handlersReady()
......
// NOTE: This file duplicates the detection helper added in
// https://github.com/vercel/next.js/pull/91854 (branch: imm/agent-telemetry).
// When that PR lands, whichever branch merges second should collapse the
// duplicate — the contents are intentionally identical so the merge is a
// no-op. The env variable checks mirror the same functionality in the
// `vercel` CLI.
export type AgentName =
| 'cursor'
| 'cursor-cli'
| 'claude'
| 'cowork'
| 'devin'
| 'replit'
| 'gemini'
| 'codex'
| 'antigravity'
| 'augment-cli'
| 'opencode'
| 'github-copilot'
export function detectAgent(): AgentName | null {
if (process.env.AI_AGENT) {
const name = process.env.AI_AGENT.trim()
if (name) {
const normalized = name === 'github-copilot-cli' ? 'github-copilot' : name
return normalized as AgentName
}
}
if (process.env.CURSOR_TRACE_ID) {
return 'cursor'
}
if (process.env.CURSOR_AGENT) {
return 'cursor-cli'
}
if (process.env.GEMINI_CLI) {
return 'gemini'
}
if (
process.env.CODEX_SANDBOX ||
process.env.CODEX_CI ||
process.env.CODEX_THREAD_ID
) {
return 'codex'
}
if (process.env.ANTIGRAVITY_AGENT) {
return 'antigravity'
}
if (process.env.AUGMENT_AGENT) {
return 'augment-cli'
}
if (process.env.OPENCODE_CLIENT) {
return 'opencode'
}
if (process.env.CLAUDECODE || process.env.CLAUDE_CODE) {
if (process.env.CLAUDE_CODE_IS_COWORK) {
return 'cowork'
}
return 'claude'
}
if (process.env.REPL_ID) {
return 'replit'
}
if (
process.env.COPILOT_MODEL ||
process.env.COPILOT_ALLOW_ALL ||
process.env.COPILOT_GITHUB_TOKEN
) {
return 'github-copilot'
}
return null
}
import { nextTestSetup } from 'e2e-utils'
import fs from 'fs'
import path from 'path'
const AGENT_RULES_MARKER = '<!-- BEGIN:nextjs-agent-rules -->'
describe('agent-rules auto-generate on next dev (agent detected)', () => {
const { next } = nextTestSetup({
files: __dirname,
env: { CLAUDECODE: '1' },
})
it('creates AGENTS.md and CLAUDE.md at the project root when neither exists', async () => {
// A request is required to synchronize the test with the auto-gen
// hook — `✓ Ready in X` is logged before the config load that runs
// the hook, so `next.start()` resolves too early. `next.fetch` blocks
// on the request handler, which only becomes ready after the hook.
await next.fetch('/')
const agentsContent = fs.readFileSync(
path.join(next.testDir, 'AGENTS.md'),
'utf-8'
)
expect(agentsContent).toContain(AGENT_RULES_MARKER)
expect(agentsContent).toContain('node_modules/next/dist/docs/')
const claudeContent = fs.readFileSync(
path.join(next.testDir, 'CLAUDE.md'),
'utf-8'
)
expect(claudeContent).toBe('@AGENTS.md\n')
})
})
describe('agent-rules auto-generate on next dev (no agent)', () => {
const { next } = nextTestSetup({
files: __dirname,
// Explicitly clear every env var `detectAgent()` inspects so the
// test doesn't inherit one from the host shell (e.g. running it
// inside Claude Code would otherwise trigger generation).
env: {
AI_AGENT: '',
CURSOR_TRACE_ID: '',
CURSOR_AGENT: '',
GEMINI_CLI: '',
CODEX_SANDBOX: '',
CODEX_CI: '',
CODEX_THREAD_ID: '',
ANTIGRAVITY_AGENT: '',
AUGMENT_AGENT: '',
OPENCODE_CLIENT: '',
CLAUDECODE: '',
CLAUDE_CODE: '',
REPL_ID: '',
COPILOT_MODEL: '',
COPILOT_ALLOW_ALL: '',
COPILOT_GITHUB_TOKEN: '',
},
})
it('does not create AGENTS.md or CLAUDE.md when no agent is detected', async () => {
await next.fetch('/')
expect(fs.existsSync(path.join(next.testDir, 'AGENTS.md'))).toBe(false)
expect(fs.existsSync(path.join(next.testDir, 'CLAUDE.md'))).toBe(false)
})
})
describe('agent-rules auto-generate on next dev (agentRules: false)', () => {
const { next } = nextTestSetup({
files: __dirname,
env: { CLAUDECODE: '1' },
nextConfig: {
agentRules: false,
},
})
it('does not generate files when agentRules is disabled in next.config', async () => {
await next.fetch('/')
expect(fs.existsSync(path.join(next.testDir, 'AGENTS.md'))).toBe(false)
expect(fs.existsSync(path.join(next.testDir, 'CLAUDE.md'))).toBe(false)
})
})
describe('agent-rules auto-generate on next dev (AGENTS.md already has marker)', () => {
const { next } = nextTestSetup({
files: __dirname,
env: { CLAUDECODE: '1' },
skipStart: true,
})
beforeAll(async () => {
// Pre-populate AGENTS.md WITH the managed marker before the dev
// server starts, so the auto-gen sees it as already installed.
await next.patchFile('AGENTS.md', `${AGENT_RULES_MARKER}\n`)
await next.start()
})
it('leaves the file untouched and does not create CLAUDE.md', async () => {
await next.fetch('/')
const content = fs.readFileSync(
path.join(next.testDir, 'AGENTS.md'),
'utf-8'
)
expect(content).toBe(`${AGENT_RULES_MARKER}\n`)
expect(fs.existsSync(path.join(next.testDir, 'CLAUDE.md'))).toBe(false)
})
})
describe('agent-rules auto-generate on next dev (AGENTS.md exists without marker)', () => {
const { next } = nextTestSetup({
files: __dirname,
env: { CLAUDECODE: '1' },
skipStart: true,
})
beforeAll(async () => {
// User-authored AGENTS.md without the managed marker — auto-gen
// should upsert the block while preserving existing content.
await next.patchFile('AGENTS.md', '# Team rules\n\nUse tabs, not spaces.\n')
await next.start()
})
it('upserts the managed block and preserves existing content', async () => {
await next.fetch('/')
const content = fs.readFileSync(
path.join(next.testDir, 'AGENTS.md'),
'utf-8'
)
expect(content).toContain('Use tabs, not spaces.')
expect(content).toContain(AGENT_RULES_MARKER)
// CLAUDE.md must stay alone when AGENTS.md already exists.
expect(fs.existsSync(path.join(next.testDir, 'CLAUDE.md'))).toBe(false)
})
})
describe('agent-rules auto-generate on next dev (CLAUDE.md exists, no AGENTS.md)', () => {
const { next } = nextTestSetup({
files: __dirname,
env: { CLAUDECODE: '1' },
skipStart: true,
})
beforeAll(async () => {
await next.patchFile('CLAUDE.md', '# My rules\n\nBe concise.\n')
await next.start()
})
it('upserts into CLAUDE.md and does not create AGENTS.md', async () => {
await next.fetch('/')
const claudeContent = fs.readFileSync(
path.join(next.testDir, 'CLAUDE.md'),
'utf-8'
)
expect(claudeContent).toContain('Be concise.')
expect(claudeContent).toContain(AGENT_RULES_MARKER)
expect(fs.existsSync(path.join(next.testDir, 'AGENTS.md'))).toBe(false)
})
})
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Page() {
return <p>hello world</p>
}
...@@ -356,6 +356,7 @@ async function readNormalizedNFT(next, name) { ...@@ -356,6 +356,7 @@ async function readNormalizedNFT(next, name) {
"/node_modules/next/dist/shared/*", "/node_modules/next/dist/shared/*",
"/node_modules/next/dist/telemetry/anonymous-meta.js", "/node_modules/next/dist/telemetry/anonymous-meta.js",
"/node_modules/next/dist/telemetry/detached-flush.js", "/node_modules/next/dist/telemetry/detached-flush.js",
"/node_modules/next/dist/telemetry/detect-agent.js",
"/node_modules/next/dist/telemetry/events/build.js", "/node_modules/next/dist/telemetry/events/build.js",
"/node_modules/next/dist/telemetry/events/index.js", "/node_modules/next/dist/telemetry/events/index.js",
"/node_modules/next/dist/telemetry/events/plugins.js", "/node_modules/next/dist/telemetry/events/plugins.js",
......
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