How to Teach an AI Agent Your Codebase Conventions

An agent that does not know your conventions will write correct code in the wrong style, and you will spend your review time dragging it back into your patterns. It reaches for the most common approach it has seen, which is the internet average, not your codebase. The fix is to teach it your conventions explicitly, once, in a form it reads on every task. Do that and the agent's output arrives already shaped like your repo, and review stops being a style-correction exercise.

This is one of the highest-return setup investments in AI-assisted development, and most teams skip it. They correct the same drift over and over, task after task, instead of encoding the convention once so the agent stops drifting. The corrections are the symptom. The missing convention doc is the cause.

Write conventions down where the agent reads them

The agent cannot infer your rules from vibes. Put them in a file it loads with every task: a conventions doc, an agent-instructions file, whatever your tooling reads by default. State the things you actually care about. How you structure modules. How you name things. Which libraries are blessed and which are banned. How errors are handled. How tests are laid out. Be specific, because "write clean code" means nothing and "use Result types for fallible operations, never throw across module boundaries" means something.

Keep it to rules that matter and that the agent gets wrong without guidance. A giant style bible nobody maintains is as useless as no doc at all. The goal is the short list of conventions that, if the agent followed them, would make its output indistinguishable from yours. This is a form of context management: you are pre-loading the constraints so you do not have to restate them per task, which connects to how I think about the context window as a scarce resource.

Show, do not just tell

Rules stated in prose are weaker than rules shown in code. Alongside the conventions doc, point the agent at exemplar files: the module you consider a model, the test file that shows how you test, the error-handling pattern done right. Agents pattern-match, so give them the pattern to match. One good example does more than three paragraphs of description, because the example is unambiguous and the description is not.

This is where retrieval beats documentation. A system that can pull your existing code as reference, and show the agent how similar things are already done in your repo, teaches convention by example on every task automatically. That is one of the payoffs of repo intelligence before you refactor: the codebase itself becomes the convention doc, and the agent learns your patterns from the code that already embodies them.

Enforce what you can, do not just document it

Documentation sets the expectation. Enforcement makes it stick. Anything you can turn into a lint rule, a formatter config, or a CI check, do, because those catch drift without any human attention. An agent that produces code violating a lint rule gets an immediate, objective signal to fix it, which is far more reliable than hoping it read the doc carefully.

The split is: encode the mechanical conventions as automated checks, and reserve the doc for the judgment-level ones that resist automation. Naming, formatting, import order, banned APIs, those should be checks. Architectural patterns and design preferences stay in the doc and in the exemplars. Push as much as you can into enforcement, because a convention the pipeline enforces is a convention the agent cannot skip, and that is what actually keeps AI-generated code maintainable over time instead of drifting a little with every task.

Keep the conventions current

Conventions rot. You change your error-handling approach, you adopt a new library, you deprecate an old pattern, and if the doc does not follow, the agent keeps writing the old way from the stale instructions. Treat the conventions file like code: update it when the patterns change, review it when it drifts, delete rules that no longer apply. A convention doc that describes last year's codebase actively works against you.

The teams that get consistent agent output are the ones that maintain this layer instead of re-teaching it by hand each session. It is a small, boring discipline with an outsized payoff: every task inherits your patterns for free. We build this into the platform at Bootspring so conventions are a first-class input the agent always sees, and pairing it with a repo-quality tool like ReformCode catches the drift the doc misses. Teach the agent your codebase once, enforce what you can, keep it current, and stop correcting the same style mistake for the hundredth time.