Coding Agents in Codebases That Already Have History

Greenfield demos make coding agents look solved. A mature repository is a different problem. It holds years of implicit decisions — naming conventions nobody wrote down, deployment constraints that explain an ugly workaround, backwards-compatibility promises made to a customer in 2021, and a test suite where half the assertions exist because of an incident.

A capable agent can read that history far faster than a new hire. It still needs a workflow that converts speed into change you can defend in review.

Orient before editing

The first instinct — describe the bug, ask for a patch — skips the part that determines whether the patch is correct. Start with repository guidance, the dependency graph around the affected code, recent changes to the relevant files, and the smallest reproduction that fails. Ask the agent to state the behavioral contract and the likely blast radius before it proposes anything.

That step catches a specific failure: the agent finds code that looks wrong, fixes it, and breaks a caller three modules away that depended on the exact behavior it just corrected.

• Reproduce the issue with a focused failing test or a trace before proposing a fix
• Read adjacent code and its history before introducing any new pattern
• Keep the patch scoped to the verified cause — not to everything nearby that looks improvable
• Run the repository’s own checks and read the generated diff line by line
• Write down assumptions a reviewer could not infer from the code alone

The strange test is usually load-bearing

Every old codebase has a test that makes no sense until you find the postmortem it came from. Agents are very willing to delete or rewrite those, because from inside the diff they look redundant. Establish the rule early: a failing test is a question, not an obstacle. If nobody can explain why it exists, that is a research task, not permission to remove it.

The best output is often not the patch

The highest-value thing an agent produces in a mature repo is frequently the evidence: a failing test that isolates the bug, a map of every caller of a function you were about to change, a performance comparison across two approaches, or a written explanation of why the obvious fix does not work. Those artifacts make human review faster and safer, and they survive after the patch is merged.

Watch the volume

Agents will happily generate more code than your team can own. A five-hundred-line refactor that passes CI is not obviously better than a twelve-line fix — it is a larger permanent maintenance obligation with a shallower review. Push toward removing duplication, reusing what exists, and leaving the file easier to read than it was.

“Throughput only counts if the repository is cheaper to change tomorrow than it was today.”