Aider AGENTS.md vs CONVENTIONS.md: Complete 2026 Guide to Convention Files

Aider has used CONVENTIONS.md since its early days as the place to put coding standards, test commands, and project-specific rules. It works. Millions of Aider sessions have run against CONVENTIONS.md files with no issues. But 2025 changed the picture: the AI coding ecosystem expanded to dozens of tools, and AGENTS.md emerged as the cross-tool standard. Today, a team using Aider alongside Claude Code, Cursor, or GitHub Copilot has a real choice to make — and the right answer is not always obvious.

This guide covers how both formats work inside Aider, how they compare across the broader tooling landscape, and how to migrate cleanly from CONVENTIONS.md to AGENTS.md when it makes sense.

1. Aider’s Convention File System: A Quick History

Aider’s --conventions-file flag is the mechanism at the center of this. It lets you pass any Markdown file to Aider, and Aider prepends that file’s content to the system prompt before every session. The flag predates the name “CONVENTIONS.md” — it accepts any path.

The default, CONVENTIONS.md, became standard because it was what Aider’s documentation recommended and what teams naturally named the file. Over time, CONVENTIONS.md files grew to include:

• Code style rules (language-specific formatting preferences)
• Test commands (pytest -x --tb=short and similar)
• Architecture constraints (which files not to edit, which patterns to avoid)
• Commit message formats
• Dependency policies

This worked well when Aider was the only AI coding tool on a given project. The file was Aider’s own, the team knew where to look, and there was no ambiguity about ownership.

2025: AGENTS.md enters the ecosystem. OpenAI, Anthropic, GitHub, and independent tool authors converged on AGENTS.md as a shared convention file format. The Linux Foundation’s Agentic AI Foundation formalized the spec. By mid-2025, 28+ tools — including Claude Code, GitHub Copilot, Cursor, Cline, Roo Code, and Aider itself — had added AGENTS.md support.

Aider’s implementation: native AGENTS.md detection was added, and the existing --conventions-file flag became the explicit way to route Aider to AGENTS.md. The two mechanisms are equivalent in behavior; the difference is whether you rely on automatic detection or explicit configuration.

2. How Aider Reads CONVENTIONS.md (and AGENTS.md)

The internal mechanics are the same regardless of which file you use. When Aider loads a convention file, it:

1. Reads the file in full
2. Prepends the content to the system prompt that accompanies every conversation turn
3. Keeps it active for the entire session

This means Aider processes the entire file — not just specific sections. Unlike some tools that parse AGENTS.md and extract only relevant sections, Aider treats the convention file as a flat document that it presents to the model as context.

Practical implication: sections you add to AGENTS.md for other tools (like a ## GitHub Copilot section with Copilot-specific rules) will also be visible to Aider. This is not a problem — the model is smart enough to apply relevant rules — but it means you should write rules as generally applicable constraints rather than tool-specific overrides when possible.

Default detection behavior:

# Aider looks for CONVENTIONS.md automatically in the project root
aider

# Explicit override to use AGENTS.md
aider --conventions-file AGENTS.md

# Use a file in a subdirectory
aider --conventions-file docs/AGENTS.md

As of 2025, Aider also detects AGENTS.md in the project root without explicit flags, but the --conventions-file path remains the explicit, reliable method. If you want guaranteed behavior regardless of Aider version, set it in .aider.conf.yaml.

3. AGENTS.md vs CONVENTIONS.md: Head-to-Head Comparison

The content format is identical — both are plain Markdown with no enforced schema. The only structural difference is in tooling recognition: AGENTS.md is understood by the entire ecosystem, while CONVENTIONS.md is understood only by Aider.

4. Should You Migrate from CONVENTIONS.md to AGENTS.md?

The answer depends on your tool setup.

Stay with CONVENTIONS.md if:

• Your team uses Aider exclusively
• No other AI coding tools are in use on the project
• You have an existing CONVENTIONS.md with no intention of adding other tools

There is no functional benefit to renaming the file in a purely Aider environment. The content works identically. Migration adds overhead with zero upside.

Migrate to AGENTS.md immediately if:

• You use Aider alongside Claude Code, Cursor, Copilot, or any other AGENTS.md-supporting tool
• You want a single convention file that serves all AI tools on the project
• You are starting a new project and want future-proof configuration

In a multi-tool environment, CONVENTIONS.md means your conventions only apply to Aider sessions. Claude Code sessions, Cursor edits, and Copilot completions operate with no awareness of your project’s rules. That gap accumulates into inconsistent code across tools.

If you have both AGENTS.md and CONVENTIONS.md: Remove CONVENTIONS.md. Having two files creates ambiguity — which is authoritative? Teams end up updating one and forgetting the other. Consolidate into AGENTS.md, configure Aider to use it, and commit the cleanup.

5. Migration Guide: CONVENTIONS.md → AGENTS.md

This migration takes less than 15 minutes for most projects.

Step 1: Rename or copy the file

# Option A: rename in place
mv CONVENTIONS.md AGENTS.md

# Option B: if you want to preserve CONVENTIONS.md temporarily
cp CONVENTIONS.md AGENTS.md

Step 2: Add standard AGENTS.md sections (if not already present)

AGENTS.md has no enforced schema, but the ecosystem has converged on a few standard section names. Check that your file has at minimum:

# AGENTS.md

## Commands

```bash
# Tests
pytest -x --tb=short

# Linting
ruff check .

Code Style

• Use type hints on all public functions
• Follow PEP 8; formatter is black (line length 88)
• Prefer explicit over implicit

Architecture Notes

• Do not edit files in /generated — they are auto-generated
• API clients live in src/clients/; do not make HTTP calls elsewhere

The section names matter because some tools (Claude Code, in particular) parse specific sections. Aider reads the entire file regardless of section names, so this change does not affect Aider behavior — but it improves compatibility with other tools that do parse.

### Step 3: Configure .aider.conf.yaml

Create or update `.aider.conf.yaml` in the project root:

```yaml
# .aider.conf.yaml
conventions-file: AGENTS.md
auto-commits: false
model: claude-sonnet-4-5

This makes the AGENTS.md association permanent. Every aider invocation in this project will load AGENTS.md without requiring the --conventions-file flag.

Step 4: Remove CONVENTIONS.md (if you renamed a copy)

# Only if you chose Option B in Step 1
rm CONVENTIONS.md

Step 5: Verify other tools pick it up

• Claude Code: Run claude in the project root. Claude Code reads AGENTS.md automatically. No additional configuration needed.
• Cursor: Open the project in Cursor. It will read AGENTS.md on session start.
• GitHub Copilot: In VS Code with the Copilot extension, AGENTS.md is read from the workspace root.
• Cline/Roo Code: Both read AGENTS.md from the project root.

Before/after snapshot:

Before migration:

my-project/
├── CONVENTIONS.md        ← Aider reads this
├── .aider.conf.yaml      ← (may not exist)
└── src/

After migration:

my-project/
├── AGENTS.md             ← All tools read this
├── .aider.conf.yaml      ← conventions-file: AGENTS.md
└── src/

6. Aider-Specific AGENTS.md Sections That Work Best

Not all AGENTS.md content has equal impact in Aider sessions. Some sections reliably affect Aider behavior; others are informational for humans or for other tools.

High impact in Aider:

• Code style rules — Aider applies these precisely. Language, formatting, import ordering, type hints. Be specific.
• Test commands — Aider uses these when running tests during edit-test loops. Include the exact flags you want.
• Forbidden patterns — Rules like “do not modify files in /generated” or “never use eval()” are reliably respected.
• Architecture constraints — Which modules own which responsibilities. Aider uses these to decide where to place new code.

Lower impact in Aider (but safe to include):

• PR/commit message formats — Useful context, but Aider’s commit behavior is more directly controlled by --auto-commits and similar flags.
• Tool-specific sections — A ## GitHub Copilot section with Copilot-specific rules will be visible to Aider but is unlikely to affect its behavior. Aider will treat it as informational context.
• Project overview — Background on what the project does. Helpful for context but not actionable for Aider’s edit decisions.

Adding Aider-specific rules to AGENTS.md does not break other tools. The content is readable Markdown; other tools will simply skip rules that do not apply to them or treat them as general context.

7. Full AGENTS.md Template for Aider Teams

The following template is optimized for teams using Aider as the primary tool alongside at least one other AI coding assistant. Comments indicate which tools actively use each section.

# AGENTS.md

<!-- Read by: Aider, Claude Code, Cursor, GitHub Copilot, Cline, Roo Code -->

## Commands

<!-- Aider: uses these in edit-test loops. Claude Code: runs these for validation. -->

```bash
# Setup
pip install -e ".[dev]"

# Tests
pytest -x --tb=short             # Run tests, stop on first failure
pytest --cov=src --cov-report=term-missing  # With coverage

# Linting & formatting
ruff check .                     # Linting
ruff format .                    # Formatting
mypy src/                        # Type checking

# Build
python -m build

Code Style

• Python 3.11+ — use match/case, type hints on all public functions
• Formatter: ruff (line length 100)
• Type annotations: required on all public methods and module-level functions
• Docstrings: Google style, required on public classes and functions
• Imports: stdlib → third-party → local, separated by blank lines (ruff enforces)
• No print() in library code — use logging with appropriate levels

Architecture

• src/core/ — domain logic, no external dependencies
• src/adapters/ — I/O, external services, databases
• src/api/ — HTTP layer only, delegates to core
• tests/ mirrors src/ structure
• Do not import from src/api/ in src/core/ — direction is one-way

Constraints

• Do not edit files in src/generated/ — auto-generated from schema
• Do not use eval(), exec(), or dynamic imports
• All database queries through the repository layer — no raw SQL in API handlers
• New dependencies must be added to pyproject.toml, not installed ad-hoc

Testing Standards

• Every public function needs at least one unit test
• Use pytest fixtures, not setUp/tearDown
• Mock external services at the adapter boundary
• Parametrize tests over multiple inputs rather than repeating test functions
• Test file names: test_<module>.py

Git

• Commit message format: type(scope): description (Conventional Commits)
• Types: feat, fix, docs, refactor, test, chore
• Keep commits atomic — one logical change per commit

## 8. Configuring .aider.conf.yaml for AGENTS.md

`.aider.conf.yaml` is the most reliable way to bind Aider to AGENTS.md. Place it in the project root and commit it alongside AGENTS.md — this ensures every developer on the team gets the same Aider behavior without needing to remember command-line flags.

```yaml
# .aider.conf.yaml

# Convention file — point Aider at AGENTS.md
conventions-file: AGENTS.md

# Model settings
model: claude-sonnet-4-5

# Behavior
auto-commits: false      # Require manual commits; review before committing
dirty-commits: false     # Do not commit when working tree has uncommitted changes
suggest-shell-commands: true

# Output
pretty: true
stream: true

Key points on this configuration:

• conventions-file: AGENTS.md is the single change that routes all convention loading to AGENTS.md
• auto-commits: false is a common setting for teams that prefer reviewing AI-generated changes before committing — it has no relation to AGENTS.md but is worth including in a committed config
• The model setting can be left out if you prefer to set it per-session; including it standardizes the team’s default

If your AGENTS.md lives outside the project root (e.g., in a monorepo setup at the workspace root), use a relative path:

conventions-file: ../../AGENTS.md

Aider resolves conventions-file paths relative to the directory where .aider.conf.yaml is located.

9. FAQ

Does Aider read AGENTS.md?

Yes. Aider added native AGENTS.md support in 2025. You can also explicitly point Aider at it using aider --conventions-file AGENTS.md, or set conventions-file: AGENTS.md in your .aider.conf.yaml to make it permanent.

What is the difference between AGENTS.md and CONVENTIONS.md in Aider?

CONVENTIONS.md is Aider’s original convention file format, recognized by Aider only. AGENTS.md is a cross-tool standard supported by 28+ AI coding tools including Claude Code, GitHub Copilot, and Cursor. Both work identically inside Aider — the difference is portability.

How do I make Aider use AGENTS.md instead of CONVENTIONS.md?

Add conventions-file: AGENTS.md to your .aider.conf.yaml file in the project root. Alternatively, run aider --conventions-file AGENTS.md on the command line. Aider will then read AGENTS.md as its convention file instead of CONVENTIONS.md.

Should I delete CONVENTIONS.md if I have AGENTS.md?

Yes, if you have fully migrated the content to AGENTS.md. Keeping both creates confusion about which file is authoritative. Configure Aider to use AGENTS.md via .aider.conf.yaml, then remove CONVENTIONS.md to avoid drift between the two files.

Does AGENTS.md replace CONVENTIONS.md?

For teams using Aider alongside other AI tools (Claude Code, Cursor, Copilot), AGENTS.md is the recommended replacement. For Aider-only teams, CONVENTIONS.md still works and requires no migration. The practical advantage of AGENTS.md is that a single file serves all tools.

What is .aider.conf.yaml?

.aider.conf.yaml is Aider’s project-level configuration file. It lets you set defaults for flags like --conventions-file, --model, --auto-commits, and others, so you do not need to pass them on the command line every time. Place it in the project root and commit it to version control.

Related Articles

• AGENTS.md Best Practices: What 60,000+ Repos Teach Us
• AGENTS.md vs CLAUDE.md: Which File Controls Claude Code?
• Cline vs Roo Code: Rules Files Compared

Keep Aider’s API Keys Secure

Aider connects to Claude, GPT-4, and other providers — each requiring its own API key. 1Password CLI lets you inject those keys via op run -- aider without storing them in .env files or shell profiles. Works with any model Aider supports.