at making quick implementations. However, now that coding has become a commodity, one of the main bottlenecks that I see is the knowledge transfer between a human brain and the coding agent.
If an idea is presented correctly to the coding agent, it is extremely effective at implementing the solution, testing it, and ensuring the correct implementation.
However, in a lot of cases, there are a lot of details, and it’s really hard to ensure all the details are included when you prompt the coding agent.
This is where alignment comes in, and in this article, I’ll discuss how to effectively ensure your intentions are aligned with your coding agents, and I’ll present some techniques you can use to do this.
Why align with coding agents
First of all, I always want to discuss why you should care about a specific topic. In this case, it’s why you should align with coding agents such as Claude Code.
Coding agents are incredibly good at implementing things if they’re given a very specific and well-described spec.
However, creating this well-described spec is harder than you might think. First of all, you have to describe exactly what you want to implement, where you have an idea in your head of what you want to do. However, there are always a lot of nuances that are hard to cover in such a way when describing it to the coding agent.
- You might forget to mention some parts of what has to be implemented
- You might be unaware of a decision you have to make regarding the implementation
- There might be ambiguities in your explanation
These points are typically things that you don’t notice beforehand, because, of course, as a human, you can’t have a perfect context of what you want to implement, which, in many cases, is something you are implementing because another person has told you what you need, for example, a customer or a product manager.
Secondly, you don’t have full context because you’re not fully aware of everything that’s in the codebase, especially now that a lot of code is written by AI. It’s hard to have a full overview of everything beforehand, and thus, you’re missing perfect context.
This is why coding agent alignment is so hard, and in this article, I’ll cover how to align with your coding agents effectively so that your coding agents perform optimally and are better at one-shotting the implementations you ask them to do.
How to align with your coding agents
In this section, I’ll cover specific techniques that I utilize to align with my coding agent, and also a mindset on how I align with my coding agents.
Each section will include a specific idea, mindset, or technique that you can implement into your own work as a programmer to effectively align with your coding agents.
Agents always go to the default solution
The first concept I want to cover is that coding agents always go to the default solution whenever they try to implement something.
What I mean by this is that the coding agent will typically look at previous implementations of something similar in your repository, replicate that, and do it again.
This means that if your code repository is poorly organized and you ask the coding agent to implement a new feature, the coding agent will likely continue the poor pattern from before and place the new feature in a sub-optimal manner.
Let me give you a specific example:
A lot of codebases have a lot of LLM calls, naturally. In an ideal codebase, you have one service, which is basically a single file or folder that is called an LLM service, where you have all your LLM calls. You have functions with options that decide how the LLM call is done. For example, deciding which LLM to use, whether to use structured output or not, max output tokens, and so on.
However, a poorly organized codebase will not have this as a single file, but instead define the LLM call providers in many different files, and each file will contain a separate call to the LLM.
This is called poor separation of concerns.
Now, if you’re in the well-organized codebase and you ask to implement another LLM call, the LLM will default to the natural solution, which is to, of course, use the common shared LLM service file, which is great.
However, if you’re working in a poorly organized codebase, where LLM calls are done separately in many different files, the agent will likely continue this behavior and make another new separate LLM call, further worsening the pattern of poor separation of concerns.
The point I’m trying to make here is that the coding agent will just follow the natural pattern in your codebase, whether that’s a good pattern or a bad pattern. That’s why it’s so important, if you want to effectively align with your coding agent, to ensure your codebase has good patterns throughout and that you refactor your code on a regular basis.
If you want to learn more about refactoring your code, you can read my TDS article on the topic below:
How to Refactor Code with Claude Code
The great thing about refactoring now is that you can simply ask coding agents to do it for you.
Active usage of plan mode
An important technique to align with your coding agents is to actively use plan mode whenever interacting with them. Plan mode is so great because it helps you identify ambiguities between the implementation that you’re envisioning and explaining to the LLM and the current codebase. You might have forgotten that if you make one change to the codebase, this impacts other parts of the codebase that you didn’t think about, and you need to make a decision on whether to still go ahead with the change or change the implementation details.
You shouldn’t expect yourself to have full knowledge of the codebase beforehand, simply because codebases are now written mostly by coding agents, and it’s impossible to have a full overview of the codebase.
However, you don’t really need a full overview of the codebase because you can simply ask your LLM about the codebase itself. Tell it to help you identify ambiguities in the implementation that you want
In short, whenever you’re looking to roll out a new feature, it’s wise to start with plan mode alongside your AI coding partner. You should really invest plenty of time in this planning back-and-forth, discussing things like:
- Your overall vision for the feature
- Any potential roadblocks the AI might spot in your proposed approach
- How to address and work through those concerns together
Give Your Coding Agent All the Background Information You Can
Another frequent reason for miscommunication between engineers and their AI coding assistants is that the engineer knows details about the project that haven’t yet been shared with the AI.
Let’s say you’ve been asked to build a feature that sorts images into 10 distinct categories. Naturally, you’d want to use the latest Claude Opus model since you know it delivers the best results — because who wouldn’t want the most accurate model for the job?
But wait — in a recent meeting with your manager, they made it clear that using Claude Opus just isn’t financially feasible. Instead, you need to figure out an approach that costs at least 10 times less.
Now, if you turn to your coding agent and simply say, “Hey, we need a feature that sorts images into these 10 categories — can you get that done for me?”, you’ve dropped the ball.
The core issue here is that you’ve given the AI enough detail about the problem to solve — which it absolutely can do. However, you neglected to share a critical constraint: the default approach of using top-tier LLMs like Claude Opus is off the table. You need a solution that’s at least 10 times more affordable.
This creates a serious disconnect between your intent and what the AI delivers. What will likely happen is the AI goes ahead and builds the solution, and only after it’s done will you realize the cost makes it impractical. At that point, you’re back to square one, burning time on creating a replacement approach — meaning all the effort spent on the first version was essentially wasted.
Now, the example I’ve shared might not be the most realistic scenario — chances are you’d remember to mention cost optimization. But this same type of oversight happens constantly in real projects. Engineers forget to communicate some vital piece of information to the coding agent, it goes ahead with an implementation that ends up being wrong, and then you have to start all over again.
To avoid this, make sure to equip your coding agent with as much relevant background as possible. For instance, consider providing access to:
- Transcripts from team meetings
- Slack channels and direct messages
- Notes from Notion or similar tools
And really, any source of knowledge or context that might help the AI make better decisions during implementation. When your coding agent has access to all the right information, you dramatically reduce the chances of costly misunderstandings and suboptimal choices.
Wrapping Up
Throughout this article, I’ve explored strategies for staying properly aligned with AI coding partners. A recurring challenge I’ve observed is that engineers and coding agents are often working from different mental pictures of what should be built. The engineer has one vision in their head, a colleague might envision something different, and the AI yet another interpretation entirely.
This kind of misalignment is incredibly problematic and something you should actively work to prevent. That’s why I’ve outlined these tips and approaches for you to keep in mind and put into practice every time you collaborate with a coding agent. Staying aligned from the start makes the entire development process more efficient and effective.
👋 Let’s Connect
👉 My Free E-Book and Webinar:
🚀 10x Your Engineering Skills with LLMs (Complimentary 3-Day Email Course)
📚 Grab My Free E-Book on Vision Language Models
💻 Watch My Webinar on Vision Language Models
👉 Follow Me on Social Media:
💌 Substack
🐦 X / Twitter
