Desarrollo basado en especificaciones con IA: comience con un nuevo kit de herramientas de código abierto

A medida que los agentes de codificación se han vuelto más potentes, ha surgido un patrón: se describe el objetivo, se obtiene un bloque de código y, a menudo… parece correcto, pero no funciona del todo. Este enfoque de «codificación dinámica» puede ser excelente para prototipos rápidos, pero menos fiable al crear aplicaciones serias y cruciales o al trabajar con bases de código existentes.

A veces el código no compila. A veces resuelve parte del problema, pero no cumple con su propósito. La pila o la arquitectura podrían no ser las que elegirías.

El problema no es la capacidad de codificación del agente, sino nuestro enfoque. Tratamos a los agentes como motores de búsqueda cuando deberíamos tratarlos más como programadores en parejas con mentalidad literal. Son excelentes en el reconocimiento de patrones, pero aún necesitan instrucciones inequívocas.

Por eso estamos repensando las especificaciones: no como documentos estáticos, sino como artefactos vivos y ejecutables que evolucionan con el proyecto. Las especificaciones se convierten en la fuente compartida de la verdad. Cuando algo no tiene sentido, se vuelve a la especificación; cuando un proyecto se vuelve complejo, se perfecciona; cuando las tareas parecen demasiado extensas, se desglosan.

Spec Kit, nuestro nuevo kit de herramientas de código abierto para el desarrollo basado en especificaciones, proporciona un proceso estructurado para llevar el desarrollo basado en especificaciones a los flujos de trabajo de su agente de codificación con herramientas que incluyen GitHub Copilot, Claude Code y Gemini CLI.

¿Cuál es el proceso basado en especificaciones con Spec Kit?

Spec Kit convierte su especificación en el centro de su proceso de ingeniería. En lugar de redactar una especificación y dejarla de lado, esta guía la implementación, las listas de verificación y el desglose de tareas. Su función principal es dirigir; el agente de codificación realiza la mayor parte de la escritura.

Funciona en cuatro fases con puntos de control claros. Pero la clave está en esto: cada fase tiene una tarea específica y no se pasa a la siguiente hasta que la tarea actual esté completamente validada. 

Así es como se desglosa el proceso:

1. Especificar : Proporcionas una descripción general de lo que estás desarrollando y por qué, y el programador genera una especificación detallada. No se trata de pilas técnicas ni de diseño de aplicaciones. Se trata de la experiencia del usuario, sus recorridos y cómo se ve el éxito. ¿Quién lo usará? ¿Qué problema les resuelve? ¿Cómo interactuarán con él? ¿Qué resultados importan? Piensa en ello como un mapa de la experiencia de usuario que quieres crear y deja que el programador desarrolle los detalles. Fundamentalmente, esto se convierte en un artefacto vivo que evoluciona a medida que aprendes más sobre tus usuarios y sus necesidades.
2. Plan : Ahora, la fase técnica. En esta fase, proporciona al agente de codificación la pila, la arquitectura y las restricciones deseadas, y este genera un plan técnico completo. Si su empresa estandariza ciertas tecnologías, aquí es donde lo indica. Si se integra con sistemas heredados, tiene requisitos de cumplimiento o tiene objetivos de rendimiento que debe alcanzar, todo eso se incluye aquí. También puede solicitar múltiples variaciones del plan para comparar y contrastar diferentes enfoques. Si pone su documentación interna a disposición del agente de codificación, este puede integrar sus patrones y estándares arquitectónicos directamente en el plan. Después de todo, un agente de codificación necesita comprender las reglas del juego antes de empezar.
3. Tareas : El agente de codificación toma la especificación y el plan y los desglosa en trabajo real. Genera pequeños fragmentos revisables, cada uno de los cuales resuelve una pieza específica del rompecabezas. Cada tarea debe ser algo que se pueda implementar y probar de forma independiente; esto es crucial, ya que le permite al agente de codificación validar su trabajo y mantenerse al día, casi como un proceso de desarrollo basado en pruebas para su agente de IA. En lugar de «crear autenticación», se obtienen tareas concretas como «crear un punto final de registro de usuario que valide el formato del correo electrónico».
4. Implementar : Su agente de codificación aborda las tareas una por una (o en paralelo, si corresponde). Pero esto es diferente: en lugar de revisar miles de líneas de código, usted, el desarrollador, revisa cambios específicos que resuelven problemas específicos. El agente de codificación sabe qué debe construir porque la especificación así lo indica. Sabe cómo construirlo porque el plan así lo indica. Y sabe exactamente en qué trabajar porque la tarea así lo indica.

Fundamentalmente, tu función no es solo dirigir, sino verificar. En cada fase, reflexionas y perfeccionas. ¿Capta la especificación lo que realmente quieres construir? ¿El plan considera las limitaciones del mundo real? ¿Hay omisiones o casos extremos que la IA pasó por alto? El proceso incorpora puntos de control explícitos para que puedas analizar lo generado, detectar deficiencias y corregir el rumbo antes de seguir adelante. La IA genera los artefactos; tú te aseguras de que sean correctos.

Cómo usar Spec Kit en sus flujos de trabajo de agencia

Spec Kit funciona con agentes de codificación como GitHub Copilot, Claude Code y Gemini CLI. La clave está en usar una serie de comandos sencillos para dirigir el agente de codificación, que se encarga de generar los artefactos automáticamente.

Configurarlo es sencillo. Primero, instala la specifyherramienta de línea de comandos. Esta herramienta inicializa el proyecto y configura la estructura necesaria.

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Una vez inicializado el proyecto, use el /specifycomando para proporcionar una indicación general y el agente de codificación generará la especificación completa. Concéntrese en el qué y el porqué de su proyecto, no en los detalles técnicos.

A continuación, use el /plancomando para guiar al agente de codificación a crear un plan de implementación técnica. Aquí, usted proporciona la dirección técnica general, y el agente de codificación generará un plan detallado que respeta su arquitectura y sus limitaciones.

Finalmente, use el /taskscomando para que el agente de codificación desglose la especificación y el plan en una lista de tareas ejecutables. Su agente de codificación usará esta lista para implementar los requisitos del proyecto.

Este flujo de trabajo estructurado convierte indicaciones vagas en intenciones claras que los agentes de codificación pueden ejecutar de manera confiable.

Pero ¿por qué este enfoque tiene éxito cuando las indicaciones vagas fracasan?

¿Por qué funciona esto?

Este enfoque funciona donde «simplemente indicarle a la IA» falla debido a una verdad básica sobre el funcionamiento de los modelos de lenguaje: son excepcionales para completar patrones, pero no para leer mentes. Una indicación vaga como «añadir compartir fotos a mi aplicación» obliga al modelo a adivinar miles de requisitos no especificados. La IA hará suposiciones razonables, y algunas serán erróneas (y a menudo no descubrirá cuáles son del todo correctas hasta bien avanzada la implementación).

Por el contrario, proporcionar una especificación clara desde el principio, junto con un plan técnico y tareas específicas, proporciona al agente de codificación mayor claridad, lo que mejora su eficacia general. En lugar de adivinar sus necesidades, sabe qué construir, cómo hacerlo y en qué secuencia.

Por eso, este enfoque funciona con diferentes tecnologías. Ya sea que desarrolles en Python, JavaScript o Go, el desafío fundamental es el mismo: traducir tu intención en código funcional. La especificación captura la intención con claridad, el plan la traduce en decisiones técnicas, las tareas la descomponen en partes implementables y tu agente de codificación de IA se encarga de la codificación.

Para las organizaciones más grandes, esto resuelve otro problema crítico: ¿Dónde se ubican todos los requisitos en torno a políticas de seguridad, normas de cumplimiento, restricciones del sistema de diseño y necesidades de integración? A menudo, estos elementos residen en la mente de alguien, están enterrados en una wiki que nadie lee o están dispersos en conversaciones de Slack que son imposibles de encontrar posteriormente.

Con Spec Kit, todo esto se incluye en la especificación y el plan, donde la IA puede usarlo. Los requisitos de seguridad no son una idea de último momento; están integrados en la especificación desde el primer día. Y el sistema de diseño no es algo que se añada posteriormente. Forma parte del plan técnico que guía la implementación.

La naturaleza iterativa de este enfoque es lo que le confiere su poder. Mientras que el desarrollo tradicional limita las decisiones iniciales, el desarrollo basado en especificaciones simplifica el cambio de rumbo: basta con actualizar la especificación, regenerar el plan y dejar que el programador se encargue del resto.

3 lugares donde este enfoque funciona muy bien

El desarrollo basado en especificaciones es especialmente útil en tres escenarios:

1. Greenfield (de cero a uno) : Al iniciar un nuevo proyecto, es tentador empezar a programar sin más. Sin embargo, un pequeño trabajo inicial para crear una especificación y un plan garantiza que la IA construya lo que realmente se pretende, no solo una solución genérica basada en patrones comunes.
2. Trabajo de funcionalidades en sistemas existentes (N a N+1) : Aquí es donde el desarrollo basado en especificaciones es más eficaz. Añadir funcionalidades a una base de código compleja y existente es difícil. Al crear una especificación para la nueva funcionalidad, se aclara cómo debe interactuar con el sistema existente. El plan codifica las restricciones arquitectónicas, garantizando que el nuevo código se sienta nativo del proyecto en lugar de una adición adicional. Esto agiliza y hace más seguro el desarrollo continuo. Para que esto funcione, podrían requerirse prácticas avanzadas de ingeniería de contexto; las abordaremos por separado.
3. Modernización de sistemas heredados : Al reconstruir un sistema heredado, la intención original suele perderse con el tiempo. Con el proceso de desarrollo basado en especificaciones que ofrece Spec Kit, puede capturar la lógica de negocio esencial en una especificación moderna, diseñar una arquitectura nueva según el plan y luego dejar que la IA reconstruya el sistema desde cero, sin arrastrar la deuda técnica heredada.

La principal ventaja es separar el «qué» estable del «cómo» flexible, lo que permite un desarrollo iterativo sin costosas reescrituras. Esto permite crear múltiples versiones y experimentar rápidamente.

Hacia dónde nos dirigimos

Estamos pasando de la idea de que «el código es la fuente de la verdad» a la de que «la intención es la fuente de la verdad». Con la IA, la especificación se convierte en la fuente de la verdad y determina lo que se construye. 

Esto no se debe a que la documentación haya cobrado mayor importancia, sino a que la IA hace que las especificaciones sean ejecutables. Cuando la especificación se convierte automáticamente en código funcional, determina qué se construye.

Spec Kit es nuestro experimento para hacer realidad esa transición. Lo publicamos porque este enfoque trasciende cualquier herramienta o empresa. La verdadera innovación reside en el proceso. Pronto abordaremos más detalles, en concreto, sobre cómo combinar prácticas de desarrollo basadas en especificaciones con la ingeniería de contexto para desarrollar capacidades más avanzadas en tu conjunto de herramientas de IA.

¡Nos encantaría saber cómo te funciona y qué podemos mejorar! Si estás desarrollando con patrones basados ​​en especificaciones, comparte tu experiencia con nosotros. Nos interesa especialmente:

• Haciendo el flujo de trabajo más atractivo y usable : Leer textos extensos puede ser tedioso. ¿Cómo podemos hacer que este proceso sea realmente agradable?
• Posibles integraciones con VS Code : Estamos explorando maneras de integrar este flujo de trabajo directamente en VS Code. ¿Qué te resultaría más natural?
• Comparar y comparar múltiples implementaciones : Iterar y comparar entre implementaciones abre posibilidades creativas. ¿Qué sería lo más valioso en este caso?
• Gestionar especificaciones y tareas a gran escala en tu organización : Gestionar muchos archivos Markdown puede resultar abrumador. ¿Qué te ayudaría a mantenerte organizado y concentrado?

Nos entusiasma ver cómo aprovechas la IA para descubrir mejores formas de traducir la creatividad humana en software funcional.

Fuente: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/