From d2c46c1c2d50982f0c5b82121ab44564d259f494 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 11:20:59 +0000 Subject: [PATCH] fix(docs): stop `next dev` writing untracked AGENTS.md / CLAUDE.md into apps/docs `next dev` (Next 16.3.1) runs `ensureAgentRulesForDev` on boot and, whenever it detects 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 here: 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 its own text argues for committing itself. The generated `CLAUDE.md` is the single line `@AGENTS.md`, an import directive that pulls the stub in. Set `agentRules: false` in `apps/docs/next.config.mjs`, turning generation off at the source rather than gitignoring the paths: an ignore rule for `apps/docs/AGENTS.md` would silently swallow a future repo-authored `AGENTS.md` for this app, failing invisibly at exactly the moment someone was adding real guidance there. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt --- apps/docs/next.config.mjs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index b90a9ee212..67b08f23fd 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -6,6 +6,28 @@ const withMDX = createMDX(); /** @type {import('next').NextConfig} */ const config = { reactStrictMode: true, + // `next dev` otherwise writes `apps/docs/AGENTS.md` and `apps/docs/CLAUDE.md` + // into the working tree whenever it detects an AI coding agent (Next 16 + // `ensureAgentRulesForDev`). 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, so 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. + // + // Disabled at the source rather than gitignored on purpose: an ignore rule + // for `apps/docs/AGENTS.md` would silently swallow a future repo-authored + // `AGENTS.md` for this app, failing invisibly 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. + // + // This only stops future generation: a checkout that already ran `next dev` + // keeps its copies until they are removed once by hand + // (`rm -f apps/docs/AGENTS.md apps/docs/CLAUDE.md`). + agentRules: false, // No `output: 'standalone'` here on purpose. The standalone packer // (`writeStandaloneDirectory` -> `copyTracedFiles`) opens // `.next/next-server.js.nft.json`, and that open is the ONLY thing in a