07. Working With Legacy Code (How to Guide AI Through Older Patterns)

How we help AI navigate older structures
without breaking what still works

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

'Legacy code' is part of every real system.
It carries history, constraints, tradeoffs,
it carries decisions made long before AI entered the workflow.

Some of it is stable.
Some,fragile.
And some of it is waiting to be replaced
— but not today.

AI does not know which is which.

To AI,
legacy code is simply text,
no different from modern patterns.
So when AI interacts with older code,
it may try to “modernize” it,
“improve” it, or “fix” it
in ways that break assumptions that
'the system still depends on'.

A simple mental model:

'Legacy code' is a living archive.
AI needs our guidance
to move through it
safely.

This page teaches us how to help AI understand older patterns,
how to protect fragile areas, and how to make safe,
incremental improvements without rewriting history.

AI does not know:

• which parts of the system are stable
• which parts are fragile
• which parts are temporary
• which parts are intentionally outdated
• which parts are tied to older browsers
• which parts depend on legacy frameworks
• which parts must not be touched

To AI, everything looks equally editable.

A simple truth:

We must name the age,
purpose, and fragility of legacy code.
AI cannot infer it.

We help AI by declaring the context:

“This is legacy code.
It works, but it is fragile.
Please avoid structural changes.”

Or:

“This pattern is outdated, 
but still required for compatibility.
Do not modernize it.”

Or:

“This component uses older conventions.
Please keep the naming and structure 
exactly as they are.”

This prevents AI from “helpfully” rewriting history.

A simple reminder:

AI respects the constraints we declare.
It cannot see the constraints we do not.

Legacy code comes in different forms:

• Legacy naming (e.g., content-wrapper, main, box)
• Legacy structure (deep nesting, wrapper-heavy layouts)
• Legacy CSS (floats, clearfix, global resets, IDs for styling)
• Legacy frameworks (Bootstrap-era patterns, jQuery-era markup)
• Legacy browser support (IE fallbacks, vendor prefixes)
• Legacy hacks (negative margins, clearfix, magic numbers)

Each type requires a different approach.

A simple principle:

We do not modernize blindly.
We modernize with awareness.

Some legacy code should not be touched:

• it is stable
• it is widely depended on
• it is fragile
• it is tied to older systems
• it is part of a long migration plan
• it is not worth the risk

We tell AI:

“Do not refactor this.
Only help us understand it.”

Or:

“This code must remain unchanged.
Please explain what it does.”

A simple truth:

Preservation is sometimes
the safest form of refactoring.

We can safely improve legacy code when:

• the change is small
• the behavior remains identical
• the structure remains intact
• the naming stays consistent
• the component is isolated
• the risk is low
• the improvement is meaningful

Examples of safe improvements:

• removing unused CSS
• simplifying overly specific selectors
• replacing magic numbers with variables
• reducing unnecessary wrappers
• clarifying naming without breaking dependencies
• removing duplicated rules

A simple reminder:

Small improvements accumulate.
Large rewrites destabilize.

Legacy naming often
predates modern conventions.

AI may try to “fix” it.

We prevent this attempt by saying:

“Keep all existing names.
They are part of the legacy system.”

Or:

“Do not rename classes.
Other components depend on them.”

Or:

“Use the legacy naming style 
when adding anything new.”

A simple truth:

Naming is historical.
AI must follow the history we describe.

Legacy structure may include:

• nested wrappers
• layout tables
• float-based grids
• clearfix hacks
• global selectors
• ID-based styling

AI may try to flatten, modernize,
or reorganize these patterns.

We guide it by saying:

“Keep the structure exactly as it is.
Only adjust the part we highlight.”

Or:

“This layout uses floats.
Do not convert it to flex or grid.”

Or:

“This wrapper is required for compatibility.
Do not remove it.”

A simple principle:

Legacy structure is often fragile.
AI must move gently.

When modernization is allowed,
we proceed in 'small steps':

1. We identify the legacy pattern.
2. Explain the goal to AI.
3. Show the current snippet.
4. Describe the desired modern equivalent.
5. Ask for the minimal change.
6. Review the output carefully.
7. Test in context.
8. Remove temporary hacks.

For example:

“We want to replace this float-based layout with flex.
Keep the markup the same.
Only update the CSS.
Make the smallest possible change.”

A quiet truth:

Modernization is a migration,
not a leap.

AI may propose:

• renaming everything
• rewriting the structure
• replacing floats with flex
• replacing flex with grid
• removing wrappers
• reorganizing markup
• introducing new patterns

We evaluate these suggestions
using the same criteria
from the refactoring chapter by asking:

• Does it strengthen the structure?
• Does it preserve behavior?
• Does it respect naming?
• Does it introduce risk?
• Does it solve a real problem?

If the answer is 'not',
we decline the proposal.

A simple reminder:

AI proposes.
We protect the architecture.

Legacy code is not a burden.
It is a record of how
the system grew, adapted, and survived.

A closing thought:

AI sees legacy code as text.
We see it as history.
Collaboration begins
when we share that history.

• Suggested Next Reading: → Working With Themes and Plugins (How to Keep AI Inside the Boundaries)

_{Tony de Araujo —New York | Lisbon}

• Top↑
• Back to Topic ↔
• Home←