Specification-Assisted Development
Specification-Assisted Development es la práctica de utilizar especificaciones y otros artefactos de diseño para orientar cambios asistidos por IA, manteniendo explícitas las expectativas, restricciones y decisiones que el trabajo debe respetar. La especificación aporta una referencia durable para interpretar el encargo; el agente puede ayudar a examinarla, encontrar contradicciones, proponer alternativas y modificar software dentro del alcance acordado.
La práctica no establece una metodología universal llamada Spec-Driven Development ni exige documentar extensamente cada modificación. Un contrato pequeño puede ser suficiente para un cambio localizado. Un cambio de interfaz compartida puede necesitar mayor precisión. La pregunta es qué incertidumbre debe resolverse y conservarse para trabajar y revisar con criterio, no cuántos documentos puede generar el agente.
Especificación, prompt y plan
Una especificación describe de manera estructurada comportamiento esperado, decisiones de diseño o restricciones. Puede incluir ejemplos, invariantes y casos excluidos. Un Task Prompt solicita una acción: investigar una discrepancia, implementar parte de ese contrato o revisar una propuesta. Ambos pueden compartir texto, pero cumplen funciones distintas. Un encargo transitorio puede apuntar a una especificación que sobreviva a muchas sesiones y cambios de responsables.
Un plan expresa cómo se pretende proceder: explorar consumidores, ajustar una interfaz, modificar implementaciones y ejecutar comprobaciones. Puede derivarse de la especificación, pero no la reemplaza. “Agregar validación y actualizar tests” no determina qué entradas son válidas. A la inversa, definir las entradas permitidas no resuelve en qué orden se modificarán los componentes.
La verificación necesita evidencia sobre el resultado de un cambio concreto. Marcar todos los pasos del plan como completados no la establece. Una lista puede registrar que se ejecutó un comando sin demostrar que su cobertura alcanza el contrato. Mantener separadas expectativas, intención de ejecución y resultados observados permite evaluar cada pieza sin atribuir a una más autoridad de la que tiene.
Cuándo aporta valor
La asistencia mediante especificaciones resulta útil cuando el encargo admite interpretaciones distintas, cruza límites entre componentes o debe conservarse para futuras modificaciones. También ayuda cuando una sesión interrumpida necesita recuperar decisiones sin reconstruir toda la conversación. La referencia común reduce la posibilidad de que cada participante complete los huecos de manera diferente.
Su valor disminuye si el artefacto solo repite el código, queda desactualizado inmediatamente o agrega formalidad sin resolver incertidumbre. Corregir una errata no necesita una nueva especificación de plataforma. Tampoco conviene escribir anticipadamente contratos para funcionalidades hipotéticas. La profundidad documental debe seguir el riesgo, la duración esperada del acuerdo y el costo de una interpretación incorrecta.
Repository Exploration and Task Framing ayuda a decidir qué contrato hace falta. La exploración identifica el comportamiento actual y las dependencias; el encuadre delimita qué debe cambiar. La especificación conserva las expectativas pertinentes. No todo lo descubierto debe pasar al contrato: detalles incidentales del repositorio pueden ser evidencia útil sin convertirse en requisitos permanentes.
Contenido suficiente para orientar un cambio
Una especificación útil declara el problema y la frontera del comportamiento que regula. Explica qué debe cumplirse, bajo qué condiciones y qué queda excluido. Los ejemplos aclaran casos, pero no sustituyen las reglas cuando hay variaciones importantes. La consistencia entre ambos importa: si la regla y el ejemplo discrepan, el agente debe señalarlo en vez de elegir silenciosamente el que resulte más fácil de implementar.
Las restricciones pueden incluir compatibilidad de consumidores, formatos públicos o conservación de datos. Deben distinguirse de preferencias de implementación. Una API que necesita mantener un campo no obliga necesariamente a conservar una clase interna. Convertir cada detalle observado en un requisito dificulta cambios legítimos; ignorar contratos existentes permite simplificaciones que rompen a otros equipos.
También interesa registrar el estado del acuerdo. Una alternativa propuesta por el agente no tiene el mismo valor que una decisión aceptada. Una pregunta pendiente no debe aparecer en una sección normativa como si ya estuviera resuelta. Esta distinción puede expresarse con lenguaje claro y las convenciones existentes del proyecto; no requiere introducir un esquema documental nuevo para cada tarea.
Autoridad y cambios de requisitos
El agente puede detectar que falta definir el tratamiento de un caso o que dos restricciones son incompatibles. Puede explicar opciones y consecuencias, y recomendar una salida sustentada en evidencia. No debería convertir esa recomendación en una decisión de producto sin la autoridad correspondiente. Las personas responsables aportan intención, prioridades y contexto organizacional que el repositorio puede no contener.
Esto no implica detener cualquier trabajo rutinario. Dentro de un contrato claro, el agente puede elegir nombres internos, adaptar una prueba o reorganizar una función según las convenciones vigentes. La necesidad de consulta aparece cuando una elección cambia expectativas o introduce un compromiso fuera del encargo. La autonomía útil requiere distinguir decisiones de ejecución de decisiones sobre el resultado esperado.
Cuando el contrato cambia, debe conservarse la relación entre la decisión nueva y sus efectos. No conviene modificar la especificación después de implementar solo para hacer que el resultado parezca conforme. Si una limitación real obliga a revisar el acuerdo, la justificación y la aceptación corresponden al proceso del equipo, no a una autoevaluación del modelo.
Plan-Guided Execution
Un plan puede descomponer el trabajo en incrementos comprensibles y mostrar dependencias entre ellos. Para un cambio de contrato, quizá primero se identifiquen consumidores, luego se prepare compatibilidad y después se modifique el comportamiento. Para una corrección local, puede bastar una breve secuencia mental o escrita. El plan es una herramienta de coordinación, no un entregable obligatorio de tamaño fijo.
La descomposición debe producir pasos con significado técnico. “Implementar todo” no permite seguir progreso; veinte pasos que nombran cada edición trivial pueden ocultar lo importante. Interesa separar partes con riesgos, decisiones o comprobaciones diferentes. El agente debería poder explicar qué hecho permite avanzar y qué resultado inesperado justificaría reconsiderar el siguiente paso.
Seguir el plan incluye actualizarlo cuando cambian los datos. Si aparece un consumidor no contemplado, puede ser necesario incorporar una transición o limitar el alcance. Replanificar preserva el objetivo y modifica el camino. Cambiar el objetivo para no reconocer una dificultad es otra decisión, que necesita tratarse explícitamente. Un plan obsoleto no debe seguir guiando herramientas solo porque figura como aprobado.
Progreso y puntos de comprobación
El progreso puede registrar trabajo realizado, obstáculos y pasos pendientes. Debe diferenciar “código editado”, “comprobación ejecutada” y “resultado aceptado”. La distinción ayuda a retomar una sesión y evita que un resumen convierta una intención en un hecho. También impide que un agente posterior dé por verificadas comprobaciones que solo estaban previstas.
Los puntos de comprobación deben responder al riesgo del incremento. Después de cambiar una representación pública puede importar comprobar consumidores; después de modificar una regla, observar sus casos relevantes. No se trata de ejecutar toda la suite tras cada línea ni de reducir la validación a un único comando al final. El plan organiza cuándo obtener evidencia útil sin confundir su organización con la evidencia misma.
Los Development Context and Execution Records pueden conservar el estado de ese recorrido. Conviene registrar resultados reales y límites, incluyendo checks no ejecutados. El registro hace el proceso inspeccionable, pero una descripción convincente de resultados no reemplaza los artefactos o salidas que los sustentan.
Design Assistance
La IA puede asistir en la comparación de alternativas, el análisis de impacto y la elaboración de interfaces. Puede señalar que un cambio exige coordinar consumidores o que una opción desplaza complejidad hacia otro componente. Su aporte mejora cuando las propuestas se contrastan con restricciones reales del repositorio, en vez de aplicar una arquitectura reconocible a cualquier problema.
Design Process conserva el marco general para tomar decisiones de diseño. La asistencia automatizada no transforma una lista de ventajas genéricas en una decisión arquitectónica. Una propuesta debe declarar supuestos y costos relevantes: compatibilidad, operación, evolución y capacidad del equipo. Si el agente no conoce uno de esos factores, corresponde mantenerlo como incertidumbre.
El diseño de API ilustra la diferencia. El agente puede proponer nombres, errores y ejemplos coherentes; también puede detectar una operación ambigua. Pero decidir si una acción admite repetición o qué compatibilidad se promete afecta a usuarios y sistemas externos. Esas elecciones necesitan una autoridad y una justificación situadas, aunque el código para implementarlas sea sencillo.
Ejemplo: importaciones con resultados parciales
Un equipo quiere que una importación informe errores por fila y conserve las filas válidas. El prompt inicial pide “soportar importación parcial”. La especificación debe aclarar qué significa válida, cuándo se confirman los cambios y qué ocurre si dos filas dependen entre sí. También debe resolver si repetir la misma importación crea registros nuevos o recupera un resultado previo. El agente puede localizar esas preguntas; no responderlas a partir del nombre de la funcionalidad.
Una vez acordadas las reglas, el plan puede separar el cálculo de resultados, la persistencia y la presentación. El agente propone alternativas para el contrato de respuesta y muestra qué consumidores necesitan adaptación. Si descubre que un consumidor interpreta cualquier error como un rollback completo, hay una incompatibilidad relevante. No basta con modificar los tests de ese consumidor para que acepten silenciosamente la semántica nueva.
Durante la ejecución, una comprobación puede mostrar que una fila válida depende de otra rechazada. Ese hallazgo obliga a volver al contrato, no necesariamente a rehacer toda la planificación. La decisión puede ser rechazar el grupo dependiente o definir otra política. El ejemplo muestra una colaboración iterativa: especificar orienta la implementación y la evidencia concreta puede revelar preguntas que todavía no estaban formuladas.
Conexión entre contrato, cambios y evidencia
Una relación trazable puede ser pequeña: una expectativa concreta, los componentes que la implementan y la comprobación que informa sobre ella. No hace falta construir una matriz exhaustiva para cada función. Sí conviene poder explicar por qué un cambio satisface la intención y qué parte de la expectativa sigue sin comprobarse.
En AI-Assisted Implementation and Change Maintenance, esa referencia limita la expansión del diff. En AI-Assisted Test Generation, aporta una base para resultados esperados que no derive únicamente de la implementación generada. En AI-Assisted Code Review, permite revisar coherencia con el acuerdo en lugar de evaluar solo estilo o legibilidad.
La especificación tampoco elimina errores correlacionados. Si contiene una premisa incorrecta y tanto implementación como tests la reproducen, habrá consistencia sin corrección respecto de la necesidad real. Por eso importa revisar de dónde provienen las expectativas y qué autoridad las sostiene. La precisión formal de un documento no compensa una decisión de producto equivocada.
Fricciones y límites de la práctica
Versiones del acuerdo y compatibilidad
Una especificación puede evolucionar mientras una implementación anterior sigue en uso. El agente necesita saber qué versión regula el cambio y qué consumidores permanecen bajo el contrato previo. Trabajar siempre sobre el texto más reciente sin considerar la transición puede romper compatibilidad aunque cada versión sea internamente coherente. La asistencia de diseño puede localizar esa coexistencia y proponer una adaptación gradual, dejando explícita la decisión que necesita el equipo.
Los ejemplos también tienen una revisión implícita. Copiar un payload de una conversación antigua a tests nuevos puede reintroducir una expectativa retirada. Conviene mantener una referencia identificable al acuerdo aplicable y evitar que resúmenes sucesivos se conviertan en copias divergentes. La trazabilidad puede ser sencilla: una referencia al documento y una explicación del cambio de comportamiento. Lo importante es que el siguiente lector pueda recuperar la decisión vigente sin tener que adivinar cuál de varios textos tiene autoridad.
Una fricción frecuente es mantener dos fuentes del mismo contrato que evolucionan por separado. Otra es mezclar requisitos, propuestas y decisiones en un texto donde todo parece obligatorio. El agente puede amplificar ambas al copiar fragmentos sin su estado o contexto. La solución pasa por identificar la referencia autoritativa y actualizar solo los artefactos que realmente dependen del cambio.
También existe el riesgo de sobreplanificar: invertir más esfuerzo en anticipar pasos que en resolver la incertidumbre que los condiciona. Un experimento breve puede aportar más que un plan detallado basado en supuestos. El equipo puede autorizarlo con límites claros y usar su resultado para decidir. Eso sigue siendo trabajo disciplinado aunque no se ajuste a una secuencia documental fija.
Specification-Assisted Development orienta la colaboración y conserva acuerdos. No garantiza que el agente comprenda cada restricción, que el plan sea óptimo ni que el resultado esté verificado. Su utilidad aparece cuando ayuda a distinguir lo esperado, lo decidido, lo ejecutado y lo observado, sin imponer un método único a toda tarea de ingeniería.