Using AI Agents Effectively

Pro Only

AI agents are astonishingly fast and accurate, but like all competent engineers they can misunderstand instructions, forget important details, and make other mistakes. They are also limited in how much they can remember at once, by the size of their working memory (called the context window). Your role is to manage the AI agent, keep it working efficiently, and review its work. Here are some tips for getting the most out of this way of working:

Write clear, thorough requests. The quality of an AI agent's work depends heavily on the quality of your instructions. Describe in detail what features you want. If you have preferences for how something should be implemented, point the agent to existing patterns in your code or describe your requirements as concisely as possible. Vague requests produce vague results; specific requests produce specific results.

Don't micro-manage. There's no need to spell out every detail of every task. If you're asking for a feature that is relatively standard or obvious, just ask for it. For example, it may be enough to say "implement undo for all these features" in a relatively large specification, without getting into the details of what undo does or how it works. Similarly, if the AI agent writes code that doesn't work, don't start by telling it the specific error but ask it to "please write unit tests for the new functionality and use them to find any remaining bugs." Only get involved in the details if the AI fails to do that on its own.

Explore before starting work. An exploratory conversation is often very useful before diving into implementation. You can discuss ideas, ask the agent to evaluate the feasibility of different approaches, or have it sketch out a design before writing any code.

Use Plan Mode to prevent changes on disk. For a substantial refactor, a change that touches many files, or anything where you want to see the approach before any code is written, run the task in Plan Mode. The agent investigates the code and proposes a plan without modifying any files; you review the plan, ask for adjustments, and only then approve it for execution. Because a Plan Mode task makes no edits, you can start one that reads code another task is actively changing, without risk of conflicting edits.

Manage context size. As you work, the conversation context grows, and larger contexts consume more tokens per request. Context is valuable while working on the same or related tasks — the agent remembers what it has already done and can build on it. But when switching to an unrelated task, always run /clear to start fresh. This saves money and keeps the agent focused. Humans do this automatically, but at least for now AI agents don't. You can use Resume Session in the Claude Code tool's Options menu to go back to sessions you left behind when you previously used /clear and you can name sessions with /rename <session name>.

Build feedback into your requests. Ask the AI agent to write, run, and fix unit tests as part of any implementation. The goal is to take yourself out of the loop when it comes to verifying that code actually works. Think about how to enable the agent to "see" what you see. That might mean providing it with instructions so the agent knows how to run your code with some added logging that it can look at directly, it might mean asking it to run the code in the debugger so it can see what is happening at runtime, or in some cases it might mean setting up a headless browser or other means by which the agent can observe a UI it is building. In general, the least productive sessions with an AI agent are ones where the developer is stuck in a loop of manually testing, reporting back, and asking for another fix.

Step in when the agent gets stuck. Particularly when fixing difficult bugs, AI agents can sometimes lose their way, trying one speculative fix after another, rather than reasoning more deeply or using a debugger to find out what the code is actually doing. In other cases, an AI can stubbornly fixate on a particular solution, ignoring explicit instructions to find a different approach. It may even dismiss your reports of broken behavior as unimportant. Most of the time you do not need to watch the details of what the agent is doing, but when you notice it spinning, step in and provide guidance on how to proceed. If that does not help, don't try to iterate more than once or twice. Instead, use /clear to start over with fresh context. Be sure to check first for unwanted code and ask it to remove that first. The new session will have no knowledge of the origin or correctness of uncommitted code and may even fixate on the wrong solution in the same way.