Prompting Aider is less about writing clever instructions and more about choosing the right scope for a single change. Aider is a terminal-based AI pair-programmer that edits files in your working directory and commits each change to git automatically. That commit-per-change loop is the defining constraint: small, atomic prompts work with it, big sweeping ones fight it. This guide covers what Aider is, how the commit model shapes the prompting style, how /add and /drop control scope, why atomic prompts beat ambitious ones, and a set of anti-patterns worth avoiding.
What Aider Is
Aider is an open-source CLI pair-programmer. You launch it inside a git repository, add the files you want it to work on, describe a change in plain English, and Aider applies the edit directly to your working tree. Two traits define its character:
- It lives in the terminal. The interface is a REPL-style prompt in the same shell where you run tests, git, and your editor.
- It commits to git after every change. Each successful edit becomes a commit with a generated message on whatever branch you are on.
The second trait is the one that shapes prompting. For broader context, see The Complete Guide to Prompting AI Coding Agents. For the category definition, see the tool use glossary entry.
The Git-Commit-Per-Change Model
Most AI coding tools present a diff and let you decide what to do with it. Aider takes the next step automatically — it applies the edit, then creates a git commit with an auto-generated message. If the result is wrong, you undo with a git operation (git reset, git revert, or Aider's own undo) rather than by declining the change.
Three implications for prompting:
First, each prompt is a unit of history. A prompt that mixes "rename this variable and also refactor the error handler and also add a test" produces a commit that is hard to review, revert, or bisect through. A prompt that does one thing produces a commit that reads cleanly six months later.
Second, mistakes are cheap only if you notice them. Rolling back a bad edit is one git command, but the cost of letting a bad edit stack under five more changes is high — untangling requires interactive rebase or manual reverts. Review each commit soon after it lands.
Third, the commit log becomes an audit trail. git log after a session tells you what Aider did step-by-step — useful for debugging regressions, reviewing AI changes, and accountability on shared branches. The log only reads well when each commit is a coherent single idea, which is a prompting discipline, not a tool feature.
/add and /drop — Explicit File Scoping
Aider only edits files you have explicitly added to the session. Two commands manage the active set:
/add <path>puts a file (or glob) into Aider's edit scope./drop <path>removes it.
Everything else in the repo is invisible for edit purposes — the single most important thing to internalize about prompting Aider. The agent will not wander into a file you did not add, nor "helpfully" refactor an adjacent module while you were asking about one function. The scope of a session is exactly the set of files you /add-ed.
Aider can also read reference files without making them editable — useful when you want it to understand an interface or test without risking edits there. Check /help in your version for the exact command, since flag names evolve.
The practical consequence: add the minimum set of files the change needs, no more. A wide /add widens the blast radius of every prompt. A narrow one makes scope errors nearly impossible — the worst case is Aider asks for another file.
| Session habit | What it does to prompting |
|---|---|
/add only the files the current change touches | Keeps each commit scoped to one concern |
/add a wide set "just in case" | Invites cross-file edits you did not ask for |
/drop files when done with them | Keeps the context window lean for later prompts |
Forget to /add a file before describing a change | Aider asks for it, slowing the loop |
| Rely on Aider to infer what files matter | Unreliable — be explicit |
Small Atomic Prompts — The Sweet Spot
Because every prompt becomes a commit, the right unit of prompting is the right unit of commit. That is: one concern, one testable change, one thing you would review on its own.
Good atomic prompts read like this:
- "Rename the
userIdparameter toaccountIdinlib/auth/session.tsand update the call sites in the same file." - "Add a null check before the array access on line 42 of
utils/parse.ts. Leave everything else alone." - "Extract the cache key construction on lines 80-95 of
api/fetch.tsinto a helper function namedbuildCacheKey. Do not change behavior."
Bad prompts are the ambitious ones. "Refactor the auth module" is not an atomic change — it is a week of work pretending to be a sentence. Aider will take a swing at it, but the resulting commit will be large, mixed, and hard to review. If part of it is wrong, you untangle the good from the bad by hand.
The reframing: before sending a prompt, ask "what is the smallest change that moves the code closer to where I want it?" That is the prompt to send. Five atomic prompts usually beat one ambitious one, because each step is reviewable and revertible on its own.
Same discipline as spec-driven AI coding — decompose before you describe. Aider pushes it further because the commit model makes the cost of not decomposing immediately visible.
Model Selection
Aider supports multiple model providers — Claude, GPT, Gemini, local models via ollama or a custom endpoint, and others. The specific list changes as vendors ship new models, so check the Aider docs for the current one.
Two things matter more than which model you pick:
- The prompt is usually the bottleneck. A clear atomic prompt with the right files added produces a good edit on most capable models. A vague prompt produces a bad edit on all of them. Invest in the prompt before agonizing over the model.
- Cost trades off against quality. Bigger models do better on hard edits but cost more. For a codebase where most edits are small and well-scoped, a cheaper model is often enough. Escalate to a stronger one for the gnarly edits — Aider lets you switch mid-session.
Same trade-off as in the Claude Code prompting guide and the Continue.dev prompting guide: model choice is a tuning knob, not the main lever.
Browser Mode and the Web UI
Aider offers a browser-based interface alongside the CLI. It presents the same functionality — adding files, describing changes, seeing diffs — in a graphical form, which some users prefer for longer sessions or screen-sharing. The underlying model of atomic changes and git commits is identical; you are just interacting with it through a different surface. Check the current Aider docs for setup specifics, since they evolve.
An Atomic Edit Prompt Example
This is hypothetical — not a real Aider session — and illustrates the rhythm of /add followed by a focused description.
$ aider
> /add lib/api/client.ts lib/api/client.test.ts
Added lib/api/client.ts to the chat.
Added lib/api/client.test.ts to the chat.
> In lib/api/client.ts, the `request()` function currently
> throws immediately on network errors. Change it so that
> network errors and 5xx responses are retried up to 3 times
> with exponential backoff: 100ms, 200ms, 400ms. 4xx responses
> should still throw immediately. Do not change the function's
> exported signature. Also add one test in client.test.ts
> that proves a 500 triggers exactly one retry.
[Aider proposes and applies a diff to client.ts and
client.test.ts, then creates a commit.]
> /run pnpm test lib/api/client.test.ts
[Test output shown.]
> /drop lib/api/client.test.ts
Removed lib/api/client.test.ts from the chat.
> In lib/api/client.ts, the retry delays are currently hardcoded.
> Extract them to a constant named RETRY_DELAYS_MS at the top of
> the file. Do not change behavior.
[Aider proposes and applies a smaller diff, then creates a
second commit.]Two prompts, two commits, each a reviewable unit. The first added behavior with a test; the second is a pure refactor. If the refactor turned out to be wrong, reverting it would not undo the retry logic. That separability is the payoff.
When Aider Shines
Aider is strongest in a specific slice of coding work:
- Small-to-medium codebases where you can hold the architecture in your head and know which files a change should touch.
- Known-scope changes — bug fixes, targeted refactors, adding a test, renaming an identifier. Anything where "done" is a concrete diff.
- Git-hygiene-minded teams where a clean commit history is a feature. Auto-commits read like a careful developer wrote them, provided the prompts were atomic.
- Solo or small-team development without a need for shared workspaces or team-level policies.
Aider is less well-suited to greenfield architecture work, cross-repo changes, or sprawling investigations where "I don't know yet — let's explore" is the honest answer. Those benefit from richer context management or IDE integration.
Common Anti-Patterns
- Big refactor in one prompt. Aider will try, and the commit will be large, mixed, and hard to review. Fix: decompose into three or five atomic prompts and send them one at a time.
- Not
/add-ing a file the change needs. Aider either asks mid-flow, slowing you down, or misses the relevant file. Fix: decide which files the change touches,/addthem all, then describe the change. - Ignoring the commit trail. A bad edit can be buried under three later changes. Fix: after every commit or two, run
git log --onelineandgit show HEAD. - Widening the active set "just in case." If you
/addtoo many, scope drift follows. Fix: keep the set small./dropfiles when done. - Chained vague prompts. "Now make it better" has no target. Fix: name the file, the symbol, and the before/after state concretely.
- Skipping tests because the commit looked right. Aider is fluent, which makes bad edits look confident. Fix: run your tests after every change.
FAQ
How is prompting Aider different from prompting Claude Code or Cursor?
The commit-per-change model is the biggest difference. In Cursor, changes are diffs you accept in the editor; in Claude Code, a run can stack many edits before you review. In Aider, each successful prompt becomes a git commit immediately. That rewards smaller, atomic prompts and makes sprawling ones visibly painful to review or revert.
What if I want Aider to edit a file I haven't added?
It will ask. Aider won't silently touch files outside its scope; if a change needs a file you haven't added, it prompts you to add it. That is usually a sign to pause and think about scope, not to add the file reflexively.
Can I turn off auto-commit?
There are modes that change when or whether commits happen — check the current Aider docs for the exact flags. The auto-commit model is the workflow Aider is designed around. Teams that want a review step often let Aider commit to a feature branch and use standard git tooling (rebase, squash, PR review) before merging.
How do I handle a big refactor if Aider wants small prompts?
Decompose it. Write a short plan — a list of bullet points works — then send one prompt per bullet. Each prompt produces a commit; the sequence of commits is your refactor. If a later step reveals an earlier one was wrong, revert just that commit.
Does Aider work with local models?
Yes — via endpoints like ollama or a custom OpenAI-compatible server. Quality depends on the local model and how it handles the edit format Aider expects; hosted frontier models are generally more reliable for tricky edits. Start hosted to learn the workflow, then try local if privacy or cost pushes you that way.