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 and how that might contradict the current codebase.
In summary, whenever you want to implement a new feature, you should use plan mode with your agent. You should be spending a lot of time in plan mode, talking back and forth to the model about:
- What you’re envisioning
- What problems can the LLM see about what you want to implement
- How can you resolve those issues
Provide the coding agent as much context as possible
Another reason I often see misalignment between what an engineer wants to implement and what a coding agent actually implements is that the engineer possesses context that hasn’t been provided to the LLM.
Imagine, for example, that you are asked to implement a feature to classify images into one of 10 categories. You want to use the latest Claude Opus model because you know that’s the best model, and of course, you want to use the best model to achieve the highest possible accuracy.
However, in a meeting you recently had with your boss, he told you that we cannot use the Claude Opus model because it’s cost-prohibitive, and we need to find a solution that’s 10 times cheaper.
Then, when the engineer asks the coding agent to implement the solution, the engineer simply tells the coding agent: “Hey, we need to implement this feature where we classify images into one of these 10 categories. Please fix that for me right now.”
The problem here, of course, is that the engineer has given the LLM or the coding agent context of the problem to be solved, and of course, it’s a problem the coding agent can easily solve now. However, the engineer has forgotten to provide the LLM all the context it needs, which is that it cannot use the default solution, which would be to use the latest and greatest LLMs, such as Claude Opus. He has to find a solution that’s at least 10 times cheaper.
This is, of course, a major misalignment between the coding agent and the engineer. What’s going to happen is that the coding agent is going to make the implementation. After implementation is done, you, the engineer, will likely discover that the solution is not really possible because of costs. You have to spend time coming up with yet another solution, essentially meaning that the entire time spent implementing the first solution is wasted.
Of course, the example I provided here is not that likely to happen, because hopefully you would remember to tell your coding agent the context of minimizing cost. However, this exact same thing happens all the time, where you forget to tell the LLM or coding agent some piece of context. It starts implementing something, and that is basically incorrect, and the engineer has to perform yet another implementation.
To prevent this from happening, you need to give the coding agent as much context as possible. For example, you should give the coding agent access to:
- Meeting note transcripts
- Slack channels and DMs
- Notion notes
And everything else that might be useful knowledge and context for the LLM or coding agent when performing an implementation. This prevents issues where the coding agent lacks context, which makes it worse at decision-making.
Conclusion
In this article, I discussed how to effectively align with coding agents. A very common issue I see with engineers and coding agents is that they’re not fully aligned on what they want to implement. The engineer has one image in their mind of what they want to implement and what it would look like. Another engineer might have another image in their mind, and lastly, the coding agent might have a third image of what the implementation would look like.
This is, of course, very problematic and should be avoided at all costs. Thus, I provided some techniques and ideas that you should remember and think about and actively use whenever you interact with your coding agents to make sure you’re as aligned as possible, which in turn makes the implementation and coding more effective.
👉 My free eBook and Webinar:
🚀 10x Your Engineering with LLMs (Free 3-Day Email Course)
📚 Get my free Vision Language Models ebook
💻 My webinar on Vision Language Models
👉 Find me on socials:
💌 Substack