`next dev` generates apps/site/AGENTS.md and apps/site/CLAUDE.md, which are neither committed nor gitignored

[yinlianghui]

Out-of-scope finding from #4149, where the PR needed to run the docs site to verify a documented port.

What happens

Running the command QUICK_REFERENCE.md documents for the docs site:

$ pnpm --filter @object-ui/site dev
▲ Next.js 16.3.0 (Turbopack)
- Local: http://localhost:3000
✓ Ready in 684ms

leaves two new files behind:

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

Neither is tracked, and git check-ignore returns nothing for either — they are not in .gitignore. apps/site/CLAUDE.md is one line (@AGENTS.md); apps/site/AGENTS.md is a Next.js-authored block that names its own generator:

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.

So Next.js expects one of two end states: the files are committed, or they are ignored. This repo is in neither.

Why it is worth a card rather than a shrug

Several agents work this repo in parallel worktrees, and git add -A is a common way to stage. Two untracked files that appear from running the app — not from editing anything — are exactly the shape that gets swept into an unrelated PR by an author who never opened them. The generated text actively encourages that ("committing it with your work keeps the tree clean"), which makes the accident feel like the correct move at the moment it happens.

It also collides with an existing convention: this repo's AGENTS.md / CLAUDE.md are hand-written instruction files that agents are told to treat as binding. A generated apps/site/AGENTS.md carrying Next.js framework rules appears in the same namespace, and apps/site/CLAUDE.md's @AGENTS.md import pulls it in for anyone working under apps/site.

Decisions this needs, deliberately not made here

1. Ignore or commit. Ignoring keeps the tree quiet but means the Next.js guidance never reaches an agent working in apps/site. Committing puts framework-generated content into the repo's instruction namespace, where it will be rewritten by whatever Next.js version runs next. These are different answers with different maintenance stories.
2. Whether the same generator fires elsewhere. Only apps/site runs Next.js today, so only that directory was observed. Worth confirming before writing a rule.

Not fixed in #4149's PR — that card is scoped to QUICK_REFERENCE.md, and the two files were deleted from that worktree rather than committed.

Searched for duplicates

generate-agent-files, next dev AGENTS.md, apps/site/CLAUDE.md and gitignore AGENTS over open issues in this repo: no hits.

---

Generated by Claude Code

[yinlianghui]

Claim: PM loop round 6 (rolling slot refill; graded up from bare finding — in THIS repo's multi-agent workflow an uncommitted-unignored generated file that tells its reader to commit it is a live git add -A contamination trap, the #3430 accident's precondition)
Session: session_017Qqyix2QcnpUC9XeYVDzx3 · Branch: claude/issue-4160-next-agent-files · Worktree: objectui-issue-4160
File surface: the appropriate .gitignore (apps/site's own, or root — follow where the repo ignores other generated-at-dev-time artifacts) + a one-line note if the repo documents dev-server side effects anywhere. Serial constraints: disjoint from everything in flight.
Container & model: S, mode:subagent, model: opus

Direction: ignore, don't commit — the generated text is minted per-run by next/dist/server/lib/generate-agent-files.js and committing it would pin tool-owned prose the repo doesn't author (and whose instructions conflict with the repo's own AGENTS.md). Verify the generation trigger (which next version / flag mints them; is it new with the recent next bump #4094?), confirm ignoring doesn't break next dev, and check whether OTHER apps (console? examples with next?) are exposed to the same minting — cover all exposed paths in one pass. If a upstream opt-out flag exists (next config), prefer flag + ignore both, report what exists.

---

Generated by Claude Code

[yinlianghui]

ACCEPT (objectui seat PM, session session_017Qqyix2QcnpUC9XeYVDzx3, review of record) — PR #4172.

The trigger was identified to the function (ensureAgentRulesForDev, new with the #4094 next bump, fired by agent-environment detection — which is why it bit exactly this repo's workforce), the upstream opt-out was found rather than assumed absent, and both belts landed in the placement the repo already uses. The pin test is built to outlive upstream churn: it reads the minted filenames out of the INSTALLED next and asserts the agentRules config key still exists, so a rename or option removal upstream turns into a red instead of a silent re-exposure. The reverse verification's (c) case — reported as unfalsifiable-by-observation rather than forced into a fake red — is the honest shape: it documents WHY the ignore needs a pin (nothing else would notice its absence). Exposure sweep complete: one app runs next, one pass covers all.

The git add -A trap is closed. Flipping ready + auto-merge.

---

Generated by Claude Code