El Problema de Ir Sobre la Marcha

Imagina esto: tienes una funcionalidad clara en mente. Entras a tu asistente de código favorito con IA, escribes una solicitud rápida y observas cómo reescribe la mitad de tu base de código con total confianza. Una hora después, estás frente a un PR que resuelve un problema que en realidad no querías resolver, de una forma que rompe cosas que no querías romper.

¿Te suena familiar? No eres el único. A medida que los agentes de código con IA han evolucionado de simples respondedores de preguntas a editores de código, muchos desarrolladores están descubriendo que el mismo enfoque despreocupado que funciona con los chatbots se queda corto cuando hay repositorios reales en juego.

La solución no está en prompts más detallados. Está en un cambio fundamental en cómo pensamos los documentos que enviamos a estos agentes.

Prompts vs. Especificaciones: Una Diferencia Clave

Esto es lo que pasa con los prompts: están optimizados para iniciar trabajo. Son geniales para explicaciones rápidas, scripts temporales y conversaciones exploratorias. Un prompt vive en una sesión de chat, puede usar abbreviaturas y frecuentemente asume contexto que solo el autor entiende.

Eso funciona bien cuando solo estás haciendo preguntas.

Pero cuando un agente de IA va a editar código compartido, ejecutar comandos de terminal y producir ramas que tus compañeros revisarán... tu prompt casual se convierte en una asignación. Y las asignaciones necesitan más que buenas palabras: necesitan el contexto adecuado, límites claros, ejemplos concretos y criterios de validación.

Ahí es donde entran las especificaciones.

Una especificación no es un prompt más bonito. Es un documento estructurado que captura qué problema estás resolviendo, qué comportamiento debe cambiar, qué debe mantenerse igual y cómo sabrás si el trabajo fue exitoso. A diferencia de un prompt que desaparece cuando el agente empieza a trabajar, una especificación permanece visible durante todo el flujo de trabajo, guiando al agente, informando a los revisores y ayudando a futuros mantenedores a entender por qué se tomaron ciertas decisiones.

Qué Lleva una Buena Especificación para Agentes de IA

No necesitas un documento de 20 páginas. Lo que necesitas son cinco elementos clave:

1. Contexto: ¿Por qué existe esta tarea? ¿Qué problema de usuario o deuda técnica la impulsa? ¿Qué restricciones existen en el código que el agente debe entender?

2. Comportamiento a cambiar: ¿Qué funcionalidad específica debe modificarse, añadirse o eliminarse? Sé concreto: "los usuarios deben recibir notificaciones por email cuando X ocurra" es mejor que "mejorar el sistema de notificaciones".

3. Restricciones a preservar: ¿Qué no debe cambiar absolutamente? ¿Qué funcionalidad existente, contratos de API o características de rendimiento deben mantenerse intactos?

4. Ejemplos de corrección: Escenarios concretos que demuestren qué significa un buen resultado. El formato Dado/Cuando/Entonces funciona bien aquí, pero incluso unos pocos casos de prueba explícitos ayudan al agente a entender tus expectativas.

5. Criterios de validación: ¿Cómo sabrá un revisor si el trabajo está completo? ¿Qué debe inspeccionar? ¿Qué preguntas debe hacerse?

Este marco debería resultarte familiar si has trabajado con escenarios de desarrollo guiado por comportamiento (BDD), plantillas de issues con criterios de aceptación o documentos de diseño. El formato específico importa menos que tener la información correcta en una forma compartible y revisable.

Dónde Viven las Especificaciones en Tu Flujo de Trabajo

Una de las mejores cosas de las especificaciones es su flexibilidad. No tienen que ser documentos separados que te ralenticen. Una especificación puede vivir en cualquier lugar que tenga sentido para tu equipo:

• Un issue de GitHub con criterios de aceptación explícitos
• Una descripción de PR que nombre el comportamiento que está cambiando
• Un escenario BDD en tus archivos de características
• Una nota de diseño ligera antes de la implementación
• Herramientas como OpenSpec o GitHub Spec Kit que formalizan este patrón

La clave es hacer que el contexto y los criterios de revisión sean visibles y persistentes. Tu especificación no debería desaparecer cuando termina la sesión de chat. Debe viajar con el trabajo, dando a tus compañeros algo concreto para evaluar.

La Capa de Asignación: Separando la Intención de la Ejecución

Aquí es donde las cosas se ponen realmente interesantes.

Las especificaciones más sólidas se comportan como pequeños contratos de comportamiento. Separan tres preguntas distintas:

1. ¿Qué comportamiento debe cambiar? (El requisito)
2. ¿Qué restricciones o ejemplos definen la corrección? (Los criterios de aceptación)
3. ¿Qué camino de implementación parece apropiado ahora mismo? (El enfoque técnico)

Estas preguntas están conectadas, pero no deberían colapsar en un solo bloque de instrucciones.

¿Por qué importa esto para los agentes de código con IA? Porque cuando mezclas intención e implementación demasiado pronto, el agente puede optimizar para la cosa equivocada. Podría seguir fielmente un detalle de implementación sugerido mientras se pierde el comportamiento real que necesitabas. O podría producir código que es técnicamente interesante pero no resuelve el problema stated.

Una capa de asignación mantiene el requisito estable mientras permite que la implementación evolucione. A medida que el agente lee el código, descubre complicaciones y refina su enfoque, la especificación permanece como el punto de referencia: "¿El trabajo satisface esto?"

Esto es especialmente valioso para bases de código existentes. La mayor parte del trabajo de ingeniería no es en terreno virgén: estás cambiando comportamiento que ya existe. Una buena especificación dice: aquí está el comportamiento actual, y aquí está lo que necesita cambiar. Los revisores no tienen que reconstruir mentalmente tu intención a partir de los detalles de implementación.

Haciendo el Cambio

Si estás acostumbrado a tratar los agentes de código con IA como motores de búsqueda sobrealimentados, esto puede parecer sobrepensar. Pero considera la alternativa: cambios descontrolados en código compartido, PRs difíciles de revisar y trabajo que no termina de encajar con lo que imaginabas.

El cambio hacia la colaboración con IA basada en especificaciones no se trata de burocracia. Se trata de dar tanto a humanos como a máquinas la claridad que necesitan para trabajar juntos de forma efectiva.

Empieza poco a poco. La próxima vez que estés a punto de enviar un agente de código con IA a un repositorio, tómate cinco minutos para anotar el contexto, el cambio de comportamiento y los criterios de éxito. Ponlo en algún lugar visible, aunque sea solo en la descripción del PR.

Tu yo del futuro (y tus compañeros) te lo agradecerán.

En pocas palabras: Los agentes de código con IA son colaboradores poderosos. Trátalos como colaboradores. Dale un briefing adecuado y obtendrás trabajo que vale la pena revisar.