Programmers will document for Claude, but not for each other
Programmers are increasingly writing detailed markdown files and specs so large language models like Claude can understand their code, even though similar documentation for human coworkers has long been neglected or ignored. Commenters argue the incentives have shifted: AI reliably "reads" and benefits from any extra context, immediately improving its output, whereas humans often skip manuals and internal docs, making the effort feel wasted. This shift is prompting more written architecture and design docs, but also raises concerns about doc quality, staleness, and how much of this new documentation is being optimized for machines rather than people.
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.