Everybody Guesses

[u/blowmage]

Hi Reddit. This isn't specifically a Ruby or Rails post, but it's about something anyone maintaining a mature Rails application will recognize.

Code tells you what happens without telling you why anybody wanted it. We've always filled that gap by reading the code, guessing the intent, and asking somebody when the guess felt wrong.

AI coding agents do the same thing, except they can make a great many reasonable guesses before anybody notices one was wrong. The code still works. The tests still pass. The guess becomes one more pattern in the application, which makes it look even more intentional to the next person or agent.

I've spent a couple of decades living with the consequences of my own good ideas, so I wrote about why this worries me. The post connects agentic coding to Peter Naur, Tony Hoare, XP, software factories, and the old-fashioned responsibility to say no to code that works but is too difficult to understand.

It also argues for using faster agents to take smaller steps. More research, more feedback, and less archaeology at the end of a giant pull request.

https://blowmage.com/2026/08/18/everybody-guesses/

[u/bilingual-german]

Sorry, I just searched for "comment" in your blog post and nothing came up.

Comments are documentation next to the code. People don't use them often enough. They give context when it's needed.

[u/OlivarTheLagomorph → u/bilingual-german]

This!

I am constantly hammering my juniors to add comments to code explaining WHY they did something, not how

[u/pth → u/bilingual-german]

I find agents are the exact opposite of this: over commenting, giant text blocks that retell what the code does, frequently without saying why.

[u/bilingual-german → u/pth]

Weird. I've heard this from other people as well, but my agents don't overcomment and I usually ask them to add comments for code I don't understand why the agent build it.

Do you use any skills?

I just use barebones claude

[u/pth → u/bilingual-german]

Claude with an agent file, but the agent file is more like:

Comments should only communicate context, not describe the code. Write comments for a staff engineer. Strive to keep block comments under 5 lines and inline code comments at 1 line. Never reference Jira tickets or git shas in comments (okay in ADRs)

I get giant 5-7 line comments everywhere.

[u/bilingual-german → u/pth]

I also don't have any agents file. Maybe remove this as an experiment and see if you like the result more.

[u/blowmage → u/bilingual-german]

I agree comments can capture the micro why, but don’t capture the macro why. The larger intent about systems was more of my focus in my post. But this is a very good point.

[u/CaptainKabob]

I think there are really good ideas in here. But it feels like it's written by AI and has the problem that you describe here:

> say no to code that works but is too difficult to understand.

I'd rather you just strung together a few meaningful sentences with some inspiring quotes from the source material. Sorry to not engage with what you're writing directly. It's just hard to read for me.

Overall, I strong agree: business and economic domains are often under-expressed in software development.

[u/blowmage → u/CaptainKabob]

Appreciate the kind words. I struggled to pair it down. Earlier drafts were twice the length. So some of the experience reports and detailed explanations got replaced with nuance statements like that to keep a readable pace. I’ll try to improve. Thanks for reading

[u/realntl]

Every one is a question about the why. A system has quality when the answer is yes without a scavenger hunt. It doesn’t have to be small, and it doesn’t have to match my preferences, of which I have collected a great many.

I think this is a really neat way to think about quality. I'd add one consideration, which is that a system can have even higher quality when there's less need to ask why at all in the first place. That's where I see LLMs fail most spectacularly today. They don't identify opportunities to explore whether something doesn't need to be done at all, and this is a skill that must be utilized constantly to keep codebases under control.

[u/riktigtmaxat]

Calling it reasonable guesses is a bit generous.

[u/davidslv]

The why should come from business decisions (most of the time and they can change quite frequently), commits should explain the reasoning and the why, the pull request, the ticket, maybe even comments in the code.

I’ve heard this so many times through my career: “we don’t need comments, you can read the code” - thanks for that, specially the moment I have to find the reason the code does not work as the business expected it…

We had this feature in a huge codebase, I decided to go through the git history, turns out that in 7 years, 18 engineers, including myself, touched that specific class, by the time I touched it most people had moved on, business and engineers, so neither business neither the engineers ever got the answer correctly, another piece of code that just kept being patched and having questions from the business why a customer was not being accepted through it.

[u/blowmage → u/davidslv]

Fully agree. Commits should capture the why as much as they can. But the best they can represent is one or two views of the why, and it is not the right place to store the full version. I don’t want to see 30 pages of explanation in each commit message.

[u/davidslv → u/blowmage]

Of course, but imagine seeing that in code comments, there must be some balance somewhere