import DefinitionCard from "@site/src/components/DefinitionCard"

# AI Bug Fix Workflow

_Reproduce the failure, identify its cause, then make the smallest verified fix._

## Introduction

A [coding agent](/learn/concepts/ai-engineering/coding-agents) can search code it has never seen, follow call paths, and test hunches. It can also hand you a believable patch before it understands the failure. This workflow keeps the diagnosis ahead of the fix.

Use it when you can reproduce the bug, or when you can collect enough runtime evidence to get there.

## Understanding the Workflow

A **reproduction test** shows the reported failure before you touch production code. It has to fail for the right reason. A test that fails because the setup is broken tells you nothing about the bug.

Next comes the **root cause**, the thing in the system that actually produces the failure. Rewording an error, swallowing an exception, or returning a default can hide the symptom and leave the cause sitting there.

The agent collects evidence and offers a diagnosis. You decide whether the evidence holds it up, and whether the patch leaves nearby behavior alone.

## Applying It in Practice

Record the problem before starting:

- exact reproduction steps
- expected and actual behavior
- complete error output or stack trace
- relevant input and environment details
- the first known affected version

Create an isolated workspace from the revision that broke. A bug in a release may not show up on current `main` at all.

Ask the agent to dig in and write a failing test before it edits production code. Read that test and run it yourself, and stop if it passes or fails for some unrelated reason.

Once the reproduction holds up, ask for a plain explanation of the cause. It should join up the input, the state changes in between, and the result you saw. Check each of those claims against the code and the runtime evidence.

Then ask for the smallest fix that removes the cause. Read the diff for a hidden symptom, unrelated tidying, changed error behavior, and other code paths carrying the same bug.

Run:

1. the reproduction test
2. tests for the affected component
3. the broader regression suite
4. static checks and the build

Keep the reproduction test as a regression test. It is part of the fix, not scaffolding you throw away.

## Engineering Considerations

Do not name a solution in the first report unless you have already proved it. A suggested fix anchors the investigation, and the agent will bend the evidence to fit your guess.

Tests are evidence, not a finished diagnosis. A test can carry the same mistake as the patch, which is why the [human-in-the-loop review](/learn/ai-code-review) still has to read the reasoning. Check that the setup matches the real failure, and that the assertions tell correct behavior apart from a convenient workaround.

Flaky and environment-specific failures need runtime evidence first. Use the agent to work out which logs, traces, assertions, or metrics would tell the competing explanations apart. Do not ship a guess just because it looks related.

Security and data-corruption bugs need a wider response. Fix the code, work out which data and versions were hit, rotate any exposed credentials, and follow the incident process.

## Scaling and Operations

Add fields for the reproduction and the root cause to your bug-fix pull requests. Reviewers can then read the report, the failing test, the diagnosis, and the patch as one chain.

Track recurring defect patterns. If the same API misuse appears in several places, create a separate remediation task after the immediate fix, and consider [running agents in parallel](/learn/parallel-coding-agents) across the independent call sites. Keep broad cleanup out of an urgent patch unless leaving it creates immediate risk.

In a production incident, pick a fix you can undo and agree on rollback criteria before you deploy. Watch both the original failure signal and the behavior around it after release.

## Next Steps

- [AI Feature Development Workflow](./ai-feature-development): implement a defined behavior change
- [AI Refactoring Workflow](./ai-refactoring): improve structure after the defect is contained
- [Human-in-the-Loop Review Workflow](/learn/workflows/git/human-in-the-loop-review): review agent changes before merge
- [What are Coding Agents?](/learn/concepts/ai-engineering/coding-agents): understand how agents inspect and modify code