Aider CONVENTIONS.md

What is Aider CONVENTIONS.md?

Aider CONVENTIONS.md is a project-level markdown file that tells Aider what coding conventions to follow while editing your codebase. In practice, it acts like a lightweight instruction file that Aider can read into the chat so the agent keeps your team’s preferences in mind. (aider.chat)

Understanding Aider CONVENTIONS.md

Aider’s documentation recommends loading CONVENTIONS.md with /read or the aider --read flag, which marks it as read-only and allows it to be cached when prompt caching is enabled. That makes the file useful for stable guidance such as preferred libraries, formatting rules, typing conventions, naming patterns, or repo-specific architectural choices. (aider.chat)

In a typical workflow, the conventions file sits alongside your source code and becomes part of the context Aider uses while generating edits. You can also configure Aider to always load it through .aider.conf.yml, which is helpful when you want the same standards applied every time someone works in the repo. The result is a more consistent editing experience, especially on teams that want AI-generated changes to match an existing code style. (aider.chat)

Key aspects of Aider CONVENTIONS.md include:

1. Project-scoped guidance: The file lets each repository define its own coding expectations instead of relying on one generic assistant behavior.
2. Read-only context: When loaded with /read, Aider treats it as reference material rather than editable source code.
3. Prompt efficiency: Because Aider can cache read-only files, conventions can be reused without needing to rebuild that context every turn.
4. Team consistency: The file helps multiple contributors get the same style and implementation preferences from the agent.
5. Configurable loading: Teams can load it manually, or set it in .aider.conf.yml so it is always included.

Advantages of Aider CONVENTIONS.md

1. More consistent output: The agent is more likely to follow the same rules across tasks and contributors.
2. Less repeated prompting: Common preferences do not need to be restated in every chat.
3. Better repo fit: Teams can capture local standards, such as dependency preferences or formatting rules.
4. Faster onboarding: New contributors can learn the project’s conventions from a single file.
5. Reusable across sessions: Once set up, the conventions file can become a durable part of the workflow.

Challenges in Aider CONVENTIONS.md

1. Keeping it current: If the file drifts from the real codebase, the agent may follow outdated guidance.
2. Over-specifying rules: Too many instructions can make the file noisy or harder to apply well.
3. Balancing breadth and brevity: It needs enough detail to be useful, but not so much that it becomes a policy dump.
4. Team agreement: Conventions work best when the whole team aligns on what belongs in the file.
5. Context management: Like any prompt context, it works best when paired with clear file selection and workflow discipline.

Example of Aider CONVENTIONS.md in action

Scenario: A team wants all new Python code to use httpx, add type hints, and avoid introducing new dependencies unless necessary.

They create a CONVENTIONS.md file with those preferences and run Aider with /read CONVENTIONS.md before asking it to implement a new API client. Aider then uses those instructions while editing the code, so the generated changes are more likely to match the team’s preferred style from the start. (aider.chat)

For example, instead of defaulting to requests and untyped functions, the agent can produce code that follows the project’s chosen patterns. That reduces review back-and-forth and makes AI-assisted edits feel more native to the repository.

How PromptLayer helps with Aider CONVENTIONS.md

PromptLayer gives teams a place to manage prompt behavior, versions, and evaluations in a more structured way. If you are using convention files to steer coding agents, PromptLayer can help you keep those instructions organized, observable, and easier to iterate on as your workflows grow.

Ready to try it yourself? Sign up for PromptLayer and start managing your prompts in minutes.