AI Coding Agents on Existing Codebases: A Practical Guide

Almost every tutorial, demo and case study about AI coding agents starts the same way, with an empty directory, a fresh npm init and a prompt like "Build me a task management app." The agent sets up a project, adds the dependencies, writes tests and gives you something that works in a few minutes, and the results look good.

Then you try the same thing on your real codebase, the one with 200,000 lines of code, six years of architectural decisions, three different state management patterns and a deployment pipeline that took two sprints to stabilise. This time the agent rewrites your authentication module in a framework you don't use.

People don't talk much about this gap between new projects and existing codebases, but it's one of the biggest limits of AI coding agents today. In this article we look at why the gap exists, how you can close it, and where agents really do speed up work on established codebases.

Why Greenfield Is Easy Mode

AI coding agents do very well on new projects for the same reason junior developers do, because there are no existing rules or patterns to learn and no old decisions that come back to cause problems six months later.

On a greenfield project every choice the agent makes is consistent, because it wrote all the code and so the patterns match. There's no legacy state management to understand, no undocumented business logic hidden in a database trigger and no deployment pipeline that breaks if you rename a directory.

The METR study, a randomised controlled trial of 16 experienced open-source developers working on 246 real-world tasks, put numbers on this gap. Developers using AI tools (Cursor Pro with Claude 3.5/3.7 Sonnet) on repositories they had maintained for years were 19% slower than those working without AI. These were large, established repositories averaging over 22,000 stars and more than a million lines of code.

Before they started, the developers expected AI to speed them up by 24%, and even after the slowdown they still believed AI had made them 20% faster. That's a gap of nearly 40 percentage points between what they felt and what actually happened.

Google's internal study found something different. Developers on a standardised coding task (adding a logging feature across 10 files in an unfamiliar codebase) finished 21% faster with AI assistance. So AI seems to speed up work on code you don't know, but it can slow down experts on codebases they know well.

If you lead an engineering team, this means you'll need a different approach for AI agents on your existing codebase from the one that works on greenfield projects.

Onboarding an Agent to Your Codebase

When a new developer joins your team, they don't start by rewriting your authentication system. They read the documentation, ask questions, look at the existing patterns and make small, safe changes while they learn. AI agents need the same kind of onboarding, you just give it to them in a different way.

CLAUDE.md and Project Configuration

The most useful tool for onboarding an agent is a well-written project configuration file. In Claude Code this is CLAUDE.md, in Cursor it's .cursorrules and in GitHub Copilot it's .github/copilot-instructions.md. The name changes, but each one does the same job, which is to give the agent context about your project that stays with it from one session to the next.

Nolan Lawson, a well-known open-source developer who describes himself as a former "hard-line anti-AI zealot," now uses Claude Code a lot on real projects. His advice is that someone who "really knows the codebase's dirty little secrets should write a good CLAUDE.md that explains the overall structure, which parts are stable, which parts are still under development, and which parts have dragons." Without this, "the LLM is just coming in fresh to the project every time and it's going to wreak havoc."

A good project configuration file covers:

• Architecture overview: how the system is structured, where business logic lives, how data flows
• Naming conventions: your patterns for files, functions, variables, database columns
• Technology constraints: which frameworks and libraries to use (and which to avoid)
• Testing conventions: how to run tests, what coverage is expected, where test files live
• Deployment pipeline: what happens when code is merged, what CI checks must pass
• Known gotchas: the undocumented quirks that trip up every new developer

DX's research on enterprise adoption found that teams without proper AI configuration see 60% lower productivity gains than teams with structured documentation, so just giving people an AI tool with no context doesn't help much.

Structuring Context for Large Repositories

For monorepos and large codebases, the agent's context window starts to hold you back, because you can't feed a million-line codebase into a single prompt. What helps is scoping, where you give the agent the part of the system it needs and nothing more.

Anthropic's own engineering team wrote about this in their work on long-running agents. Each new session starts with no memory of what came before, so agents need a clear way to carry their work from one session to the next. Anthropic's answer uses progress files, git commits with descriptive messages and a feature-by-feature task breakdown to keep things joined up.

Practical strategies for large repositories:

• Scope sessions to subsystems. "Work only in the src/billing/ directory" is more effective than "fix the billing bug."
• Describe the architecture instead of pasting code. A paragraph describing how the billing module interacts with the payment gateway is more useful than pasting 50 files into context.
• Use progress files. A claude-progress.txt or similar file that tracks what's done and what's left lets the agent pick up where it stopped.
• Commit often. Ask the agent to commit after each meaningful change with a descriptive message, so you have points to go back to when things go wrong.

The "Rewrite Everything" Trap

If you've worked with AI agents on established code, you've probably seen this. You ask the agent to fix a bug in a React component and it rewrites the entire file, changing the state management pattern, renaming variables, and restructuring the JSX. The fix ends up buried in a diff that touches 200 lines when only 3 needed to change.

This happens because the agent doesn't care about your existing code. It writes what it thinks is the best code from scratch, using patterns from its training data instead of the patterns in your codebase. VentureBeat's analysis said that agents produce "near-repetitive logic without anticipating unarticulated developer needs, leading to tech debt and harder-to-manage codebases."

So how do you stop it? You give the agent clear limits:

• State the scope in every prompt. "Fix the null check on line 47 without changing anything else in this file" works much better than "fix the bug."
• Review the diffs. Always look at changes as diffs instead of whole files, and if a diff is much bigger than you expected, something has gone wrong.
• Keep batches small. The 2025 DORA report found that working in small batches amplifies AI's positive effects on product performance and reduces friction. AI can easily produce huge blocks of code that are hard to review and test, and sticking to small batches keeps that in check.
• Configure your rules file. Add explicit instructions like "Do not refactor code unless specifically asked" and "Match existing patterns in the codebase" to your project configuration.

Anthropic's engineering team found this step-by-step approach was "critical to addressing the agent's tendency to do too much at once." When they asked the agent to work on one feature at a time, commit its progress and write summaries, they got much better results than when they gave it broad, open-ended tasks.

Incremental Adoption: Where to Start

The Stack Overflow 2025 developer survey shows a mixed picture. 80% of developers now use AI tools, but trust in AI accuracy has fallen from 40% to 29% year-over-year. The number one frustration, cited by 45% of respondents, is "AI solutions that are almost right, but not quite." Two-thirds of developers say they spend more time fixing "almost-right" AI-generated code than they would writing it from scratch.

So it makes sense to begin with tasks where "almost right" is still useful and where mistakes don't cost much.

Phase 1: Tests

Writing tests is a very good place for AI agents to start on existing codebases. Tests have clear pass/fail criteria, so a wrong test fails where you can see it instead of quietly putting a bug into production. Your existing codebase also gives the agent plenty of context for what the tests should check.

DX's research found that test case generation and stack trace analysis give the highest return on investment for AI tools in enterprise settings. Start by asking agents to write tests for your most important code paths, review what they write carefully and build up coverage bit by bit.

Phase 2: Bug Fixes and Small Tasks

Once you have tests as a safety net, agents get good at small, well-scoped bug fixes. The agent needs a specific bug to fix, a specific file to work in and tests that will confirm the fix works, because open-ended instructions like "investigate why the app is slow" give results you can't rely on.

Phase 3: Feature Development

When your context files are in place, you have good test coverage and your team is happy with how reviews work, agents can help build features. You still work the same way, by scoping the work, giving context, reviewing diffs carefully and committing in small steps.

Phase 4: Refactoring and Modernisation

This is where AI agents give the biggest returns on established codebases, and some enterprise case studies show strong results. Thomson Reuters migrated 1.5 million lines of code monthly with AI assistance, achieving 30% cost savings while cutting technical debt in half. Air Canada modernised thousands of Lambda functions in days, with an 80% reduction in expected project time and cost.

In the modernisation projects that go well, AI does the mechanical work (rewriting syntax, updating API calls, converting patterns) and people make the big decisions (what to migrate, in what order, with what testing strategy).

Real Risk Areas

Not every part of your codebase is a good fit for AI help, and in some areas the risks are bigger than the time you'd save.

Database migrations. AI agents don't understand the difference between a migration that adds a column and one that restructures a table containing 50 million rows. Both look like simple schema changes, but the first takes milliseconds and the second can lock the table for hours. A person should always review any migration that touches production data.

Authentication and authorisation. Security researchers keep finding that AI agents default to less secure patterns. A financial services company found that over 60% of AI-generated code suggestions contained high-severity vulnerabilities, including SQL injection and authentication bypass flaws. Your auth system should be written, reviewed and maintained by developers who think like an attacker.

Payment flows. Race conditions in payment processing can lead to double charges, missed charges or wrong amounts, and these bugs are known to be hard to reproduce and test. AI agents have no idea of the financial and regulatory cost of getting payment logic wrong, so keep people closely involved here.

Compliance-sensitive code. This covers things like GDPR data handling, financial reporting calculations and healthcare data processing. Be very careful in any area where regulations set out how the code has to work, because the cost of an AI-generated compliance breach is far bigger than any time you'd save.

When Agents Genuinely Accelerate Legacy Work

There are still plenty of areas where AI agents give real, measurable value on existing codebases:

• Documentation generation. Agents are very good at reading existing code and writing accurate documentation. The risk is low, because wrong docs won't crash your application, and good docs make every future task faster.
• Boilerplate and repetitive patterns. Adding logging, error handling, or API response formatting across dozens of files is boring work for people and easy for agents.
• Code exploration. Asking an agent "how does the billing module calculate discounts?" is faster than reading through 15 files yourself, and even if the answer isn't perfect, it gives you somewhere to start.
• Test coverage expansion. Going from 30% to 70% test coverage with AI-generated tests, then manually reviewing and refining them, is much faster than writing every test from scratch.
• Dependency updates and syntax migrations. Upgrading from React Router v5 to v6 across 200 files is exactly the kind of mechanical transformation agents handle well.

The central finding of the 2025 DORA report fits here too. It describes AI as an amplifier that magnifies the strengths of high-performing engineering organisations and the dysfunctions of struggling ones. Organisations with solid foundations (clear documentation, strong version control practices, established testing conventions, and well-structured codebases) see AI agents accelerate their work. Organisations without these foundations see AI adoption correlate with decreased team performance, increased friction, and greater instability.

Making AI agents useful on your existing codebase takes the same things that make any new developer useful, which are good documentation, clear conventions, the right scope and careful review. If you're not sure where to begin, writing your CLAUDE.md file and asking the agent for tests on one important part of the code is a sensible first step.

---

LibraBit helps engineering teams adopt AI coding tools on established codebases, from writing effective CLAUDE.md files to establishing review workflows and identifying safe entry points. Get in touch to talk through how your team could get started.

---

References

• Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity, METR
• Effective Harnesses for Long-Running Agents, Anthropic Engineering
• How I Use AI Agents to Write Code, Nolan Lawson
• AI Code Generation: Best Practices for Enterprise Adoption, DX
• 2025 Stack Overflow Developer Survey, Stack Overflow
• 2025 DORA State of AI-Assisted Software Development, Google DORA
• Why AI Coding Agents Aren't Production-Ready, VentureBeat