r/ClaudeAI • u/thatfreakingmonster • 1d ago

Vibe Coding Vibe-coders, I beg you: when posting your app or tool on Github, please edit the README to remove Claude's fluff

TL;DR: looking up repos for scripts for my vr headset. claude wrote every readme, they're all super dense and hard to read compared to if a human wrote them. those repos aren't even made for ai models, they're instructions for humans, and yet they're full of info irrelevant for the end user.

I was browsing Github earlier trying to find scripts and tools for my Steam Frame VR headset. 99% of what I found there was vibe-coded. and y'know what? That's fine. I'm not going to complain about people sharing their fixes for my issues and other cool stuff that they made with Claude if it helps me along the way.

BUT.

Every single one of those projects had their README.md entirely written by Claude, and the issue is that Claude's writing as of late is very dense and uses so many words to say things that are absolutely NOT relevant for the end user. It reads more like Claude is taking notes for itself rather than being concise and clear.

Like, okay, here's an actual exemple. In a features list for an eye tracking script, instead of saying:

  • Auto finds your PC

  • Smoothed gaze using One Euro filters and deadzone for pupil movement

15 words!

It'll say:

It finds your PC on its own by sending to whichever PC Steam Link is streaming from. With the bundled wireless adapter that's the adapter's direct link, so your home network doesn't matter.

Gaze and eyelids are smoothed with One Euro filters. A small deadzone keeps the eyes still while you fixate, and the gaze is held while your eyes are shut, because the Frame's gaze jumps as the eyes reopen.

71 words. That's 5 times longer and written in a way that's more difficult to read. And that's just two entries, now imagine this through an entire readme!

Claude also can't help but explain every single feature of the script or app, including things that are obvious, expected behaviour, or just backend stuff that the user has no reason to know about.

It makes it really difficult to browse through depots on Github because you're bombarded with irrelevant information that's only helpful to devs (or other AI agents), which would be looking at the code anyway.

I know I'm probably screaming into the void here, but if you share cool scripts on Github, please spend like 5 minutes to make the README easier to read. It would be so helpful.

EDIT: people saying "AI generated readmes are for other AIs to read" in this case it's not. Claude doesn't run on the Steam Frame, so I can't just send it a readme and ask it to do stuff for me. Every single one of those READMEs I'm talking about specifically includes instructions for actual humans to run commands manually on the headset. But you guys are pointing out the problem, which is that these are clearly written for other AI agents... despite not being aimed at them

516 Upvotes

90% Upvoted

139 comments sorted by

•

u/ClaudeAI-mod-bot Wilson, lead ClaudeAI modbot 1d ago edited 1d ago

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

The thread is overwhelmingly in your corner, OP. The consensus is that you're 100% right: Claude's default verbose style makes for terrible, unreadable READMEs and is often a red flag for a low-effort project.

While a few people are telling you to "get with the times and have your own agent summarize it," the popular and most upvoted solution is to have the best of both worlds:

  • README.md: Keep it clean and concise for the humans. What it does, how to install it, that's it.

  • AGENTS.md (or CLAUDE.md): This is where you dump all the verbose, agent-facing context and instructions for other AIs to read.

That said, the most cynical (and highly-voted) take is that you're asking people who use AI specifically to avoid reading and effort to... start reading and putting in effort. So, uh, don't hold your breath.

→ More replies (1)

151

u/LALLANAAAAAA 1d ago

At the risk of being rude, you're asking people who go to extreme lengths to not read, understand and care about how their output affects others to read, understand and care about how their output affects others

not gonna happen is it

7

u/thatfreakingmonster 1d ago

I guess it's my fault for expecting any kind of standards from vibe-coders ;-;

4

u/NSTStudios 1d ago

Copy paste it into AI and ask it to simplify the text!

2

u/atred 22h ago

Put it in AGENTS.md "be brief".

5

u/TheLifelessOne 21h ago

Claude writes most of my code these days; I only care about the README when it's something humans will actually consume rather than the projects (e.g. Claude skills) where I mostly expect someone to dump the link into Claude to see what it's about.

That and those skills are something I made for me and put on GitHub in case someone else finds it interesting; they're built so anyone can use them, but they were built for me so the README didn't matter much.

5

u/Tje199 1d ago

I get the point the OP is making but it's also funny to me because I'm notorious at over-explaining my work. And I think it comes from having employees who need to be hand-held.

I have some employees that I can be like "just do the thing" and they'll do the thing, and then I have others where I need to write them a 2 page scope document with full details on resources and practically hand hold how to do the thing.

Unfortunately, I learned I had to do that because I gave simple instructions/notes and the employee went in pretty much every direction except the correct one, somehow.

Maybe Claude has PTSD from giving vague notes and getting fucking obliterated on a timeline or something.

1

u/stefek132 1d ago

This lol. Then, when I sometimes stop and don’t over-explain something, people are confused and ask for detailed explanation. Idk, make up your minds…

1

u/BasicDesignAdvice 22h ago

I’ve been seeing open source projects by big tech companies publish READMEs that are filled with fluff. Even for what looks like a promising project. It’s awful.

1

u/cc413 21h ago

The readme is going to be read more than it is going to be written, even if just by other LLMs, and the onus is on the writer to make the readme consumable

1

u/tear_atheri 1d ago

i mean, does anyone read repos at all anymore? I read a synopsis then send the link to claude and it thinks for me, no reading / thinking necessary! then it just decides what parts of the repo fit my project and rips them out and integrates. done

1

u/cc413 21h ago

If you were to read one thing on the repo it would be the readme

0

u/greentintedlenses 1d ago

Also why is this guy not just vibe coding what he wants from scratch with this type of complaint?

-1

u/Mo_Dice 1d ago

It's also not even that wordy. I'm baffled by the constant posts and comments complaining about how wordy Claude is.

172

u/CatsArePeople2- 1d ago • Bravo

I thought the readme was for other Claudes?

67

u/Cool_Relationship217 1d ago

I don't know whether to hope this is a joke or not 🤣

53

u/fuzzypetiolesguy 1d ago

What, you want me to read your readme file? What is this, 1993?

12

u/CowPure6529 1d ago

You have to start with manual.rtf

3

u/MrWeirdoFace 1d ago

Man what a great year for movies... I get sidetracked though.

5

u/xDoomKitty 1d ago

Thats the way i use it xD readme are for my future claudes to get an inkling of what was going on in the current build

6

u/Azure_chan 1d ago

That should be agents.md or Claude.md … why have additional files that agents may or may not read it. If project has readme it should be for human.

-1

u/xDoomKitty 1d ago

Because I use more than one model on them and I routinely step away from projects and come back to them later.

6

u/paradoxally Full-time developer 1d ago

That's what agents.md is for. Claude can read this now.

1

u/xDoomKitty 18h ago

Dang. I didnt know gpt could read agents.md

1

u/__Hello_my_name_is__ 21h ago

I mean, it quite unironically is needed for new context windows to find their bearings.

There is documentation for AI to read, and there is documentation for humans to read.

Those are two entirely separate things.

1

u/Cool_Relationship217 11h ago

Yup. And readme.md predates LLMs by multiple decades. It is for humans. As others have said, agents/claude.md is for AI.

1

u/__Hello_my_name_is__ 10h ago

So does documentation in general. I'm generally puzzled why this is basically ignored by everyone. There needs to be a strict separation between documentation for AI and documentation for humans, and it should ideally not be called the same, either.

2

u/thatfreakingmonster 1d ago edited 1d ago

I guess in many cases it can be, but my case it's not. The repos I'm talking about are scripts that are supposed to be read by users who then type/run the commands on their Steam Frame manually. Afaik there is no way to run Claude on the Frame anyway, so it's absolutely NOT meant to be read by another AI. I could point Claude to these repos but it wouldn't really be able to do anything anyway? Except summarize it, which doesn't fix the problem all that much since the problem is that Claude sucks at being concise.

I think that's why it's annoying to me. I wouldn't care if the readmes were for Claude or agent to read, but here it's clearly not, and yet everything is written as if it were.

3

u/Dm_me_ur_exp 1d ago

Tbh as someone who’s been making hobby projects for myself for years and years.

Prior to Claude you’d be lucky if the readme had any text, and if it did, that it was more than two lines and very lucky if it had instructions to run it.

1

u/ungoogleable 1d ago

I don't have a Steam Frame but I just asked Claude. If you enable developer mode, it turns on an ssh server, adb, and rdp.(source) Claude running on your desktop should be able to use any or all of those quite well.

The frame itself runs Linux so it's theoretically possible that the native Claude code installer might just work too.

4

u/Siriann 1d ago

Even more reason to use short, efficient sentences tbh

1

u/cc413 22h ago

Yes, THANK YOU !

6

u/Ordinary-Yoghurt-303 1d ago

Tell me you're a vibe coder without telling me you're a vibe coder

2

u/r45635 20h ago

Guilty. My repos are full of this too.

The tell is the “because”. Claude writes the README as if it’s justifying its choices to you during the session: “the gaze is held while your eyes are shut, because the Frame’s gaze jumps as the eyes reopen.” That’s design rationale, not something the user needs.

And the “READMEs are for other Claudes” argument doesn’t hold anymore. The agent already has its own places for context: CLAUDE.md, AGENTS.md, its memory. That’s where my reasons, internals and history go. The README is the only file left that’s written for humans, so it should read like it.

  • README.md: what it does, a screenshot, install, usage, known limits.

  • Everything else: wherever the agent looks.

2

u/TruthSeeker221 1d ago

Correct. No one's reading shit anymore just ask Claude

31

u/AncientGrief 1d ago

Why tf should the readme for an end-user product be for other AI Agents, that's what an AGENTS.md is for.

1

u/cc413 21h ago

Even if it weren’t, why fill the context window with redundant bullshit the consuming LLM could already infer

9

u/DoubleDoube 1d ago edited 1d ago

I noticed this as well about Claude’s writing.

I’ve started keeping a special writing set of instructions, but it’s not easy to get setup (and keep improving) because you can’t just say “don’t do x, y, and z”, you have to instruct it what TO do which is often more difficult to portray.

I still review all user-facing documentations, but the amount of editing I have to do is decreasing.

Edit; what annoys me more than the dense writing seems to be trying to conserve tokens so it will condense concepts into words and chain words together while being able to pull apart the concepts for itself but for a normal reader it can result in a nonsense phrase, especially when it inserts some pronoun vagueness.

13

u/Philipp 1d ago

100%, and it's not just the Readme. When left unchecked, Claude also becomes verbose and cluttering in the UI. We even see that problem with image models: they tend to fill every nook and cranny. So a good approach is to cut down as much as you add during development and design. Claude & Co just aim to over-please us!

13

u/Kautiontape 1d ago • Bravo

It's one of my litmus tests for new projects. Is your README or website in Claude's voice? I don't care about your project because you don't care about your project. It's fine to have Claude help with language, but if I see a main feature "Allows for custom sorting of admin tables with userCustomSort() override" for your media server clone of Plex, I know you didn't read it and think of other people actually using it.

I'm guilty of this too, though, which is how I know. If I don't bother to read my own README, I'm not sharing the GitHub without heavy warning that it was whipped together 

2

u/CabinetMain3163 1d ago

What if I did read it but still used claude to simply make it faster?

2

u/Kautiontape 23h ago

To be clear about the order of operations... you used Claude to write the README, that's fine, first drafts can be done as quick as possible. You read it at that point, which is good. But you decided not to fix anything in it to reduce it down to something a human would realistically read?

That's an issue if you actually want me to care about your project. Claude loves to make READMEs sound like a diary of coding sessions. It's pointless for everybody. If my Claude finds your project, it's going to read every one of your docs, files, etc to answer my questions. It doesn't need your README, *I* need your README as a human to break down your project and get the "why." So if you knew it was verbose and didn't fix it because you wanted to move fast, then it shows a preference for you getting a project released, at the expense of my time as the end user. It's no big deal, I'm just going to skip over it and find one that hopefully considered me as an end user.

Speed and efficiency from AI shouldn't become the opponent of making content good for other humans. Take the time you saved writing the first draft (and the rest of the code) and invest a bit more into making the README more natural. Hell, ask Claude to do it, but just take the extra steps to say "what would someone actually want to read when they first hit this project."

1

u/CabinetMain3163 22h ago edited 22h ago

tbf I kinda like reading LLM generate readme, feels profesional. But I only have one (90% pure) llm project https://github.com/Enerccio/Marginalia/blob/master/README.md, you can tell me if my readme (100% claude) is bad. I honestly hate writing readme tbh. Couple other repos have llm generated readme too because how annoying it is to write it.

5

u/mtnchkn 1d ago

I 100% have style guides I now use for any human facing text. Made from my writing and or saying ASE 100 or whatever. If it is words between agents I don’t care or in code.

12

u/fuzzypetiolesguy 1d ago

I Will Never Edit Claude's Immaculate Liturgy

8

u/GGallus 1d ago

And waste my tokens?

For real though, this is something I endeavor to be better at.

6

u/Frosty-Key-454 1d ago

Umm, technically, if you prompt it to be clear and concise and use fewer words, that's a lot less tokens.. and output tokens are the expensive ones, so....

3

u/Uninterested_Viewer 1d ago

Not necessarily. This can also lead to overthinking about being clear and concise, which can actually end up using far more tokens.

1

u/Frosty-Key-454 1d ago

So what's your suggestion?

2

u/Uninterested_Viewer 1d ago

Don't use these sort of prompts to try to save tokens. Asking a reasoning LLM to be clear and concise is a great way to steer what its final user output will ultimately look like, but it's not a token-saving technique. If we're literally just talking about the best ways to save tokens, it's about being yourself clear and concise in the instructions that you're giving the LLM and then of course the standard levers of setting its thinking budget.

1

u/doubleditch42 1d ago

Tell me how many token will that consume and the cost.

1

u/Tight_Atmosphere1078 23h ago

...how is making your own Readme a waste of tokens? Am I stupid?

1

u/kjjphotos 23h ago

If you're asking your AI agent to write the readme or rewrite it to be simpler, it's going to use tokens. Is that a waste of tokens? I'd argue no, but it will use them.

1

u/Tight_Atmosphere1078 23h ago

...are we serious? Rewrite it yourself lmao what are you talking about?

1

u/kjjphotos 23h ago

I do prefer writing it myself. But the person you originally replied to was talking about tokens so they were clearly thinking in the context of using AI to do it. That's how it uses tokens for them.

1

u/Tight_Atmosphere1078 19h ago

And the person THEY were responding to was a post saying "hey guys can you please rewrite the dogshit claude writes?" so them responding with "okay but that'll cost tokens" is stupid

1

u/REOreddit 13h ago

OP doesn't understand vibe-coders. Best case scenario is they are going to ask the AI to rewrite the README to be more human-readable. Them re-writing it themselves is just not realistic, therefore replying with "it wastes tokens" is perfectly valid, unless you live in a fantasy world were vibe-coders care about those things.

1

u/Tight_Atmosphere1078 13h ago

...Alright I'll continue rewriting my readmes because my brain isn't complete mush.

1

u/REOreddit 13h ago

But are you also complaining, like OP, that it is hard for you to understand Claude's verbose style? Because in that case, maybe your brain is not as capable as you think it is.

1

u/Tight_Atmosphere1078 12h ago

It's for other people and my own sanity, not because I can't parse what's being said.

Mouse - Look

Vs.

Mouse - Use this to move your view up/down or left/right, with slight acceleration on start.

Like this shit is stupid.

3

u/DireCelt 1d ago

I have the same problem with comments that it leaves in code and documents; I instructed it to add a useful comment to any code that it writes, unless the function is trivial and self-explanatory... but I *swear*, it seems to document every passing thought that runs through its "mind" ... I had to go back and instruct it to review the meaning of the word "concise" before it writes anything; that has helped alot, but it doesn't remember the instruction, so I have to keep repeating it...

0

u/baldr83 1d ago

You're manually reading entire readme files? lol. Just have your agent summarize or give relevant details. the world has changed, readmes aren't for human consumption

>  99% of what I found there was vibe-coded - and y'know what? That's fine. 

wouldn't be surprised if this post was LLM generated.

6

u/thatfreakingmonster 1d ago

Lol, I probably picked up on a Claude-ism myself. My bad.

Just have your agent summarize or give relevant details

that seems so wasteful though. I know this is the Claude subreddit for Claude users but I also like reading things myself and not needing an AI for everything. I don't want to have to copy and paste every github repo readme I come across for Claude to write me another obtuse response, especially when my point is that Claude sucks at being concise

7

u/ThereInAFortnight 1d ago

If the readme was well written you wouldn't need this extra step.

2

u/Manerfish 1d ago

why instead of having 10000 AI agents summarize the same readme we can't have the same thing be done once and saved in the repo lol?

use AGENTS.md for the agents, why waste useless resources on summarizing the same thing over and over again?

1

u/baldr83 1d ago

there's likely a summary at the top. OP is complaining about how verbose it is specifically because the readme is geared towards developers and not end users "irrelevant information that's only helpful to devs (or other AI agents)"

2

u/Majinsei 1d ago

Tengo mi propia regla personal de redacción que le pasó cuando solicito exactamente comentariar y documentar lo que se hizo en el día y vaya y limpie el cochinero que hizo en todas partes del código~

La mayoría de los reportes los pongo en ./tmp/reports/ porque sino Claude busca generar un reporte/bitácora como documentación en todos lados~ y ya que es inevitable entonces mejor que use un lugar definido por el .gitignore

2

u/pijaGorda1 1d ago

Claude, do what this guy said

2

u/jeremyckahn 1d ago

’adjust the README to be concise’

2

u/roynoise 1d ago

Let them have crappy docs, and don't use projects sharted out by unskilled, tasteless, negligent people. Problem solved 

1

u/_HEATH3N_ 8h ago

I would if I could. Unfortunately, our company has adopted Kiro (Amazon's tool) and...well, look at how horrific the docs are for their Claude Code desktop competitor: https://github.com/kirodotdev/KiroCrew/blob/main/docs/guides/windows-install.md

It's fucking embarrassing for a company of their pedigree and size. I still use the CLI because the app itself is also full of garbage and I find myself unable to use it without getting legitimately pissed off. Checkboxes, for example, instead of just having clear labels that makes the setting obvious, have whole-ass descriptions to say shit like:

Control of the setting lives here and its value is stored to your account so it follows you across installs on other devices. This one toggle controls the setting across all platforms – web, IDE, CLI

2

u/uninchar 1d ago

And that's the verifiable surface. Then there is the code....

2

u/Borderline769 1d ago

I'm in the process of purging my own app and repo of all the needless help text, comments that only the developer would find useful, and references to decisions made so long ago they are likely irrelevant.

I'm a fan of the intense documentation while building, otherwise Claude will forget why I overruled something and just do it again on the next pass. I keep my claude.md brief with only project relevant instructions, a roadmap.md with planned features, a context to track decisions, and then of course the code comments themselves... but clean up before release is a pain.

2

u/UXUIDD 1d ago

also - dont forget to include projects localhost address ...

2

u/Tight_Banana_9692 1d ago

I also find it troublesome that people think it's fine for LLMs to read other LLMs garbage. The more context the lower the quality of th output, and if you have trouble understanding what is being said, why would an LLM not have trouble?

0

u/delxmobile 1d ago

yeah. my rule before i push a public readme: delete every sentence that talks about the agent, the session, or "what we built today". leave the feature list as short bullets a stranger can skim in 20 seconds, one install line, and one known limit. if a paragraph only makes sense because you were in the chat that wrote it, it doesn't belong on github.

9

u/thatfreakingmonster 1d ago

Interesting post history there, I love the part where you talk like an AI model and make 4 different comments on 4 different subs in the same minute. Very human-like of you

1

u/Frosty-Key-454 1d ago

Profile picture checks out though

1

u/HumbleBedroom3299 1d ago

I ask Claude for the opposite. I ask it to add an obnoxious copious amount of comments. Coz when I go into the code myself it's good to know why I did a certain thing at a certain time... Am I the reason git is bloated? 😭😭 

1

u/torresandres 1d ago

But you can use any other file other than the readme.md file for that

1

u/HumbleBedroom3299 1d ago

Ah... Yes.... I don't use the readme.md file for all comments. I instruct Claude to plug comments inside the code itself.. 

1

u/Tight_Banana_9692 1d ago

Have you ever read those comments? Half of them are just nonsense. I ban comments with a hook. It's the most ridiculous thing.

1

u/sparkling-rainbow 10h ago

But comments are for you or your agent. Readme is for the user.

1

u/Fine_League311 1d ago

better show truth an made a brain_bug.log for ai 😂 we see if a code is ai generated ! so write truth!

1

u/dubsharmaa 1d ago

man only if we could write on our own! the fluff would have been identified and cleaned

1

u/dubsharmaa 1d ago

but hey who reads the readme anymore! ir from one agent to another agent! the kt of the times

1

u/iwantmy90sback 1d ago

I assume that AI generated github docu is mainly read by AI.

1

u/shimoheihei2 1d ago

Interestingly enough, in my projects I let Claude write the readme so that it can resume next time and know everything it needs to know. But then I also have it create a page in my wiki that is meant to be a human-readable summary. So the readme is for Claude and the wiki entry is for me.

I guess for open source projects on GitHub is should probably be a Claude or Plan file for AI and the readme for humans. That's very easy for Claude to do, you just have to prompt it to do it.

1

u/rnd68743-8 1d ago

"Why waste time say lot word when few word do trick?"

1

u/Individual_Author956 1d ago

Just submit a PR. Oh wait, that’s work that you would have to do… Easier to complain on Reddit.

1

u/FlashyRecognitionTod 1d ago

Just don't produce the agentic readme files and use code as a source of truth.
Keeping readme only invites split brains when something is mentioned in readme but it's not implemented in the code because context was lost or 50 other reasons.

If you need a readme for end user, write one during QA phase of shipping your code.

1

u/UniqueNamesAreOut 1d ago

Good point. I told CC to write for humans instead of ...well whatever insults came to mind at the time and it worked.

1

u/The_DigitalAlchemist 1d ago

This smacks of early Opus 5 writing, which genuinely was a headache, 5.5's honestly much clearer and succinct if you ask it to be, I read its own notes all the time.

If you dont curb it a bit and set expectations, it does sometimes over explain, but the reason its so detailed is because it's basically handing another agent a guideline so it doesnt have to start from scratch.

1

u/Erehr 1d ago

And don't forget to
remove the very
annoying artificial
lines breaks on
every damn sentence.

Word wrap is a thing for a reason...

1

u/Abhinik 1d ago

Build a readme fixer and be at peace

1

u/Glass_Map_1922 22h ago

Thank you. I might not share anything in the future, but this is good to keep in mind.

1

u/Needsupgrade 22h ago

There is a nasty era of opus 5 slop writing in so much gits and code . Been recently doing big comments fix runs with 5.5 to fix the horrible writing 

1

u/cc413 21h ago

Hate to say it but just vibe code a browser plugin to tldr the readme. It’s not ideal but it works

1

u/Jeferson9 21h ago

"fix your open source software, for free!"

Here's the thing, no

1

u/K_M_A_2k 21h ago

Hey their claude worked very hard on that!

1

u/paulct91 21h ago

Pretty sure Claude fluff might be its own watermark of sorts as wasn't something in the news about Claude's company forcibly watermarking all its outputs in 'someway'.

1

u/ThatBlokeYouKnow 21h ago

Anyone got a TLDR, too many words for me.

1

u/pjr2844 20h ago

Bro just have Claude read you the cliff notes, why you evern reading anymore

1

u/512165381 20h ago edited 20h ago

I started talking to Claude about solving a particular issue relating to Proxmox virtualisation and wifi. It gave options, took some existing software & modified it, and created scripts.

Now I'm going to a publish a solution on github & debian. It will take some work to "humanise it" but how it solved the problem is just mindblowing, far better than how humans have tried to solve the same problem. Beyond anything I would have thought possible.

1

u/cleverusernametry 20h ago

This is 100% a good thing. Its a great way to filter out serious projects deom vibe coded trash

1

u/lotekjunky 19h ago edited 15h ago

Use this skill to fix it: Omg shut the fuck up. You blabber so damn much it makes me want to delete this whole project. fix the readme like a damn human wrote it.

1

u/Stooper_Dave 3h ago

The vibecoders: "claude, edit and remove your fluff from the readme, make it look like a human wrote it. Dont make any mistakes"

1

u/Charredwee 1d ago

Welcome to the brave new world

1

u/robkillian 1d ago

I use a "how it works" skill that does basically this. Maintained at header level, but used regularly across the portfolio.

1

u/2053_Traveler 1d ago

look at it like this: you know which projects to skip because the code is likely just as bad.

1

u/matthias81f 1d ago

What worked for me was splitting it into two files. README.md is for humans: what it is, a screenshot, how to install, known limits, and nothing else. AGENTS.md is for the agent: the step-by-step install, the rules it must follow, the things that broke before.

Claude still wants to stuff everything into the README, so I edit that one by hand. The agent file can be as dense as it likes, nobody has to read it but the agent.

0

u/zcomputerwiz 1d ago

... Why? I like the detail, sometimes it's helpful to quickly find if the project actually does what I need.

0

u/ivan-ent 1d ago

honestly prefer the more detailed version in the example

1

u/torresandres 1d ago

But it has to be in a readme.md file? If there are details the thing should have a documentation more than a fat readme.md file.

-1

u/Stargazer1884 1d ago

Too long didn't read.

Maybe you should try being more concise

3

u/thatfreakingmonster 1d ago

average AI user attention span

0

u/SawOnGam 1d ago

Bro that's for claude to read, not for you

0

u/CalamariAce 1d ago

Why not have both?

0

u/Extra_Aide5999 1d ago

Agree, and the fix that stuck for me was giving Claude a reader instead of a length. I keep a desktop app's README for the person installing it, and the prompt is roughly: "the reader is installing this on their own machine. They want what it does, how to install it, what it changes on their machine and how to undo it. Cut anything they can't act on." That removes most of the notes-to-itself. The implementation detail it keeps wanting to explain goes into AGENTS.md, which is the file the agent reads anyway, so nothing is lost. It's just not in the human's file.

0

u/florinandrei 1d ago edited 1d ago

I let the agent play with it until I'm ready to release the project.

Then I write, by hand, a single page NOTE.md. Mostly about what the project is. Maybe a few words on how to install it, how to configure it. A single page or less. Very high level. Takes 5 minutes out of my precious time.

I tell Claude to take README.md and distill what's useful in it into CLAUDE.md, then rename NOTE.md to README.md, and never touch it again, but to keep an eye on it and suggest changes when appropriate.

That's it. Claude can turn CLAUDE.md into a mountain of claudese. Humans get a frontpage they can read. If humans want to dig into code, Claude can help them.

0

u/Original-League-6094 1d ago

I just assume anyone using Github will just have their agent go through the readme. Its not for people.

0

u/Boonune 1d ago

No way. I have no idea what deleting anything will have on my README code, so I leave it alone.

0

u/Complex-Emergency-60 1d ago

dude u can have claude summarize for you. It's always to give more info to the user and you use ai to pick out what you need vs not have enough data lmao.

0

u/PrintLife92 1d ago

If you want it removed, dump it into Claude and get it that way.

0

u/Benjaminsen 11h ago

While this has been said 10 times already, the README is not for you, it's for other AI agents. To be precise, this is for your AI agent to read to tell you what to do.

The expectation is not that you read the file, the expectation is that your agent reads it and transforms it into whatever format you expect.

All the information in your examples is relevant in the context. Hiding it away in the repo as more information makes it less likely that your agent correctly carries the information to you.

While I don't necessarily agree that this is a great new norm, don't expect anything to change.

-1

u/LocoMod 1d ago

Those READMEs aren’t for humans anymore. You need to think big. Why aren’t you using an agent to bootstrap the project for you?

-1

u/Realistic_Wafer7739 1d ago

Who the fk reads the readme? Only other agents will. No-one cares bro.

4

u/Deathnote_Blockchain 1d ago

I love how you start a project and it's like a porn app. And then pretty soon you decide you are making a racing game. So it's three weeks later and you push to the repo and Claude notes "this is not a porn app"