Getting Started With Aider: The Setup Tutorials Get Wrong

Most Aider tutorials are wrong about the very first thing they tell you to do. They say: add your files, point it at the repo, start chatting. Follow that advice and your first session is expensive, unfocused, and a little disappointing — which is why a lot of people try Aider once and quietly go back to their IDE. This Aider AI coding tutorial takes the opposite stance, because the thing that makes Aider genuinely good is the part beginner guides bury at the bottom.

Here's a composite from real patterns I keep seeing, to show what goes wrong and how to fix it.

The Problem a Senior Engineer Faced

Call her Priya — a senior backend engineer at a logistics startup, comfortable in the terminal, skeptical of AI tools. She'd read three quick-starts, installed Aider, and wanted it to refactor a payments module spread across eight files.

pip install aider-chat
aider
,[object Object],

What this does: Installs Aider and starts a session. The

/add

Her first session cost more than she expected, produced a sprawling diff, and touched files she never meant to change. The tool worked. The approach didn't. This is the gap most any Aider AI coding tutorial leaves you to fall into on your own.

The Wrong Approach

The mistake is treating Aider like a chatbot that needs to see your whole codebase to help. It doesn't. Aider already builds a repository map with tree-sitter — a compact summary of every function signature and class definition across the project — and hands that map to the model as ambient context. When you also

/add

[object Object],
/add src/**/*.py
> refactor the payments logic to be cleaner

What this does: Adds every Python file and gives a vague goal. The agent now has too much to look at and no clear target, so it makes broad, low-confidence changes. This is the pattern to avoid.

⚠️ Common mistake: Adding files "just in case." Every file you add is context you pay for and noise the model has to filter. The repo map already tells Aider what exists; you only

/add

The Correct Prompt — The Aider AI Coding Tutorial Most People Skip

Two changes fix Priya's session. First, narrow the context to just the files being edited. Second — and this is the part that's genuinely underused — switch on architect/editor mode.

Architect mode splits the work across two models. A strong "architect" model reasons about what to change and writes the plan. A cheaper "editor" model takes that plan and produces the precise file diff. You get frontier-level reasoning where it matters and cheap, reliable edits where it doesn't.

aider --architect --model o1 --editor-model sonnet src/payments/core.py src/payments/fees.py
> add idempotency keys to the charge and refund handlers; keep the public API unchanged

What this does: Starts Aider in architect mode with a high-reasoning planner and a cheaper editor model, scoped to just two files. The planner decides the approach; the editor applies it as a clean diff. Narrow context plus a specific, bounded goal.

The prompt itself does real work too. "Keep the public API unchanged" is a constraint that stops the agent from helpfully rewriting your interfaces. Specific verbs ("add idempotency keys to the charge and refund handlers") beat vague adjectives ("cleaner") every time.

⚡ Pro tip: Aider's leaderboard tracks 70-plus models, and you can mix them freely. Use an expensive model as the architect only for the hard reasoning, then let a much cheaper model do the mechanical edit. On a big refactor this two-model split can cut token cost substantially versus running one premium model for everything.

Results and What Changed

With narrow context and architect mode, Priya's second attempt produced a two-file diff that did exactly what she asked, and Aider committed each change atomically with a generated message. When one edit wasn't quite right,

/undo

That auto-commit behavior, by the way, is the other thing beginners get told to disable and shouldn't. Every turn becomes its own commit, so your session reads like a working log you can bisect, revert, and squash later before opening a pull request.

The cost difference was the part that changed Priya's mind. Running one premium model for both planning and editing on a multi-file change adds up quickly, because the editing step — producing exact diffs — burns a lot of tokens on mechanical work that doesn't need frontier reasoning. Splitting that across a strong planner and a cheap editor put the expensive thinking only where it mattered. On her payments refactor, that structure meaningfully cut what the session cost, and the edits were more accurate, not less, because the editor model had a clear plan to follow instead of reasoning and editing at once.

⚡ Pro tip: Watch the token counter Aider prints after each turn. If the number spikes on a simple edit, that's your signal the context is too wide — you added files you didn't need, or the repo map is set too large. The counter is the fastest feedback loop you have for keeping cost sane.

git ,[object Object], --oneline -5   ,[object Object],
/undo                  ,[object Object],

What this does: Shows the atomic commit trail Aider produced, and demonstrates the one-command rollback. Git is the safety net, which is why treating the auto-commits as a feature — not a nuisance — is the right instinct.

Understanding Aider's Edit Modes

Architect/editor is one of four edit modes, and knowing when to switch is the difference between an Aider AI coding tutorial that reads well and one you can actually work from. The modes trade off precision, cost, and how much of a file the agent touches.

Diff mode is the everyday default: the agent returns a search-replace diff, so it changes only the lines it needs to. It's cheap and produces small, reviewable changes — the mode you want for most edits.

Whole mode has the agent return the entire file. It's more reliable when a change is sweeping and the file is small, but on a large file it's expensive and produces a diff that's hard to review. Reach for it rarely.

Architect mode is the two-model split covered above: a planner reasons, an editor applies. Use it for changes hard enough that the reasoning matters — non-trivial refactors, anything touching business logic.

aider --edit-format diff src/api/routes.py
> add rate limiting to the /login route only

What this does: Forces the compact diff format and scopes the change to one route in one file. The agent produces a minimal search-replace edit instead of regenerating the file, so your review takes seconds.

⚡ Pro tip: Match the mode to the change, not the other way around. Small, surgical edit? Diff mode. Genuinely hard refactor where you'd want a senior engineer to think first? Architect mode. Don't default to the most powerful mode for everything — you'll pay for reasoning you didn't need.

How to Apply This to Your Situation

A data engineer maintaining a dbt project: run Aider with

--no-auto-commits

An indie developer on a tight budget: put your model config in

.aider.conf.yml

map-tokens

# .aider.conf.yml
architect: true
model: o1
editor-model: sonnet
map-tokens: 2048

What this does: Makes the two-model architect setup and a bounded repo map your permanent defaults, so every session starts cost-aware without extra flags.

A team lead onboarding juniors: pair Aider's

--watch

AI?

# AI? add error handling here

A machine-learning engineer maintaining a training pipeline: Aider's editor-agnostic design means she runs it in a tmux split on the remote GPU box over SSH, edits files there, and never installs an IDE on a machine whose whole job is running jobs. The repo map keeps the sprawling pipeline code navigable, and atomic commits give her a clean trail to roll back when an experiment's code change doesn't pan out.

⚡ Pro tip: Aider is still on 0.x versioning, and CLI flags plus the

.aider.conf.yml

Closing the Loop: Let Aider Run Your Tests

The single feature that turns Aider from a code generator into something closer to a teammate is the test-and-fix loop, and almost no beginner guide switches it on. Aider can run your test command after every edit, read the failures, and take another swing — without you retyping the error into the chat.

aider --auto-test --test-cmd ,[object Object], src/payments/core.py
> add a per-account daily charge ,[object Object],; existing tests must still pass

What this does: After each edit, Aider runs the payments test suite. If a test fails, it feeds the failing output back to the model and asks it to fix the code, repeating until the suite passes or it gives up. You review a change that's already green instead of one you have to run yourself.

The same idea works for linters. Point

--lint-cmd

ruff

eslint

There's a real limit worth naming. The loop is only as good as your tests. If coverage is thin, a green run means little, and Aider will happily converge on code that passes weak tests while breaking behavior nobody checks. The auto-test loop rewards teams that already test well and quietly punishes teams that don't.

⚠️ Common mistake: Turning on

--auto-test

pytest tests/payments

⚡ Pro tip: Combine

/ask

--auto-test

Next Steps

The correction was small and it changed everything: narrow the context to the files you're editing, give a bounded goal with explicit constraints, and use architect/editor mode to put expensive reasoning only where it earns its cost. That's the Aider AI coding tutorial the quick-starts should have led with.

Save the config and the prompts that worked — the architect flags, the "keep the public API unchanged" constraints, the

AI?