Clean code is bad for vibe-coding. For decades, the software engineering industry has put a lot of effort into making code readable — for example, books like Clean Code and Refactoring became influential because they focused on readability, maintainability, and improving existing code. And the progress is remarkable: we have come up with a lot of architectures to make code readable.

And for LLM agents readability is even more important. If an agent is like a senior software engineer with amnesia, they need to be able to understand the project with the least effort.

So why do I say that techniques that were crafted for readability are bad for agents?

Because humans read code differently.

Let’s say I have an endpoint with some GET endpoint. To see what it does, usually I would go to the controller, look for that endpoint, read the handler, it calls a service, the service calls a repository, and so on. So to fully understand it, without hallucinations and relying on the names, I would need to go through 5-6 hops of files.

If the code is written well, each hop would read something like 100-200 lines of code. So to really understand the flow, I need to read 500-1000 lines of code. Of course, we don’t do that. The human brain is very efficient and it would strip away all the things that are not related to my current task, and I would actually think only about a couple of lines each hop.

Agents “read” differently: they will digest all 1000 lines into the context.

Why is this bad? Dex Horthy popularized the term “Dumb Zone” / “Smart Zone”. He states that when approaching the end of the context window, models are getting worse and worse at performing tasks. It is recommended to keep your context window under 100k tokens with SOTA models as of now. HumanLayer’s post on advanced context engineering for coding agents also talks about context management, compaction, and keeping coding-agent context useful instead of just large.

100k tokens is around 2000-2500 C# lines of code, so this means an agent can only effectively understand 2-3 endpoints.

I see 2 ways of solving this problem: a custom harness that would read code as effectively as humans, or trying to design software to be more readable for agents. Ideally, both.

So how do we make code more readable:

  • reduce boilerplate as much as possible. Boilerplate is your worst enemy. Kill all ceremonies, reduce noise
  • make the full flow of business logic readable in a very concise way
  • reduce redundant comments and md noise — if they duplicate the code, it is just wasted tokens. Especially agent-generated .md. It is ironic that when you ask an LLM to write a plan for an LLM, it will do it in the most inefficient way, by making it super verbose.

We need to reevaluate our design approaches and think of how to write agent-readable code.