fix(docs): stop next dev writing untracked AGENTS.md / CLAUDE.md into apps/docs

[claude]

Fixes#10249

What

Sets agentRules: false in apps/docs/next.config.mjs.

next dev (Next 16.3.1) calls ensureAgentRulesForDev on boot and, whenever
@vercel/detect-agent reports an AI coding agent, scaffolds apps/docs/AGENTS.md and
apps/docs/CLAUDE.md. Neither path is tracked or ignored, so both land as ?? and any
git add -A after booting the docs server sweeps them into an unrelated PR.

Those two filenames are load-bearing in this repo: the root AGENTS.md is the binding
playbook and agents are told to read the AGENTS.md governing the files they touch. A
Next-authored stub pointing at node_modules/next/dist/docs/ can be read as this repo's
discipline, and the generated text argues for committing itself, which nudges an agent the
wrong way. The generated CLAUDE.md is the single line @AGENTS.md — an import directive
that pulls the stub in.

Why disable rather than ignore

Turned off at the source instead of adding a .gitignore entry, and this is a deliberate
choice rather than a cost comparison. An ignore rule for apps/docs/AGENTS.md would
silently swallow a future repo-authoredAGENTS.md for the docs app, and that failure
would be invisible at exactly the moment someone was trying to add real guidance there. A
visible untracked file is a better failure than an invisibly ignored one for this filename
specifically. The reasoning is recorded in the config comment so the next reader does not
re-litigate it.

Evidence

Measured in a dedicated worktree off origin/main @ 01c50322a1. The detector was
confirmed live in this shell first — determineAgent() returns
{"isAgent":true,"agent":{"name":"claude-code_2-1-238_agent"}} — so a clean tree after the
fix cannot be a false negative caused by non-detection.

Baseline, all four checks from the issue, in a checkout that had not run next dev:

check	result
git ls-files apps/docs | grep -iE 'AGENTS|CLAUDE'	exit 1 — nothing tracked
git check-ignore -v apps/docs/AGENTS.md apps/docs/CLAUDE.md	exit 1 — not ignored
grep -n agentRules apps/docs/next.config.mjs	exit 1 — not set
ls apps/docs/AGENTS.md apps/docs/CLAUDE.md	neither file exists

Boot 1 — base config, both files absent, port 31249:

✓ Ready in 530ms
✓ Generated AGENTS.md and CLAUDE.md for AI agents. Set `agentRules: false` in next.config to disable.
GET /docs 200 in 48s

$ git status --porcelain
?? apps/docs/AGENTS.md
?? apps/docs/CLAUDE.md

Boot 2 — with agentRules: false, both files deleted first so the run starts from the
same state, port 31250:

✓ Ready in 417ms
GET /docs 200 in 11.8s (220754 bytes)
GET / 200 in 628ms

$ git status --porcelain
M apps/docs/next.config.mjs
$ ls apps/docs/AGENTS.md apps/docs/CLAUDE.md
ls: cannot access 'apps/docs/AGENTS.md': No such file or directory
ls: cannot access 'apps/docs/CLAUDE.md': No such file or directory

No Generated ... line, no new files. Deleting the two files before boot 2 is the load-bearing
part of the control: ensureAgentRulesForDev also returns early when the current block is
already present, so leaving them in place would have produced a clean tree whether or not the
flag worked.

The server still starts and serves after the config change — Ready in 417ms, /docs and /
both HTTP 200, and /docs returned 220754 bytes, byte-identical in size to the pre-fix boot.
Next's zod config schema accepts the key (agentRules: z.boolean().optional()), and
✓ Running next.config.mjs took 282ms confirms the config parsed with no validation warning.

Residue

agentRules: false stops future generation; it does not delete copies from a checkout that
already ran next dev. No cleanup script: the affected population is small, self-limiting and
already visible as ??, and once this lands the files are never rewritten, so removing them
once is permanent. Handled with a sentence in the config comment naming the one command
(rm -f apps/docs/AGENTS.md apps/docs/CLAUDE.md), which is where someone asking "why do I have
these files" will be reading. No copies exist anywhere in the container this was built in.

Gates

Derived with node scripts/pm/dispatch-gates.mjs from the real change set (it reads the merge
base itself), re-run after the final commit at d2c46c1c2d. Exit codes captured before any
pipe; verdict lines are each gate's own output.

gate	exit	verdict
pnpm check:test-source-alias	0	check-test-source-alias OK — 72 packages with tests scanned
pnpm check:type-source-resolution	0	check-type-source-resolution OK — 76 packages with a tsconfig.json scanned
pnpm check:nul-bytes	0	check-nul-bytes: OK (scanned 6237 text file(s) -- 6237 tracked, 0 untracked-not-ignored ...)

The first two are the families dispatch-gates matched for apps/docs/next.config.mjs
(both via gate source apps/*); check:nul-bytes is run because the diff touches a text file.

No changeset

A dev-server config flag publishes nothing — no package behaviour changes for any consumer.
Labelled skip-changeset.

---

Generated by Claude Code