Why asking AI to code before it understands your codebase is a costly shortcut.
A feature request can fit in one sentence. The changes AI makes to implement it can affect half your application.
The problem often starts with a simple prompt:
“Add a notification system to this application.”
The request sounds reasonable. The AI has a clear objective, and it can generate code quickly. But it doesn't necessarily know how your application handles permissions, where business rules belong, which components are shared, or what existing behavior must remain unchanged.
So it makes assumptions.
It might introduce a new service when an existing one already handles similar operations. It might duplicate business logic, modify a shared component, or add a dependency that the project doesn't need.
The code can look clean, the feature can appear to work, and the implementation can still be wrong for the application.
I'm Ayman Atif, a freelance software engineer working with business software, APIs, automation, and data processing. I share more of my work and engineering projects on my portfolio.
One lesson from building software is that getting AI to produce code is not the same as getting it to make the right change.
The mistake: treating implementation as the first step
Prompt engineering is often discussed as a matter of finding the right words, adding more context, or making instructions more detailed.
Those things can help. But there's a more fundamental issue: the order in which you ask AI to work.
When you immediately ask for an implementation, you're encouraging the model to solve the problem before it has established how the problem fits into the existing system.
A detailed prompt doesn't automatically solve this. You can write several paragraphs describing the desired feature and still leave important architectural questions unanswered.
For example, consider this request:
Add email notifications when an order is completed. Make sure the code is clean and follow best practices.
The instructions sound good, but they leave several questions open.
Does the application already have an email service? Where is an order considered complete? Could the operation run more than once? What happens if sending the email fails? Which files should change, and which must remain untouched?
The model may choose reasonable answers to these questions. The issue is that reasonable assumptions are not necessarily correct assumptions.
Change the prompt, not just the wording
Instead of asking AI to implement the feature immediately, split the work into two stages.
Stage one: understand the system.
Try this prompt:
Inspect the existing codebase to understand how order completion works and how email notifications are currently handled.
Do not modify any files yet.
Identify the relevant components, existing services, business rules, and potential side effects. Explain the smallest change that would implement this feature while preserving existing behavior.
If an important requirement is unclear, ask before proceeding.
This changes the immediate objective. The AI must first build a picture of the existing implementation and identify the assumptions that could affect its solution.
You can then review its findings, correct misunderstandings, and decide whether the proposed approach fits your requirements.
Stage two: implement the agreed approach.
Once the inspection is satisfactory, give the AI a separate instruction:
Implement the agreed change using the existing architecture. Keep the scope limited to the files and behavior identified during planning. Avoid unnecessary dependencies and unrelated refactoring. Add or update tests for the new behavior and relevant regressions. Report the files changed, the tests run, and any remaining risks.
The difference isn't that the second prompt contains magic words. It's that implementation now follows an explicit understanding of the codebase and an approach you've reviewed.
Why this matters beyond prompt engineering
This habit becomes particularly valuable in business applications, where a seemingly small change can affect permissions, financial calculations, background jobs, or data shared across multiple customers.
A notification feature, for example, might appear harmless. But if the underlying event can fire twice, customers could receive duplicate messages. If the implementation bypasses an existing authorization check, the problem could be more serious than a duplicated notification.
AI can help identify these risks, but it cannot be assumed to understand every constraint simply because the request sounds specific.
The engineer still needs to decide what must remain true, verify the proposed changes, and test the behavior that matters.
That is where good prompt engineering becomes part of good software engineering.
A practical rule I use
Before asking AI to change an existing application, ask it to explain the relevant code and propose a minimal plan first.
Review that plan before allowing implementation to begin.
This doesn't need to become a lengthy process for every change. A small, isolated task may require only a quick inspection. A change involving authentication, payments, tenant isolation, or shared infrastructure deserves more scrutiny.
The point is to match the amount of investigation to the potential impact of the change.
AI is useful precisely because it can help us move faster. Understanding the existing system first helps ensure that the speed produces a better result rather than more code to maintain.
The best first prompt isn't always “Build this.” Sometimes it's “Understand what already exists, then tell me how you would change it.”
I'm Ayman Atif, a freelance software engineer focused on business software and backend development. Explore my projects and engineering work at ayman-atif.vercel.app.
Top comments (0)