Search for a command to run...
Why messy architecture and weak typing are the absolute fastest ways to break your automated development workflows.
Interesting perspective. I wonder if "AI-readability" will eventually become a standard code review criterion alongside maintainability and performance. As AI tools become more agentic, the quality of context we provide may matter just as much as the prompts we write.
exactly
Really like the line “your codebase is your context.”
One place I’d extend this: AI-readable code helps the agent understand the repo, but agents also need readable execution environments.
That’s where MCP gets interesting. A clean codebase tells the agent what the app is trying to do. An MCP server can tell it what the outside system actually does: available tools, expected inputs, state transitions, webhook outcomes, logs, and failed runs.
For API integrations, this is a big shift. Instead of an agent only reading code + docs and guessing, it can use MCP to run the workflow before editing the code.
So the stack becomes:
code clarity → repo context
MCP → execution context
agent → better changes
We’re exploring this with FetchSandbox MCP for API workflows: giving agents a stateful sandbox they can execute against before touching app code.
Thankyou, (*Dont self promote here and no links )
Great piece, Ahmer. It’s highly ironic that as we move toward highly autonomous AI agents, the solution isn't fancier prompt engineering ,it’s just going back to the basics of solid, clean code. The point about code consistency across files is huge; humans can context-switch between an API fetch and a Supabase query easily, but it completely breaks an AI's mental model of the codebase.
Thankyou Srashti! Clean code is the ultimate prompt.
Hey, I'm Syed Ahmer Shah. This series looks at where autonomous agents fail, where "vibe coding" hits a wall, and why engineering discipline is the only thing standing between your codebase and a production disaster. AI can write code, but it doesn't have to maintain it. Through these logs, I’m putting tools like Claude, ChatGPT, and nascent AGI models to the test in real-world scenarios. Instead of riding the hype train, I am documenting the exact limits, the unexpected crashes, and the massive gaps between AI-generated boilerplate and actual, scalable systems thinking. You’ll see exactly when AI helps and precisely where it falls apart. As part of Syed Ahmer Shah | Engineering Logs: Design, Sync, Energize, this specific series filters the AI noise through the lens of true engineering execution. If you want to know what happens when autonomous AI meets real-world software constraints—and how to actually leverage these tools without destroying your architecture—this is the log to follow.
How Anthropic’s "bulletproof" safety layer collapsed in 24 hours, exposing a 120k-character system prompt and a covert performance-sabotage controversy.
Why the World's Most Powerful Open AI Model Is Completely Inaccessible: The Kimi K3 Paradox Explained
From Flowstep to v0 — testing which AI tools nail the design, and which ones actually hand you usable code.
No Ghost in the Machine — Just 512 Billion Parameters Doing Linear Algebra at Industrial Scale.
From design-to-code generators to agentic IDEs, here's what's worth your attention — and what's changed since last year.
Why cloud marketing promises instant speed, but drops the ball on data integrity.
Syed Ahmer Shah | Engineering Logs: Design, Sync, Energize
37 posts
Hi, I am Syed Ahmer Shah! Welcome to my little corner of the internet. I am a software engineering student, and this is where I document my actual, everyday journey of building full-stack web apps from scratch.
Instead of polished textbooks, you will find my real dev logs, honest lessons from project mistakes, and a good laugh at the bugs along the way.
I dive deep into three main series here: The Engineering Logs, AI vs Reality, and Battle of BackFront.
I write about hands-on coding, testing
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.
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.
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.
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.
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.
# 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.
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.
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.
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.
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.
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.
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.
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.
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