Most AI refactoring advice starts in the wrong place.
It assumes the hard part is telling the model what to change.
So the prompt gets longer:
Act as a senior architect.
Review this codebase.
Find refactoring opportunities.
Improve maintainability.
Make it more testable.
That sounds reasonable.
But in a real repo, that prompt is too vague to be useful.
The hard part is not asking for better architecture.
The hard part is finding the parts of the codebase where architecture is actually hurting the work.
Not every ugly file needs a refactor.
Not every repeated function needs extraction.
Not every small module is a good module.
Not every "clean" interface hides useful complexity.
Sometimes the code that looks messy is doing the real work.
Sometimes the code that looks clean is only clean because the complexity was pushed into every caller.
That is the part an AI coding agent needs help with.
It needs an architecture workflow.
The problem with generic refactoring agents
When I let an agent inspect a codebase with only a broad refactor instruction, it tends to do one of three things.
First, it finds obvious style issues.
Naming.
Duplication.
Large files.
Missing comments.
Inconsistent patterns.
Those can matter, but they are rarely the architectural bottleneck.
Second, it proposes interface extraction too early.
The agent sees coupling, so it creates a service.
It sees repeated logic, so it creates a helper.
It sees conditionals, so it creates strategies.
The code looks more "designed" afterward, but the system may become harder to understand because the same concept is now split across more files.
Third, it treats testability as an extraction problem.
If something is hard to test, the agent may pull small pure functions out of the flow until the tests become easy.
That can make unit tests pleasant while hiding the real bugs in orchestration, boundaries, state, and integration behavior.
The result is a codebase with more files, more seams, more mock points, and not necessarily better architecture.
I do not want an agent to refactor like that.
I want the agent to slow down and ask a better question:
Where did understanding this system become expensive?
Architectural friction is a better signal than file size
A useful architecture pass should start by exploring the codebase the way a new senior engineer would.
Not by counting lines.
Not by ranking files by complexity score.
Not by searching for "TODO".
By following concepts.
For example:
- Where does one business concept require bouncing through five shallow modules?
- Where is the public interface almost as complicated as the implementation?
- Where do callers need to know too much about internal sequencing?
- Where are tests mostly checking implementation details?
- Where do changes require touching several files that should probably move together?
- Where does the agent keep losing the thread while trying to understand one behavior?
That last one is underrated.
If an agent gets lost while navigating the repo, that is not only a model limitation.
It may be an architecture signal.
Humans feel this too. We just describe it differently:
Every change here takes longer than it should.
or:
You have to know too much context before touching this module.
or:
The tests pass, but I do not trust this area.
That is the layer worth investigating.
The deep module idea maps surprisingly well to agents
John Ousterhout's deep module idea is still one of the best ways to think about this.
A deep module has a small interface that hides meaningful complexity.
That matters for humans because a good interface reduces the amount of system knowledge a developer needs to hold in their head.
It matters for AI agents for the same reason.
Agents are good at following local instructions.
They are worse when every small change requires reconstructing a hidden social map of the repo:
This helper is called here.
But only after this validation.
Unless this flag is set.
And this type is technically shared.
But this caller mutates it.
And the test mock does not match production behavior.
When the implementation is scattered but the concept is unified, the agent has to infer the module boundary every time.
That is waste.
Good architecture gives both humans and agents a smaller surface to reason about.
The goal is not fewer files.
The goal is better boundaries.
A better workflow for agent-assisted architecture review
The workflow I prefer has seven stages.
1. Explore before proposing
The agent should walk the codebase and record friction.
No refactor proposals yet.
No new interfaces yet.
No patches yet.
Just exploration.
The output should be a list of architectural friction points, not a list of code smells.
For each candidate, I want:
- the module or concept cluster involved
- why those files are coupled
- what state or behavior is spread across them
- what tests are hard to write or trust
- what kind of change becomes expensive there
This is the step most refactor prompts skip.
2. Present candidates, not solutions
The agent should show the candidates and ask which one to explore.
That sounds small, but it prevents a common failure mode:
The agent picks an area that looks bad but is not important.
Architecture work should follow business and maintenance pressure.
If an area is ugly but stable, it may not be the next refactor.
If an area changes every week and every change creates review anxiety, that is a better target.
3. Frame the problem space
Before designing anything, the agent should describe the constraints.
For example:
This cluster handles customer eligibility.
It currently depends on plan state, billing status, account flags, and region rules.
The callers mostly need one decision: can this customer use this feature?
The current implementation exposes too many intermediate checks.
This framing is useful because it separates the problem from the proposed interface.
The team can disagree with the framing before arguing about code.
4. Generate multiple interface designs
One proposal is not enough.
Architecture design benefits from contrast.
I like asking separate agents, or separate passes, to design different interfaces:
- one minimal interface
- one flexible interface
- one optimized for the most common caller
- one ports-and-adapters version if external dependencies are involved
The point is not to blindly choose the most elegant design.
The point is to expose trade-offs.
5. Compare the designs in prose
This is where the main agent should be opinionated.
Not:
Here are three options. Which do you prefer?
Better:
Option A is easiest to adopt but leaks dependency order.
Option B hides the right complexity but may be too abstract for current callers.
Option C is the strongest default because most callers only need one decision.
I would use C, with the error reporting shape from B.
That is the kind of help I actually want from an agent.
6. Turn the decision into an RFC
Once the direction is chosen, do not jump straight to a giant PR.
Create a refactor RFC issue.
It should include:
- the current friction
- the chosen boundary
- the interface sketch
- migration plan
- test strategy
- risks
- what not to change yet
This gives the team a reviewable architecture artifact before implementation begins.
7. Only then edit code
The implementation should be the last step, not the first.
If the agent starts by editing, it will often optimize the local patch instead of the architecture.
The workflow has to force the design conversation first.
Where Terminal Skills fits
This is the kind of workflow that belongs in a skill, not in a one-off prompt.
The Terminal Skills catalog has an improve-codebase-architecture skill that packages this exact style of process:
Improve Codebase Architecture on Terminal Skills
It is not a magic refactoring button.
That is the point.
It teaches the agent to:
- explore the codebase organically
- treat navigation friction as a signal
- identify shallow modules and coupling clusters
- present candidates before proposing interfaces
- design multiple alternative boundaries
- compare trade-offs
- create a GitHub issue RFC instead of silently rewriting the system
Install command for Codex:
npx terminal-skills install improve-codebase-architecture --agent codex
For Claude Code:
npx terminal-skills install improve-codebase-architecture
The native ad here is simple:
If your agent keeps making refactors that look clean but do not make the codebase easier to change, do not give it a bigger prompt.
Give it a repeatable architecture workflow.
Why this matters more now
Agent skills are becoming a serious part of terminal-agent work.
The ecosystem is moving in the same direction: reusable procedures are becoming a way to encode what to accomplish, when to apply it, and how to execute terminal tasks. The uncomfortable side is that skill retrieval, skill quality, and reusable automation can become fragile if the procedure is vague or unsafe.
That matches what I see in practice.
Skills are powerful when they are specific, procedural, and verifiable.
They are weak when they are just long advice files.
An architecture skill is a good test case because it cannot succeed by memorizing commands.
It has to guide judgment.
It has to slow the agent down.
It has to preserve human decision points.
It has to make the final artifact reviewable.
That is what separates an agent workflow from an agent vibe.
My practical checklist
If I were evaluating an architecture skill for a coding agent, I would ask:
- Does it force exploration before edits?
- Does it identify concept clusters, not just files?
- Does it distinguish coupling from duplication?
- Does it ask for human selection before deep design?
- Does it generate multiple interface options?
- Does it compare trade-offs in plain language?
- Does it produce an RFC before implementation?
- Does it define what should not be changed?
- Does it improve test boundaries instead of just adding mocks?
If the answer is no, it is probably not an architecture workflow.
It is just a refactor prompt wearing a better title.
The broader lesson
AI agents are getting better at writing code.
That makes architecture more important, not less.
When the agent can produce a thousand-line refactor in minutes, the bottleneck shifts from typing to judgment:
Was this the right boundary?
Did we hide the right complexity?
Did we make future changes easier?
Can the team review the decision?
Can the agent explain why it chose this shape?
Those questions do not belong at the end of the PR.
They belong in the workflow.
That is why I think the next useful layer for AI coding agents is not more autonomous editing.
It is better operating procedures.
Skills are one way to package those procedures.
And architecture review is one of the places where that packaging starts to matter.
Disclosure: AI assistance was used to draft and edit this article.
Top comments (0)