El código muestra lo que un equipo entregó. Rara vez muestra por qué un comportamiento se volvió estándar, por qué se aceptó una excepción o qué problema decidió resolver una interfaz. Mientras el trabajo lo hacían solo personas que habían participado en las conversaciones, ese vacío podía compensarse con memoria, revisión y preguntas de pasillo.
Con agentes capaces de producir interfaces y cambios de código rápidamente, esa compensación se vuelve más frágil. El agente encuentra componentes, nombres y ejemplos en el repositorio. Si la razón de una decisión quedó en una reunión, en un comentario antiguo o en la cabeza de alguien, no forma parte del contexto que orienta el siguiente cambio.
Ese es el punto central de la experiencia que describe Vercel: las decisiones de producto aceptadas se tratan como código. Viven en el repositorio, pasan por revisión y quedan disponibles para los agentes que trabajan en ese sistema. La consecuencia va más allá de documentar el diseño. Convierte el criterio de producto en una dependencia explícita de la arquitectura de entrega.
El código conserva el patrón, no la intención
Un agente puede copiar la apariencia de una pantalla y reutilizar el componente correcto. Eso no garantiza que entienda el motivo de una elección. Un mensaje breve puede haberse adoptado porque reduce una duda recurrente. Un botón puede aparecer en una posición específica porque el flujo necesita evitar una acción irreversible. Un estado aparentemente redundante puede existir para orientar la recuperación después de una falla.
Sin esa explicación, el agente trata lo que existe como una colección de ejemplos. Generaliza a partir del caso más cercano, incluso cuando la similitud visual oculta una diferencia de contexto. La implementación puede compilar, pasar una captura visual y aun así contradecir una decisión de producto ya tomada.
Lo mismo vale para las excepciones. Una regla como "usa el componente de confirmación para acciones destructivas" no basta si no registra qué acciones se consideraron destructivas, qué información necesita el usuario antes de confirmar y cuándo se puede deshacer la operación. El patrón ayuda a ejecutar; la decisión explica el límite.
El contexto versionado es parte de la arquitectura
Llamar documentación a este material puede hacerlo parecer complementario. En sistemas operados por agentes, la distinción pierde fuerza. Si la ausencia de una decisión altera el resultado producido, esa decisión forma parte del sistema que produce software.
No hace falta convertir el repositorio en un manual extenso. El contexto útil es breve y verificable. Para una decisión, conviene registrar:
- el problema que había que resolver;
- el comportamiento elegido y lo que quedó fuera del alcance;
- la razón que distingue esa elección de alternativas cercanas;
- las señales que permiten revisar o retirar la decisión.
Ese registro puede vivir junto a los componentes, en una carpeta de decisiones de producto o en una skill que carga el agente. El lugar importa menos que tres propiedades: el flujo de trabajo tiene que encontrarlo, tiene que pasar por revisión y tiene que cambiar cuando cambia el producto.
Vercel describe una estructura con una skill de agente, linters y un ciclo de revisión que reúne evidencias de Slack, Figma y GitHub para proponer actualizaciones de las directrices. El detalle operativo puede variar entre equipos. La decisión arquitectónica es la misma: el contexto de producto necesita un responsable, una fuente y un camino de actualización.
El riesgo de congelar decisiones antiguas
Versionar una decisión no significa volverla eterna. Un repositorio puede conservar patrones con tanta eficiencia que también conserva elecciones que perdieron validez.
Por eso, cada registro tiene que dejar visible su alcance. Una decisión puede valer solo para una superficie, para un tipo de usuario o para una restricción temporal de integración. Sin ese límite, el agente encuentra una regla verdadera en un contexto y la aplica como ley general.
Revisar el contexto también debe formar parte de los cambios que lo consumen. Si un nuevo flujo necesita abrir una excepción, el pull request no debería limitarse a cambiar la interfaz. Debería indicar si la regla sigue vigente, si la excepción es local o si el patrón tiene que reescribirse. La revisión deja de preguntar solo "¿funciona el código?" y pasa a preguntar "¿la decisión que materializa este código sigue siendo la correcta?".
Qué merece convertirse en contexto para agentes
No toda conversación de diseño necesita archivarse. El filtro más práctico es preguntar si la ausencia de esa información aumenta la probabilidad de un cambio plausible pero equivocado.
Entran primero las decisiones que afectan muchos caminos: vocabulario del producto, estados de error, permisos, patrones de navegación, componentes obligatorios, criterios de accesibilidad y límites entre superficies. También entran las excepciones que parecen contradecir una regla común. Son justamente las que un agente no puede inferir con seguridad a partir de un ejemplo aislado.
Los detalles cosméticos y las preferencias sin consecuencias no necesitan el mismo tratamiento. Si una elección puede cambiar sin alterar la comprensión, el riesgo o el comportamiento, un token o un componente compartido probablemente ya es contexto suficiente.
La decisión para el equipo
Antes de pedir a los agentes que produzcan más pantallas, el equipo debería listar qué decisiones de producto hoy solo se pueden recuperar preguntándole a una persona. Después puede clasificar cada una: patrón codificado, decisión documentada, regla automatizable o criterio que todavía exige revisión humana.
El objetivo no es que el agente participe en todas las discusiones. Es reducir el espacio en el que tiene que adivinar. Cuando la decisión queda cerca del código, el equipo gana velocidad sin convertir la coherencia en coincidencia.
Si tu empresa está evaluando algo parecido, escríbeme por LinkedIn o por WhatsApp.
