There are two main problems with Coding Agents:
How can you fix this? Junior team, only one new technology, and dare to automate.
What?
Let me explain by start with a story first.
You’re a team leader in an e-commerce company. It’s Monday morning, and your brand-new junior team smiles at you: business analysts, front-end and back-end developers, a tester, and a system admin. It’s everybody’s first day. Everybody’s first hour, to be precise.
You look at one of the developers and say, “Hi! Many of our customers don’t download their invoices. Change our system to send these invoices automatically to these customers. The code is documentation enough. Don’t ask me for clarification. You can split up the work among yourselves if you want to. I’ll see you in two weeks when you’re done!”
Your team looks at you in shock as you walk out the door.
Now in real life, you’d never do this: No proper specification, no documentation, no onboarding, no checkpoints, no questions, no nothing. This is madness!
But this madness is exactly what people often unknowingly do when they tell a Coding Agent to fix a problem or add a feature in an application: no proper specification, no documentation of the application, no proper onboarding, no idea what the Coding Agent showld always do or never do, and not enough questions being asked. And even if you put this information into your prompts, the Coding Agent has soon forgotten that and will never learn from this.
To fix this, it’s helpful to go back to the story and think of the Coding Agent as a junior team of business analysts, front-end and back-end developers, testers, and system admins. How would you then solve these two problems?
The first thing you must do is treat your Coding Agent like a human junior development team: onboard them, check their plans, and teach them to know when they’re done.
Onboarding means to tell the Coding Agent what your application does and how it does it, how to build, run, test, deploy, and troubleshoot it, what to always do and what to never do, and about other development tools like ticketing, source control, or the continuous integration system. And because Coding Agents are controlled by LLMs, which always forget and never learn, it’s best to put that information in a place where the Coding Agent can easily reach it.
For Claude Code, that place is the CLAUDE.md file. For other Coding Agents, that’s the AGENT.md file. The Markdown format puts simpe formatting instructions into text files and has emerged as the default Coding Agent file format. All the information from the previous paragraph goes in here, except for what your application does and how it does it. Although Claude Code should always read CLAUDE.md, it often ignores it partially. 😒
What your application does and how it does it should go into a Product Requirements Document (PRD) file – PRD.md. The CLAUDE.md/AGENT.md references the PRD.md, which means the Coding Agent always has the specification of your application at hand. Well, mostly, as it sometimes ignores it. 😁
You neither write the CLAUDE.md/AGENT.md nor the PRD.md yourself: You tell the Coding Agent to write them, then review and change them.
Once your Coding Agent is onboarded, you check its plans. For smaller tasks, this means going into plan mode in the Coding Agent (which is [Shift]-[Tab] in Claude Code), For medium tasks, you let the Coding Agent write a plan file with detailed steps and review it. For big tasks, you let the Coding Agent write a PRD file first, review it possibly in your team, and then produce a detailed plan file with multiple implementation phases.
One of the biggest frustrations with Coding Agents is when they tell you that they’re done – and their not. That’s not unlike a junior human developers where you teach them to properly build, test, and document their work. Same goes for Coding Agents: Put into the CLAUDE.md/AGENT.md when and how to build your application, how to run the Linter that checks the source code style, how to run the tests, and how you CI/CD pipeline works that automatically builds your application. Your Coding Agent will ignore this often enough probably, but it will still reduce the frustration with premature “I’m done!” messages.
As a side note, the CLAUDE.md/AGENT.md file and the application PRD.md are helpful for onboarding human developers, too! 💪🏻
Another reason why Coding Agents don’t do what you want them to is that you don’t understand what they’re doing wrong. As mentioned before, Coding Agents can create software in any language with any framework for any system. Let’s say you’re a Java programmer who has worked with the Maven build tool, the Spring Boot framework and dabbled in HTML with Thymeleaf templates. Now you can build Kotlin applications with the Gradle build tool and the Quarkus framework and a Next.js front end!
But you shouldn’t: You still have to know when the Coding Agent is right. And you can’t do this when you have four new technologies in your project. So, following the popular guideline of only allowing for one miracle per project when planning, you should also allow for one new technology per project. In the Java example, you could switch to Kotlin in one project, then try out Gradle in the next one, and finally use Next.js in the project after that. Yes, you still have to know when the agent is right, but limiting this to one technology will help.
Another frustration with Coding Agents is, “They don’t work for coding tasks, and because that’s all they can do, they just don’t work well at all for me!” Now the previous section hopefully helps you getting Coding Agents to do what you want them to. And if you think of them as a team of business analysts, front-end and back-end developers, testers, and system admins, it’s clear that they can do so much more than coding.
For instance, Coding Agents can write tickets, update Confluence pages, review other people’s code, fix broken builds, and optimize slow applications and slow databases. For most of your development work on the computer, assume that a Coding Agent can do it and then assess if it’s worth having the Coding Agent do it.
In other words, dare to automate: Let the Coding Agent write scripts to automate simple tasks (like checking who deployed which component in your shared test environment) or create so-called custom commands that you can invoke in your Coding Agents for more complex tasks, like reviewing a PR, creating a PR, or implementing a ticket. The Coding Agent can use your browser, too, so that opens up new possibilities.The sky’s the limit, or so it seems! 😁
Wrap-Up
In the beginning, I wrote that “Junior team, only one new technology, and dare to automate” is the answer to why Coding Agents don’t do what you want them to and why they don’t do enough useful things. I hope that answer is clearer now: Treat Coding Agents like a junior team by onboarding them, checking their plans, and teaching them to know when they’re done. Don’t use more than one new technology per project – you still have to know when the agent is right. And finally, dare to automate because a Coding Agent is also a business analyst, a tester, and an admin.