On using AI Agents: get the best out of them by thinking first

Over the past months, I’ve had more than 3,000 conversations with Claude Code and Codex. I have analysed them and extracted the patterns I used. Here, I’ll describe my approach to getting the most out of AI Agents for software development.

When working with AI, I tend to go all in or not bother at all. I don’t like the tab-autocomplete style. I prefer to have an AI Agent that works with me and helps me think through and produce the right solution. But before coding a solution, researching and thinking are essential parts of a solid engineering approach.

What AI Agents benefit from are the same things a human benefits from when planning and executing: a clear vision. Writing a spec of what the project does, what each feature is expected to achieve and how to verify it will give the AI Agent the knowledge it needs to know when its job is done.

By following this approach, I’ve improved the software testability and quality and reduced re-prompts.

Help the AI reason by thinking first

Explain what and how

Use AGENTS.md and/or CLAUDE.md to define your core software engineering principles first, then provide examples, splitting them into multiple files to give enough context when necessary without having all in one file. A solution is to tell the AI to read more about it in directories like docs/ai/testing.md or docs/ai/observability.md.

Describe what you care about. For example, I tell it to use a TDD approach, keeping things simple and mixing OOP and FP, with the intent to keep initial and final data pure while remaining pragmatic about every rule. This is how I write the code myself, and with AI Agents following those rules, they’ll tend to structure their code following the same principles, making my code reviews easier.

A note about discovery

If you’re not familiar with a codebase, asking the AI to summarise or illustrate the project’s structure is a totally valid starting point, but don’t just assume that what the AI tells you is right; always think it through and challenge it if something feels off.

Use cases

Use cases and their scenarios specify what the software does and serve as a description and verification step for AI Agents and Humans. It is important to define them in terms of user/service output without specifying technical details.

There are open source solutions that add complexity, sometimes warranted, like openspec, but I had excellent results starting with a simple USE_CASES.md file and expanding from there via linking different files. The important part is to write use cases and scenarios to define what the product should do.

The spec

Use the spec, either in a temporary file or directly as the first input for an AI Agent, to describe the goal and provide context on the required changes. An MCP integration with a tool like Linear is possible here, but the spec is usually more detailed and complete.

Describe the problem, add context and insights, point to the right resources and provide an end goal. Use cases should be referred to here.

Being clear about what each feature does is as important as ever; treat the AI like you would a human collaborator, they have to fully understand the problem and be given the right context to help you.

The plan

This is the part that requires the most back-and-forth between the AI and the developer. Start by pointing the AI Agent to the spec file or pasting the spec to the AI Agent, and ask the AI to create a plan based on that spec. The goal is to challenge each other’s assumptions and create a refined plan that can be worked on by one or multiple AI Agents over a period of time.

This is where prompting is helpful. AI Agents tend to over-engineer their solutions. It is important to remind them to adhere to the project’s principles and review their proposals to help them spot architecture smells. My principles are simplicity, speed, and clarity, achieved by avoiding extra libraries when not absolutely necessary and keeping the architecture boundaries clean.

During your sessions, if you notice something that could be useful in future sessions, create a Markdown handbook on a specific technology, framework, or book that can serve as a reference. Even though many tasks can be automated by AI, your knowledge and experience remain incredibly valuable.

You know you’ll have a plan ready for execution when there is a clear goal, a set of milestones that can be verified, and each milestone has steps that can be done one at a time. If multiple agents are used, make sure to define the different tasks for each in the plan itself.

If you want, have the plan written in a markdown file. It allows you to review and modify it as needed. It doesn’t have to be perfect, but it has to describe what it wants to achieve, outline the steps to take, and define done.

Use cases are used together with the plan to define the desired final output.

Session and context management

Each session should have a specific focus, whether it is a high-level view or about minute details. It is important to manage what is being worked on to avoid mixing the AI context with different ideas, which could otherwise be mistakenly utilised.

Context limit is a bottleneck. There are models with 1M tokens, but a good approach is to manage it before it is auto-compacted by summarising the work done and what remains, and pointing to the relevant details where necessary.

AI Agents in action

Once the plan is defined, one or more AI Agents can then tackle the problem.

A multi-agent approach uses multiple agents, each of which can specialise in one part of the problem, adding only the resources and capabilities required for that part.

Where does this leave us?

The end goal is to have a working solution. With this approach, the AI Agents can be assigned to their tasks with a clear goal, so they’ll know when to stop and report their results. There will be times when more details are necessary, but as happens when working on a software project without AI, things are discovered while building.

Not every task requires the full ceremony, but the longer AI Agents are left working on their own, the more a structure and a goal are useful to lead them to a useful result.