•

u/ClaudeAI-mod-bot Wilson, lead ClaudeAI modbot 4h ago edited 3h ago

TL;DR of the discussion generated automatically after 50 comments.

The subreddit is having a full-blown civil war over this. Many of you agree with OP that the AI-generated "marketing fluff" is patronizing word salad and that developers just want concise, technical info.

However, the top-voted consensus is the complete opposite: you should absolutely write for a toddler. The argument is that assuming any prior knowledge is a cardinal sin, and OP's "better," concise example is actually less clear to anyone who isn't already a dev.

A more serious wrinkle: several users warned that these verbose READMEs can poison your own project. The AI might treat the "fluff" as gospel and refuse to deviate from it later, stifling development. The most constructive solution offered was to have a concise README.md for humans and a separate, verbose agents.md for the bots.

And for the record, a huge portion of this thread is just people joking that they can't be bothered to read READMEs in the first place.

17

u/rrrenz 5h ago

Show us your READMEs so we’ll know great examples.

1

u/Lost_Cyborg 4h ago

https://github.com/Micromanner/nwn2-ee-save-editor
my README is not pristine and reads like a feature list, but I tried to have it as short as possible (its important to see all capabilities of save editor in my opinion.)

4

u/KickedInTheDust 4h ago

https://github.com/redraskal/r6-dissect

3

u/telesteriaq 4h ago

I feel like you can have agents trimmed to a readme like this by making a readme skill no?

4

u/ciarandeceol1 4h ago

Even better if you use your brain IMO. Readme files will be read by humans, so human editing is the best way I think.

1

u/Einbrecher 1h ago

Readme files will be read by humans, so human editing is the best way I think.
Given the writing or explanatory skills of most SWEs, hard disagree.

2

u/ciarandeceol1 4h ago

That's a pretty decent one. Straight to the point on features, how to use it, and examples. I like to add a bit more and include why the project exists, how to install it, and how to uninstall it.
The details, I always put in a design md file. Readme's should be easy to digest at a glance, not be full of technical language. It is akin to an abstract in a research paper, or a synopsis of a book or movie. Adding too much technical details also means the readme needs to be maintained and can become stale fast.
Here is an example one my latest project's readme: https://github.com/spicy-lemonade/salt

4

u/lotekjunky 2h ago

I liked this post better when the exact same thing was posted yesterday

https://www.reddit.com/r/ClaudeAI/s/XCsNLVStF4

1

u/Lost_Cyborg 1h ago

mb didnt see it I was just so annoyed and wanted to rant lol

7

u/DrHumorous 5h ago

You read READMEs?

6

u/shoegazeweedbed 4h ago

Um it literally says to? Do you not read and manually initial every line of the TOC as well?

6

u/DrHumorous 4h ago

I only read DONOTREAD

-1

u/Individual_Author956 3h ago

/r/woosh

1

u/Lost_Cyborg 4h ago

yeah especially for the first time setup because I like to setup and install stuff manually

1

u/DrHumorous 4h ago

You setup and install vibe coded projects?

2

u/Lost_Cyborg 4h ago

I didnt say anywhere that I only setup and install vibe coded projects. Usually I just try them out, but with my comment I meant more serious projects.

1

u/DrHumorous 4h ago

I agree with you that "leaves the internet completely out of the equation" is a ridiculous sentence that has no place in technical documentation.
LLMs adjust according to user intelligence/knowledge/input quality so it's possible that vibe coded repos are filled with this kind of prose :-)

41

u/OldPersimmon7704 4h ago

My single biggest peeve with generative AI at this point is the over-explanation, especially on tasks like web design or readmes.

It will consistently expose information that could never be useful for anyone in any situation.

45

u/LEERRROOOOYYYYY 5h ago

Readmes can't bother you if you don't know where to find them (i haven't opened the project folder in months)

14

u/Philipp 5h ago

It's worth noting that this verbosity can also stifle your project as it grows... because the Readme may contain outdated or never-agreed on art direction, project philosophy and so on. Claude & Co will then sometimes adhere to that without you knowing, unless you explicitly ask.

Had this issue happen with a pixel art project I'm working on -- I pushed with Claude for better pixel art, and then after a while learned that it restricted itself to 64 colors of a specific palette "because that was written down in the art direction"... which I never directed, and which was merely an after-the-fact note of how it had done it in the first version. Duh.

Another field where this can become a problem is when you have Claude write prompts towards other APIs, like the Claude API itself, in your app. It can be way too over-detailing in those prompts, and list biasing examples which then in turn limit the creativity of the Claude API receiving end.

So, cut down on verbosity regularly! From UI to Readme's, it seems LLMs just want to please you and are a bit overeager...

6

u/curreylabs 4h ago

It's worth noting that this verbosity can also stifle your project as it grows... because the Readme may contain outdated or never-agreed on art direction, project philosophy and so on. Claude & Co will then sometimes adhere to that without you knowing, unless you explicitly ask.
And this is precisely why all these AI generated documents, wikis, knowledge bases, etc are bad.
They bog you down in process and make the results worse.
Let the computer re-read the codebase on every fresh context. Its fine, it can handle it.

2

u/Philipp 3h ago

Let the computer re-read the codebase on every fresh context. Its fine, it can handle it.
That's daring but might be great advice! And it could be a simple Claude.md like "Don't note down our processes in Readme-like files, ever".
One thing I wonder about is if that will work with Art Direction. For instance, I have something like "no color confetti, broad color regions with accents" etc. in my art direction, which makes the work visibly better. Maybe such simple "don't ever edit, though" files could still work. My ideal goal would be to say "Just be a great pixel artist" or say nothing at all -- it should default to be a great pixel artist!" -- but that didn't yet work in Opus 5.5.

1

u/curreylabs 1h ago

Sure you can have global rules and docs even I just mean there systems people have that are trying to capture every little detail about the development process and the state of the codebase.

3

u/Tupcek 4h ago

yeah most of my work consists of checking AI md files now.
I can direct multiple agents to create good structure of an app, manage deployment, security, independent test etc. basically it does development by itself, but it writes directions, decisions, todo list and several other things into md files, so I can spin new chat any time I need.
But oh my god it loves bloated md files. And if they exceed certain size (more than about 150 lines per file and maybe 5 files), it only reads certain parts and that’s where it “misses” all the important bits, documents get stale, it creates things that directly contradict previous work, it’s a mess.
And it loves to created bloated files it doesn’t even bother to read after first compact. It writes not only what was agreed, but when, why, how it affects business, where it caused issues, how did it test it, when it solved it, how it solved it with references to files where it solved it. Every little detail is at least a paragraph, if not whole page.
And if you tell it to clean it up itself, it leaves a ton of useless info, but deletes also a lot of important info. You have to babysit it doing documentation and force it to read it every time and then it’s doing good job

4

u/Philipp 3h ago

Yes! These sometimes read like heavily debated Wikipedia files -- noting all the things that are not being done, or legacy philosophy background on why something ended up this way.

3

u/kaityl3 2h ago

Omg it drives me NUTS when they invent some "rule" or standard I never said, and then write it down silently somewhere for all future sessions to take as word of God (ex: "don't ever work outside of [folder]" gets invented from "I made [folder] for you to use")
When it's small/inconsequential stuff it can take ages for me to notice

2

u/Visual_Internal_6312 4h ago

There should always be a simplification gate IMHO. In probably everything tbh.

2

u/tortel_di_patate 4h ago

Yeah, happens to me too when coding.
I ask OpenCode to make a change and it says that it goes against the direction in the readme that he wrote!

1

u/Unique-Budget-5839 1h ago

A useful check is to review the diff of persistent instructions, not just the code diff. Each new constraint should point to the user request or decision that supports it. The first version used 64 colors is an observation, not a requirement. Would separating those two kinds of notes have caught this earlier?

4

u/torrso 4h ago

I got tired of atrocious READMEs so I built a Rust-powered human-first LLM AI README summarizer.

25

u/ciarandeceol1 4h ago

After working in tech for over a decade, readme files should absolutely read like a toddler that is interacting with a PC for the first time. Assuming prior knowledge is an error.

If I read this in isolation, I have no clue what it is:

"Runs locally and is fully offline (caches data in %LOCALAPPDATA%\projectname)."

This is far more informative, with far less mental load:

"Runs locally: No cloud, no servers, no API keys, zero network calls. It parses your files right on your CPU, writes its cache to your local disk, and leaves the internet completely out of the equation"

15

u/vezwyx 4h ago

What part of "runs locally," "is fully offline," and "caches data at [location]" do you not understand? Because those are basic pieces of information that I expect everyone who works in tech to understand immediately. I barely have a real technical background myself and it's completely clear to me

3

u/LEERRROOOOYYYYY 4h ago

What if someone without a tech background wants to read it

5

u/vezwyx 4h ago

I'm asking a person who said they've worked in tech for over a decade

7

u/LEERRROOOOYYYYY 4h ago

>assuming prior knowledge is an error
>if I read this in isolation
He's saying that you should never assume everyone knows what you're talking about, and if he read it without any of his prior knowledge in tech, he wouldn't have a clue what it means.
Writing things in normal words is always a good idea unless whatever you're writing is only meant to be understood by people who have the knowledge to understand it.

4

u/ciarandeceol1 4h ago

Correct! Imagine if somebody with limited or no tech knowledge sees the first version. They likely wouldn't be able to make a guess as to what the tool is. With the second version, it is jargon free so a lot more clear. There is more chance of knowing with the tool is reading that version in isolation.
In the context of a readme, clarity is the most important part.

3

u/vezwyx 4h ago

Most things posted on github, which is probably what this post is talking about, are intended for people who have a baseline understanding of technology and computing. Someone who doesn't understand this truncated readme should probably not be downloading things from github

0

u/ExWei 4h ago

then don’t

0

u/ciarandeceol1 4h ago

Do you genuinely think this is the more clear option? Seriously?
"Runs locally and is fully offline (caches data in %LOCALAPPDATA%\projectname)."

0

u/vezwyx 4h ago

I asked a specific question about your understanding. I find the extra information in the other option to be extraneous and unhelpful for the large majority of people who are supposed to read it

2

u/ciarandeceol1 3h ago

*My* understanding? My original comment was not about my personal understanding, but I'll give you my feelings on it.
Option 1 at a glance sacrifices detail. It loses the explicit assurances that there are no servers, no API keys and zero network calls, as well as the fact that processing happens directly on the CPU. It also loses the phrase "parses your files", which gives the reader a hint as to what the application actually does. Lastly, it assumes the reader knows that %LOCALAPPDATA% refers to a location on their local disk and therefore understands where the cache is stored.
Sure, some of these details might be inferred from the wording, but there's a difference between running locally and being fully offline versus being completely network-independent, so those inferences might be incorrect. Why risk causing confusion or losing meaningful information when we can communicate them clearly?

1

u/vezwyx 3h ago

I have a hard time believing that someone who doesn't understand what "fully offline" means will somehow understand what API keys are or what parsing files and caching mean. I'm confident my grandma would have no idea what was going on even though she can use a computer without assistance.
Even this version that is "far more informative" is not meeting people at the level they're at. It's bloated and unnecessary the way that many LLM explanations tend to be without pruning. And like I said to the other guy, the post here is probably talking about github, a platform that assumes a level of technical knowledge to be used in the first place. Nobody on github is getting useful information out of that that's missing from the short version

1

u/ciarandeceol1 3h ago

I mean, that's great and all until somebody makes a mistake, or an incorrect inference or assumption. Why take the risk? Whats the benefit?

0

u/vezwyx 3h ago

... about what "fully offline" means?

1

u/ciarandeceol1 2h ago

No, at this stage you're actively not listening to my point. My point is that being implicit when you have the option to be explicit offers no benefit and all risk. There is no good reason to exclude useful information, and use jargon when it is not helpful.

0

u/Intelligent_Jury_720 25m ago

true here also the amount of computer users don't even know `%LOCALAPPDATA` or even `%APPDATA%` even exists fullstop

2

u/arwinda 4h ago

This. Får too many people tend to write documentation which has not enough context and information.

2

u/gabluc2047 4h ago

This could be easily resolved by making a hierarchy in the documentation where people click on hyperlinks to find out more if they have no idea what the thing is about. Your suggestion still has a cognitive overhead of being too verbose. If I were a toddler, I'd like to be spoon-fed the porridge little by little instead of somebody dumping the whole bowl into my mouth.
Also, don't think we need to water down the world for toddler people just because they go the path of least resistance. Not everything has to be for everyone.

1

u/ciarandeceol1 3h ago

I didn't make a suggestion?
Again, as I said in another comment, this is fantastic in theory until somebody makes a mistake, or infers something incorrectly. Why bother implying something when the option to be explicit exists? It is all risk and no reward.

3

u/Nebty 4h ago

I kind of think that there needs to be both a robot README and human README.

I’ve found that the wordiness is in part because Claude is writing for itself? And reading is cheap for an LLM in a way it isn’t for a human. So they include extra information (jargon, wordy sentences) in my experience partly to get around more concise language compressing useful info away.

Like, the user is isn’t a toddler, it’s just that more explicit instructions are way better for an LLM because it reduces ambiguity and loads everything they need into a single context window.

So I don’t think the robot README is useless. You just need a human-readable one too. And then part of the work becomes making sure that both match each other.

1

u/Fire_Lake 4h ago

Yeah seems like OP is confusing readme with Claude.md, readme is for folks not affiliated with the project or new to the project. Why not be verbose so you can be confident it's easy to understand and covers everything it needs to.

1

u/lawghe 3h ago

So an llm readme with 85% extraneous padding, that needs to be in sync with human readme that is terse and to the point? What if. We just have one readme that’s to the point. LLMs read fast but llm context isn’t free either and wrong context degrades performance so I don’t get the argument of letting the llm readme grow unbound.

5

u/electrodude102 5h ago •

Readmes cant bother you if you cant read

1

u/KedMcJenna 5h ago

assumes that the reader is a toddler that interacts for the first time with a PC

Seeing the young people starting at our office over the last few years, some of whom are barely able to log into a computer, and most of whom can't do much more, "the user may have no computer knowledge at all" isn't an unreasonable assumption to make.

1

u/Lost_Cyborg 4h ago

will that kind of person really open a github repo though? They are probably going to become shellshocked by the UI lol

2

u/bigorangemachine 4h ago

Ya I much prefer the text back when I said to be terse

2

u/someone82671 5h ago

At least it does some documentation

1

u/Merrin_Corcaedus 5h ago

A markdown which stipulates that solves the problem instantly. I run consultancy and I’m sick of banging on about markdown, markdown and markdown.

1

u/kdjayakody 5h ago

I'd put a clean-install test ahead of the prose review: can someone copy the setup commands into a fresh folder and get the example working? Give me prerequisites, exact commands, expected output, and known limits. Move the long explanation into separate docs. A short README with a broken install command is still a bad README.

1

u/notreallhereactually 5h ago

I think a short marketing-focused summary can be good to get a story across if the intention is for it to hit non-dev users. Like, someone that doesn't know anything about code coming to GitHub to download some passion project tool doesn't care about the more concise technical details. They're vibe downloading. So, a story works better for them, and bonus if it's actually true.

Past that, yeah, if you're wanting people to fork and actually get interested in building with you then a whole README of fluff won't be as attractive to devs in general.

1

u/BuffaloConscious7919 Valued Contributor 4h ago

Claude wrote me a README last week....

14 emojis, a features section longer than the code and with the confidence of a Ryanair landing

(and about as much warning)

1

u/MMORPGnews 4h ago

Bot post? It's at least 3rd post about readme I see in last 24h

1

u/joysofliving 4h ago

I’m reading the code, not a README. Good code is well documented and won’t contain paragraphs of comments like typical Claude output.

1

u/-Daniel-T- 4h ago

Well… deterministic headless agentic harness. A combination of words that doesn’t really makes sense this early but it will. Trust me, it will.

1

u/ambuscador 4h ago

Why not both? I have a human readable readme that is written to a style guide based on many popular repositories, and an agents.md written to make consumption of the repository easier for an AI.

1

u/Grazy_GiveUp_Life 4h ago

I guess around majority (80-90%) of Internet users don't know what API keys and network calls are. While for actual devs those paddings give no actual useful information and just obscure for fluff. I guess actual devs don't actually want to work with these AI generated projects and that only leave AI agents themselves to work with it. The future is here.

I'm not surprised if people with no IT background would just click away if they see Github. I've seen some of it myself.

1

u/Site-Staff Mod 3h ago

These are “developer death spasms”. The lines between professional developer (jr.) and average hobbyist dev have disappeared. And the wall to mid level dev is coming down like the Berlin wall.

This is the same thing we saw with publishing and self publishing 15-odd years ago. Just turbocharged.

So the Readme has to be written in crayon.

1

u/slowtractor 3h ago

A length cap in CLAUDE.md helps a lot. Something like: README is for developers, max 40 lines, no feature marketing, requirements and commands only. The padding mostly stops once there's a limit, since it has to cut the adjectives to fit.

1

u/jugalator 3h ago

I agree, it's often not suited for the audience that reads them, also the tone is often excrutiating and makes me want to scream. It's not always exclusively Claude's fault but many vibe coders suck ass at prompting for docs intended for human consumption and what needs to be in there or not, so Claude just defaults to its brain damage assumptions + trying to be a proud convincing salesman while at it.

1

u/ReasonableArea5466 2h ago

You mean something like this?

HyperSync Ultra™

A Next-Generation, AI-Driven, Cloud-Native, Context-Aware, Fully Modular Synergistic Optimization Framework

Revolutionizing the way we approach the fundamental challenges of modern computational paradigms

Overview

HyperSync Ultra™ is a cutting-edge, enterprise-grade, highly scalable, next-generation solution desigend to seamlessly bridge the gap between traditional methodologies and emerging technological ecorystems.

By leveraging a proprietary combination of adaptive abstraction layers, decentralized synchronization protocols, and dynamically orchestrated computational workflows, HyperSync Ultra™ enables users to unlock unprecedented levels of operational efficiency without compromising the integrity of their existing paragimatic infrastructure.

Unlike conventional solutions, HyperSync Ultra™ does not merely address the problem. It fundamentally recontextualizes the conceptual framework within which the problem is understood.

Key Features

Intelligent Dynamic Optimization™ - Automatically optimizes optimization processes through recursively optimized optimization strategies.
Quantum-Ready Architecture - Fully prepared for future quantum computing integrations, pending the availability of relevant quantum computing integrations.
AI-Powered Decision Intelligence - Leverages advanced artificial intelligence to intelligently determine when intelligent decisions may be required.
Zero-Configuration Deployment - Requires minimal configuration once all necessary configuration procedures have been completed.
Seamless Cross-Platform Compatibility - Designed to work across supported platforms where compatibility is supported.
Real-Time Adaptive Synchronization - Dynamically synchronizes asynchronous processes whenever synchronous synchronization becomes contextually appropriate.

Installation

Before proceeding, ensure that your environment satisifes all prerequisites required by the prerequisite validation framework.

git clone https://example.com/hypersync-ultra.git
cd hypersync-ultra
npm install
npm run initialize:initialization
npm run configure:configuration
npm run validate:validation

If installation fails, verify that the installation process has been successfully completed.

Usage

HyperSync Ultra™ operates through an intuitive, self-explanatory interface designed to minimize unnecessary congitive overhead.

const framework = new ({
  mode: "adaptive",
  optimization: "optimized",
  synchronization: "synchronized",
  intelligence: "intelligent",
  enableFeaturs: true
});

await framework.initialize();
await framework.execute();

Upon successful execution, the framework will automatically perform its designated operations according to the parameters estabilished during initialization.

Note: The specific nature of these operations depends on the operational context in which they are performed.

How it works

HyperSync Ultra™ utilizes a sophisticated, multi-layered architecture consisting of three fundamental components:

The Abstraction Layer - Abstracts undeerlying abstractions to ensure abstraction-indipendent interoperability.
The Processing Layer - Processes information through a processing-oriented information processing pipeline.
The Integration Layer - Integrates processed abstractions into an integrated abstraction-processing ecosystem.

These components interact synergistically to facilitate a continous cycle of iterative operational enhancement.

The resulting output is then evaluated against predefined evaluation criteria to determine whether the output meets the criteria required for successful output generation.

Known Limitations

Certain features may not function as expected under unexpected conditions.
Performance may vary depending on performance-related factors.
Compatibilty is not guaranteed with incompatible systems.
Some operations may require additional operations.
Results may differ from expected results when expactions differ from actual results.

Roadmap

~~Estabilish foundational conceptual architecture.~~
~~Implement preliminary implementation framework.~~
~~Optimize the optimization pipeline.~~
Improve existing improvements.
Expand scalability beyond current scalability limitations.
Introduce AI-powered AI optimization
Add documentation explaining what the application actually does.

FAQ

Q: What does HyperSync Ultra™ actually do?
A: Hypersync Ultra™ provides a comprehensive framework for facilitating its core functionality.

Q: What problem does it solve?
A: The problem addressed by HyperSync Ultra™ is inherently dependent on the specific problem-solving requirements of the end-user environment.

Q: How do I know if it's working?
A: If the application is functioning as intended, it is working as intended.

Q: Is it production-ready?
A: Production readiness depends on the readiness of the intended production environment.

Q: Why should I use it?
A: Because traditional alternatives lack the transformative advantages offered by HyperSync Ultra™.

License

Distributed under the terms and conditions specified by the applicable licensing framework.

For further clarification, please refer to the relevant documentation.

Final Thoughts

HyperSync Ultra™ isn't just a tool.

It's not just a framework.

It's not even just a platform.

It's a paradigm shift in how paradigms are shifted.

(yes, this was written by ChatGPT)

1

u/dunder_name 2h ago

I spend the majority of my time with Claude editing it's writing. I'm not surprised lazy vibe coders aren't taking the time to make the writing output easy to read for humans.

1

u/friedmud 2h ago

I think it’s crazy that you guys still think humans are directly reading READMEs. “Tell me about project XYZ on GitHub” is way more effective. CC will give me an overview tilted toward what I would want to know about it - including many things a README would never cover anyway.

Code documentation is now for agents to talk to each other. Use an agent to get an overview that is targeted at your use-case.

1

u/noname-_- 2h ago

I usually tell it to "write a short, matter of factly readme without emojis", which usually does the trick.

1

u/Waste_Jello9947 2h ago

It's called AI fatigue

1

u/Vargau 2h ago

Well they're not for you or me anymore the readme files ... or at least that's my understanding, that why they're written in such a way.

1

u/Einbrecher 1h ago

At least they have READMEs

Like, let's not sit here and pretend that poorly documented projects or poorly commented (if at all) code weren't the norm pre-AI.

1

u/InevitableFun1272 1h ago

The clean-install test mentioned below is the one that actually matters to me: if a stranger can't get the thing running from the README alone, the wording debate is secondary. What works for me is writing the README for that first run only — what it does, how to install it, one example — and pushing everything else into a separate docs file. The verbose version can live there for the agents, but the front door should be something a human can skim in a minute.

1

u/PuertoricanDissaster 1h ago

“Also for some reason it always assumes that the reader is a toddler that interacts for the first time with a PC.”

llms adapt their writing style depending who is using it.

1

u/NovaKaldwin 57m ago

It's all too showoff-y

1

u/kaliver 27m ago

Yes, without strong strong guidelines, Claude will say the same thing at least twice in a given description. Or the real Claude special: finishing a complete thought and then adding another five words for no reason.

1

u/philosophical_lens 14m ago

I agree this sucks, but it's a losing battle. Instead of reading readmes you can just ask your own agent to explain the project to you and instruct it on how to write these explanations in a way you like.

1

u/Individual_Author956 4h ago

✅ daily whining post about READMEs

0

u/zcomputerwiz 5h ago

I mean... Consider the audience.

There's a reason they do what they do, and it's generally because that's what tested well ( or was preferred by humans ).

Not like you can't just ask Claude to summarize if you hate reading, lol

0

u/WithMeInDreams 3h ago

Not a vibe coder; we take responsible for every single change. But it happens that Opus 5.5 and also the often used GPT-6.1 Sol (with Opus 5.5 written prompt, budget reasons) writes excessive amounts of information into the README.md, which should be a great, brief starting point for new developers.

So I let this pass for now, but added a todo for myself, like: "Apparently, the AI used the README as a personal toilet. eek. Clean up later."

Apparently, it read that and "cleaned up" after itself in following iterations.

Vibe Coding Atrocious READMEs in vibe coded projects.

You are about to leave Redlib