How to Use Aider’s Architect Mode on Refactors That Touch Many Files
Architect mode runs Aider twice: one model plans the change in prose, a second model writes the actual edits. You enable it with /architect or --architect, then pick a reasoner for planning and a cheaper coder for the diff.
The split exists because the two jobs want different models. Refactor planning rewards long-chain reasoning. Emitting a correct patch rewards instruction-following and precise file context.
How does architect mode differ from normal Aider chat?
In normal mode the same model reads the files, reasons, and writes the diff in one pass. On small edits that is faster and fine.
On a rename spanning 12 files, one-pass models get sloppy around file 7. They lose the naming convention, or they edit a call site and forget the import. A planner that writes down the rule first fixes most of that.
Concretely: the architect model produces a plan, then hands it plus the file context to the editor model. The editor applies it literally.
How do you configure architect mode for a refactor?
- Start Aider with
/architector runaider --architect. - Set the planner:
aider --architect --model o3 --editor-model sonnet. /addevery file the refactor touches, plus one test file.- Ask for a plan, not code: “Describe the steps to move user auth into src/auth/. Do not edit yet.”
- Read the plan. Fix it in chat — one or two rounds max.
- Say “implement the plan”. Review each commit.
Step 5 is where the value is. Correcting a paragraph of prose costs one message. Correcting a 12-file diff costs ten.
Which models work best as planner vs editor?
Planner: a reasoning model. Thinking-model outputs on refactor plans are noticeably better at spotting ordering problems, like renaming a symbol before its imports.
Editor: a fast, strong instruction-follower. It does not need to reason deeply because the plan already did. Mid-tier models work here for a fraction of the cost.
Cost shape: the planner runs once or twice, the editor runs per response. A 3-round refactor with a reasoning planner and mid-tier editor lands around 20-40 cents. All-top-tier is 3-4x that for similar output.
Where does architect mode still break?
Type-level changes. If a function signature changes and callers use keyword arguments, the editor will miss some callers even with the plan in hand. Run your type checker after every round.
Cross-language changes. Adding a new API endpoint in Python that a TypeScript client calls — the editor only edits what is in context. It cannot see your frontend unless you /add it.
Anything with a migration step. The planner will describe the schema change; the editor will not run it. That is your job, and the plan will not remind you.
People also over-trust the plan. If the plan is wrong at step 2, every later edit inherits the error. Read it.
How does this compare with handing the task to a full agent?
Tools like Devin AI take a ticket and work unattended. Aider’s architect mode keeps you in the loop at every commit. The trade-off is time versus control.
For a codebase you own and understand, architect mode usually wins. You already know what the plan should look like, so you catch bad plans in one message.
For a large legacy repo you have never read, a fuller agent with its own browser and shell gets further before you need to intervene.
Quick Summary
- Architect mode splits planning and editing across two models; enable with
/architect. - Use a reasoning model as planner and a mid-tier model as editor to keep cost near 20-40 cents per refactor.
- Ask for a plan first, fix it in chat, then say “implement the plan”.
- It still misses call sites on signature changes — run the type checker after every round.
- Best for repos you own. For unfamiliar legacy code, an unattended agent may get further first.
