You’ve felt it. That sinking feeling when you open a project and the README is a perfect, sterile paragraph that tells you nothing about the person who made it. The code compiles, the tests pass, but something is off. You can’t trust it. And you’re right not to.
We are drowning in a sea of machine-generated code that looks like human effort but lacks human understanding. LLMs can now produce entire repositories in minutes—clean, idiomatic, and utterly hollow. The traditional README, once a humble guide, has become a camouflage. It pretends the code is a coherent product of human reasoning. It’s not.
The README is no longer a guide to your code. It’s a confession.
This is the paradox of AI acceleration: more code leads to less comprehension. Every line generated by a model adds to the burden of trust. You can’t audit a million lines of slop. You can’t reason about code that was never reasoned about. So what do you do? You start flagging.
One developer I know added a note at the very top of his README: “This project is 100% LLM-written. Don’t trust anything below.” He didn’t apologize. He didn’t explain. He just told the truth. That note is now the most valuable part of the repository.
We are entering the era of the Human README—a deliberate, explicit disclaimer that separates human intent from machine generation. It inverts the traditional software hierarchy. The code used to be the ground truth; the README was just a guide. Now the README is the truth, and the code is a maybe.
If you’re not adding a human-written warning to your README, you’re doing it wrong.
Think about it. When you clone a project, what do you read first? The README. If it’s written by a human—with typos, opinions, and contradictions—you know there’s a mind behind it. If it’s polished, neutral, and generic, you know it’s AI. And that’s fine, as long as the AI content is flagged. The problem is when the flag is missing.
This is not about Luddism. It’s about survival. The industry is moving toward a future where every repository is a mix of human and machine. Without explicit markers, we lose the ability to trust anything. The Human README is the new contract: “I wrote this part. The rest is LLM slop. Proceed with caution.”
Some will argue that this breaks the collaborative spirit of open source. They’ll say it’s elitist, that it creates a hierarchy of authenticity. To that I say: good. A hierarchy of authenticity is exactly what we need. Not all code is equal. Not all code deserves the same trust. In the age of AI, the most valuable thing you can write is ‘I don’t know what this does.’
The Human README is not a sign of weakness. It’s the only honest thing left. Start writing it. Your future self—and everyone else who touches your code—will thank you.
FAQ
Q: Isn't this just a trend? Why can't we trust AI-generated code if it's tested?
A: Testing catches bugs, not intent. AI code can be perfectly correct but completely unmaintainable—it lacks the reasoning and design decisions that humans need to understand and modify it. A Human README flags that uncertainty.
Q: What's the practical implication for my daily workflow?
A: Start every README with a human-written summary. If you use AI to generate code, add a clear disclaimer. This forces you to actually understand the code, and it saves everyone else from wasting time on false assumptions.
Q: Won't this discourage people from using AI-generated projects?
A: No—it builds trust. A project that openly admits its AI origins is more reliable than one that pretends to be human. The warning is a signal of transparency, not weakness. It's the difference between a used car salesman and a honest mechanic.