Playbooks · Coding agents

Fix a bug with an agent without breaking the test suite

A solo builder reproduces a bug, hands Aider the failing case, and lets the suite decide whether the fix is safe.

Audience: Solo builder · Stack: A git repo with an existing automated test suite and a test command you already run · Tool: Aider (terminal)

Before you start

A git repo with a test command you can run by hand and that passes before you start. If the suite already fails, fix or record that first — otherwise you cannot tell whether the agent broke something.
Aider installed per its author README: python -m pip install aider-install followed by aider-install. Set up the model and API key as the author install docs describe; this page names no model and no price.
The bug written down as steps to reproduce, the expected result, and the actual result. Paste the failing output, not a paraphrase of it.
A branch for the fix, so the main branch stays clean while you work.

Steps

Reproduce the bug first, by hand, and note the exact failing command and output. If you cannot reproduce it, do not hand it to the agent yet.
Start Aider in the project directory with aider, then add only the files involved with /add <file>. Aider edits the files added to the chat; keeping that set small keeps the fix small.
If you want tests run after every edit, start with the project's test command, for example aider --test-cmd "<your test command>" --auto-test. The author lint/test docs describe exactly these two switches. Otherwise, run tests yourself with /test <test-command> after each change; Aider runs the command and tries to fix errors when it returns a non-zero exit code.
Give the agent the reproduction, the expected result, and one constraint: change the smallest amount of code that fixes the case, and do not change unrelated tests to make them pass.
After each edit, read the diff with /diff. Aider commits each of its edits with a descriptive message, per its author git docs, so the history shows what it did step by step.
Run the full suite, not just the failing test. A fix that passes one test and breaks three others is not a fix.
If an edit makes things worse, use /undo, which the author docs describe as undoing the last git commit done by Aider. Then re-brief with the new information instead of piling more edits on a bad one.

Worked example

A solo builder's invoicing script totals an invoice wrong when a line item has a quantity of zero: the total includes a stray charge. They reproduce it with the project's test command, see one failing case, and start Aider with /add on the totals module and its test file only. The brief is: “Quantity zero must contribute nothing to the total. Change only the totals calculation. Do not change the tests.” Aider edits the calculation, /test shows the failing case now passing, the full suite is run, the diff shows a two-line change, and the fix is committed on its branch. When an earlier attempt also changed a rounding helper, /undo removed that attempt and the builder re-briefed with the narrower constraint.

What can go wrong

The agent “fixes” the bug by changing a test's expectation. Fix: /undo, then restate that tests are not to be changed to fit the code, and check the diff before accepting anything.
The failing test passes but the full suite fails. Fix: treat the full suite as the gate. Ask the agent to fix the regression, or /undo back to the last green state.
Aider edits files you did not add. Fix: check what is in the chat with /ls and remove files with /drop <file>; both commands are in the author in-chat command list.
The suite is slow and you are tempted to skip it. Fix: run at least the module's tests after every edit and the full suite before committing. Skipping the suite removes the only check this playbook relies on.

Limits

Aider fixes what the test command reports. If your tests do not cover the buggy behaviour, a green suite proves nothing about the bug.
The agent can find a fix that passes the tests but misunderstands the intent — for example, special-casing one input. Reading the diff is the defence, and it only works if you read it.
A non-zero exit code is how Aider knows a test failed, per its author docs. A test command that exits zero while printing failures will mislead it.

Time and cost: NOT_MEASURED. This page gives no time or cost figure because the tool docs fetched for it state none that applies to this task.

Verification

Checked 2026-10-23 against the author's own docs. The workflow on this page was not run end to end; every command, flag, and capability claim was checked against an author doc or repo fetched that day.

Cut from this page, with reason:

No specific test framework named in the commands: the reader's own test command is the verified input, so the page uses a placeholder rather than inventing a framework command.
No time or cost figure: NOT_MEASURED, for the reason given on the page.
No model named: the author README shows model flags, but the task needs none, so none is recommended.

If a step here does not match what your installed tool shows, trust the tool's own docs for your version and stop before approving a change you cannot read.

Back to: Coding playbooks hub · Skills index