Aider Conventions File: Generate a Model-Agnostic CONVENTIONS.md From Your Stack

What an Aider Conventions File Does

An Aider conventions file is a markdown file — usually CONVENTIONS.md — that tells Aider the coding rules to follow in a repo: library preferences, naming, architecture decisions, the practices a reviewer would otherwise enforce by hand. You load it with /read CONVENTIONS.md, which marks it read-only and caches it. Because Aider forwards it to whatever model you're running, the file is model-agnostic in a way a tool-specific config isn't.

Aider's conventions docs show how to load the file and include a before/after example: with conventions, the same task uses httpx and type hints; without them, it reaches for requests and skips the types. Useful demonstration. But the page assumes you've already written the file. The community conventions-md repo collects examples, mostly unstructured. None produce a focused file from your stack.

Why a Conventions File Beats Ad-Hoc Prompting

The before/after in Aider's docs is the whole argument. Type the task with no conventions and the model defaults to whatever its training data favored: often a library you've moved off, a style your reviewers reject. Load a conventions file and the same task lands inside your house rules on the first try.

The catch is that a sprawling conventions file underperforms a focused one. Pile in every preference you've ever had and you get a file that's read-only context on every request, where the rule that matters is buried among forty that don't. The skill isn't listing conventions. It's listing the ones that actually change the output.

The Section Contract for a Useful CONVENTIONS.md

A generator prompt that reads your stack can fill a fixed skeleton, so the file is focused instead of a brain-dump:

• Library preferences. The libraries this repo standardized on, and the ones to avoid. httpx over requests, not "use good HTTP libraries."
• Naming and style. The conventions a formatter doesn't already enforce. What reviewers actually flag.
• Architecture decisions. The structural choices the model should respect: layering, where logic lives, patterns to follow.
• Testing expectations. What the model writes alongside a change, and how it runs.
• A verification block. A short checklist the model self-applies before returning a diff: did it use the preferred library, follow the naming, write the tests. This is the piece that turns a wish list into a contract.

That verification block is the difference between conventions the model reads and conventions the model checks itself against.

Why Read-Only and Cached Both Matter

Aider loads the conventions file with /read, which does two quiet things worth understanding. It marks the file read-only, so Aider treats it as reference the model consults rather than code the model might rewrite. And it caches the file when prompt caching is on, so you're not re-paying for those tokens on every message in a session.

Both matter more than they sound. Read-only means a stray "clean up the markdown" request won't have the agent editing its own rulebook mid-task. Caching means a thorough conventions file costs less than the line count suggests, which removes the usual excuse for keeping it thin. You can afford the verification block and the library list, because after the first message they're effectively free for the rest of the session.

The practical setup is to wire read: CONVENTIONS.md into .aider.conf.yml so it loads on every launch automatically. Then the file is always present, always read-only, always cached, and you never think about it again until a convention changes. That's the difference between a conventions file you maintain and one you set up once and forget, in the good way.

How to Generate Your CONVENTIONS.md, Step by Step

1. Gather stack facts

The libraries you've standardized on, the naming reviewers enforce, the architectural lines you protect.

2. Fill the variables

The prompt takes {{stack}} and {{conventions}}. The output is a focused file plus a verification block tuned to those conventions.

3. Load it into Aider

Add read: CONVENTIONS.md to .aider.conf.yml so it loads on every launch, marked read-only and cached.

4. Tighten over time

When Aider keeps reaching for the wrong library, that's a missing convention. Add the one line, not a paragraph.

One Opinion: A Verification Block Beats a Longer Convention List

Here's a stance most conventions files miss. The reflex, when the model ignores a rule, is to restate it louder or longer. That rarely helps. The model already had the rule; it didn't check itself against it. A short verification block ("before returning, confirm: preferred libraries used, naming followed, tests included") forces a self-check that a buried convention never triggers.

Three checked rules beat thirty listed ones. The model weights the recent self-check more than a convention it read paragraphs earlier, the same way a code review policy with an explicit findings contract outperforms a prompt that just says "review carefully." Put the contract at the end, where the model reads it last.

Variables You'll Set

Getting Started

1. List the libraries you've standardized on, and the ones to avoid.
2. Write the conventions a formatter doesn't already catch.
3. Feed {{stack}} and {{conventions}} to a generator prompt with a fixed contract.
4. Take the focused file plus its verification block.
5. Wire it into .aider.conf.yml with read: CONVENTIONS.md so it loads every session.

For the review rules that pair with conventions, the Code Review Policy System Prompt produces a severity-rated findings contract the model can self-apply. And since CONVENTIONS.md can double as an AGENTS.md per the agent-rules standard, the AGENTS.md Generator for Polyglot Monorepos emits the same facts in the canonical cross-tool format.

Why the contract survives a model switch

A tool-specific config bakes in assumptions about one model's quirks. A contract-locked CONVENTIONS.md states the rules and the self-check plainly, so it behaves the same whether Aider routes to a strong model or a cheap one. That portability is the point — the conventions are yours, not a particular model's. When the model changes, the file doesn't.

A conventions file is the cheapest way to make any model code like your team instead of like its training set. Keep it focused, give it a verification block, and load it on every launch. For the tool-specific equivalents, see Cline rules and how to write .cursorrules that actually work.