Agentic AI
8 mins
Agents made writing code cheap, but reading it is now the bottleneck. How naming rules, a shared vocabulary and a review routine can make agent-written code read like a story again.
By Srijan, founder of WBOS · November 2026 · ~8 minute read
The short version
I’ve been writing code for the last 15 years, and it’s only since Opus 5.5 came out that I’ve started relying heavily on code written by agents. These days most of my development time goes into writing and refining specs, and then reviewing what comes back.
And honestly, reading thousands of lines of changes every day is a pain, and it’s very easy to get lazy and let anything that passes the tests go to production. But any experienced developer knows the cost of code they don’t fully understand: how it works, where each piece of logic lives, and what will break when you change it. You can already see the effect in the falling quality of software, even at the big tech companies.
I don’t blame the developers, though. Review used to be just one step in the process, and now it has become the bottleneck. When there’s more code to read than a person can actually read, rubber-stamping is what happens, so the real question is how to make agent-written code faster and safer to read.
By default, code written by agents looks clean because it’s formatted, typed, tested and well structured. But in my experience it often isn’t that readable for humans: it’s technically correct, but when you try to skim through it, it keeps breaking your flow.
Good human-written code (not counting all freshers) reads like natural language, with verbs, nouns and prepositions, so you can read it top to bottom like a story. Its vocabulary comes from the words the team uses every day, whereas an agent’s vocabulary is much broader, so it reaches for words nobody on your team actually says and the story gets harder to follow. My hunch is that agents also lean towards shorter names to save tokens, though I can’t prove that. Either way, here’s what it looks like in practice:
async function procPayout(req: Req) {
const acct = await resolveSellerCtx(req);
if (!acct?.meta?.kyc) return handleIneligible(acct);
const amt = calcNet(acct.bal, acct.cfg);
return dispatch(acct, amt);
}
That’s correct code, but every line makes you stop and decode something. What’s a “seller ctx”, what does procPayout actually do, and where does dispatch send things? Here’s the same logic written to be read:
async function releasePayoutToSeller(request: PayoutRequest) {
const sellerAccount = await getSellerAccountForRequest(request);
if (!sellerAccount.hasCompletedKyc) {
return rejectPayoutForUnverifiedSeller(sellerAccount);
}
const payoutAmount = calculatePayoutAfterFees(sellerAccount);
return sendPayoutToBankAccount(sellerAccount, payoutAmount);
}
You can read the second version out loud and it tells you exactly what happens: get the seller’s account, reject the payout if they haven’t completed KYC, work out the amount after fees, and send it to their bank, all without opening a single other function.
The same principle applies to every name. A function called sellerAccount could return an account, an ID, or a yes or no on whether one exists, whereas getSellerAccountId tells you what it does and what it returns without you having to check the definition. This is one of the oldest fundamentals of coding, and it matters even more now that a human is reading code they didn’t write.
Once you start looking, the same few patterns come up again and again:
ctx, acct, cfg, svc and tmp, which are small on their own but together turn reading into decoding.?. fallbacks everywhere, which hide the path the code actually takes.Here’s the moment that convinced me that reading every line still matters. I asked an agent to fix a security loophole in the read and write permissions on one of our models, and the fix worked and all the tests passed. But when I read the diff carefully, I saw that the agent had introduced a brand new way of blocking access, even though the codebase already had a method that did exactly that job.
If I hadn’t read that line, we would now have two different ways of handling permissions. Nothing would have broken that day, but the next time someone, human or agent, came to change permissions, they would have to work out which one was the real one, or they’d update one and forget the other, which is exactly how security bugs get made.
This is what I call comprehension debt: each change looks fine on its own, but an agent doesn’t know a solution already exists unless it goes looking for it, so left alone it keeps adding new ways to do old things. In the long run the code becomes unmanageable, and you pay the debt back during an incident at 2 a.m., or six months later when you need to change something and nobody understands it any more.
My permissions fix was caught in time, but not every team has been so lucky this year.
In March, the Financial Times reported that Amazon called its retail engineers to a mandatory meeting after a “trend of incidents” with a “high blast radius”, which an internal briefing note linked to “Gen-AI assisted changes”, and one of those outages left customers unable to check out for around six hours. Amazon now requires senior engineers to sign off on AI-assisted changes made by junior and mid-level engineers, and although it disputes that AI-written code was to blame, the new rule tells you where it sees the risk: in what gets through review.
In February, Cloudflare withdrew about 1,100 IP prefixes from the internet for roughly six hours, after a cleanup task sent an API request with an empty value and the API read that as “all prefixes” rather than none. AI had nothing to do with it, but Cloudflare’s own postmortem says the testing and code review “focused on the BYOIP self-service API journey” and never covered the path that broke. That’s the review bottleneck in a sentence: the reviewers checked the story they expected, not the one the code actually told.
To be fair, not every outage is a code-review failure. Microsoft 365’s outage earlier this month has been put down to a network change, and the four-hour FAA ground stop in the US to an overloaded router, with officials explicitly ruling out AI. But as agents write more of our code, I expect a growing share of incidents to start with a change that nobody fully read.
Domain-driven design has a name for this idea: a ubiquitous language, meaning one set of words that the business, the code and the team all share. Now that agents write so much of the code, it’s worth writing that language down explicitly.
Keep a short glossary in your CLAUDE.md, for example “We say seller, never merchant or vendor. We say order, never purchase.” Because the agent’s vocabulary is broader than your team’s, you have to tell it which words your team actually uses, and once the glossary exists, the agent will stick to it more consistently than most of us do.
Here’s a starting point you can copy and adapt, and the last naming rule is the one that would have caught my permissions problem.
## Naming and readability - Name functions as a verb plus what they return: getSellerAccountId(), not sellerAccount(). - get... throws if the thing doesn't exist. find... returns null. load... fetches from the database or network. - Booleans start with is, has, can or should: isPublished, hasCompletedKyc. - No abbreviations: account, not acct; request, not req. Allowed: id, url, api, html. - Use the words in the glossary below. If a concept isn't there, ask before inventing a new word for it. - A function should read top to bottom like a paragraph: high-level steps first, details in the functions it calls. - Before adding a new helper, guard or check, search for an existing one that does the same job and reuse it. If a second one is really needed, explain why in the PR. ## Glossary - Seller: a business that sells on the platform. Never "merchant", "vendor" or "store owner". - Order: a confirmed purchase. Never "purchase" or "transaction". - Payout: money we send to a seller. Never "settlement" or "disbursement".
This is where agents have a real advantage over us. Plenty of human code is a mess too, and a style guide is only as good as the people remembering it, whereas an agent follows a written rule every single time. So agent code may be hard to read by default, but with the rules in writing it can end up more readable than code written by hand.
Better rules shrink the problem, but you still have to read the code, and these habits have made my reviews faster:
id-length and @typescript-eslint/naming-convention catch the easy cases, so your attention goes to the hard ones.Agents have made writing code cheap, but reading it costs as much as it always did, and not understanding it costs more than ever. The teams that do well with agents will be the ones that keep their code readable for the humans who are still responsible for it.
If you can’t read the code like a story, you don’t really own it, you’re just hosting it.
I’m curious what others are doing: what naming rules have you put in your CLAUDE.md, and which ones made the biggest difference to your reviews? And if you think agent code is perfectly readable as it is, I’d like to hear that too.
If your team is shipping agent-written code and wants help setting up the specs, rules and review process around it, this is the kind of problem WBOS works on. Book a 30-minute build session.
Srijan is the founder of WBOS, an AI and product engineering studio. The code examples in this post are simplified illustrations, and the incident details are as reported at the time of writing, with some root-cause investigations still open.
Partner. Build. Scale
Partner. Build. Scale
INFORMATION
WHERE WE WORK
Let's discuss how we can engineer it into reality. We are ready to partner with you.