Detailed Analysis
A Reddit post in r/Anthropic has surfaced a recurring complaint among developers using Claude Code: the model's tendency to generate excessive, verbose comments that can, in some cases, account for 60 to 80 percent of the total code output, particularly in scripts. The original poster describes these as "ultra inflationary comments" that document assumptions, values, or logic that quickly become stale as the underlying code changes elsewhere. The core grievance is not that Claude comments code — a broadly beneficial practice — but that it does so excessively and by default, without apparent restraint, creating a maintenance burden rather than easing one. The poster specifically flags "drift" as a consequence: comments that once accurately described behavior become misleading artifacts once the code around them evolves, effectively becoming a source of misinformation embedded directly in the codebase.
This complaint touches a well-known tension in AI-assisted coding tools. Large language models trained to be helpful and thorough often default toward verbosity, treating exhaustive explanation as a proxy for quality. In conversational contexts this instinct is usually harmless or even useful, but in code generation it can backfire. Comments that restate the obvious, narrate step-by-step logic that's already self-evident from well-named variables, or annotate temporary values as if they were permanent specifications add noise without adding safety. Worse, as the poster notes, stale comments are arguably worse than no comments at all, because future developers (human or AI) may trust outdated documentation over the actual executing code, leading to compounding errors down the line. This is a classic software engineering hazard that predates AI coding assistants, but the scale at which Claude Code can generate output makes the problem more acute — a human writing a script might add a handful of comments, but an AI producing hundreds of lines in seconds can just as easily produce hundreds of comment lines to match.
The issue reflects a broader pattern in how coding-focused AI agents are evaluated and tuned. Anthropic, like other labs building agentic coding tools (GitHub Copilot, Cursor, and similar products), has to balance multiple competing priorities: helpfulness and transparency in explaining generated code, token efficiency and cost, and long-term code maintainability. Verbose commenting may score well on short-term readability metrics or user satisfaction in isolated demos, while simultaneously degrading the developer experience in real, evolving codebases where code review, refactoring, and diffing become harder to parse amid comment noise. This is emblematic of a wider critique leveled at AI coding assistants: they optimize for producing plausible-looking, well-annotated code in a single pass, but are less attuned to the lifecycle concerns — versioning, drift, technical debt — that experienced engineers weigh instinctively.
The practical workaround described by the poster — manually cleaning up generated code and defining explicit rules around commenting behavior — points to an emerging best practice among power users of Claude Code and similar tools: treating system prompts, custom instructions, or CLAUDE.md-style configuration files as necessary guardrails rather than optional tuning. Many teams have begun codifying explicit style guides (e.g., "avoid comments that restate code," "only comment non-obvious business logic") specifically to counteract default verbosity tendencies in LLM-generated code. This trend suggests that as agentic coding tools mature, effective use increasingly depends not just on model capability but on the surrounding scaffolding of constraints, linting, and review processes that keep AI output aligned with real-world software engineering discipline — a dynamic likely to shape how Anthropic and competitors refine default behaviors in future model releases.
Read original article →