chore(site): ignore the AGENTS.md/CLAUDE.md that next dev mints, and turn the minting off at the source (#4160)

[yinlianghui]

Fixes #4160

Running the docs site left two untracked files behind that were neither committed nor gitignored, and whose own generated text asks the reader to commit them. This lands the direction the card settled on: ignore, don't commit — plus the upstream opt-out, so the files stop being written at all.

Reproduced on this branch's base

$ pnpm exec next dev -p 4610       # in apps/site
▲ Next.js 16.3.0 (Turbopack)
✓ Ready in 555ms
✓ Generated AGENTS.md and CLAUDE.md for AI agents. Set `agentRules: false` in next.config to disable.

$ git status --short
?? apps/site/AGENTS.md
?? apps/site/CLAUDE.md

$ git check-ignore -v apps/site/AGENTS.md apps/site/CLAUDE.md
(no output, exit 1 — neither is ignored)

apps/site/CLAUDE.md is one line, @AGENTS.md. The generated apps/site/AGENTS.md carries the managed block, which ends:

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

That last sentence is what makes this a live trap rather than noise: a file that appears from merely running the app, is invisible to git check-ignore, and tells its reader that committing it is the tidy move — in a repo where parallel agents stage with git add -A. Same shape as objectui#3430.

Trigger, and why now

next dev calls ensureAgentRulesForDev (next/dist/server/lib/app-info-log.js), which asks @vercel/detect-agent whether an AI coding agent is driving the session — it keys on environment variables including CLAUDECODE, CLAUDE_CODE, CURSOR, CODEX_THREAD_ID, GEMINI_CLI and AI_AGENT, all true for the agents that work this repo — and then writes both files beside the app's next.config.

It is new with the #4094 bump. Next's own bundled guide (node_modules/next/dist/docs/01-app/02-guides/ai-agents.md) says so directly:

On version 16.2, the docs are bundled but AGENTS.md is not auto-generated.

So 16.2.12 minted nothing and 16.3.0 does; the premise is current, not expired.

An upstream opt-out exists, so this uses both belts

The call site is gated: if (initResult.agentRules !== false). agentRules is a documented top-level config key (agentRules?: boolean, default true), declared in next's config schema, and the dev server itself names it in the message above.

1. agentRules: false in apps/site/next.config.mjs — stops the write at the source instead of hiding it.
2. Both paths gitignored — repo root .gitignore (next to the existing apps/site/.next / .map.ts / .source block) and apps/site/.gitignore (next to next-env.d.ts). Those two files are ignored in both places today, so this matches the placement the repo already uses for this app's dev-time artifacts.

Half 2 is not redundant with half 1: agentRules is upstream-owned and can be renamed or dropped by any bump — and next validates config against a strict object where an unknown key only warns at startup, so losing the flag would be silent. Other entry points (create-next-app, @next/codemod agents-md) write the same files too.

Committing them was rejected for the reason the card gives: the block is minted per next version, and apps/site/CLAUDE.md being a bare @AGENTS.md import would splice framework-owned prose into this repo's own binding instruction chain.

Exposure sweep

apps/site is the only workspace member that runs Next.js — it is the sole package.json in the repo declaring next (packages/components declares next-themes, which is unrelated). apps/console is Vite; examples/* contains no Next.js app. No other exposed path.

Pin

scripts/__tests__/site-next-agent-files-4160.test.ts (8 cases) holds both halves, and — because the filenames are upstream literals — does not treat its own list as the source of truth:

• each minted path is git-ignored, and is not tracked (pinning the "ignore, not commit" decision itself);
• next.config.mjs still sets agentRules: false;
• the generator module still exists, and every .md filename literal read back out of the installed next is covered by the ignore — so a bump that renames AGENTS.md or adds a third file goes red instead of silently re-exposing the trap;
• next still declares agentRules in its config schema — the drift that would otherwise turn the opt-out into a warning nobody reads.

Verification

pnpm exec vitest run scripts/                 → 31 files, 586 tests passed
pnpm run type-check:scripts                   → exit 0
pnpm --filter @object-ui/site lint            → 0 errors (7 pre-existing warnings in playground/page.tsx)
node scripts/check-control-bytes.mjs          → OK (3848 tracked text files)
node scripts/check-doc-links.mjs              → Links are valid across 7 scan roots
node scripts/check-lint-coverage.mjs          → 45/45 packages linted
node scripts/check-changeset-presence.mjs     → "No source of a released package changed in this range, so no changeset is owed"

Dev server after the change, with the site's dependency closure built (pnpm --filter '@object-ui/site^...' build):

▲ Next.js 16.3.0 (Turbopack)  ✓ Ready in 550ms
✓ Running next.config.mjs took 382ms          # no "Generated AGENTS.md" line, no invalid-config warning
GET /     -> 200
GET /docs -> 200
$ git status --short                          # empty after a full dev run

Reverse verification — the two halves fail differently, which is the point

Directions predicted before running. Removals done with git checkout origin/main -- path, never git stash.

• Ignore entries removed (flag kept): 3 of 8 cases go red — both is gitignored cases and the upstream-derived ignores every filename the installed next actually writes.
• agentRules: false removed (ignore kept): the config case goes red, and a real next dev run mints both files again — but the tree stays clean, which is the ignore half doing its job in isolation:

✓ Generated AGENTS.md and CLAUDE.md for AI agents.
$ ls apps/site/AGENTS.md apps/site/CLAUDE.md   # both present on disk
$ git status --short
M  apps/site/next.config.mjs                   # only the deliberate revert; no ?? entries
$ git add -A --dry-run                         # stages nothing

• The mirror case is deliberately reported rather than forced into a red: with the ignore removed and the flag kept, nothing observable regresses — next dev mints nothing, so the tree looks fine right up until the flag stops working. That silence is exactly why the ignore is pinned here instead of left for a dev-server run to notice.

Notes

• No changeset: .gitignore, a private app's config and a scripts test change no released package's src/; the presence script arbitrates and says none is owed (output above).
• No skip-changeset label — decorative in this repo (objectui#3724).
• content/docs/releases/ untouched.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 10, 2026 3:32pm