/ BLOG

How I Built a Claude Code Sub Agent to Fix CSS Architecture Nightmares

Turning a weekend debugging session into an automated solution

2025 · 07Claude Code · CSS architectureOriginally published on Peerlist

A terminal listing four /css-architecture-fixer commands — analyze, fix, migrate-to-modules and namespace — each under a comment describing what it does.

The Problem: CSS That Works... Until It Doesn't

Last week, I was stressed out over a bug that made no sense. My Next.js app's styling worked perfectly on first load. But navigate to another page and come back? Total chaos.

Table widths would break unexpectedly
Modal headers and content styling disappeared
Button colors changed between page visits
Everything magically fixed itself on refresh

If you've worked with large codebases, you know this feeling. The CSS works, then it doesn't, then it does again. It's like playing whack-a-mole with stylesheets.

Discovering the Root Cause

After hours of debugging, I finally found the culprit: global CSS conflicts. Even with Claude Code and Cursor, I was going around in circles until i had to manually look for files where these conflicts were occurring and then pointing it out.

The numbers were staggering:

.modal-content appeared in 8+ different component files
.btn was defined in 12+ places
Same story for dozens of other common class names

In a global CSS world, the last imported file wins. So depending on your navigation path and Next.js's code splitting, you'd get different styles. No wonder it felt random.

Building the Solution

Instead of manually refactoring thousands of lines of CSS over several days, I decided to spend my weekend building a Claude Code subagent to automate the entire process.

The agent's markdown definition, listing its purpose against global class name collisions and Bootstrap overrides, then four numbered capabilities: CSS conflict audit, namespace generation, CSS Modules migration, and validation and reporting. — The agent definition — purpose, then one section per phase of the job.

The file .claude/agents/css-architecture-fixer.js open in an editor, showing a CSSArchitectureFixer class with auditCSSConflicts, generateNamespaces, migrateToModules and validateMigration methods, each commented with its phase number. — The implementation behind it: one method per phase, collapsed to their signatures.

The CSS Architecture Fixer Agent works in four phases:

Phase 1: Audit & Detection

Scans the entire codebase for duplicate class names
Identifies Bootstrap class overrides
Maps component-to-CSS relationships
Generates a conflict severity report

Phase 2: Smart Namespacing

Creates unique namespaces using three strategies:
Feature-based: .auth-login-button
Component-based: .login-form-button
BEM-like: .login__form--button
Preserves Bootstrap utility classes (this was tricky!)
Updates both CSS and JSX files automatically

Phase 3: CSS Modules Migration

Converts traditional CSS imports to CSS Modules
Transforms .btn → styles.btn in components
Handles SCSS features like variables, mixins, and nesting
Updates all import statements

Phase 4: Validation

Verifies all classes are properly scoped
Ensures no visual regressions
Checks that Bootstrap utilities still work
Generates a migration report

Using the Agent

The best part? It's incredibly simple to use:

# Find all CSS conflicts in your codebase

/css-architecture-fixer analyze

# Fix conflicts for a specific component

/css-architecture-fixer fix --component components/auth/Login.jsx

# Migrate an entire feature to CSS Modules

/css-architecture-fixer migrate-to-modules --feature auth

# Apply smart namespacing across all CSS files

/css-architecture-fixer namespace --pattern feature-component

I'm still improving the agent. Some ideas I'm exploring:

Visual regression testing with screenshots
Integration with design systems

If you're interested in the implementation details or want to build something similar, feel free to reach out. Always happy to share learnings with fellow developers.