Desarrollo guiado por especificaciones para proyectos de IA

La IA hace mucho más fácil producir código con rapidez. También hace mucho más fácil producir con rapidez el código equivocado. Precisamente por eso el desarrollo guiado por especificaciones es más importante, no menos importante, en proyectos asistidos por IA.

Cuando un equipo desarrolla sin una especificación clara, el producto se desvía con el tiempo de su propósito. Cuando la IA participa en ese proceso, esa desviación puede aparecer en una sola tarde. El código puede compilar, la interfaz puede verse pulida y las pruebas pueden incluso pasar. Aun así, el producto puede ser erróneo.

Por qué la IA cambia el perfil de riesgo

La IA acelera el ritmo de la interpretación. Un solo prompt puede producir arquitectura, texto, validación, nomenclatura y flujo de usuario. Eso es útil, pero peligroso cuando la fuente de verdad no es lo bastante clara.

En la práctica, la IA suele optimizar lo que en ese momento es más visible:

• el último prompt
• el archivo más cercano
• la ruta de implementación más fácil
• el patrón genérico más conocido

Nada de eso significa automáticamente la decisión correcta de producto.

Son atajos útiles para la generación. Pero no sustituyen el juicio de producto.

Qué hace una buena especificación

Una buena especificación cumple al menos cuatro funciones:

• define el propósito
• fija límites
• establece el criterio de revisión
• sirve como memoria del equipo

Primero, define el propósito. El equipo puede ver si una funcionalidad apoya el producto real o simplemente añade salida.

Segundo, define límites. Aclara qué está dentro del alcance, qué está fuera del alcance, qué es opcional y qué debe seguir funcionando incluso cuando fallen sistemas opcionales.

Tercero, define el criterio de revisión. En lugar de preguntar solo si un cambio funciona técnicamente, los revisores pueden preguntar si coincide con el flujo de trabajo previsto y con los compromisos del producto.

Cuarto, actúa como memoria. Los sistemas de IA no mantienen por sí solos una memoria institucional estable. Una especificación en el repositorio sí.

Esto es muy claro en Let Books. AGENTS.md insiste varias veces en que el flujo manual debe seguir siendo útil incluso sin servicios de IA de pago y en que las copias físicas de los libros no son lo mismo que los registros bibliográficos. No son detalles técnicos, sino límites de producto.

No son detalles de implementación. Son límites de producto. Si un asistente de IA genera un flujo que bloquea la entrada manual o mezcla datos de la copia física con metadatos de la edición, el problema no es el estilo. El problema es la deriva del producto.

Por qué la documentación no debe esperar

Si la documentación está desactualizada o es confusa, personas y herramientas distintas deducirán productos distintos a partir del mismo repositorio. Una seguirá la demo, otra un README antiguo y otra el archivo más cercano.

Sin documentación actual:

• los prompts se vuelven incoherentes
• la revisión se vuelve subjetiva
• las demos empiezan a redefinir el producto por accidente
• los futuros colaboradores heredan comportamientos sin saber si eran intencionales

Por eso la documentación no es solo una explicación posterior. Es parte del sistema operativo del proyecto. En este repositorio, README.md describe el estado actual, AGENTS.md la intención del producto, AGENTS-Implementation.md las reglas tácticas y docs/ las reglas de publicación y evidencia.

El papel de las demos

Una demo es útil porque muestra lo que existe y revela problemas del flujo de usuario. Pero no debería convertirse silenciosamente en la especificación del producto.

Las reglas del repositorio ya distinguen entre especificaciones y documentación canónicas por un lado, y estado de implementación por otro. Si una demo revela un flujo mejor, hay que actualizar la especificación y la documentación, en lugar de dejar que la demo gane por sí sola.

Si una demo revela un mejor flujo de trabajo, la respuesta no es dejar que gane en silencio. La respuesta es actualizar la especificación, la documentación y el criterio de revisión para que ese mejor flujo pase a ser intencional.

Markdown, pruebas y CI forman una cadena

En un desarrollo guiado por especificaciones, estas capas no están separadas.

• Markdown almacena la intención en una forma revisable.
• La documentación explica cómo debe interpretarse.
• Las pruebas verifican expectativas ejecutables.
• Las reglas de validación detectan la deriva estructural.
• CI aplica las reglas de forma regular.

Juntas crean una memoria de producto que sobrevive a la velocidad del desarrollo.

Cada capa es incompleta por sí sola. Juntas crean una memoria de producto que sobrevive a la velocidad, la iteración y los cambios de equipo.

Lo que esto significa para los equipos que usan IA

Los equipos que usan bien la IA no eliminan el proceso. Acercan el proceso a la fuente de generación.

Eso suele significar:

• escribir especificaciones de producto más claras antes de pedir la implementación
• mantener explícita la guía de implementación
• actualizar la documentación cuando cambia el comportamiento del producto
• comprobar los demos frente a las especificaciones en lugar de asumir la paridad
• añadir gradualmente reglas de validación para que la coherencia no dependa solo de la memoria humana

Esto no es anti-IA. Es como la IA se vuelve fiable.

La lección duradera

La IA puede producir rápidamente código, contenido e interfaces. Por sí sola no puede garantizar que todos esos resultados sigan describiendo el mismo producto.

El desarrollo guiado por especificaciones es la manera en que un equipo evita que la velocidad se convierta en deriva.

En los proyectos asistidos por IA, la especificación no es papeleo posterior. Es el límite, la memoria y el criterio de revisión que hacen fiable una entrega rápida.

Lecturas relacionadas

• ../../wiki/spec-driven-development.md
• ../../wiki/validation-layers.md
• ai-as-an-oracle.md
• spec-driven-development-in-let-books.md