How do you give an AI coding agent context about your codebase?

Write a short instructions file at the repository root — AGENTS.md is the emerging convention, with tool-specific equivalents like CLAUDE.md — containing how to build, test and run the project, the conventions that are not obvious from the code, the paths that are off limits, and the definition of a finished change. Keep it under roughly 200 lines, because instructions that exceed the model's attention budget get partially ignored rather than fully applied.

Why do AI agents perform worse on my codebase than in demos?

Demos run on small, conventional, well-tested repositories where the right pattern is visible from any file the agent opens. Real codebases have local conventions, dead code that looks live, tests that do not run cleanly, and undocumented constraints. The agent copies whatever pattern it finds first, so if your repository contains three ways to do the same thing, you get a random one of the three.

What should be in an AGENTS.md file?

Six things: the exact build and test commands, how to run the project locally, the conventions a newcomer would get wrong, directories that must not be modified, the definition of done for a change, and known traps such as flaky tests or generated files. Write it as instructions to a competent contractor on their first day, not as marketing copy about your architecture.

How do you know if agent onboarding worked?

Measure the merge rate of agent-authored pull requests and the number of review cycles each one needs. A well-onboarded repository sees most agent pull requests merged with at most one round of changes. If you are consistently rewriting the agent's output or rejecting it outright, the problem is almost always missing context rather than an inadequate model.

Quick Answer

How to Onboard AI Agents to Your Codebase 2026 Guide

Published: August 21, 2026

The Short Answer

AI coding agents are competent and contextless. They fail on real repositories for the same reasons a strong contractor would fail on day one with no documentation: they do not know your build command, your conventions, or which of your four similar-looking patterns is the current one.

Onboarding fixes most of that in an afternoon. Five steps:

Write an instructions file at the repository root.
Make tests runnable in one command.
Mark off-limits territory explicitly.
Give a machine-checkable definition of done.
Measure merge rate, then iterate on the instructions.

Step 1: Write The Instructions File

The emerging convention is AGENTS.md at the repository root, with tool-specific equivalents (CLAUDE.md and similar) read by particular agents. Most modern agents look for one of these automatically.

What belongs in it — six sections, nothing else:

Section	Content
Build & test	Exact commands. Copy-pasteable. Not “run the usual tests”
Run locally	How to start the thing, including required services
Conventions	What a newcomer would get wrong: error handling, logging, naming, module layout
Off limits	Directories and files never to modify — generated code, vendored deps, migrations
Definition of done	What must be true before a change is finished
Known traps	Flaky tests, generated files that look editable, the module everyone hates

Keep it under roughly 200 lines. This is counterintuitive but consistent: instructions that overflow the model’s practical attention budget are partially applied, which is worse than a short file fully applied. If yours is 800 lines, you have written documentation, not instructions.

Write it for a competent contractor on day one. Not for a new hire who will absorb culture over months, and definitely not as architecture marketing. Imperatives, specifics, commands.

Step 2: Make Tests Runnable In One Command

This is the highest-leverage single fix, and it is almost always the real blocker.

An agent verifies its work by running tests. If your test suite needs a running database, three environment variables and a VPN connection, the agent cannot verify anything — so it guesses, confidently, and you get the failure mode everyone complains about.

Minimum bar: one command, from a clean checkout, that runs the tests and exits with a meaningful status code. If that requires a docker-compose file or a seeded fixture database, write it. You are not doing it for the agent; you are doing it for every human who joins too.

Second bar: the suite should be honestly green. A repository with twelve known-failing tests teaches the agent that failing tests are normal, which destroys your only automatic verifier.

Step 3: Mark Off-Limits Territory

Agents modify what they can reach. Reachability is your control surface.

Always mark as off limits:

Generated code (protobuf output, ORM models, API clients)
Vendored dependencies
Database migrations that have already run
Lock files, unless the task is a dependency upgrade
CI configuration, unless that is the job
Anything under a security or compliance boundary

State it in the instructions file and enforce it in review. Instructions are guidance; a check that rejects diffs touching generated/ is enforcement. Use both, and rely on the second.

Step 4: Define Done, Explicitly

“Done” for a human carries years of implicit context. For an agent it has to be written down:

Tests pass, and a new test exists that would have failed before the change
No new dependencies without explicit permission
Changes confined to expected paths
Public API changes documented
No commented-out code, no leftover debug logging
Diff small enough for one-sitting review

Every item on that list corresponds to a real, common agent failure. The last one matters most: large agent diffs get rubber-stamped, and rubber-stamping is where incidents originate.

Step 5: Fix The Repository Problems The Agent Exposes

Agents are unusually good diagnostic instruments. When one fails on your codebase, it is usually pointing at something real:

“It used the wrong pattern.” You have more than one pattern for the same job. The agent picked whichever it found first — as would any new hire. Consolidate, or state the winner in the instructions.

“It did not know about that constraint.” The constraint lives in someone’s head or a Slack thread from 2024. Write it down. This is worth doing regardless of agents.

“It broke something unrelated.” Coupling you did not know you had, plus tests too weak to catch it. That is a pre-existing defect the agent surfaced cheaply.

“It touched files it should not have.” Your boundaries were never explicit. Now they are.

Teams that treat onboarding as documentation debt repayment get compounding returns. Teams that treat it as agent-babysitting rewrite the same context every session.

Step 6: Measure, Then Iterate

Two metrics, tracked weekly:

Merge rate of agent-authored pull requests. Well-onboarded repositories land most of them.
Review cycles per merged PR. Target: at most one round of changes.

If merge rate is low, the instructions file is missing something. Read the three most recent rejections and ask what the agent would have needed to know. Add exactly that, in one or two lines. Do not add a paragraph of general advice — that is how a 200-line file becomes an 800-line file that gets partially ignored.

Re-read and prune the instructions file monthly. Stale instructions are worse than none, because the agent follows them faithfully into a convention you abandoned.

What This Does Not Fix

Onboarding raises the floor; it does not change the ceiling. An agent with perfect context still should not be handed architecture decisions with genuine trade-offs, security-sensitive logic, or work whose requirements are actually unclear — no instructions file resolves ambiguity that the humans have not resolved either.

Onboarding buys you reliability on the large volume of legitimately mechanical work in every codebase. That is most of the value on offer, and it is unlocked by an afternoon of writing things down.