Revisión y limpieza de código con Claude Code
Sin romper nada

01. El contexto

El archivo: fabrica-agentes-WIZARD.html

Un prototipo funcional completo de la Fábrica de Agentes IA. Una SPA (Single Page Application) con todo inline: HTML, CSS y JavaScript en un solo archivo.

Incluye:

• Dashboard principal con métricas y gráficos
• Panel de agentes IA (crear, editar, probar, eliminar)
• Wizard de 6 pasos para crear agentes
• Gestión de números de teléfono con SIP
• Centro de ayuda con búsqueda y chatbot
• Panel de administración
• Sistema de alertas y notificaciones

Todo funcionaba. El diseño estaba cerrado. La funcionalidad validada.

Pero antes de entregarlo necesitaba una revisión limpia: estilos duplicados, código muerto, accesibilidad básica, errores de consola.

02. El prompt maestro

Esto es lo más importante del artículo. El prompt que le pasé a Claude Code antes de empezar. Sin este prompt, la revisión habría sido un desastre.

Las reglas son lo que separan una revisión controlada de un "refactor" que rompe todo.

Necesito una revisión general y limpieza de código del archivo
fabrica-agentes-WIZARD.html

Es un prototipo funcional (~3039 líneas, HTML + CSS + JS inline,
single-page app). El objetivo es dejarlo limpio y profesional
para entrega sin alterar nada visual ni funcional.

REGLAS CRÍTICAS:
- NO cambios visuales ni funcionales; el diseño actual es correcto
- NO eliminar ni modificar textos, labels, descripciones o contenido
- NO reorganizar secciones ni mover bloques de HTML
- Antes de cada cambio: mostrar qué se va a hacer y esperar aprobación
- Después de cada grupo de cambios: verificar en preview que nada se rompió
- Cero errores: esto es entrega final

QUÉ REVISAR:
1. CSS duplicado / inline styles que ya existen como clase
2. Variables CSS (:root) no usadas
3. JS muerto (funciones nunca llamadas)
4. Naming inconsistente (clases, ids, funciones)
5. Comentarios obsoletos o engañosos
6. Atributos HTML redundantes
7. Errores de consola (verificar con preview)
8. Accesibilidad básica (alt en imágenes, label en inputs)

MÉTODO DE TRABAJO:
1. Leer el archivo entero y diagnosticar SIN tocar nada
2. Presentar lista organizada de cambios propuestos
3. Aplicar cambios uno a uno o en grupos pequeños con verificación

Por qué funciona este prompt

Hay 3 cosas que lo hacen funcionar:

1. Reglas negativas primero. Le digo lo que NO debe hacer antes de lo que sí. Esto acota el espacio de acción. Claude no va a "mejorar" cosas que no le he pedido.
2. Método explícito. Diagnosticar primero, tocar después. Cada cambio con aprobación previa. Esto evita que aplique 20 cambios de golpe y luego no sepas cuál rompió algo.
3. Contexto del archivo. Le digo que son 3.039 líneas, que es un prototipo funcional, que es entrega final. Esto calibra el nivel de cuidado.

03. El método

Le pedí que leyera las 3.039 líneas completas antes de proponer ningún cambio.

Leyó el archivo en bloques (por límites de contexto) y construyó un diagnóstico completo organizado en 3 prioridades:

Grupo C: Riesgo mínimo

Inline styles redundantes (ya existen como clase CSS). Impacto cero si se eliminan.

Grupo B: Riesgo bajo

Accesibilidad (aria-labels, id/for en formularios). Añaden atributos sin modificar nada visual.

Grupo A: Riesgo medio

Eliminar CSS no usado y funciones JS muertas. Requiere confirmar que realmente no se usan.

04. Los 8 cambios

Cada uno aplicado individualmente o en grupos pequeños. Cada uno verificado en preview.

Cambio 1: Inline styles redundantes en sliders

Los .slider-track tenían style="flex:1;position:relative;" en el HTML, pero esas propiedades ya estaban definidas en la clase CSS.

<!-- Antes -->
<div class="slider-track" style="flex:1;position:relative;">

<!-- Después -->
<div class="slider-track">

Impacto visual: Ninguno. Las propiedades ya existían en el CSS.

Cambio 2: <hr> inline reemplazados por clase .divider

Había 6 separadores <hr> con estilos inline idénticos: border:none;border-top:1px solid var(--gris-borde). La clase .divider ya existía con exactamente esas propiedades.

<!-- Antes -->
<hr style="border:none;border-top:1px solid var(--gris-borde);margin:0;">

<!-- Después -->
<hr class="divider" style="margin:0;">

3 con margin:0 y 3 con margin:20px 0. Se mantuvo el margin inline porque varía entre instancias. Solo se eliminó el border duplicado.

Cambio 3: aria-label en botones de eliminar

4 botones de papelera en las tarjetas de agentes no tenían texto accesible. Solo contenían un icono <i class="bi bi-trash">.

<!-- Antes -->
<button class="btn-s" style="color:var(--rojo);border-color:#fecaca;">
  <i class="bi bi-trash"></i>
</button>

<!-- Después -->
<button class="btn-s" style="color:var(--rojo);border-color:#fecaca;"
  aria-label="Eliminar agente">
  <i class="bi bi-trash"></i>
</button>

Cambio 4: id/for en 13 pares label + input

13 campos de formulario en los pasos del wizard tenían <label> sin for y <input> sin id. Al hacer clic en la etiqueta, no se activaba el campo.

Campos actualizados en:

• Paso 1: nombre del agente, nombre de empresa, descripción
• Paso 2: mensaje de inicio
• Paso 4: tipo de ambiente
• Paso 5 (Transferencia): cuándo transferir, nombre contacto, instrucción, tipo destino, teléfono
• Paso 5 (Cal.com): API key, event type, zona horaria, link

Cambio 5: 6 clases CSS no utilizadas eliminadas

Claude leyó cada clase CSS y buscó su uso en todo el archivo. Encontró 6 clases huérfanas que ya no se referenciaban en ningún lugar del HTML ni del JS:

/* Eliminadas: */
.rcards-3   /* Grid de 3 columnas - no usado */
.vcard      /* Tarjeta de voz - reemplazada */
.vcard:hover
.vcard.on
.vcard .vav
.vcard-v .vav2
.vav        /* Avatar de voz - reemplazado */
.vmeta      /* Meta de voz - no usado */

Todas verificadas individualmente: ninguna aparecía en el HTML ni en el JS.

Cambio 6: 2 funciones JavaScript muertas

Dos funciones que existían en el código pero nunca se llamaban desde ningún lugar:

/* Eliminadas: */
function toggleCalcom() { ... }
function toggleGuiaCalcom() { ... }

Verificado con búsqueda en todo el archivo: ni en onclick, ni en event listeners, ni llamadas desde otras funciones. Código muerto de una iteración anterior.

Cambio 7: 3 <hr> más en sección Cal.com y números

Mismo patrón que el cambio 2, pero con margin:20px 0. Tres separadores más en la sección Cal.com y la guía de números SIP.

<!-- Antes -->
<hr style="border:none;border-top:1px solid var(--gris-borde);margin:20px 0;">

<!-- Después -->
<hr class="divider" style="margin:20px 0;">

Cambio 8: Verificación de consola

No es un cambio de código, pero era parte del checklist. Se lanzó el preview y se navegó por todas las vistas verificando la consola del navegador:

Resumen de todos los cambios

05. Verificación final

Después de los 8 cambios, el resultado:

El artefacto quedó exactamente igual por fuera. Por dentro, más limpio, más accesible y sin código muerto.

06. Lo que aprendí

1. Las reglas negativas son más importantes que las positivas

Decirle a Claude lo que NO debe hacer es más valioso que decirle lo que sí. "NO cambios visuales" es más poderoso que "haz cambios solo de limpieza". La restricción acota mejor que la instrucción.

2. El método de aprobación previa es no negociable

Cada cambio se describe antes de aplicarse. Se aprueba. Se aplica. Se verifica. Sin excepciones. Si haces 20 cambios de golpe y algo se rompe, no sabes cuál fue.

3. Diagnosticar primero, tocar después

Claude leyó las 3.039 líneas completas antes de proponer un solo cambio. Construyó un mapa del archivo: dónde está el CSS, dónde el HTML, dónde el JS, qué clases se usan, cuáles no. Solo después propuso cambios.

4. Priorizar por riesgo, ejecutar de menor a mayor

Empezar por lo que tiene riesgo cero (eliminar un inline que ya existe como clase) te da confianza para subir a lo que tiene algo más de riesgo (eliminar funciones muertas).

5. La verificación de consola cierra el ciclo

No es suficiente con que "se vea bien". La consola tiene que estar limpia. Sin errores. Sin warnings. Eso es lo que diferencia un prototipo de una entrega profesional.