CONVENTIONS.md

aid: conventions-md
url: https://raw.githubusercontent.com/api-evangelist/conventions-md/refs/heads/main/apis.yml
name: CONVENTIONS.md
kind: standard
description: CONVENTIONS.md is a Markdown convention popularized by AI pair programming tools such as aider and adopted by
  AI coding agents like Cursor, Cline, and Claude Code. It documents project-specific coding standards, library preferences,
  naming conventions, architecture decisions, and development practices in plain natural language so both human developers
  and AI assistants share the same expectations. The file is loaded into the model context to steer code generation toward
  project conventions.
image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
tags:
- AI Coding
- Aider
- Best Practices
- Coding Standards
- Conventions
- Developer Workflow
- Documentation
- Markdown
- Project Configuration
created: '2025-01-01'
modified: '2026-04-28'
specificationVersion: '0.19'
apis:
- aid: conventions-md:format
  name: CONVENTIONS.md Format
  tags:
  - AI Coding
  - Convention
  - Markdown
  - Project Configuration
  image: https://kinlane-images.s3.amazonaws.com/shared/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
- aid: conventions-md:related-conventions
  name: AI Coding Conventions Ecosystem
  tags:
  - AI Coding
  - Comparison
  - Conventions
  image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
  humanURL: https://docs.anthropic.com/en/docs/claude-code/memory
  properties:
  - url: https://docs.anthropic.com/en/docs/claude-code/memory
    type: Documentation
  - url: https://docs.cursor.com/context/rules-for-ai
    type: Documentation
  - url: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
    type: Documentation
  - url: https://aider.chat/docs/usage/conventions.html
    type: Documentation
  description: 'CONVENTIONS.md sits alongside several closely related AI coding conventions. CLAUDE.md is used by Claude Code
    for repository memory. .cursor/rules and .cursorrules are used by Cursor. .github/copilot- instructions.md is used by
    GitHub Copilot. Each follows a similar pattern: a Markdown or text file describing repository-specific rules that gets
    injected into the AI assistant prompt context. CONVENTIONS.md is the most tool-agnostic option and is widely adopted across
    multiple AI coding agents.'
  x-features:
  - Tool-agnostic file naming compared to CLAUDE.md or .cursorrules
  - Often committed to repo root for visibility to humans and AI
  - Frequently referenced by other agent files such as CLAUDE.md
  - Composable with .editorconfig, .prettierrc, and lint configurations
  x-useCases:
  - Sharing one set of rules across aider, Cursor, Cline, and Claude Code
  - Consolidating coding standards for human and AI contributors
  - Documenting cross-cutting concerns separate from tool-specific config
common:
- type: Documentation
  url: https://aider.chat/docs/usage/conventions.html
- type: Documentation
  url: https://docs.anthropic.com/en/docs/claude-code/memory
- type: Documentation
  url: https://docs.cursor.com/context/rules-for-ai
- type: Documentation
  url: https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com