Programmers will document for Claude, but not for each other

Why People “Document for Claude”

• Developers see immediate, tangible payoff: better AI outputs when they supply focused context, specs, and CLAUDE.md files.
• Claude reliably “reads” everything; coworkers often don’t. This makes the ROI of writing for an AI feel much higher.
• Documentation for Claude is judged only on information content, not prose quality, so people are willing to dump rough notes, dictation, and slop they’d be embarrassed to share with humans.
• Some argue devs aren’t documenting for Claude but for themselves and any user of Claude; AI just finally guarantees an attentive reader.

Human vs AI Use of Documentation

• Many recount years of writing careful docs that colleagues ignored, then got asked the same questions anyway.
• Some teams try to enforce a “read the docs first” culture (asking where someone looked, tying docs habits to reviews), but report mixed success.
• Several note that most users don’t read on-screen text at all; many companies are “oral cultures.”
• AI is praised for being able to read large, messy doc sets, cross‑reference PRs, tickets, wiki pages, and tailor explanations to a person’s current understanding.

Quality, Drift, and Maintenance

• A recurring complaint: CLAUDE.md and AI-generated docs quickly go stale and can mislead future AI sessions, even hallucinating removed classes and architectures.
• Some respond by deleting such files; others add agents to maintain a small set of living docs (overview, key flows) and discard ephemeral plans.
• Inline documentation (e.g., jsdoc-style) and build-time doc extraction are cited as ways to keep code and docs aligned.
• One heuristic: if an LLM can’t derive correct answers from your docs, the docs themselves are probably unclear or wrong.

New Workflows and Tooling

• People describe custom “skills” and agents: parallel code reviewers, infinite issue generators, documentation agents that detect drift, and repo overviews maintained via Claude.
• Specs, design docs, and decision documents are becoming central, both to align teams and to drive agents; some foresee spec formats evolving into de facto “programming languages” for AI.

Enthusiasm vs Skepticism

• Enthusiasts report 4–8× productivity gains and a renaissance in specs and architecture docs now that they directly improve implementation speed.
• Skeptics warn that LLM output is non-deterministic, partially wrong, verbose, and can encourage anti-social, AI‑mediated collaboration.
• There is concern that massive, AI-generated doc piles will be unreadable, quickly outdated, and ultimately disposable.