Context engineering: getting AI coding tools to understand your codebase

AI coding assistants are trained on the world's code, not yours. So when you ask for a change, they pattern-match against a generic average and guess at the specifics — inventing a service you don't have, importing from a path that never existed, ignoring the conventions your team relies on.

The fix is rarely a better model. It's better context. Context engineering is the practice of writing down what your codebase assumes, in a form the tools read automatically — so the assistant stops guessing and starts following.

Start with a context file

Most assistants now read a project file — CLAUDE.md, AGENTS.md, or editor rules for Cursor and Copilot. Treat it like a README written for a very fast, very literal new hire. The highest-value things to include:

• The architecture in three sentences.
• The hard rules that aren't obvious from the code.
• The mistakes newcomers always make.

A few lines go a long way:

# Payments service

- Money is always integer cents (`amountCents`), never floats.
- New endpoints live in `src/api/v2` and need a Zod schema in `schemas/`.
- Never call the ledger directly — go through `LedgerClient`.

That snippet prevents an entire category of wrong answers before it happens.

Encode conventions as rules, not hope

If a convention matters, don't rely on the model inferring it. State it. "Prefer composition over inheritance," "all dates are UTC," "errors bubble up as typed Result values" — each rule you write down is a class of review comments you never have to leave again.

Give it a data dictionary

Generated database queries are only as good as the assistant's understanding of your schema. A short data dictionary — tables, key columns, relationships, and the business meaning behind them — turns plausible-looking SQL into correct SQL. Even a single markdown table describing your core entities pays for itself quickly.

Capture the work you repeat

Every codebase has operations you do the same way every time: add an endpoint, wire a migration, scaffold a component. Write those steps down as reusable prompts (some tools call them "skills" or "commands"). Now the boring, error-prone parts happen your way, consistently, instead of being reinvented on each request.

A minimal starting point

You don't need a big rollout. In an afternoon you can:

1. Add one context file at the repo root with your top ten rules.
2. Describe your three most important database tables.
3. Capture your one most-repeated task as a reusable prompt.

The goal isn't to document everything. It's to write down the handful of things the assistant keeps getting wrong — and let the payoff compound from there.

Context is the cheapest performance upgrade your AI tools will ever get. Most of it is knowledge your team already has; it just isn't written where the tools can read it yet.