Aider Conventions: How to Write Effective .aider.conf.yml Rules

What is Aider?

Aider is an open-source AI pair programmer that runs in your terminal. Unlike Cursor or Windsurf, it works with any editor. You launch it from the command line, and it edits your files directly using models like Claude Opus, GPT-4o, or Gemini. If you spend most of your time in a terminal or prefer not to switch editors, Aider is often the fastest way to get AI assistance on real codebases.

The tradeoff is that Aider doesn't have a GUI for managing project context. Instead, it relies on configuration files to understand your conventions. Get the configuration right, and Aider produces remarkably consistent, idiomatic code. Get it wrong, and you'll spend half your session correcting the same mistakes.

This guide covers the two key configuration mechanisms: .aider.conf.yml for runtime settings and CONVENTIONS.md for coding guidelines, and how to combine them effectively.

.aider.conf.yml: Runtime configuration

The .aider.conf.yml file lives in your project root and controls how Aider runs: which model to use, how to format output, which files to read automatically, and dozens of other options.

Here's a solid starting point:

# .aider.conf.yml
model: claude-opus-4-6
dark-mode: true
auto-commits: false
dirty-commits: false
read:
  - CONVENTIONS.md
  - docs/architecture.md
map-tokens: 4096
stream: true

The most important settings to get right:

model

Pick a model that matches your use case. For complex refactors across large files, claude-opus-4-6 or o1 is worth the extra cost. For quick edits or high-volume work, claude-sonnet-4-6 or gpt-4o-mini gives good results at lower cost.

# For complex, architectural changes
model: claude-opus-4-6

# For everyday edits and high velocity
model: claude-sonnet-4-6

read

The read key is where most projects under-invest. Files listed here are included in every Aider context window; Aider reads them but won't edit them. This is where you put your conventions, architecture docs, and any context that should always be present:

read:
  - CONVENTIONS.md
  - docs/architecture.md
  - docs/api-patterns.md
  - .env.example

Including .env.example (not .env) gives Aider visibility into your environment variable names without exposing secrets.

auto-commits

Whether to auto-commit after each change is a personal preference, but most teams working in shared repos turn this off:

auto-commits: false
dirty-commits: false

With auto-commits: false, Aider makes the code changes but leaves the commit to you. This fits better with conventional commit workflows and PR review processes.

map-tokens

The repo map is how Aider understands your codebase without reading every file. It builds a summary of your project's classes, functions, and structure within a token budget. The default is often too small for medium-to-large projects:

map-tokens: 4096   # default 1024, increase for larger codebases
map-refresh: auto

For projects with 50+ files, setting this to 4096–8192 dramatically improves Aider's ability to find the right files and understand dependencies.

CONVENTIONS.md: Coding guidelines

While .aider.conf.yml controls runtime behavior, CONVENTIONS.md is where you encode your project's coding conventions. Aider reads this file at the start of every session (when listed under read:) and applies the guidelines throughout.

This is the file that prevents Aider from generating code that technically works but violates your patterns: using the wrong import style, writing tests in the wrong format, or missing required error handling.

What to include

A good CONVENTIONS.md covers:

Tech stack and versions - Don't assume Aider knows what you're using:

## Stack

- Language: TypeScript 5.7 (strict mode enabled)
- Runtime: Node.js 22 / Bun 1.2
- Framework: Next.js 15 (App Router only, no Pages Router)
- Database: PostgreSQL via Drizzle ORM
- Testing: Vitest + React Testing Library
- Styling: Tailwind CSS v4

Naming conventions - These are surprisingly important for consistency:

## Naming

- Files: kebab-case (e.g., `user-profile.ts`, not `UserProfile.ts`)
- React components: PascalCase named exports (never default exports)
- Database tables: snake_case plural (e.g., `user_sessions`)
- Environment variables: SCREAMING_SNAKE_CASE
- Types/interfaces: PascalCase, no I-prefix (e.g., `User`, not `IUser`)

Code patterns - Show the exact structure you expect:

## API routes

All API routes use Next.js App Router handlers:

export async function POST(request: Request) {
  try {
    const body = await request.json()
    const validated = schema.parse(body)
    const result = await processRequest(validated)
    return Response.json({ data: result })
  } catch (error) {
    if (error instanceof ZodError) {
      return Response.json({ error: error.issues }, { status: 422 })
    }
    return Response.json({ error: 'Internal server error' }, { status: 500 })
  }
}

Hard boundaries - The things you never want:

## Do NOT

- Do not use `any` type; use `unknown` and narrow explicitly
- Do not use `var`; use `const` or `let`
- Do not write raw SQL; use Drizzle query builder
- Do not use `console.log` in production code; use the `logger` utility
- Do not install new packages without asking first

Structure your CONVENTIONS.md for skimmability

Aider parses your conventions into its context window. Clear headers and short sections are more reliable than dense paragraphs. Use level-2 headers for each topic, keep each section under 20 lines, and put the most critical conventions first.

# Project Conventions

## Stack
...

## Code Style
...

## Error Handling
...

## Testing
...

## Do NOT
...

A complete working example

Here's a full configuration for a TypeScript/Next.js project:

# .aider.conf.yml
model: claude-sonnet-4-6
dark-mode: true
auto-commits: false
dirty-commits: false
stream: true
map-tokens: 4096
map-refresh: auto
read:
  - CONVENTIONS.md
  - docs/architecture.md
cache-prompts: true

# CONVENTIONS.md

## Stack
- TypeScript 5.7, strict mode
- Next.js 15 App Router
- Drizzle ORM + PostgreSQL
- Vitest for tests
- Tailwind CSS v4

## Naming
- Files: kebab-case
- Components: PascalCase named exports
- DB tables: snake_case plural

## Error handling
All async functions use try/catch and return typed errors.
Never use `!!` to assert non-null; use explicit checks.

## Testing
Tests live at `src/__tests__/` mirroring the source structure.
Each test file imports from `@/test-utils` for shared fixtures.

## Do NOT
- No Pages Router code
- No `any` type
- No default exports for components
- No raw SQL queries

Multi-file conventions with aider-ignore

Like .gitignore, Aider respects a .aiderignore file to exclude files from its repo map:

# .aiderignore
node_modules/
.next/
dist/
*.lock
coverage/

Excluding lockfiles and build artifacts keeps the repo map focused on actual source code. For monorepos, you can also use this to exclude packages Aider shouldn't touch in a given session.

The cross-team problem with Aider conventions

Writing great CONVENTIONS.md and .aider.conf.yml files is meaningful work, but those conventions have a scope problem. They only apply to the project where the files live.

If your team has five repositories, you're either duplicating the conventions five times (and keeping them in sync by hand) or accepting that each repo drifts toward its own dialect. If you bring on a contractor who uses Cursor instead of Aider, the conventions don't transfer at all.

This is the same problem facing the entire AI coding tools space: every tool has its own rules format, and there's no shared layer between them.

localskills.sh provides that shared layer. You write your conventions once, publish them as a skill, and install them into any combination of tools and repositories with a single command. For Aider specifically, the CLI writes the correct files into your project directory:

# Install your team's conventions into the current project for Aider
localskills install your-team/api-conventions --target aider

This writes the convention files in the right location and format for Aider, adds the read: entries to .aider.conf.yml, and links to the version you installed so you can see when updates are available.

Versioning your conventions

Conventions should evolve. When your team adopts a new pattern (switching from REST to tRPC, adding Zod for validation, moving to a different test structure), you update the conventions and want those updates to reach everyone.

With files checked directly into each repo, "updating everyone" means opening PRs in five repositories. With a published skill, it's:

# Update to the latest version of the conventions skill
localskills pull

Skills are versioned with semantic versioning, so a breaking change in conventions increments the major version and teams can migrate at their own pace.

Combining Aider with other tools

Many developers use Aider alongside Cursor or Claude Code: Aider for quick terminal sessions, Cursor for longer context or UI-heavy work. If your conventions live in published skills, both tools stay in sync automatically. When you update the skill, you run localskills pull once and every tool in every project reflects the change.

Read more about writing rules that work across all AI coding tools, or follow the step-by-step guide to publishing your first skill.

Summary

A well-configured Aider setup has two layers:

The conventions file does the real work. Specific, example-driven guidelines consistently outperform vague style guidance. Put the hard rules at the top, show the patterns you want with code examples, and list explicit "do not" items.

Once you've written conventions you're happy with, publish them to localskills.sh so the whole team benefits and they stay consistent across every repo and every AI coding tool you use.

---

Ready to share your Aider conventions across your team and tools? Sign up for localskills.sh and publish your first skill today.

npm install -g @localskills/cli
localskills login
localskills publish