CONVENTIONS.md

CONVENTIONS.md is a Markdown file, kept in a repository, that documents a project’s coding standards, naming conventions, architecture decisions, and development practices in one place. It began as human-facing documentation but has taken on a second life as context that AI coding assistants — tools like Aider — load so that generated code follows the same conventions a human maintainer would enforce.

• Single source of conventions - Naming, formatting, architectural, and workflow expectations captured where the code lives.
• Human and machine readable - Written for developers, but structured plainly enough for an LLM to absorb as guidance.
• AI-assistant context - Assistants read it before generating or editing code, so output matches house style instead of a generic default.
• Versioned with the code - Because it sits in the repo, the conventions evolve alongside the project and stay reviewable in pull requests.

For API teams, CONVENTIONS.md is where the rules that a governance ruleset enforces at the pipeline get restated at the point of authorship — the naming, structure, and design conventions an OpenAPI definition should follow. It is part of the same shift toward governing in the IDE, where the work happens: encoding conventions as machine-readable context so that both human developers and AI coding agents produce APIs that are consistent, predictable, and easier to govern downstream.