okay so this is gonna sound ironic. maybe even a little embarrassing.
Most of us — and yes, I'm including myself here — use AI tools to write code every single day. GitHub Copilot, Cursor, Claude, whatever. We let the AI generate entire functions for us. We prompt it to refactor our components, debug our APIs, write our tests.
And yet, somehow, the code we feed back into those same AI agents is a mess that confuses them completely.
I noticed this in one of my own projects a few months back. I was building a full-stack app — Node/Express on the backend, React on the frontend — and I asked Cursor to help me trace a bug through three files. The AI just... gave up halfway. It kept referencing variables that didn't exist, confused one function's output with another's, and confidently wrote code that broke things even worse.
At first I blamed the model. Then I looked at my code.
The Problem Nobody's Talking About
We've spent years writing code for ourselves. Or for teammates who will hop on a call if something's unclear. Or for future-us who will eventually remember what we meant.
But AI agents don't have that luxury. They don't ask questions mid-read (well, the good ones try, but there's limits). They parse your code with a context window — a fixed amount of tokens they can "see" at once — and they try to infer everything from that snapshot.
If your code is ambiguous to a human reading it cold, it's invisible to an AI agent trying to reason about it.
As of early 2026, models like Claude Sonnet and GPT-4o have context windows of 200k-450k tokens. That sounds like a lot. But a production codebase? Hundreds of files. Thousands of dependencies. Layers of abstraction. No AI agent sees all of it at once.
So when you ask Cursor to fix a bug that spans four files, it's reasoning under partial information. Your naming, your structure, your comments — all of that becomes the difference between the agent understanding your intent or hallucinating its way through your codebase.
What "AI-Readable" Actually Means
Before I get into the specifics, let me be clear: I'm not saying you should write code for AI. That's backwards. Good code is good code. What I'm saying is that the things which make code readable to a tired human at 2am are the exact same things that make code readable to an AI agent working with limited context.
AI-readable code is just... good code. We forgot how to write it.
The Sins We're All Guilty Of
1. Variable Names That Mean Nothing
This one's embarrassing because we all know better.
// this is what my code actually looked like last year
const d = await fetchData(u);
const r = process(d);
return r.f.map(x => x.v * x.m);
What is d? What's u? What's f? What the hell is v * m?
I know what it means. I wrote it. But if I paste this into an AI agent and ask it to add error handling, it has to guess what everything represents. And it will guess wrong. Or rather — it will guess confidently and write broken code.
Compare that to:
const userData = await fetchUserProfile(userId);
const processedUser = normalizeUserData(userData);
return processedUser.friends.map(friend => friend.views * friend.multiplier);
Now an AI agent can reason about this. It knows normalizeUserData probably returns something predictable. It knows friends is an array. It can infer what .views and .multiplier are about. Error handling writes itself almost.
2. Functions Doing Way Too Much
I had a function called handleSubmit in a React component. It was 180 lines long. It validated form data, made an API call, updated three different state variables, dispatched a Redux action, logged to analytics, and conditionally redirected the user.
When I asked Claude to help me add loading state to it, the response was almost hilariously wrong. It added setLoading(true) in four different places because it literally couldn't track the flow.
The fix:
// before: one 180-line monster
async function handleSubmit(e) { ... }
// after: broken down properly
async function handleSubmit(e) {
e.preventDefault();
const validationError = validateFormData(formState);
if (validationError) return setError(validationError);
setLoading(true);
try {
const result = await submitUserForm(formState);
trackFormSubmission(result.userId);
redirectToOnboarding(result.userId);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
}
Now every sub-function has a single job. An AI agent can understand, modify, or extend any one of them without needing to understand the rest of the 180-line mess.
3. Magic Numbers Everywhere
# what does 86400 mean here?
if time_diff > 86400:
send_reminder_email(user)
I've seen this in so many codebases. Including ones I wrote. The AI has no idea that 86400 is seconds in a day. It might assume it's a timeout value, a database ID limit, a file size — anything.
SECONDS_IN_A_DAY = 86400
if time_since_last_login > SECONDS_IN_A_DAY:
send_reminder_email(user)
Now it's obvious. To a human. To an AI. To you when you come back in three months.
4. Missing or Useless Comments
Two kinds of bad comments:
// no comments at all (bad)
async function sync(items, flag) {
if (flag) return items.filter(i => i.s === 'a');
return await bulkUpdate(items);
}
// completely useless comments (somehow worse)
// this function syncs items
async function sync(items, flag) {
// filter items if flag is true
if (flag) return items.filter(i => i.s === 'a');
// otherwise update
return await bulkUpdate(items);
}
Neither of these help an AI agent understand why this logic exists, what edge cases it handles, or what flag represents.
/**
* Syncs inventory items with the database.
*
* @param {Array} items - Array of product objects from the frontend
* @param {boolean} dryRun - If true, returns filtered items without persisting (used in preview mode)
* @returns {Array|Promise} - Filtered items (dry run) or DB update result
*
* Note: items with status 'a' (archived) are excluded from live syncs
*/
async function syncInventoryItems(items, dryRun = false) {
if (dryRun) return items.filter(item => item.status === 'archived');
return await bulkUpdateInventory(items);
}
This is the kind of comment that lets an AI agent understand intent, not just syntax. Big difference.
5. Inconsistent Patterns Across Files
This is a subtle one but it absolutely kills AI agents.
In one file you do:
const { data, error } = await supabase.from('users').select('*');
In another:
const response = await api.get('/users');
const users = response.data.users;
In another:
fetchUsers().then(setUsers).catch(console.error);
Three different async patterns. Three different error handling approaches. Three different ways to store the result. When an AI agent is trying to understand your app's data flow, this inconsistency forces it to treat every file as a fresh puzzle with no assumptions it can carry over.
Pick a pattern. Use it everywhere. Your team will thank you. The AI will thank you. Future-you will thank you.
A Real Scenario: Debugging with Claude
Let me tell you what happened to a classmate of mine (we're both studying Software Engineering and he was working on his semester project).
He had a Node.js backend, pretty standard REST API. Something was wrong with his authentication middleware. He pasted the auth file into Claude and asked what was wrong.
Claude responded with something like:
"It looks like your
verifyTokenfunction is usingreq.headers.authorization, but your middleware in the routes file may be expecting the token in a different format..."
Except the routes file wasn't pasted. Claude was inferring from the auth file that there was probably a routes file doing something with the token. It was making educated guesses — and sometimes they were right, sometimes totally off.
When my classmate cleaned up his auth file — better naming, clearer structure, a comment explaining the expected header format — and pasted it again, Claude immediately identified the actual bug: he was calling next() before the token was fully validated.
Same model. Same Claude version. Different code quality. Totally different result.
The 2026 Context: Why This Matters More Than Ever
According to the Stack Overflow Developer Survey 2025, around 76% of developers were already using or planning to use AI tools in their development process. By 2026, that number's almost certainly higher — adoption isn't slowing down.
GitHub Copilot crossed 1.8 million paid subscribers as of mid-2024, and Cursor reportedly onboarded over a million active users within months of gaining traction. These tools are deeply embedded in how we code now.
But here's the thing: these tools are also getting more agentic. They're not just autocompleting lines anymore. They're:
- Running multi-step tasks across your codebase
- Writing and executing tests automatically
- Making PRs, reviewing diffs, suggesting refactors
- Debugging by reading logs and tracing through files
The more autonomous these agents become, the more your code quality becomes a dependency of their success. You are, in a real sense, writing code that AI will read, execute, and modify — not just suggest.
If your code is unreadable, your AI agent is flying blind.
Quick Wins: What You Can Start Doing Today
Here's the stuff that actually moved the needle for me:
On naming:
- Functions should be verbs:
getUserById,validateEmailFormat,sendWelcomeEmail - Booleans should be questions:
isLoggedIn,hasPermission,shouldRedirect - Arrays should be plural nouns:
userIds,selectedProducts,pendingOrders
On functions:
- One function, one job. Seriously. Name it after what it does. If the name needs "and" in it, split it.
- Aim for functions under 30 lines. Not a hard rule but a good gut-check.
On comments:
- Comment the why, not the what. The what is visible in the code. The why usually isn't.
- Use JSDoc or Python docstrings. Not because tooling needs them (though it helps), but because it forces you to explain the function in a single sentence.
On structure:
- Keep related code close together. An AI agent given one file should be able to understand its purpose without needing three others.
- Export types/interfaces alongside the functions that use them.
On consistency:
- Write a simple conventions doc for yourself (or your team). Even three rules are better than none.
- When you pick an async pattern, stick to it. When you pick a naming convention, stick to it.
The Downside: Don't Overdo It
I'll be honest — there's a risk of going too far with this.
- Over-commenting creates noise. If every line has a comment, nothing stands out.
- Excessive abstraction can make code harder to follow, not easier. Splitting a 30-line function into ten 3-line functions sometimes just creates a maze.
- Obsessing over naming can lead to ridiculously long variable names that break line length and readability.
Balance is real. The goal isn't to make your code perfect for AI — it's to make your code good. Good code happens to work well with AI agents because good code has clear intent, single responsibility, and honest documentation.
Don't write for the AI. Write clearly. Those end up being the same thing.
One Last Thing
There's a quote I keep coming back to from Martin Fowler:
"Any fool can write code that a computer can understand. Good programmers write code that humans can understand."
He wrote that in 1999. But in 2026, I'd add a corollary:
Good programmers write code that humans and AI agents can understand — because the tools that help you ship are only as useful as the code they can reason about.
Your codebase is your context. Make it readable.
References & Sources
- Stack Overflow Developer Survey 2025 — AI tool adoption among developers
- GitHub Copilot — 1.8M subscribers — subscriber milestone reporting
- Cursor — AI Code Editor — agentic coding tool
- Martin Fowler, Refactoring (1999) — on code clarity
- Anthropic Claude Context Windows — model specs 2026
- OpenAI GPT-4o Technical Details — context window and capabilities
- Clean Code by Robert C. Martin — naming, functions, comments
- The Pragmatic Programmer — general software craft
Find me across the web:
- Medium: @syedahmershah
- DEV.to: @syedahmershah
- Hashnode: @syedahmershah
- GitHub: @ahmershahdev
- LinkedIn: Syed Ahmer Shah
- Portfolio: ahmershah.dev
Top comments (28)
The irony is real: AI is forcing us to return to fundamental Clean Code principles that we should have been following all along. Descriptive names and short functions are no longer 'nice-to-haves'—they are functional requirements for AI collaboration.
Well said, Sagar. It’s an interactive loop. We can't expect magical output from AI if we feed it garbage input. Clean architecture is the foundation that makes automation actually viable.
I’ve noticed this explicitly with Cursor and Claude. If I modularize my backend controllers into single-responsibility functions, the AI fixes bugs on the first prompt. If I feed it a legacy mega-function, it just writes confidently wrong code. Separation of concerns is a superpower again.
😂 This is brilliant and incredibly accurate. A violent psychopath might come looking for you, but an AI agent will quietly break your production DB while smiling and telling you it successfully completed the task. That's a whole new level of horror.
This is the real evolution of the 'Developer' role. We are transitioning from raw code writers to context managers and system architects. If you can't provide clear context through your code structure, you can't leverage AI effectively.
100% Tahir. A huge context window is just a larger bucket; if you fill it with muddy water, you still get mud. Attention mechanisms degrade when forced to parse massive, deeply nested spaghetti functions. 'Lost in the middle' is a very real problem for codebases.
Interesting take. If AI readability becomes a standard metric, I wonder if we’ll see linters in the future specifically designed to score code based on 'LLM comprehension probability' before it's pushed to a repo.
Exactly. The critic has changed from a pedantic senior dev at a 10 AM code review to a confidently incorrect AI model hallucinating dependencies at 3 AM. The rules of Clean Code are exactly the same, but the feedback loop is terrifyingly faster now.
Reminds me of the saying: 'Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.' Now, replace 'violent psychopath' with 'an AI agent that will happily hallucinate a breaking change in production.'
Perfectly articulated, Aley. The modern developer is becoming an editor and an orchestra conductor. If you feed the AI bad context, you get bad music. Prompt engineering isn't just about what you type into the chat box; it's about how you structure your entire project repository.
This is such a crucial shift in mindset. We used to write clean code to survive code reviews with colleagues, but now we're writing clean code so our AI pair programmers don't hallucinate a ghost variable at 3 AM. The standards haven't changed, but the stakes definitely have
This is a fascinating prediction! I could absolutely see a future where CI/CD pipelines have a step like npm run linter:ai-ready. If a function has too much cyclomatic complexity or poor naming conventions, the build fails because 'Expected AI Error Rate > 5%'. You might be onto a brilliant open-source tool idea here!
This highlights why TypeScript/strongly-typed languages feel like cheating when using AI tools nowadays. Explicit types give the agent a structural map of the data without it having to guess what d or r contains.
Explicit types act like semantic guardrails for LLMs. Instead of wasting its reasoning tokens trying to infer what d or r could possibly be, the AI can immediately focus on the actual logic. TypeScript isn't just for developer experience anymore; it’s an AI optimization tool.
The context window bottleneck is real. People think a 200k+ token window means an LLM understands their entire monolithic repo, but semantic drift happens fast when functions are hundreds of lines of spaghetti.
Haha, we've all been there! It’s the classic 'I'll fix this variable name later' trap. Consider this a safe space—just think of the refactoring as doing a favor for your future AI coworker. 😂
Excellent points. We’ve focused so much on what AI can do for us that we forgot we need to build a stable foundation for it to work on. It’s a two-way street.
This mirrors my experience completely! Single-responsibility functions give the AI a localized problem to solve. The moment you give it a mega-function with side effects, its reasoning splits and it defaults to confident nonsense. Separation of concerns truly is a modern superpower.
It turns out the best way to prompt an AI is actually just to write readable code in the first place. Who would've thought? 🤯
Right?! Who knew Uncle Bob’s Clean Code was actually the ultimate prompt engineering handbook written decades ahead of its time.