05. When AI Suggests a Refactor (How to Decide What to Accept)

How we evaluate AI’s ideas with clarity, structure,
and architectural intent

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

AI is generous with refactoring suggestions.
Sometimes it offers small improvements.
Sometimes it proposes sweeping changes.
Sometimes it invents patterns that look modern
but do not belong in our system.

A simple mental model:

AI proposes.
We decide.
Architecture is the space between the two.

This page teaches us how to evaluate AI’s refactoring suggestions with calm judgment and structural awareness.

AI does not know:

• our naming conventions
• our design system
• our architectural boundaries
• our legacy constraints
• our portability requirements
• our long‑term goals

A quiet truth:

AI optimizes locally.
We must think globally.

A 'refactor' is worth considering when it:

• clarifies the component’s shape
• reduces nesting
• improves naming
• removes duplication
• simplifies selectors
• strengthens boundaries
• improves portability
• aligns with our existing patterns

A simple principle:

Clarity is the measure.
Not novelty.
We choose what strengthens the system.

AI often invents names:

• card_section
• header_title-text
• content-wrapper
• main-container

These names may be reasonable,
but they may not match our vocabulary.

We accept a 'refactor' only if:

• the names align with our system
• the names reinforce meaning
• the names are consistent with existing components

If not, we adjust the names or decline the refactor.

A simple reminder:

Naming is architecture.
AI does not know our language
unless we teach it.

AI sometimes proposes structural changes that alter:

• spacing
• layout
• responsiveness
• interaction
• semantics

So, we check whether the refactor:

• changes the visual outcome
• changes the DOM structure
• changes accessibility
• changes how CSS applies
• changes how the component behaves in context

If the behavior changes unintentionally,
we decline.

A simple truth:

A refactor that changes behavior
is not a refactor —
it is a redesign.

We look for signs of risk:

• new wrappers
• deeper nesting
• more specific selectors
• global overrides
• unnecessary modifiers
• new dependencies
• changes that affect unrelated components

If a refactor increases fragility,
we decline.

A simple rule:

If the risk is unclear,
the answer is no.

AI sometimes refactors
simply because it can.

So, we ask:

• What problem does this solve?
• Does the component become easier to maintain?
• Does the structure become clearer?
• Does the CSS become simpler?
• Does the naming become more consistent?
• Does the system become more predictable?

If the answer is “no,”
we decline.

A quiet reminder:

Refactoring is not decoration.
It is purpose.

When we accept a refactor, we:

1. review the entire change
2. ensure naming matches our vocabulary
3. ensure structure matches our patterns
4. ensure behavior remains unchanged
5. ensure no unrelated components are affected
6. remove any temporary hacks AI introduced
7. narrate the intent back to AI

For example:

“We accepted the structural simplification.
We kept the original naming.
Please continue using this pattern.”

A simple principle:

Every accepted refactor
becomes part of the system’s future.

When we decline a refactor, we explain why:

“This changes the component’s behavior.”

“This naming does not match our vocabulary.”

“This adds unnecessary nesting.”

“This introduces risk without solving a problem.”

“This pattern does not exist in our system.”

This prevents AI from repeating the same suggestion later.

A simple truth:

Declining a refactor
is part of teaching the system.

AI can propose endlessly.
We choose intentionally.

A quiet closing thought:

AI offers possibilities.
We shape them into architecture.
That is the heart of collaboration.

• Suggested Next Reading: → Safe Refactoring: How to Guide AI Toward Minimal, Predictable Changes

_{Tony de Araujo —New York | Lisbon}

• Top↑
• Back to Topic ↔
• Home←