Mantener a personas y coding agents en la misma página

Ya estaba trabajando en el Design System cuando un problema distinto empezó a hacerse evidente: los coding agents podían generar interfaces rápido, pero la velocidad no era la parte difícil.

La consistencia sí lo era.

La intención de producto, las reglas de componentes y las decisiones de interacción vivían en demasiados lugares, o a veces solo en la cabeza de alguien. Si los agentes iban a participar en el desarrollo de producto, ese conocimiento tenía que pasar a ser parte del sistema.

Resumen

Equipo

Área de Inteligencia Artificial de Falabella, con equipos multidisciplinarios en Chile e India

Alcance

El Design System, su documentación legible por agentes, un framework interno de GenAI agnóstico de modelo, y los productos internos construidos con ellos

Coding agents

Claude Code · OpenAI Codex · GitHub Copilot · OpenCode, como entornos de implementación

En producción

El Design System se usa en múltiples productos internos; el framework se usa en varios de esos proyectos. Todo esto es interno, por eso este caso muestra estructura en vez de pantallas.

# Story: S-014 — Run history filterStatus: READY · Type: frontend · Risk: low## User storyAs an operator, I want to filter runs by status and date,so that I can find failed runs without scrolling.## Acceptance criteria1. status = failed → only failed runs, count updates2. no match → DS empty state with reset3. reload → filter persists in the URL## DS componentsSelect · DateRange · EmptyState  ← from the Design SystemNo new components. Tokens only.

El Design System vino primero

Lo creé desde cero: una capa de tokens de tres niveles (primitivo, semántico, componente), una librería de componentes de producción adaptada de Radix y shadcn/ui, y una CLI que instala el código fuente de los componentes en cada proyecto. Sus principios caben en una línea: claridad sobre complejidad, consistencia con propósito, accesibilidad como base, tokens antes que valores.

Hacer que los componentes y tokens fueran legibles para los coding agents mejoró la consistencia de implementación, pero expuso una brecha mayor. Un agente podía usar el componente correcto y aun así tomar la decisión de producto equivocada cuando los estados, las reglas de interacción o la razón detrás de la interfaz seguían siendo implícitas.

Antes, un ticket podía nombrar un control pero dejar el comportamiento de carga, error, vacío y responsive abierto a interpretación. Después, un brief de diseño registraba esas decisiones antes de la implementación, así el owner, el diseñador, el coding agent y el revisor trabajaban desde el mismo contrato.

Eso se convirtió en un framework interno de GenAI agnóstico de modelo, diseñado para llevar la intención de producto, las historias, las reglas de interacción, las guías del Design System y las restricciones de implementación desde la idea hasta el código.

En la práctica, el framework viaja con cada proyecto. Empaqueta guías de ciclo de vida, definiciones de rol, convenciones específicas del stack, contexto compartido y un Definition of Done en un formato que tanto las personas como los coding agents pueden usar.

El Design System entra a través de una capa semántica sincronizada que contiene componentes, tokens y guías para agentes. Los proyectos pueden actualizar esa capa sin editarla a mano, y la validación de cierre revisa el código en busca de valores hardcodeados y componentes reimplementados.

¿Por qué no simplemente escribir mejores prompts?

Los prompts y la documentación siguen dejando espacio para la interpretación. El framework convierte las partes no negociables en un contrato: reusar un componente existente antes de crear uno, usar tokens en vez de valores hardcodeados, escribir el brief de diseño antes de implementar, y verificar umbrales estructurales de forma mecánica al completar.

Qué significa “legible por agentes”

Una historia es la unidad desde la que trabaja un coding agent. Su estructura es fija para que cada sección sea legible por el owner y parseable por los agentes que la refinan, implementan, testean y revisan. El ejemplo ilustrativo de arriba muestra las piezas clave: intención del usuario, criterios de aceptación verificables, decisiones del Design System y tareas de implementación.

Cada historia de UI también recibe un brief de diseño antes de escribir código. Registra el objetivo del usuario, el patrón, los componentes, los tokens, los estados de pantalla y de control, el comportamiento responsive y los requisitos de accesibilidad. La implementación lee el brief primero.

Una sola fuente, distintos coding agents

No quería que el flujo de trabajo dependiera de un solo proveedor, así que se diseñó en torno a la especificación y al Design System en vez de un coding agent particular. Las guías se mantienen una sola vez y se adaptan a lo que cada entorno entiende. El trabajo crítico también puede revisarse a través de un modelo distinto sin cambiar el contrato de producto.

He usado el flujo de trabajo con:

React solo duró dos semanas

La primera versión asumía React.

Eso duró unas dos semanas, hasta que un proyecto solo de documentación ni siquiera pudo instalarlo. Los productos internos no usaban todos el mismo stack, y fijar el framework a una sola tecnología de implementación habría ido contra el propósito.

Saqué el comportamiento específico del stack de la estructura central y lo llevé a perfiles que el framework instala después de detectar el stack, así la especificación de producto podía mantenerse estable mientras el entorno de implementación cambiaba.

La adopción se convirtió en el verdadero problema de diseño

Si probarlo requería una configuración larga, nadie lo iba a usar.

Así que la instalación y el onboarding también se volvieron problemas de producto: verificaciones previas, un comando para instalar, una guía de inicio rápido corta, un comando para actualizar, y un script de diagnóstico que te dice qué falta.

Parte de la adopción también fue con personas. Hago mentoría a diseñadores y desarrolladores en flujos de trabajo agénticos y spec-driven development, en equipos de Chile e India. Un lenguaje de producto compartido importa más cuando las personas que lo comparten están a varios husos horarios de distancia.

Dónde funciona

El Design System está en producción en múltiples productos internos del área de GenAI y Data de Falabella. El framework se usa en varios proyectos y puede agregarse a medida que empieza trabajo nuevo.

• Plataformas agénticas internas
• Plataformas de datos internas
• Plataformas internas de eventos
• Herramientas operacionales

Una vez que las personas y los agentes dependen de las mismas reglas, la documentación deja de ser material de apoyo. Pasa a ser parte del sistema.