What is CONVENTIONS.md?

CONVENTIONS.md meaning

`CONVENTIONS.md` is a Markdown file that specifies coding guidelines for AI coding agents to follow. It was popularized by Aider, the AI pair-programming tool, and has since been adopted by other agents such as Cursor, Cline, and Claude Code. It documents project-specific coding standards, library preferences, naming conventions, and architecture decisions in plain natural language.

What to include in CONVENTIONS.md

• Library and package preferences, for example "prefer httpx over requests"
• Type annotation and typing requirements
• Code style and formatting guidelines
• Naming conventions
• Architecture and project-structure rules
• Testing and review expectations

The format is free-form Markdown, so you can write the rules as plain sentences under clear headings.

How agents load it

With Aider, you load the file as read-only so it is not edited and can be cached:

# load for one session
aider --read CONVENTIONS.md

# or inside a session
/read CONVENTIONS.md

To load it automatically every time, add it to your `.aider.conf.yml` config with `read: CONVENTIONS.md`. Other agents can reference the same file, which is why CONVENTIONS.md works as a shared, tool-neutral convention document.

A short CONVENTIONS.md example

# Conventions

- Language: Python 3.12 with full type hints.
- Prefer httpx over requests for HTTP.
- Use pytest for tests; one test file per module.
- Functions stay small and single-purpose.
- Public APIs need docstrings.

Why a shared conventions file helps

AI agents follow concrete, written rules far better than unwritten team habits. A CONVENTIONS.md keeps standards in one reviewable place, reduces inconsistent output, and works across multiple tools because it is just Markdown. Marking it read-only also means the agent treats it as guidance rather than something to rewrite.

CONVENTIONS.md vs other agent files

CONVENTIONS.md overlaps with AGENTS.md, Cursor rules, and CLAUDE.md. The difference is emphasis: CONVENTIONS.md focuses on coding standards, while AGENTS.md also covers commands and operations. Many projects use both. Compare them in the AI agent instruction files guide.

Edit CONVENTIONS.md with a preview

Draft the file in the Markdown Docs online editor to preview the structure, or download Markdown Docs to edit it on Windows.

Related references

• Aider: specifying coding conventions official Aider docs.
• conventions-md overview on the cross-tool convention.