Aider: `CONVENTIONS.md` location, format and template

Where Aider reads project instructions, whether it reads AGENTS.md, and what the format allows. From the official documentation, checked Oct 7, 2026. See also Aider: pricing, popularity and alternatives.

Project files

No file loads by itself: pass one with aider --read CONVENTIONS.md or /read CONVENTIONS.md
To always load it, add read: CONVENTIONS.md to .aider.conf.yml

Global (all projects)

Not documented.

AGENTS.md

– Not automatically according to Aider's docs; load it with --read AGENTS.md.

Format and limits

Files added with --read are read-only and can be prompt-cached.

Sources: aider.chat/docs/usage/conventions.html

Templates

Always load conventions in Aider.aider.conf.yml

read:
  - AGENTS.md
  - CONVENTIONS.md

AGENTS.md for a Python projectAGENTS.md

# AGENTS.md

## Project
One paragraph: what this package does.

## Commands
- Set up: `uv sync`
- Tests: `uv run pytest -q`
- Lint and format: `uv run ruff check . && uv run ruff format .`
- Types: `uv run mypy src`

## Conventions
- Python 3.12; type hints on every public function.
- Use `pathlib`, f-strings and dataclasses; no new global state.
- Tests live in `tests/` and name the behaviour they check.

## Boundaries
- Don't touch `migrations/` without asking.
- Never print or log secrets; config comes from environment variables.

Written by AgentGid as a starting point; swap in your own commands and folders.

Aider: CONVENTIONS.md location, format and template