Vibe-coders: Time to Drain the Fluff From Claude-Written READMEs

A developer vented on Reddit: GitHub project READMEs generated by Claude during vibe-coding are making life miserable for ordinary users looking for tools. While searching for scripts for the Steam Frame VR headset, he combed through relevant repositories and found that 99% of project READMEs were Claude's handiwork—verbose, extremely low information density, reading like AI taking notes for itself rather than instructions meant for humans.

When READMEs Become AI's Scratch Paper

The user emphasized that he's not opposed to vibe-coding itself. Someone willing to share fix scripts and tools written with Claude is good for the community. The problem lies in how the READMEs are written: Claude's recent output style has become unusually dense, using large amounts of text to explain things that are completely meaningless to end users.

He gave a concrete example. A feature list for an eye-tracking script, written by a human, reads: "Automatically finds your PC; uses One Euro filter to smooth gaze; uses dead zone to suppress pupil jitter"—15 words. Claude's version, on the other hand: first explains how it finds the PC through Steam Link streaming, how the wireless adapter connects directly, why the home network doesn't matter, then explains how the One Euro filter smooths gaze and eyelids, how a small dead zone keeps the eye still during fixation, how gaze is maintained when eyes are closed because the Frame's eye tracking jumps when eyes open—71 words. Same amount of information, five times the length, and worse readability.

Vibe-coding refers to a development approach where developers describe their intent in natural language and have a large language model (like Claude) directly generate usable code or project files, emphasizing "describing by feel, producing quickly" rather than writing line by line. It lowers the barrier to creation, but also means that artifacts beyond code (READMEs, comments, commit messages) are likewise ghostwritten by the model. A README is the explanatory file in a repository's root directory, typically the first document a visitor encounters with a project, responsible for answering "what is this, how do I use it, how do I install it"—its readers are strangers, not the author. When vibe-coding focuses generation on "getting the model to finish the task," the README easily degenerates into a byproduct of the model's output process rather than a reader-facing getting-started guide—this is precisely the structural reason for the readability decline described in the original post.

Information Overload: Users Don't Need to Know Backend Details

The problem isn't just verbosity. Claude also explains every feature in exhaustive detail, including those that are obvious and behave as expected, as well as details that are purely backend implementation that users don't need to know at all.

This makes browsing repositories on GitHub very difficult. Users are bombarded with large amounts of information that is only useful to developers (or other AI agents), information that should really be found in the code itself. Ironically, these READMEs clearly contain instructions for humans to manually run commands on the headset, yet they're written as if for another AI to read.

Information density refers to the amount of useful information per unit of length for the target reader. Technical documentation writing typically follows the principle of "layering for the reader": the user-facing portion retains only operational steps, prerequisites, and expected results; implementation principles, internal data structures, and exception branches are backend implementation details that should go in code comments or developer documentation. A common bias in AI-generated text is equating "explained completely" with "written well," so intermediate conclusions from the reasoning chain get written into the body text, forcing readers to filter out noise themselves. To judge whether a piece of explanation belongs in a README, use a simple criterion: if the reader doesn't need it to make an operational decision, it doesn't need to be there.

Community Disagreement: Written for Humans or for AI?

Some commenters under the post argued that "AI-generated READMEs are meant to be read by other AIs anyway." But the original poster countered that this doesn't hold in this scenario: Claude doesn't run on the Steam Frame, and users can't hand the README to Claude and ask it to operate things for them. These READMEs explicitly contain instructions for human users, yet use the register of AI-to-AI communication.

This precisely points to the essence of the problem: many vibe-coders don't shift perspective when generating READMEs—they let Claude dump its "thinking process" directly into the document without asking it to rewrite for the end reader.

AI-facing documentation and human-facing documentation do differ in register: the former tends to state context completely and explicitly list constraints and boundary conditions to reduce ambiguity; the latter relies on shared common knowledge, omits obvious prerequisites, and pursues scanning efficiency. With the spread of AI coding agents, agent-optimized instruction files have emerged (such as AGENTS.md conventions), which serve a different purpose from READMEs. The key point of contention in the original post is who the actual reader of the document is: if the instructions describe commands for humans to manually execute on the headset, then the target reader is human, and applying an "AI-facing" register is a reader mismatch, not a matter of stylistic preference.

Five Minutes of Editing for Ten Times the Usability

The poster's request is simple: if you share scripts on GitHub, spend five minutes making the README more readable. Specific steps could include: delete explanations of obvious features, cut backend implementation details, compress feature lists into short sentences humans can scan, and keep only the steps that genuinely require manual execution.

For vibe-coders, this is really a process issue: having Claude generate the README is fine, but after generation you should ask it to "rewrite a version for human users, remove implementation details, one sentence per feature." Or just edit it yourself. The README is a project's first impression—a document no one can bear to read will bury even the best tools.

Background

The One Euro filter is a low-latency smoothing algorithm for real-time interaction, commonly used in eye tracking, mouse pointer, and other signal processing scenarios. Its core idea is to let the cutoff frequency adapt to how fast the signal changes: when the signal is slow, increase smoothing to suppress jitter; when moving fast, reduce smoothing to minimize lag. The accompanying dead zone is a threshold mechanism that doesn't update the output when input changes are smaller than a set range, thereby filtering out tiny noise. The original post's mention of "dead zone suppresses pupil jitter" refers precisely to using this threshold to block the inherent细微 tremor of the eyeball during fixation, while eye movement signals jump when eyes are closed, requiring additional holding of the last valid value. These are implementation-level tradeoffs; users only need to know "it's steadier, less jittery."

One-line Summary

Claude-generated GitHub READMEs are verbose and inefficient; vibe-coders should rewrite them for human readers.

Paragraph Summary

A developer complained on Reddit that GitHub project READMEs generated by Claude vibe-coding are making ordinary users miserable: while searching for scripts for the Steam Frame VR headset, he found that 99% of READMEs were Claude's work—verbose, extremely low information density, like AI taking notes for itself. For the same eye-tracking feature description, a human writes 15 words, while Claude wrote 71 and went on about backend implementation details. Commenters argued that AI-generated READMEs are meant for AI to read, but the poster countered that these documents clearly contain instructions for humans to execute manually. The root cause is that vibe-coders let Claude dump its thinking process directly into the document without shifting perspective to rewrite for the end reader. He suggests spending five minutes to delete explanations of obvious features and backend details, compress feature lists into scannable short sentences, and keep only the steps that genuinely require manual execution.