CONVENTIONS.md Format

aid: conventions-md:format
name: CONVENTIONS.md Format
tags:
- AI Coding
- Convention
- Markdown
- Project Configuration
image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg
humanURL: https://aider.chat/docs/usage/conventions.html
properties:
- url: https://aider.chat/docs/usage/conventions.html
  type: Documentation
- url: https://aider.chat/docs/config/aider_conf.html
  type: Documentation
- url: https://github.com/Aider-AI/aider
  type: Repository
description: The CONVENTIONS.md format is a free-form Markdown file describing the coding rules an AI
  coding agent should follow inside a repository. The file is loaded into the chat context, typically
  in read-only mode, and may be referenced via /read CONVENTIONS.md, the --read CLI flag, or a persistent
  read entry in .aider.conf.yml. Common content includes preferred libraries, language and version targets,
  type system rules, lint and format expectations, error handling style, and architectural patterns the
  project favors.
x-features:
- Plain Markdown bullet list of project rules
- Loaded into AI agent context per session or via config
- Supports prompt caching when marked read-only
- Composable alongside CLAUDE.md, .cursor/rules, and copilot-instructions
- No required schema, allowing each project to define what matters
x-useCases:
- Steering AI agents toward preferred libraries and frameworks
- Documenting type hint, naming, and lint requirements
- Capturing architecture decisions for AI assisted refactors
- Aligning human and AI contributors on a single source of conventions
- Reducing rework caused by AI generated code that misses team norms