Cómo los errores están guiando el Harness Design System

Una conversación hoy con Gustavo Navarro, nuestro Engineering Manager, y Diogenes Vanzela, nuestro Group Product Manager, me hizo ver algo que estaba delante de nosotros desde el principio. El mapa de lo que necesitamos documentar en el Proyecto Harness Design System ya existía. Estaba en los errores que Claude Code había cometido en los meses anteriores.

Lo que las pruebas ya habían mostrado

Antes de formalizar este proyecto, ya habíamos hecho experimentos usando Claude Code para construir interfaces directamente en código. Algunos resultados fueron sorprendentemente buenos. Otros revelaron problemas que yo no esperaba.

Lo que funcionó fue el tipo de componente con patrón global: tablas, headers, menús. Claude Code ya vio estos elementos en miles de codebases distintas. Puede inferir qué es una tabla, cómo se comporta un menú. No necesita mucha instrucción porque el patrón existe fuera de nuestro sistema.

Lo que falló fue otro tipo de componente.

En un proyecto que probamos sin prototipado en Figma, Claude Code intentó construir pantallas que incluían drawers y componentes más complejos. En un componente que representa un diagrama de neumáticos, acertó en algunas partes y destruyó otras. La información quedó demasiado pequeña, los espaciados demasiado estrechos para cualquier legibilidad.

En los listados, usó un checkbox dentro de un formato que no existe en nuestro sistema. Creó indicadores en grid, segregando la información en cajas cuando una lista simple habría funcionado mejor. En otro caso, generó un listado de cards totalmente genérico, con colores que no tenían sentido y cajas de información apiladas sin ningún refinamiento.

El caso más emblemático: sin encontrar nuestra forma específica de tratar el estado, inventó la suya. Creó cards con fondo amarillo, rojo o verde según la situación. Esa lógica no existe en nuestro design system. La construyó desde cero porque no encontró nada a qué referirse.

El patrón detrás de los fallos

Al mirar el conjunto de errores, un patrón quedó claro: Claude Code inventa cuando no encuentra.

Cuando hay un componente disponible y documentado, lo usa. Cuando no lo hay, lo crea. Y lo que crea revela exactamente lo que falta en la documentación.

El checkbox en el listado señala que el patrón de listado necesita una regla explícita de cuándo usarlo y cuándo no. Los cards coloreados por estado muestran que nuestro sistema de estados no está documentado de forma accesible. La cajita de información que ocupa una fila entera indica que no existe ninguna orientación sobre optimización del espacio disponible para consulta.

Los componentes estructurales con patrón global funcionan porque Claude Code tiene suficiente referencia del mundo externo. Los componentes contextuales específicos del producto fallan porque la única referencia posible es nuestro sistema, y si este no documenta bien, el LLM adivina.

Cómo esto cambia la priorización

En el artículo anterior describí la lógica de priorizar por el patrón de pantalla más repetido: menú, topbar, header y tabla. Ese anclaje todavía tiene sentido como punto de partida. La conversación de hoy agregó una segunda capa que faltaba.

La primera parte sigue siendo los componentes de la pantalla ancla. El menú aparece en prácticamente el cien por ciento de las pantallas del sistema. Claude Code ya consigue construirlo razonablemente bien, pero todavía comete errores. Refinar la documentación lo suficiente para eliminar esos errores tiene impacto inmediato a escala total. Es el componente con mayor retorno proporcional.

La segunda parte va directamente adonde se concentran los errores. Los drawers son el caso más crítico: reemplazan a los modales en nuestro sistema, se usan extensamente y Claude Code los ha construido de forma totalmente aleatoria. A veces acierta un layout parecido, la mayoría de las veces se equivoca mucho.

Antes de asumir que el problema está en la documentación, vamos a probar más. Necesito entender si Claude Code falla porque no encontró el componente, porque la documentación existente es insuficiente o porque las instrucciones que dimos eran incorrectas. Cada causa tiene una solución distinta.

Una recomendación para quien está empezando

No todo equipo tiene dos semanas de dedicación exclusiva a un design system, y no todo design system tiene el problema específico que tenía el nuestro con tokens desactualizados.

Lo que este proceso sugiere como entrada más práctica: empieza usando un LLM para construir interfaces reales en el código. LLMs que entreguen código aprovechable para producción, con el desarrollador en el loop. Las herramientas de prototipado rápido quedan fuera de lo que recomiendo aquí.

En ese proceso, los errores van a aparecer. Cada uno apunta a una brecha específica en la documentación. No necesitas planificar qué documentar: el LLM muestra dónde está el hueco.

Si ya tienes experimentos hechos y casos de fallo mapeados, como es nuestro caso ahora, puedes ir directamente a lo que está fallando y priorizar a partir de ahí. Si todavía no los tienes, prueba primero, deja que el LLM falle y usa los errores como mapa.

Esto no sustituye el trabajo de base cuando es necesario. Los tokens desactualizados deben resolverse antes de cualquier capa de IA. El orden importa. Con una base razonablemente sólida, priorizar por el error puede ser el camino más rápido para generar valor real en la operación.

Lo que viene

El Proyecto Harness Design System ya está en marcha. Desarrolladores React y Flutter, yo y Glauber Franco, con foco total en esto durante dos semanas. El objetivo es salir de ese período con tokens aplicados en el código, componentes de la pantalla ancla refinados y un entendimiento claro de dónde están fallando los drawers y cómo corregirlo.

No sé qué resultados vamos a alcanzar. Pronto traeré novedades.