Teaching an Agent Your Codebase Conventions

The short answer is four categories, each written as a rule plus an example from your own repo. A style guide written for humans is a reasonable starting point, and one developer's approach is worth copying: document habits for a human audience first, on the theory that if it is human-readable enough, the model can handle it too (olano.dev).

The fourth row matters more than most teams expect. The Karpathy-derived guidelines skill makes surgical edits a named rule: do not improve adjacent code, do not refactor things that are not broken, match existing style even if you would do it differently, and mention unrelated dead code instead of deleting it (SKILL.md). The same skill states the test that belongs in every conventions file: every changed line should trace directly to the user's request.

Show, do not describe

Adjectives are the main failure mode of conventions files. "Clean, readable code" is unactionable. The Stack Overflow piece recommends guidelines that are more explicit, more demonstrative of patterns and more obvious than human-facing standards, because the agent has no shared history to fill the gaps (stackoverflow.blog). In practice, that means every rule carries a short snippet from your repository, the real one, not an idealized version.

Keep it small enough to be read

A giant conventions file has the opposite problem: the model skims, the rules rot, and the token cost lands on every request. Discussion of instruction files that grow unchecked recommends recording the same correction only after it has been needed more than twice, on the grounds that context pollution from unnecessary rules costs more than the missing rule (news.ycombinator.com). The same conversation notes that a large root instruction file is a poor fit for long-lived guidance because it is loaded eagerly and tends to decay, and the alternative proposed is smaller, targeted artifacts plus design documents read at the right moment (youtube.com).

Most teams already have the rules, scattered across linter configs, review comments and tribal memory. The job is extraction, not authoring. Four passes get you most of the way.

1. Mine review comments. Search merged pull requests for the phrases reviewers repeat: "please rename", "extract this", "we don't do that here", "use the helper". Each recurring comment is a rule missing from your file.
2. Read the linter config as documentation. If ESLint or Ruff enforces import order and line length, the conventions file should say so in one line and point at the config, not repeat the settings. Automatable formatting should be automated away; the parts worth writing down are the ones that spill into design, like how code is distributed across files and how things are named (olano.dev).
3. Sample two files per module type. Pick a handler, a service, a test and a component, and describe what they have in common: exports, error shape, how dependencies arrive.
4. Interview the reviewer with the most rejections in the last quarter. Thirty minutes produces more rules than a wiki audit.

A worked measurement

Suppose your agent rewrites a function to fix one bug. You estimate the minimal fix at about 12 changed tokens. The agent's diff is 240 changed tokens. Your diff budget for bug fixes is 80 changed lines per task, and this task is well past it. Two numbers give you a decision rule: if the agent's edit distance exceeds the true minimal edit by more than roughly half, send it back rather than reviewing it. The BigCodeBench study normalizes by token count and compares the model's edit distance against the ground-truth minimal edit, exactly so you can separate "fixed the bug" from "rewrote the file" (nrehiew.github.io).

At team scale, the cost lands on review attention. One autonomous setup reports that a five-line fix takes a minute to verify while a twelve-file diff with the fix buried inside costs real attention, and that parallel agents collide precisely on the unrequested edits, because two agents never fight over their assigned task, only over the shared utility both decided to tidy (dev.to).

Writing the file is half the job. The other half is delivery: the agent has to see the relevant rule before it writes the code, not after the diff exists.

Order of loading, cheapest first:
1. System prompt / agent config      -> the 10 rules that always apply
2. Task spec (per ticket)            -> allowed paths, and which module docs to read
3. On-demand skill or doc            -> language or framework specifics, loaded when relevant
4. Hook feedback                     -> the rule it violated, read at the moment it is blocked

Layer 1: always-on context

Put the short version in whatever file your agent reads automatically at session start. Keep it to rules that would cause damage if missed: naming, file layout, error handling shape, and the surgical-edit rule. Use the imperative mood and positive framing, because a rule the model can follow beats a rule it has to interpret.

Layer 2: the task spec

Longer conventions do not need to be in the system prompt if every task carries a pointer. A task spec with a scope block, allowed paths and a size budget gives the agent both the pattern to follow and the fence around the work (dev.to). A minimal version:

{
  "id": "task-0412",
  "goal": "Fix off-by-one in pagination helper",
  "read_first": ["CONVENTIONS.md", "src/pagination/README.md"],
  "scope": {
    "allowed_paths": ["src/pagination/**", "tests/pagination/**"],
    "max_files": 4,
    "max_changed_lines": 80
  }
}

The read_first list is the delivery mechanism for the conventions file, and the scope block is the enforcement. Note the design preference behind the numbers: bug fixes get tight budgets, feature work gets wider ones, and refactors are their own task type with an explicitly large budget, so refactoring is never smuggled inside a fix (dev.to).

Layer 3: on-demand skills

Rules that apply to one framework and not the rest of the repo belong in a skill or a doc the agent loads only when relevant. A skill in the Agent Skills format is a Markdown file whose name and description sit in the system prompt while the body loads on the first matching request, so an idle skill costs nothing and a swapped model still reads the same instructions (typingmind.com). That is the structure that keeps a conventions system from becoming one bloated file.

Layer 4: hooks that return the rule

If a rule matters enough to argue about in review, enforce it mechanically and have the hook explain itself. A pre-edit hook that receives the tool call as JSON can block a write that lands outside the task's allowed paths, and the feedback channel is the whole trick: the agent is told why and what to do instead, including parking the idea for a follow-up task (dev.to). Be honest about the limits: a path hook does not cover edits made through shell commands, so the post-run check on diff size stays necessary. A packaged version of this guard exists as a plugin, which is a reasonable place to start before writing your own (github.com).

Conventions only hold if review checks them. Git is the instrument here, because a task that started from an unclear working tree cannot be judged fairly. The ESP-IDF agent workflow recommends running git status and git diff before asking for a substantial change, branching per task with prefixes like feat/, fix/ and refactor/, and committing small verified checkpoints so review compares behavior between steps (developer.espressif.com). A prompt worth keeping in the file: ask the agent to review the current diff, identify any changes unrelated to the task, summarize the rest and propose a commit message, without staging anything.

Parallel work needs its own isolation, since two agents sharing a working directory can see each other's uncommitted changes. Git worktrees give each task its own directory over one shared history, so an agent can run in the background while you keep editing, and the branch merges like any other (nx.dev). Sources that track agent sessions through Git hooks are moving the same way, capturing what happened in a session so a reviewer can see how a commit was produced rather than only what changed (github.com).

The review checklist that follows from the rules

Record any convention the agent violated without being told, then add it to the file with a one-line example. Corrections are the raw material; the file is the artifact. That loop is why teams that invest in it report the same correction rarely recurring once it is written down (news.ycombinator.com).

There is a real cost to keeping conventions in front of the model, and it is worth sizing before you write 900 lines. A study across four languages and ten models found that removing formatting elements such as indentation, whitespace and newlines cut input tokens by an average of 24.5% with negligible loss of performance on fill-in-the-middle completion (arxiv.org). The lesson is not to strip your source, it is that context budget is measurable and that structure carries real tokens, so a conventions file competes with source code for the same window.

Use that to set a target. Keep the always-loaded section under a page, put framework specifics in on-demand skills, and let hooks carry the rules that must never be skipped. If a rule has to be in the always-on block, it has to earn its place by preventing a mistake you have actually seen.

Start with one repository and one week of corrections. Write the file with the four categories, add the task-spec pointer and the diff budget, and record violations as they happen. The first five rules will come from your linters and are nearly free. The rules that matter most, the ones about surgical edits and naming, come from review comments.

For teams running agents in parallel, the next step after conventions is consistent model access and reusced skills across the whole team, so every agent reads the same instructions and hits the same APIs. Quanta Inference provides one OpenAI-compatible API key for text, image, video, audio and embedding models, so a conventions file written once applies identically across every model your agents call. The conventions you write this week are the cheapest investment you can make in every agent session that follows.