Best Practices for Onboarding an AI Agent to a Legacy Codebase
The short answer
Pin behaviour first, then explain the system, then hand over small jobs. An agent in a legacy codebase fails for the same reason a new contractor does: nobody told it what the system does, what must not change and how to check its work. Anthropic’s Claude Code guidance names the single biggest lever — “give Claude a way to verify its work” — and in legacy code that means tests that capture today’s behaviour, bugs included. Everything below works with Claude Code, Codex, Copilot, Cursor and similar agents as of October 2026.
Step 1: Make verification possible
| Do | Why |
|---|---|
| Make build + tests run with one command | The agent can only iterate on a signal it can run |
| Ask the agent to write characterization tests for the module first | They record current behaviour, so a refactor that changes output fails loudly |
| Add a smoke test for the main user path | Catches breakage the unit tests do not cover |
| Record known failures in a file | Stops the agent “fixing” a test that was already red |
If the code cannot be tested in isolation, the first task for the agent is a seam — an interface or wrapper around the database, clock or network — not a feature.
Step 2: Write the onboarding file
Put an AGENTS.md at the repository root (Claude Code reads CLAUDE.md, Copilot reads .github/copilot-instructions.md; point them at the same content). Keep it short — every line costs context on every session.
- Commands: install, build, test, lint, run locally.
- Map: the five to ten directories that matter, one line each, and the entry points.
- Conventions: language version, frameworks in use, patterns that look odd but are deliberate.
- No-go zones: generated code, vendored libraries, migrations, billing, anything with external contracts.
- Definition of done: tests pass, no new warnings, diff under a size limit, no public API change without saying so.
Legacy-specific additions: name the dead code you know about, the hidden dependencies (cron jobs, stored procedures, config tables) and the dates or versions the system is pinned to.
Step 3: Explore read-only, then plan
Start each new area with an exploration task and no write access: “Read the payment module and explain the flow from request to ledger entry; list anything you are unsure of.” Correct its misunderstandings in the instructions file — that is how the map improves. Then ask for a plan before code. Reviewing a ten-line plan is cheaper than reviewing a 600-line diff built on a wrong assumption.
Step 4: Keep diffs and sessions small
- One concern per change. Refactor or change behaviour, never both.
- Cap the diff (for example, 200 lines) in the definition of done.
- Reset context between tasks. Anthropic’s guidance: performance degrades as the context window fills; a fresh session with a good instructions file beats a long one.
- Use path-specific instructions (Copilot’s
.github/instructions/*.instructions.md, nested AGENTS.md files) for subsystems with their own rules.
Step 5: Gate merges like any contributor
Run CI on agent branches, require human review, and add a stop-hook or CI check that blocks “done” until tests pass. For unattended runs, a separate verification step — a second agent or a reviewer — catches the agent grading its own homework.
Common mistakes
- Starting with a big refactor. Without characterization tests, the agent cannot tell whether it broke anything.
- A 2,000-line instructions file. It crowds out the code. Link to docs instead of pasting them.
- Letting the agent touch migrations or billing early. Put them in the no-go list until trust is earned.
- Ignoring what the agent gets wrong. Every repeated mistake is a missing line in the onboarding file.
For the general (non-legacy) version of this process, see how to onboard AI agents to your codebase; to keep token bills down while you do it, see how to reduce AI coding agent token costs.
Last verified: October 16, 2026.