Spec-driven Development
En la era del desarrollo de software asistido por Inteligencia Artificial, la velocidad para escribir código ha dejado de ser el principal cuello de botella. Hoy en día, herramientas como GitHub Copilot, Cursor, Claude Code y Antigravity pueden generar cientos de líneas de código en segundos. Sin embargo, esta velocidad introduce un nuevo riesgo crítico: la codificación descontrolada (vibe coding), donde los modelos de lenguaje alucinan librerías obsoletas, violan la arquitectura por capas y generan deuda técnica masiva.
Para solucionar este desafío surge el Spec-driven Development (SDD) o Desarrollo Basado en Especificaciones: una disciplina que traslada el foco desde "generar código rápido" hacia "definir con precisión arquitectónica qué debe construirse antes de escribir una sola línea de código".
En este capítulo exploraremos la comparativa entre el SDLC tradicional y SDD, cómo las 6 fases de GitHub Spec Kit formalizan este flujo, y cómo aplicar la metodología artesanal y universal mediante un archivo AGENTS.md y la carpeta .agents/ en nuestros proyectos de Spring Boot.
1. SDLC Tradicional vs. Spec-driven Development
En el ciclo de vida de desarrollo de software tradicional (SDLC), la documentación suele concebirse como un subproducto burocrático que se desactualiza tan pronto como el código se modifica. En SDD, la especificación en Markdown es el motor ejecutable que guía estrictamente la generación de código.
Explora la comparativa en paralelo de las 6 fases fundacionales de SDD frente a los riesgos del flujo tradicional:
De la Herramienta CLI al Estándar Universal
GitHub Spec Kit formalizó inicialmente este flujo con una herramienta de terminal (specify-cli), instalable a través de uv:
# 1. Instalar uv (gestor de herramientas en Rust)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 2. Instalar specify-cli
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# 3. Inicializar un repositorio
specify init mi-proyecto-backend
Sin embargo, depender de comandos y ejecutables externos introduce fricciones en equipos heterogéneos y cajas negras. La práctica profesional moderna adopta una abstracción artesanal: estructurar el contexto directamente en carpetas y archivos Markdown versionados en Git.
2. SDD Artesanal: Arquitectura con AGENTS.md y .agents/
La metodología artesanal sitúa el control en un archivo de constitución raíz (AGENTS.md) y un directorio reservado de contexto (.agents/).
Interactúa con el siguiente diagrama para recorrer cómo se organizan las carpetas de memoria, especificaciones, planes técnicos y tareas, y cómo viaja la información hacia el agente de IA:
3. Guía Práctica Paso a Paso: Implementando un Módulo con SDD Artesanal
A continuación construiremos desde cero la especificación formal para un nuevo requerimiento en nuestro backend de Spring Boot: Módulo de Auditoría de Acciones de Usuario (AuditLog).
Crear la Constitución Raíz: AGENTS.md
En la raíz de tu proyecto, crea el archivo AGENTS.md. Este documento es el primer archivo que cualquier agente de IA lee al iniciar una sesión de trabajo.
# Manual de Operación y Constitución del Agente
Eres un Ingeniero de Software Senior especializado en desarrollo backend empresarial con Spring Boot y Java 17.
## Reglas de Oro Inmutables (Non-Negotiable Rules)
1. **Arquitectura en Capas Estricta**: Controller -> Service -> Repository. Está terminantemente prohibido inyectar repositorios directamente en los controladores.
2. **DTOs Obligatorios**: Nunca expongas entidades JPA (@Entity) en los endpoints REST. Toda comunicación usa Records o Clases DTO inmutables con validaciones (jakarta.validation.constraints.*).
3. **Manejo Centralizado de Excepciones**: No captures excepciones con bloques try-catch vacíos. Lanza excepciones de dominio y manéjalas en @RestControllerAdvice.
4. **Regla de Ejecución Atómica**: No implementes funcionalidades completas de una sola vez. Consulta .agents/tasks/ y ejecuta estrictamente una tarea por iteración.
## Directorio de Contexto
* [Memoria Técnica](.agents/memory/tech-stack.md): Versiones oficiales de frameworks y base de datos.
* [Reglas de Arquitectura](.agents/memory/architecture.md): Convenciones de nomenclatura y diseño.
Definir la Memoria Permanente: .agents/memory/
Crea la carpeta .agents/memory/ y registra las restricciones tecnológicas en tech-stack.md para evitar que el agente utilice librerías incompatibles:
# Restricciones Técnicas del Stack
- **Lenguaje**: Java 17 (LTS) - usar Records, Text Blocks y Switch Expressions.
- **Framework**: Spring Boot 3.3.x.
- **Seguridad**: Spring Security 6 con JWT stateless (filtro custom JwtAuthenticationFilter).
- **Base de Datos**: PostgreSQL 16 con Spring Data JPA y Hibernate 6.
- **Validaciones**: Jakarta Validation (@NotNull, @NotBlank, @Positive, @Email).
- **Documentación de API**: Springdoc OpenAPI v2 (Swagger UI en /swagger-ui.html).
Redactar la Especificación Funcional: .agents/specs/
En .agents/specs/feat-audit-spec.md, redacta el qué. Define la necesidad del usuario, las entradas y salidas JSON, y los criterios de aceptación en formato Gherkin:
# Especificación: Registro de Historial de Auditoría (Audit Log)
## 1. Historia de Usuario
**Como** administrador del sistema,
**quiero** que cada acción crítica (login, creación de cursos, cambio de roles) quede registrada en un log de auditoría persistente,
**para** auditar la seguridad de la plataforma y cumplir con normas de trazabilidad.
## 2. Endpoints Requeridos
- `POST /api/v1/audit-logs`: Endpoint interno para registrar eventos de auditoría.
- `GET /api/v1/audit-logs`: Endpoint protegido (ROLE_ADMIN) con paginación (page, size) y orden descendente por fecha.
## 3. Esquema del Payload JSON (Entrada)
```json
{
"action": "COURSE_CREATED",
"userEmail": "profesor@icesi.edu.co",
"details": "Curso ID 101 registrado con 3 créditos",
"ipAddress": "192.168.1.45"
}
4. Criterios de Aceptación (Gherkin)
-
Escenario 1: Registro exitoso de auditoría
- Dado que un usuario autenticado realiza una acción crítica,
- Cuando el servicio emite una petición POST a
/api/v1/audit-logscon campos válidos, - Entonces el sistema responde con HTTP 201 Created y persiste el evento con marca de tiempo UTC.
-
Escenario 2: Validación de campos obligatorios
- Dado un payload con
actionvacío ouserEmailcon formato no válido, - Cuando se envía la petición,
- Entonces el sistema responde con HTTP 400 Bad Request y un listado de errores de validación.
- Dado un payload con
</Step>
<Step number="4" title="Fase Clarify: El Diálogo Crítico con el Agente">
Antes de generar código, proporciona el archivo `.agents/specs/feat-audit-spec.md` al agente y ejecútale la siguiente orden:
```text title="Prompt de Clarificación (Clarify)"
Revisa la especificación .agents/specs/feat-audit-spec.md a la luz de AGENTS.md y .agents/memory/.
Hazme de 3 a 5 preguntas sobre casos borde, índices en base de datos o manejo de errores que no estén explícitamente claros.
No generes código todavía.
- ¿Qué sucede si la base de datos de auditoría falla? ¿Debe abortar la transacción principal (Rollback) o registrarse de forma asíncrona sin bloquear al usuario?
- ¿La búsqueda en
/api/v1/audit-logsrequerirá filtrado por rango de fechas o por email de usuario?
Resolver estas dudas en el documento Markdown antes de programar ahorra horas de refactorización posterior.
Diseñar el Plan Técnico: .agents/plans/
Una vez aclarada la especificación, se redacta el cómo técnico en .agents/plans/feat-audit-plan.md:
# Plan Técnico: Módulo de Auditoría
## 1. Arquitectura de Componentes
1. **Entidad JPA**: `AuditLog.java` con tabla `audit_logs`, clave primaria `UUID`, columnas indexadas `created_at` y `user_email`.
2. **DTOs**: `CreateAuditLogRequest.java` (Record) y `AuditLogResponse.java` (Record).
3. **Repositorio**: `AuditLogRepository.java` extiende `JpaRepository<AuditLog, UUID>`.
4. **Servicio**: `AuditLogService.java` (interfaz) y `AuditLogServiceImpl.java` con método `@Transactional(propagation = Propagation.REQUIRES_NEW)`.
5. **Controlador**: `AuditLogController.java` en `/api/v1/audit-logs` con `@PreAuthorize("hasRole('ADMIN')")` para el listado.
## 2. Riesgos y Decisiones Clave
- **Aislamiento**: Usar `REQUIRES_NEW` para que el log quede guardado incluso si la operación del usuario posterior genera un error.
- **Rendimiento**: Crear índice compuesto B-Tree sobre `(user_email, created_at)` para optimizar consultas de administradores.
Desglose de Tareas Atómicas: .agents/tasks/
El plan se divide en tareas pequeñas, numeradas y con criterio de aceptación claro en .agents/tasks/feat-audit-tasks.md:
# Checklist de Tareas: Módulo de Auditoría
- [ ] **Tarea 1: Modelo de Persistencia**
- Crear entidad `AuditLog.java` con campos UUID, action, userEmail, details, ipAddress, createdAt.
- Crear migración SQL o schema DDL con índice en `created_at`.
- *Criterio de verificación*: Compila y la tabla se crea en PostgreSQL.
- [ ] **Tarea 2: Capa de DTOs y Validación**
- Crear `CreateAuditLogRequest` con anotaciones `@NotBlank` y `@Email`.
- Crear `AuditLogResponse` con campos formateados.
- *Criterio de verificación*: Pruebas unitarias de validación pasan.
- [ ] **Tarea 3: Repositorio y Servicio de Negocio**
- Crear `AuditLogRepository` con paginación `findAllByOrderByCreatedAtDesc`.
- Implementar `AuditLogServiceImpl` con propagación transaccional.
- *Criterio de verificación*: Prueba de integración en memoria guarda el registro.
- [ ] **Tarea 4: Controlador REST y Seguridad**
- Crear `AuditLogController` con endpoints POST y GET paginado.
- Proteger GET con rol ADMIN y documentar con `@Operation` de OpenAPI.
- *Criterio de verificación*: Pruebas en Postman (201 Created y 400 Bad Request).
Ejecución Guiada con el Agente de IA
Con las tareas desglosadas, interactúa con el agente autorizando estrictamente una sola tarea:
Lee AGENTS.md, .agents/plans/feat-audit-plan.md y la Tarea 1 de .agents/tasks/feat-audit-tasks.md.
Implementa ÚNICAMENTE la Tarea 1 (Entidad AuditLog y repositorio).
No toques controladores ni servicios.
Cuando termines, muestra el código creado y detén tu ejecución.
Al terminar el agente, compilas tu backend, verificas que no haya errores, marcas [x] en la Tarea 1 y autorizas la Tarea 2.
4. Buenas Prácticas para el Desarrollo Asistido por Agentes
Para obtener el máximo rendimiento al aplicar SDD con herramientas de IA en tus proyectos de Computación en Internet:
- La Regla de una Sola Tarea (Single-Task Rule): Nunca le pidas a un agente implementar múltiples módulos o capas simultáneas sin validación intermedia.
- La Verdad Vive en Markdown, No en el Chat: Toda decisión que tomes durante una conversación con la IA debe quedar asentada en un archivo de
.agents/specs/o.agents/plans/. Los chats son volátiles; los archivos.mdpersisten en el repositorio y son leídos por cualquier miembro del equipo. - Validación Cruzada con Postman: Cada tarea de controlador implementada mediante SDD debe ser verificada inmediatamente contra la colección de pruebas de Postman configurada en la sección anterior.