Today, one of the hot topics in the AI space is working with agents. We are not talking about James Bond here, but tooling that uses large language models (LLMs) to help us solve various tasks. For anyone that has tried to use these LLMs to get something done, you have likely had moments when it worked just fine, and other when it ended up in a lot of garbage.
To work with these agents more effectively, you need to have a mental model of the interaction and workflow that can guide to better outcomes. If you have such a model in place you can bridge the gap between “chat with AI” and “delegate to AI”.
I am going to talk about programming and coding here for our mental model, but this approach is not restricted to coding tasks.
This is not something unique, and you can find similar descriptions from multiple places.
Introducing our agent
Our core mental model begins with our perceived persona of the agent: a coding agent is a junior developer who is extremely fast, literal-minded, and has no implicit context about your project. Every gap you leave, it fills with what it considers plausible guesses. This may or may not be something you intended.
So we need to have a structured approach to guide this junior developer, starting with the input.
The Four-Part Input Structure
We can divide the input we provide to the agent into four parts
Context
What exists already, such as the tech stack used and version constraints for it. Relevant file paths to consider (not all files in the whole project). Existing style guides and patterns, and prior decisions made and why they were made.
Scope
What to change, with a clear goal and acceptance criteria. Be explicit with non-goals and focus on one task at a time.
Constraints
What not to break, files that should not be touched, APIs that should be preserved. Whether to add new dependencies or not, and test coverage requirements.
Output Format
How to deliver it, should it present the difference or full file content? Provide a step-by-step plan before executing the tasks, and explain before coding. Perform commits as checkpoints for the work, so that a rollback can be done.
How to talk to the agent
Focus on the goal, not the implementation. The agent probably knows how implement things, but it does not know your goal. Without a clear goal, it will guess widely what that may be.
Separate what to do from what not to do. Explicitly say what you do not want it to touch. Without such info, an agent may happily refactor/rewrite surrounding code while solving your actual problem.
State your acceptance criteria, and be concrete. Do not say “make the web call work”, say statements like “the endpoint should return 200 with an empty JSON body when there is no matching result, and not a 404”. This will make it easier for the agent to self-evaluate its work.
Ask it to make a plan before starting to code. Give it an instruction like “first, describe your approach in 3-6 bullet points. Then let me review and confirm the plan before you write any code.” This will catch any misunderstandings early, before you have a diff to review that are several hundred lines of code.
The Delegation Workflow
Now that we have some idea on how to organize the input, how to we set up the workflow with the agent?
Input
Structure your request using the four parts. System-level context that will always be there can go into an AGENTS.md file, or something similar that the agent will read and use every time. That file should be kept relatively small though, and not dump everything that may potentially be useful into that file. Be deliberate.
Task Prompts
Guide the agent through subtasks, keep them relatively small and focused. You can have specific instructions for the feature or bug you are handling. There can also be so called agent skills that describe in more detail how to do certain things, which can be loaded when needed for the task at hand.
Review
Examine the proposed plan before execution. Remember, your junior developer agent is quite literal-minded and has no prior knowledge about your project. In fact, every time you talk to it, you literally start from the beginning again!
Keep the plan on target, and focused.
Commit
Approve and proceed (or iterate) with the plan. Make sure it uses version control to commit the changes after each important step.
Tooling
Either use the coding agent with its command line interface, or use it via an integration in the IDE of choice. Make sure git or similar version control system is in place, and use it extensively.
Anti-Patterns to Avoid
Relying too much on the responses from an agent can result in some bad patterns.
- Vague scope. “Make it better” does not cut it. It will produce confident but pretty much arbitrary results.
- Missing constraints. This can become a runaway refactoring spree. The agent will optimize for solving your problem, which could include restructuring any adjacent code that was not broken.
- Insufficient context. Ask the agent to explain any choice that requires explanation. You can catch many misunderstandings that way.
- Blind commits. Review the plan before execution, and make sure all tests are executed. An agent can break tests other than those it looks at to solve the particular problem it works with.
Final words
Many of these things are actually not unique to working with agents, a lot of the good practices we already have for software development can fit well in here.
A notable difference though is that an agent is like a person with a huge short term memory, and no long term memory. We humans tend to have a much smaller short term memory, and an extensive long term memory.
We need to adapt to this persona.