How to shape 'AI’s refactoring'
so it strengthens the system
without drifting beyond the task

_{—Part of CSS Primer for the AI Era — Working with Existing Code}

AI is capable of 'sweeping refactors'.
It can rename everything,
restructure components,
rewrite CSS,
and reorganize markup in a single pass.

But most of the time, that is not what we want —
and not what the system needs.

A quiet mental model:

Minimal changes are predictable.
Predictable changes are safe.
Safe changes strengthen the system.

This page teaches us how to guide AI toward refactors
that are intentional, minimal, and aligned with our architecture.

Minimal refactoring matters because:

• small changes are easier to review
• small changes are less risky
• small changes preserve structure
• small changes avoid unintended side effects
• small changes keep components predictable
• small changes help AI stay within boundaries

A simple truth:

The smaller the change,
the clearer the intent.

AI needs explicit boundaries.
If we do not define them,
it will happily rewrite the entire component.

We tell AI what must remain unchanged:

• naming
• structure
• semantics
• behavior
• accessibility
• component boundaries
• portability
• existing patterns

For example:

“Please refactor this, but keep the structure, 
naming, and behavior exactly the same.”

Or:

“We want minimal changes.
No new wrappers, no renaming, 
no new patterns.”

Reminder:

AI respects
the limits we declare.

Safe refactoring requires clarity
about what is allowed.

We can say:

“You may simplify selectors, 
but do not change the markup.”

Or:

“You may reduce nesting, 
but do not rename classes.”

Or:

“You may remove duplication, 
but do not introduce new patterns.”

Or:

“You may adjust spacing, 
but do not change layout or behavior.”

A principle:

We define the scope.
AI works within it.

We can say:

“Please propose the smallest change that 
solves this problem.”

Or:

“We want a minimal refactor — 
one that changes as little as possible.”

Or:

“Please keep the diff small and predictable.”

This keeps the refactor focused.

A simple truth:

Minimalism is a constraint
AI understands
when we name it.

Before accepting a refactor,
we ask AI to explain:

• what it changed
• why it changed it
• what stayed the same
• what risks it avoided
• how the change aligns with our patterns

For example:

“Explain the changes you propose 
and why they are safe.”

This forces AI to think structurally,
not just syntactically.

A simple principle:

Explanation reveals intention.
Intention reveals safety.

We evaluate the 'refactor' by asking:

• Did the structure stay the same?
• Did the naming stay consistent?
• Did the behavior remain unchanged?
• Did the component stay portable?
• Did the CSS become simpler?
• Did the boundaries remain intact?

If the answer to any of these is “no,”
we refine or decline.

Reminder:

Structure is the anchor.
Safe refactoring never drifts from it.

AI loves inventing patterns:

• new modifiers
• new wrappers
• new naming conventions
• new abstractions
• new utilities

We prevent this by saying:

“Do not introduce new patterns.
Use only what already exists in the system.”

Or:

“Stay within the existing vocabulary.”

A simple truth:

New patterns are architectural decisions.
AI does not make architectural decisions.

When we want a specific outcome, we show:

• the current version
• the desired version
• the constraints

For example:

“Here is the current markup.
Here is the desired structure.
Please generate the minimal CSS needed 
to achieve this.”

This prevents AI from improvising.

Principle:

We show the destination.
AI finds the safest path.

If AI proposes too much change, we say:

“This is too large.
Please reduce the refactor to the 
smallest possible change.”

Or:

“This introduces unnecessary modifications.
Please keep the original structure and naming.”

Or:

“This is drifting.
Please stay within the existing pattern.”

Principle:

We correct the drift,
not the direction.

AI brings speed.
→ We bring judgment.

We define the boundaries.
→ AI works within them.

We review the changes.
→ AI refines them.

A closing thought:

AI can change anything.
We choose what should change.
That is how refactoring becomes safe.

• Suggested Next Reading: → Working With Legacy Code (How to Guide AI Through Older Patterns)

_{Tony de Araujo —New York | Lisbon}

• Top↑
• Back to Topic ↔
• Home←