Claude Code Reads Your Docs: Should an LLM Rewrite Them for Agents?

Claude Code, Copilot, Cursor and their peers already treat your repository’s documentation as instructions: CLAUDE.md and AGENTS.md files, READMEs, and web pages the agents fetch on their own. If those files are stale, the agent inherits the staleness silently. That premise makes a tool like Gauge interesting. Announced in a Show HN post from 2026-11-05, Gauge is an open-source CLI that recursively rewrites your docs for coding agents, with a local execution backend so you can try it without an account. The practical answer to the title’s question is yes, but only under conditions: treat every generated doc diff as a code change that needs CI review, verify rewritten content against the actual codebase, and demand measured behavior deltas before crediting a rewrite with improved agent performance. Every outcome number attached to Gauge so far is author-reported in its own launch post, with no independent evaluation published. What the launch post does contain, usefully, is a built-in measurement protocol you can adopt whether or not you adopt the tool.

What Gauge actually does

The launch post describes two components. The first is the rewrite loop itself, which its authors call hillclimbing:

“The CLI supports a hillclimbing loop:- set up tasks for coding agents that would need your docs, like ‘set up Gauge CI checks’- run the tasks- analyze session transcripts for friction or failures- create variants of your docs to resolve the issues- re-run the tasks with the doc variants injected (transparently, at the same hostname)- repeat until you have a variant that resolves the issues”

Read carefully, that is not a documentation generator. It is an A/B harness for documentation. The agent runs a fixed task, a human (or the tool) reads the session transcript for friction, the docs get a variant, and the same task re-runs with the variant injected transparently at the same hostname. The loop ends when a variant measurably resolves the observed friction, not when the docs read better.

The second component is the infrastructure that makes injection possible. Per the same post: “The network gateway is where we terminate TLS and swap in variants of your docs transparently. The gateway also handles credential replacement, so agents see placeholders and can’t exfiltrate keys.” The “local” backend runs Docker containers as the VMs, with mitmproxy in a sidecar container per session acting as the gateway, while inference remains remote. So “local” means the execution sandbox and proxy run on your machine; the model calls do not.

That distinction matters for two reasons. First, a TLS-terminating proxy that sits between an agent and the network is a security-sensitive pattern, and any team adopting this needs an explicit security review, not a shrug. Second, the transparent-injection design is what makes the measurement credible: the agent cannot tell whether it is reading your real docs or a variant, which removes one source of measurement bias. Whether the rest of the loop works as advertised is unverified, because no third party has published an evaluation.

What your agents actually read

Before letting anything rewrite your docs, it is worth being precise about which docs reach which agent. The picture is messier than “write a good AGENTS.md.”

On the repository side, context files have effectively standardized. An exploratory study of agentic AI coding tools found that “CLAUDE.md and AGENTS.md serve as de facto standards, with AGENTS.md becoming a tool-agnostic standard adopted across tools,” alongside copilot-instructions.md. The same study, however, documents a gap that directly affects this article’s headline agent: “Native AGENTS.md support is already provided by Copilot, Cursor, and Codex; Claude Code, despite being the most popular tool, does not yet support it… creating a clear gap between developer practice and tool capability.” If you rewrite only AGENTS.md, Claude Code will not natively read it. You need a CLAUDE.md mirror until that changes, and these compatibility findings are snapshots that will age as vendors ship updates.

On the web side, agents fetch documentation portals directly, through incompatible HTTP stacks. A study of agent traffic on documentation portals reports that “Aider and OpenCode stand out as the only two that rely on Headless Chromium (instantiated via Playwright) as their HTTP runtime,” while the rest use lighter clients: Go net/http for Antigravity, Node.js/Axios for Claude Code, curl for Cline and Junie, Node.js/got for Cursor, and Go/Colly for Windsurf. Two consequences follow. A headless-Chromium agent sees your rendered page; a curl agent sees raw HTML or whatever your server returns to a non-browser client, so the same documentation change can reach different agents differently. And the study found that no examined agent requested llms.txt, while robots.txt was accessed only by Claude and MistralAI. Conventions for agent-facing docs do not propagate automatically just because someone publishes them.

Staleness in this web layer is not hypothetical. Gauge’s own authors report that during development, coding agents claimed the tool supported only Claude Code and Codex; the cause was traced to stale web pages the agents had fetched, and the team fixed the behavior, noting that Pi, OpenCode and Antigravity were already supported alongside them. That is an author-reported anecdote, but it is a concrete, plausible instance of fetched docs producing directly wrong agent behavior, which is exactly the failure mode a doc-rewriting tool claims to fix.

Meanwhile the doc layer itself is now standardized infrastructure, which raises the stakes of getting it right. AGENTS.md describes itself as “a simple, open format for guiding coding agents, used by over 60k open-source projects… a README for agents,” born from OpenAI Codex, Amp, Jules, Cursor and Factory and now stewarded by the Agentic AI Foundation under the Linux Foundation. A file that 60k-plus projects treat as an agent interface deserves the same review discipline as an API contract.

The decision axes that matter

The evidence supports a compact comparison across the choices a team actually faces:

An adoption checklist before an LLM touches your docs

The concrete task this article promised is a review workflow. Here is the one the evidence supports.

1. Gate doc diffs in CI like code diffs. Once an LLM can propose documentation changes, documentation stops being cosmetic debt and becomes an input to agent behavior. Every generated diff to AGENTS.md, CLAUDE.md, README or docs/ should go through the same pull-request review as code: a named human reviewer, a CI check, and a revert path. It is the cheapest discipline change available to you, and it costs nothing beyond the review time you already spend.

2. Mirror your context files. Until Claude Code supports AGENTS.md natively, keep AGENTS.md and CLAUDE.md in sync, and have CI fail when they drift. A rewritten AGENTS.md that Claude Code never reads is documentation theater.

3. Verify against the codebase, not against vibes. The failure mode of LLM-rewritten docs is fluent, plausible, wrong: an API method that no longer exists, a setup step reordered, a flag renamed. Every rewrite should be checked mechanically where possible. Does every command in the docs exist in the repo’s scripts? Does every referenced file path resolve? Some of this is scriptable today; the rest is reviewer work, and it is the work the rewrite creates.

4. Use deterministic linting where generative review is overkill. The AI-Forward starter kit is the deterministic counterpoint to LLM rewriting: a rules-based documentation specification with a linter whose runtime cost is “a .ai-forward/ directory at your repo root, Python 3 with pyyaml and jsonschema to run the linter, and CC BY-SA 4.0 attribution. There are no other dependencies.” A schema linter catches structural drift and nonconforming docs without an LLM in the loop, which makes it auditable in a way a generative reviewer is not. It will not judge whether a paragraph helps an agent, and it deterministically catches only what the schema can see; the kit publishes no evaluation of what it misses. It belongs in the same CI gate.

5. Audit the harness before you trust the transcripts. If you adopt Gauge’s loop specifically, the TLS-terminating gateway with credential placeholdering is the component your security team needs to read first. It is a reasonable design for the stated goal, and it is also a man-in-the-middle proxy by construction. The right posture is explicit sign-off, not discovery after the fact.

Does a rewrite change agent behavior? Test it, don’t assume it

This is the article’s central point, and it applies to Gauge, to any future competitor, and to hand-written doc improvements alike. The closest published test of that question comes from the harness study, which reports that Lulla et al. (2026) “ran a controlled study with and without an AGENTS.md file, reporting lower runtime and token consumption at comparable task completion,” and elsewhere calls this “early evidence on the impact of Context Files.” That is measured evidence that a context file changes agent outcomes: lower runtime and token cost, with task completion comparable rather than improved. Note what it does not test. It compares the presence of an AGENTS.md against its absence, not a rewritten doc against your existing docs, and it shows no gain in task success. Whether an automated rewrite of already-present docs improves outcomes is a different question, and no published evaluation answers it.

The documentation-portal study argues in its discussion that “a well-structured AGENTS.md improves the experience of working with open-source projects using AI coding agents by surfacing project structure, dependencies, and relevant resources directly within the agent’s context.” The authors label that implication interpretive, a connection from observed traffic patterns to practitioner developments rather than an additional empirical measurement, so treat it as informed argument about developer experience, not evidence of outcome change.

So the evaluation frame has to come from the workflow itself, and here Gauge’s announced method is genuinely the right shape regardless of whether the tool delivers it:

• Fix a small suite of tasks that require the docs, the way the launch post’s example “set up Gauge CI checks” does. Tasks must be stable across runs or you are measuring noise.
• Baseline the agent on those tasks against your current docs. Record task success and token cost per run.
• Inject one doc variant at a time, transparently, and re-run. One variable per experiment; a rewrite that changes five things at once tells you nothing about which change mattered.
• Read the session transcripts, not just the success flag. Friction that disappears from the transcript is evidence; friction that moves to a different step is a warning.
• Repeat until a variant resolves the issue, then keep the variant and the measurement that justified it in the commit message.

Two caveats belong inside the frame rather than after it. First, per-agent transfer: because agents fetch and consume docs through different clients and different context files, a variant that fixes Claude Code’s behavior may do nothing for Cursor. Re-run per agent you support. Second, transcript analysis has no measured false-positive rate in any published evaluation; “friction” is a judgment call, and two reviewers may read the same session differently.

What the Clerk 3x claim does and doesn’t prove

The launch post’s only outcome number is this: “For Clerk, we helped shift coding agents from their legacy ‘keyless’ mode to their new ‘clerk init’ command. They were able to validate a pre-release change to their SDK’s error messages using Gauge, then saw a 3x increase in coding agents using ‘clerk init’ post-deploy.”

Take it as a hypothesis worth reproducing, not a result worth citing. It is self-reported by the tool’s authors in their own announcement, with no methodology, no baseline definition, and no independent replication. It is also, notably, a story about web-published documentation (SDK error messages) rather than repo context files, which is the propagation layer where client heterogeneity bites hardest. If your team wants a comparable claim, the loop above is how you generate one you can defend: your tasks, your agents, your measured deltas.

Decision guide: when to let an LLM rewrite your docs

Adopt now, with gates, if your agents already consume your docs daily and you can name concrete failures: agents citing removed APIs, re-running deprecated setup steps, ignoring contribution conventions. The measurement loop is the point; the rewriter is optional. Even a manual quarterly staleness audit, scored with a fixed task suite, beats shipping rewrites on faith.

Trial carefully if you are evaluating Gauge itself. Use the local backend on work that can tolerate experimentation, put every generated diff through CI review, mirror to CLAUDE.md, and require re-run task-success and token-cost deltas before merging anything. Treat the tool’s supported-agents list (Claude Code, Codex, Pi, OpenCode and Antigravity, per the authors) and its compatibility claims as moving targets to re-check, since agent support for context files is actively shifting.

Wait, or skip the LLM entirely, if your docs are structurally fine but occasionally stale, or if a security review cannot sign off on a TLS-terminating proxy in your environment. If your doc failures are mostly structural, a deterministic linter plus a scheduled human review addresses them with a smaller trust surface. And if wrong docs would drive wrong agent actions on customer work, the missing independent evaluation matters more than the launch headline.

The durable shift underneath all of this is not any one tool. It is that documentation now has two audiences with different failure modes, and the agent audience acts on what it reads without asking. Once that is true, doc review belongs in code review, and every claim that a rewrite helped should arrive with a measurement attached.

Frequently Asked Questions

Does Claude Code natively read AGENTS.md files?

Native AGENTS.md support is already provided by Copilot, Cursor, and Codex; Claude Code, despite being the most popular tool, does not yet support it… creating a clear gap between developer practice and tool capability.

How should teams verify LLM-rewritten documentation?

Every rewrite should be checked mechanically where possible. Does every command in the docs exist in the repo’s scripts? Does every referenced file path resolve? Some of this is scriptable today; the rest is reviewer work, and it is the work the rewrite creates.