Skip to content
Fran Gonzalez
← Back to blog
(updated Aug 14, 2026)·Clanker·2 min read

Next.js 16.3 writes CLAUDE.md unless you commit AGENTS.md

Next.js auto-generates agent files when it detects an AI agent, but a committed AGENTS.md with its managed block stops CLAUDE.md from ever being scaffolded.

Today I Learned#nextjs#ai-agents
Some matmuls wrote this slop, sorry. My goal with this content is to document some work I (a real human bean) do while poking the Clanker, and try to learn something along the way.

Next.js ≥16.3 auto-generates AGENTS.md and CLAUDE.md in your project root when next dev detects an AI coding agent (via env vars like CLAUDECODE, AI_AGENT, PI_CODING_AGENT). The CLAUDE.md is just a pointer (@AGENTS.md) for Claude Code. If you run next dev/next build inside an agent, fresh worktrees suddenly show two untracked files.

Fact-checked against the Next.js 16.3.0 generator source and the AI Agents guide on 2026-08-15.

The tell in the generator (next/dist/server/lib/generate-agent-files.js, verified in 16.3.0): CLAUDE.md is only scaffolded when neither file exists. Once an AGENTS.md hosting the current managed block exists, the whole thing short-circuits, and on future Next bumps that update the block it upserts AGENTS.md only (claudeMd: 'skipped').

So if you use the AGENTS.md standard and don’t want a CLAUDE.md, the fix is to commit AGENTS.md with the managed block:

<!-- apps/cms/AGENTS.md -->

<!-- BEGIN:nextjs-agent-rules -->

... Next.js maintains this block ...
<!-- END:nextjs-agent-rules -->

Content outside the markers is preserved. Deleting the block instead just re-creates the uncommitted diff on the next dev run.

To opt out of both files entirely:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = { agentRules: false };
export default nextConfig;

Notes

  • Detection happens in ensureAgentRulesForDev (app-info-log.js): no agent env var → no files, so CI runs are unaffected.
  • next build in Next 16.3.0 doesn’t trigger generation; only next dev does. Our files appeared via local builds run from an agent session.
  • In monorepos the files land per Next app (e.g. apps/cms/), not the repo root.

References

This post was written with AI assistance.