Aider best practices: the first-week workflow that makes it actually work

Aider is the OSS CLI AI pair-programmer that I reviewed positively in our Aider review. The review is the “should you use it” piece; this guide is the “OK you decided to use it — what does the first productive week actually look like?” piece.

After three months of daily Aider use, here is the configuration, conventions, and conversational habits that turn it from “competent” to “genuinely productive.”

Install and bootstrap

pip install aider-chat
# Add your Anthropic / OpenAI / OpenRouter key to ~/.aider.conf.yml or env vars
cd ~/your-project
aider

That’s it. Aider auto-detects your .git, indexes the repo, and drops you in a REPL. The first few minutes are unceremonious by design.

The .aider.conf.yml that earns its keep

A working ~/.aider.conf.yml for me looks like this:

model: anthropic/claude-3-7-sonnet-20250219
weak-model: anthropic/claude-3-5-haiku-20241022
editor-model: anthropic/claude-3-7-sonnet-20250219
# Tell Aider where to find your API keys
anthropic-api-key: sk-ant-...
openai-api-key: sk-...
# Auto-commit each accepted edit
auto-commits: true
# Don't pretty-print the diff into chat; let me read the actual diff
pretty: false
# Show token usage after each turn for budget awareness
verbose: false

The key choices:

• model: claude-3-7-sonnet for primary work. Better than 3.5 by a meaningful margin (see our 3.7 Sonnet piece). DeepSeek V3 is a viable cheaper alternative if budget matters.
• weak-model: claude-3-5-haiku for cheap operations like file searches and metadata extraction. Saves significant tokens.
• auto-commits: true — non-negotiable. The discipline of commits-per-edit is the workflow.

The .aider/CONVENTIONS.md file

Every project I run Aider on has a .aider/CONVENTIONS.md at the root. Aider reads this on session start and treats it as a system-prompt extension.

A representative one:

# Aider conventions for this project

## Stack
- TypeScript strict mode; never disable strict
- Astro 5 + Tailwind 4
- Cloudflare Workers (workerd runtime, NOT Node)

## Style
- Single quotes for JS strings except where escaping forces double
- No comments unless the why is non-obvious
- Function names: verb-noun, e.g. `loadUser` not `getUser`

## Testing
- Vitest for unit tests; integration tests are e2e via Playwright
- Don’t mock unless the real dependency is genuinely impractical

## Do not
- Edit `wrangler.jsonc` without explicitly being asked
- Add new dependencies without explicit approval
- Touch the `dist/` directory — it’s a build output

## Patterns I want
- Prefer Zod schemas for any data crossing a boundary
- Error handling at boundaries, not throughout
- Server-only modules use the `~/server/` directory

This file is the single biggest productivity multiplier I’ve found with Aider. It turns “the model occasionally does something annoying” into “the model follows my conventions consistently.” Twenty minutes of writing this file at project start saves hours of correcting drift over the next month.

The conversational pattern that works

Aider is conversational. The pattern that gets the most value:

1. Add the relevant files explicitly: /add src/api/auth.ts src/api/auth.test.ts. Aider works best when you scope its attention precisely.
2. Describe the change in one paragraph: not “fix the bug” but “the loadUser function returns null for users with deleted accounts but the type signature says non-null — make it explicit nullable and update callers.”
3. Read the diff before accepting: don’t just press Enter to confirm. Skim what changed.
4. Iterate via test failures: “run npm test. If anything fails, fix it.” Aider will keep going.
5. Use /clear between unrelated tasks: Aider’s context is conversation. Clearing reduces noise and saves tokens.

Multi-model routing

The single biggest power-user trick: route different tasks to different models.

/model anthropic/claude-3-7-sonnet
[do the hard task]
/model deepseek/deepseek-coder
[do the routine refactor]
/model openai/o1-mini
[debug the gnarly issue]

Aider lets you swap mid-session. The trade-off is each model has its own conversation cache, so you’re paying re-encoding cost on the swap. Use sparingly — but for clearly-bounded tasks the savings are real.

What to NOT do

• Don’t use Aider on greenfield single-file scripts: Cursor or just typing is faster
• Don’t add files you don’t need to context: every file is tokens
• Don’t use the same conversation for unrelated tasks: /clear
• Don’t over-specify the prompt: a one-paragraph instruction beats a half-page spec
• Don’t skip the .aider/CONVENTIONS.md: this is the cheap leverage

A real session, end to end

A representative half-hour session from last week:

1. aider in the project root, no flags (config picks up everything)
2. /add src/lib/auth.ts src/lib/auth.test.ts
3. “The auth module has stopped working after we changed the JWT signing. Run the tests, find the failure, propose a fix.”
4. Aider runs the tests, reports the failure, proposes a diff
5. I read the diff. It’s correct but missing handling for the expired-token case. I say so.
6. Aider revises. I accept. Auto-commit happens.
7. I /clear and start the next task.

The whole loop is fast because the workflow is fast — not because the model is faster than alternatives. The discipline pays off.

The bigger pattern

Aider rewards conventions. Set them up once at the project level, and the AI behaves like a team member who actually read the contributing guide. Don’t set them up, and you’re re-correcting drift forever.

For the comparative review of Aider vs the alternatives, see our Aider review. For the broader AI coding stack, Claude Code vs Cursor.