DEV Community: Samil Hazir

Your Codebase Is the Prompt: Why AI Flies in Some Projects and Fails in Others

Samil Hazir — Tue, 13 Oct 2026 15:05:01 +0000

There is an old developer joke:

“When I wrote this code, only God and I knew how it worked. Now only God knows.”

It is funny because we have all seen this project. The code works, but only one lead developer really understands it. The decisions, exceptions and unwritten rules live inside their head. Eventually, the developer becomes the codebase.

That is already an old problem for the development teams. A coding agent has even less chance. If another developer cannot understand where things belong, why they were built that way or what might break, AI will struggle with the same questions.

This article is about the habits that make a codebase easier to understand, change and verify. Most of them are not new AI practices. They are established development practices whose absence becomes much more expensive once you bring AI into the project.

AI Cannot Execute a Mood

AI works best when the work is already clear.

If you start the day with “let’s improve something” and make every decision while coding, the agent has nothing solid to follow. It can generate code, but it cannot decide what the product should do, what belongs in scope or which trade-off you actually want.

Before I involve a coding agent, I usually discuss the task with another AI first. We define the problem, question the approach, consider the edge cases and break the work into clear steps. Then I ask it to prepare a detailed prompt for the local coding agent.

AI can help at different levels. Use one agent to think through the work and another to execute it. Do not expect the coding agent to plan the product, design the architecture and implement everything from one vague sentence.

A vague task does not give the agent freedom. It gives it permission to guess.

Make the Project Predictable

A well-structured project should not surprise you.

When I open a codebase for the first time, I should have a good guess where the business logic, validation, API calls, views and shared utilities live. The same type of work should follow the same pattern across the project.

If one validation rule lives in a controller, another in a helper and the next one inside a view, the structure is already failing. AI can search the whole repository, but that does not mean it should have to.

Predictability reduces the amount of context an agent needs. It also lowers the chance that it adds the right code in the wrong place.

A clever folder structure is not the goal. A boring, consistent one usually works better.

Separate the Domains Early

A project becomes difficult to understand when unrelated business areas start leaking into each other.

Payments should not quietly depend on notification logic. User management should not know how reports are generated. Each domain needs a clear owner, a limited responsibility and an explicit way to communicate with the rest of the system.

This matters even more for AI. The smaller the boundary, the less context the agent needs and the lower the chance it changes something outside the task.

I love microservices because they make those boundaries harder to ignore. Each service owns its logic, data and communication contracts.

The goal is not to create more services. The goal is to give every change a clear place to belong.

Write Down the Hidden Rules

Code shows what the system does. It rarely explains why.

There are always hidden rules: a strange workaround, a dependency that must not be upgraded, a field that looks optional but is not, or a business rule that only one developer remembers.

AI will not discover these safely by guessing. Neither will the next developer.

I prefer to keep these rules close to the project: short architecture notes, clear README files and agent instructions for important conventions. Not a giant wiki nobody updates. Just enough context to stop the same mistakes from happening again.

If a rule matters, it should not exist only in someone’s head.

Give AI a Feedback Loop

An agent should not decide for itself that the work is finished.

At code level, it needs checks it can run: tests, builds, type checks, linters and clear error messages. These turn the task from “write something that looks right” into “make this pass without breaking that.”

I also prefer to involve another agent after the implementation. A fresh agent can review the diff, question the approach, look for missed edge cases and compare the result with the original plan.

The implementation agent is already invested in its own solution. The reviewer starts with fewer assumptions.

AI becomes much more useful when it can write, test, fail, fix and then defend its work.

One Responsibility, One Place

The Single Responsibility Principle is the first letter in SOLID. It is also one of the easiest principles to ignore.

A method should do one clear job. A class should have one clear reason to change. A business rule should have one authoritative home.

This is not about splitting everything into tiny methods. It is about making ownership and the responsibility obvious. When the same rule appears in a controller, a helper and a background job, neither developers nor AI can know which version is correct.

Delete the Wrong Examples

AI learns your project by following what already exists.

That becomes a problem when the repository contains dead code, abandoned abstractions, old patterns and temporary workarounds that somehow became permanent. The agent cannot always tell which example is current and which one survived by accident.

Remove obsolete code instead of leaving it “just in case.” When an old path must remain, mark it clearly and explain why.

Every stale implementation is another answer the agent may copy with complete confidence.

A cleaner codebase does not only reduce maintenance. It reduces the number of wrong directions available.

The Seven Deadly Sins of Coding With AI

Samil Hazir — Tue, 13 Oct 2026 14:47:22 +0000

A few years ago, people said AI would soon write most of the code. They were almost right.

AI did not replace the old workload. It multiplied it. We now build more features, generate more code and create more things to review than ever.

Now we have a new problem. AI can write code much faster than we can properly review it. It can also make inexperienced developers feel more capable than they really are. The code looks clean, confident and professional, even when the logic is wrong.

Here are the seven deadly sins of coding with AI.

1. Giving the agent access to your secrets

Do not let an agent freely read your .env files, SSH keys, API keys, database passwords, customer data or private documents.

Most coding agents let you exclude specific files or folders from their workspace. Use that feature for anything sensitive.

Once the agent can see a secret, it may end up in logs, terminal output, generated files, commits or tool calls. Putting everything in one file and telling the agent not to open it is not security.

Keep secrets outside its workspace where possible. Use limited, short-lived credentials and expose them only when needed. If an agent may have seen a key, rotate it.

A wallet private key is the wallet. Treat it that way.

2. Giving MCP tools too much power

MCP tools are useful because they let agents interact with databases, files and external services. The problem starts when one generic tool can do everything.

A PostgreSQL or MySQL MCP may be able to read, change or delete your entire database. Most tasks do not need that much access.

Build small MCP tools for specific jobs instead. Expose only the operations the agent actually needs, with clear inputs and strict limits. A tool such as findCustomerByEmail is far safer than giving the agent unrestricted SQL access.

Creating a basic MCP server is easier than it sounds. In many cases, a few narrowly defined tools are enough.

Do not give an unpredictable agent a universal remote control and hope it presses the right button.

3. Ignoring indirect prompt injection

Prompt injection does not only come from the user. It can hide in a website, README file, GitHub issue, email, source-code comment, package description or another tool’s output.

It has many forms, but the idea is the same: the agent reads untrusted content and mistakes it for instructions. A page can tell it to ignore your request, read a secret or call a tool.

Treat external content as data, not authority. Never let something the agent merely read approve a command, file change or data transfer. Prompt rules alone are not enough; limit permissions and require approval for sensitive actions.

4. Accepting code you cannot explain

AI can turn a five-line fix into three classes, two interfaces and a new dependency.

The result may look professional. That does not make it necessary.

Ask why each abstraction, package and compatibility layer exists. Ask whether the standard library already solves the problem. Then ask the agent to make it simpler.

You do not need to type every line, but you still need to understand it. Your code quality cannot exceed your ability to judge code.

5. Treating AI output as deterministic

An AI model is not a normal function. The same input can produce a different result, ignore a rule or return almost-correct JSON.

Validate its output before using it. Check the structure, types, allowed values, permissions and business rules.

Never pass raw AI output directly into SQL, shell commands, file paths, HTML or executable code. Treat it like input from an unknown user: validate everything and trust nothing.

6. Installing packages the AI invented

AI sometimes recommends packages that do not exist. The names are often convincing enough that you may install them without checking.

Attackers know this. They can register those invented names and fill the packages with malicious code. This is known as slopsquatting.

Before installing an unfamiliar dependency, check that it is real, correctly spelled, actively maintained and linked to a legitimate repository. Also check whether you need another package at all.

Never install something just because the command looks confident.

7. Merging code because it looks good

Human mistakes often look messy. AI mistakes can look beautifully organised.

The naming is clean, the comments sound confident and the code compiles. The logic can still be completely wrong.

Review the diff yourself. Test permissions, invalid inputs, failures, edge cases, migrations and critical business rules.

AI-generated tests are not enough either. The agent can misunderstand the requirement and then write tests that confirm its own misunderstanding.

Keep changes small enough to review properly. Do not let the agent write, test and approve the same code.

You still own the code

AI can write the code, but it does not own the consequences.

The faster you build, the more careful you need to be about access, validation, review and testing.

Use AI as a fast collaborator, not as a trusted operator.