Using AI Agents Effectively

AI agents are fast and capable, 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. This doesn't mean every request has to be long: a small bug fix may take one sentence, and a high-level specification of a new feature or application can be a good starting point, as long as it says clearly what you want and any constraints that matter.

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.

Let the Tasks Manager do the queueing. Once you are running more than a few tasks, deciding which ones can run at the same time, watching queues for stalls, and hunting through sessions for questions is work an agent can do for you. Turn on the Tasks Manager, write your tasks, and mark them Ready. Answer what shows up on the Questions tab, and ask the Manager whenever something about the workflow is unclear. When to make this step is up to you; see Autonomous Development below.

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. 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 task makes no edits, you can start one that reads code another task is actively changing, without risk of conflicting edits. Not every agent has a read-only mode; Wing warns before starting a Plan task on one that does not.

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, start a fresh conversation. This saves money and keeps the agent focused. Humans do this automatically, but at least for now AI agents don't. Use Clear Conversation in the AI Agent tool's Options menu (the ⋯ button), or /clear in agents that have it, and Resume Session in the same menu to go back to a conversation you left behind.

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. The guides Wing writes for agents tell them to build this ability when a project lacks it, by running the application on an offscreen or virtual display, in a headless browser, or under a pseudo-terminal, and driving it the way users do. You can also ask for it directly as an early task. 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 Conversation to start over with fresh context. Be sure to check first for unwanted code and ask the agent to remove it first. Note that the new session will have no prior knowledge of the origin or correctness of uncommitted code.

Autonomous Development

With the Tasks Manager turned on, agents can carry out a series of tasks on their own, over long periods, while you write tasks, answer questions, and read reports. This section covers what you need for that, and how to get good results.

What you need. Before letting agents work autonomously, make sure you have:

An AI agent and a plan for it that covers the amount of work you expect. For sustained use, a subscription is generally much cheaper than paying for usage on an API key. See Setting Up an AI Agent. Note that not all AI agents are well suited to run the Manager. See the table in AI Agent Safety for details.
Version control, such as git or Mercurial. You can ask your agent to set this up for you.
A virtual machine or other reasonably isolated environment. At the very least, prevent agents from reaching critical resources or pushing code to your main repository. See AI Agent Safety.

How much control to keep. You decide how much control to keep over the development process, and your answer will likely change over time. At first you may prefer to work with a single agent and review every change at the code level. Once you see that agents write and run tests reliably for your project, you may find yourself reading the task reports and judgement calls on the Review tab, and committing without reading every diff. Turning on the Manager moves your attention from individual agents and their output to writing tasks, answering questions, and reading reports. Some people make that step on the first day, others after weeks with a single agent; there is no right time, and you can turn the Manager on and off as you like.

Committing on a separate branch. The Manager can commit finished work on its own (Commits in its settings; off by default). This lets development go on for long periods without waiting for you. If you turn it on, work on a separate branch, so you stay in control of when and how the work is merged into your main branch. A review task can compare the working branch with your main branch, to help you judge correctness, security, and anything else your development process calls for.

Start from a specification. Tasks can be small, such as a single bug fix, or a high-level specification of a feature or of a whole application. A specification should describe the purpose and key features, and any technical constraints that matter from the start. It doesn't need to be detailed: add it as a task, ask for it to be researched and broken into tasks, and mark it Ready. The Manager runs the research, asks what it needs to know on the Questions tab, and puts the resulting implementation tasks on the Plan tab, where some may run right away and others wait for you to mark them Ready. This works for an empty project as well as an existing one.

Require tests. Make it a rule that agents write unit tests for new code and use them to check their work. This replaces manual testing with tests that let an agent see for itself whether the code works as specified. Without it, autonomous work stalls often, because workers can't tell whether their code works. Set the testing regimen on the AI Agent tab of Project Properties (see Configuration).

Write down your development policies. Describe your other policies and requirements, from coding style to workflow rules, in AGENTS.md (outside the block that Wing maintains there; see Setting Up an AI Agent), and tell the Manager about any that concern how work is scheduled or committed. Agents follow these policies and ask when something is unclear.

Use the application. Run and use what is being built yourself, as much as you can, and add tasks for the bugs and improvements you find before real users see it. Where that isn't practical, ask agents to write tests that act like a live user, taking the application through all its functionality the way users will.

Schedule review passes. At key points, run separate review tasks: for security flaws, data loss bugs, test coverage, missing functionality, or compatibility problems between versions. Each one can turn up problems that become new tasks. Make at least some of these part of your regular workflow.

The common thread is to build tests and cross-checks into your process, and to give agents the means to see the results of their own work and correct it. In autonomous development the work is not done by a single agent but by many, each checking the work of others.

Agent Quick Start

Most agents print hints for how to use them as you work, which makes them easy to learn about as you go. A few of the most useful details to get started with:

Pressing Esc stops the agent and returns to the prompt, where you can provide additional

System Message: WARNING/2 (<string>, line 154); backlinks:

Bullet list ends without a blank line; unexpected unindent.

instructions, refine your request, or move on to something different (in which case Clear Conversation may be in order, as described above).

If you do not know how to do something, or want to find out if something is possible, just ask.

System Message: WARNING/2 (<string>, line 158); backlinks:

Bullet list ends without a blank line; unexpected unindent.

An agent knows how to use itself, and for anything it does not know already it can search the web far faster than a human, often running many searches simultaneously.