I was reviewing a Next.js application in a worktree that already had a few unrelated changes. Before touching anything, I checked the status. After running the browser tests, I checked it again.

Two new files had appeared:

apps/web/AGENTS.md
apps/web/CLAUDE.md

My first suspicion was obvious: the coding agent had written instructions for itself. That would have been impolite, but at least easy to explain.

The timestamps pointed somewhere else. Both files had been created while the test setup started the development server. The culprit was not the agent. It was Next.js.

What Next.js generated

The generated CLAUDE.md contained one line:

@AGENTS.md

AGENTS.md contained a managed block that warned agents that this version of Next.js might differ from their training data. It instructed them to read the bundled guides under node_modules/next/dist/docs/ before changing code.

The most useful sentence was also the strangest one to find in an automatically generated repository file:

This block is written and re-added by `next dev`.

That was not boilerplate getting ahead of itself. It described the implementation accurately.

The generator hiding in node_modules

The source is shipped in the Next.js package at:

node_modules/next/dist/server/lib/generate-agent-files.js

In Next.js 16.3.2, the development server checks whether it appears to be running in the presence of a supported coding agent. If it detects one and agent rules are enabled, it calls the generator.

The generator handles a few cases:

  • If neither file exists, it creates AGENTS.md and CLAUDE.md.
  • If AGENTS.md already exists, it adds or refreshes a marked, managed block.
  • If the managed block is removed, a later next dev run can add it again.
  • CLAUDE.md points Claude-compatible tools at the same instructions.

The behavior is enabled by default. The startup code even has a log message explaining the opt-out:

Set `agentRules: false` in next.config to disable.

I had missed that message because the development server was started as a child process by the browser test runner. The new files were much louder than the log line.

How to stop it

If generated agent instructions do not belong in your repository, disable the feature explicitly:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  agentRules: false,
};

export default nextConfig;

If you already have other Next.js settings, add the property to the existing object.

Deleting the files without changing the configuration is not a fix. It only resets the scene for the next development run. Ignoring the files in Git hides the status noise, but the instructions still exist on disk and can still affect tools working below that directory.

Keeping them is also a legitimate choice. The generated warning is practical: framework conventions change, and the documentation installed with the exact dependency version is often more reliable than recalled examples. What matters is making the choice deliberately.

Why this surprised me

Development servers already write caches, build output, type declarations, and lock files. This felt different for two reasons.

First, the generated file is not merely output. AGENTS.md is input to coding tools. Its location gives it scope over the application directory, so creating it can change how later work is performed.

Second, Next.js will modify an existing instruction file by maintaining its own marked section. That is considerate compared with replacing the file, but it still means a development command mutates a human-maintained repository document.

There is a sensible product idea underneath it. An agent working against a fast-moving framework should consult version-matched documentation. The surprising part is the delivery mechanism: persistent files appear in the project based on runtime detection of the development environment.

The debugging habit worth keeping

The fix took minutes once I stopped treating the files as mysterious agent behavior and traced the process that existed at their creation time.

The useful sequence was:

  1. Compare repository status before and after the command.
  2. Check file timestamps against the process timeline.
  3. Search the installed dependency for a distinctive sentence from the generated file.
  4. Read the call site, not just the generator, to find the configuration gate.

That last step matters. Finding code that writes a file explains what happened. Finding the caller explains when it happens and how to control it.

If AGENTS.md or CLAUDE.md suddenly appears after a Next.js upgrade, your assistant may be innocent. Check next dev before starting the interrogation.