Saltar a contenido

Workflow: De Spec a Codigo con IA

Proposito

Proceso paso a paso para convertir una spec.md en codigo funcional, testeado, y listo para produccion usando IA como copiloto.

Cuando usarlo

  • Cada vez que empiezas a implementar una feature nueva.
  • Como checklist para asegurar que no te saltas ningun paso.

1. El Pipeline Spec-to-Code

spec.md
  |
  v
[1. Validar Spec] -----> Spec completa y sin ambiguedades
  |
  v
[2. Generar Domain Model] -----> Entidades, VOs, Aggregates
  |
  v
[3. Generar API Contract] -----> Endpoints, requests, responses
  |
  v
[4. Generar BDD Scenarios] -----> Given/When/Then testeables
  |
  v
[5. Implementar Domain Layer] -----> Services, entities, VOs
  |
  v
[6. Implementar Infrastructure] -----> Repos, controllers, DTOs
  |
  v
[7. Implementar Tests] -----> Unit + integration + E2E
  |
  v
[8. Review y Refinamiento] -----> Code review + ajustes
  |
  v
Codigo en produccion

2. Paso a Paso con Ejemplos

Paso 1: Validar la Spec

Input: feature-booking-system.spec.md

Prompt: 

Revisa esta spec de feature. Identifica:
1. Ambiguedades (cosas que pueden interpretarse de 2 formas)
2. Reglas de negocio que faltan
3. Edge cases no cubiertos
4. Inconsistencias entre secciones

[pegar spec]

Output esperado: Lista de issues. Los resuelves antes de seguir.

Criterio para avanzar: La spec no tiene ambiguedades y cubre todos los flujos.

Paso 2: Generar Domain Model

Input: Spec validada + ubiquitous language

Prompt: 

A partir de esta spec, genera el modelo de dominio:
1. Entidades con sus atributos e invariantes
2. Value Objects con reglas de validacion
3. Aggregates con sus limites
4. Domain Events

Usa TypeScript. Sigue los nombres del ubiquitous language:
[pegar ubiquitous language relevante]

Spec:
[pegar secciones 3 y 4 de la spec: reglas de negocio y modelo de datos]

Output esperado: Clases TypeScript de dominio.

Que revisar: - Las invariantes se validan en el constructor o metodos de negocio? - Los value objects son inmutables? - Las transiciones de estado son explicitas?

Paso 3: Generar API Contract

Input: Spec + domain model

Si ya tienes el API contract en 04-api-contracts/, este paso es verificar que el contrato y el domain model estan alineados.

Prompt: 

Verifica que este API contract es consistente con el domain model:

API Contract:
[pegar api-bookings.md]

Domain Model:
[pegar entidades generadas]

Identifica discrepancias entre:
- Nombres de campos (API vs dominio)
- Campos faltantes en la API
- Validaciones del dominio no reflejadas en la API

Paso 4: Generar BDD Scenarios

Input: Spec (seccion criterios de aceptacion) + reglas de negocio

Prompt: 

Convierte estos criterios de aceptacion en escenarios BDD
formato Gherkin (Given/When/Then):

Criterios:
[pegar criterios de aceptacion de la spec]

Reglas de negocio:
[pegar reglas]

Genera al menos:
- 1 scenario por happy path
- 1 scenario por cada flujo de error
- 1 scenario por cada edge case

Output esperado: Archivo estilo bdd-scenarios-booking.md.

Paso 5: Implementar Domain Layer

Input: Domain model + reglas de negocio + un servicio existente como ejemplo

Prompt: 

Implementa el domain service para [nombre de la feature].

Domain model:
[pegar entidades y VOs generados]

Reglas de negocio a implementar:
[listar reglas]

Patron a seguir (ejemplo de servicio existente):
[pegar servicio existente como referencia]

Genera:
1. Domain service con toda la logica de negocio
2. Unit tests que cubran cada regla de negocio
3. Custom exceptions para cada caso de error

Que revisar: - Cada regla de negocio tiene un test? - Los tests fallan si rompes la logica? - No hay dependencias de infraestructura en el domain service?

Paso 6: Implementar Infrastructure Layer

Input: Domain service + API contract + controller existente como ejemplo

Prompt: 

Implementa la capa de infraestructura:

1. Repository (TypeORM) para persistir las entidades:
[pegar entidades]

2. Controller (NestJS) con los endpoints:
[pegar API contract]

3. DTOs (class-validator) para validar requests:
[pegar request schemas del API contract]

Patron a seguir:
[pegar controller existente]

Paso 7: Implementar Tests

Input: BDD scenarios + codigo implementado

Prompt: 

Genera integration tests para estos endpoints basandote en los BDD scenarios:

Scenarios:
[pegar BDD scenarios]

Codigo del controller:
[pegar controller]

Convenciones de testing del proyecto:
- Jest + Supertest
- BD de test que se limpia entre tests
- Helpers: seedDoctor(), loginAsPatient()

Genera tests que cubran cada scenario BDD.

Paso 8: Review y Refinamiento

Prompt de review final: 

Haz un review completo de esta implementacion:

Domain Service:
[pegar]

Controller:
[pegar]

Tests:
[pegar]

Revisa:
1. Todas las reglas de negocio de la spec estan implementadas?
2. Hay bugs sutiles en edge cases?
3. Los tests realmente validan el comportamiento?
4. Hay problemas de seguridad?
5. Hay problemas de performance?

Spec original para referencia:
[pegar spec]

3. Tiempos Estimados por Paso

Paso Sin IA Con IA Nota
1. Validar spec 30 min 10 min La IA encuentra ambiguedades rapido
2. Domain model 2h 30 min Requiere revision humana cuidadosa
3. API contract 1h 15 min Mayormente generado de la spec
4. BDD scenarios 1h 15 min La IA es muy buena en esto
5. Domain layer 4h 1.5h La revision y ajuste toma mas que la generacion
6. Infrastructure 3h 1h Mucho boilerplate que la IA elimina
7. Tests 3h 1h Los BDD scenarios son excelente input
8. Review 1h 30 min Combinacion humano + IA
Total ~15h ~5h ~3x mas rapido

4. Criterios de Calidad del Output

Antes de considerar la feature "lista", verifica:

  • Cada regla de negocio de la spec tiene un test que la valida.
  • Los tests fallan cuando rompes la logica intencionalmente.
  • El codigo sigue las convenciones del proyecto.
  • No hay any en TypeScript.
  • Los errores tienen codigos especificos (no errores genericos).
  • La API responde segun el contrato documentado.
  • No hay datos sensibles expuestos en las respuestas.
  • Un companero puede entender el codigo sin explicacion verbal.

Checklist de Completitud

  • Pipeline completo documentado (8 pasos)
  • Prompts especificos por paso
  • Que revisar en cada paso
  • Tiempos comparativos (con y sin IA)
  • Criterios de calidad
  • Revisada por otro ingeniero

Archivos relacionados