Modelo Operativo

Ingeniería AI-First

Playbook completo para NovaTech Labs — reorganización de procesos, arquitectura y revisión de código para equipos donde la IA genera el 60–70 % del código.

Cliente: NovaTech Labs SL
Equipo: 7 ingenieros + 2 nuevos (julio)
Stack: TypeScript · Python · K8s · Postgres
Tech Lead: Ana García
!

Diagnóstico Actual

Síntomas detectados tras 3 meses con IA como herramienta principal

Adopción de IA sin modelo operativo → regresión de calidad

La velocidad de generación de código superó la capacidad del proceso de revisión, diseñado para código escrito manualmente.

+40%
Volumen de PRs
+25%
Defectos en producción
0
Evals sistemáticos
1

Cambios de Proceso

De la velocidad de tecleo a la calidad de planificación y las evals

📐

Planificación como palanca principal

  • Design doc obligatorio para cualquier cambio > 1 día
  • Criterios de aceptación medibles antes de abrir el editor
  • Revisión de diseño en refinement, no en code review
  • Prompts de generación versionados en /ai-prompts
📊

Eval coverage sobre confianza anecdótica

  • Cada feature: eval automatizada antes de merge
  • Golden dataset mantenido en /evals por dominio
  • Regresión de eval en CI (bloquea si baja > 2 %)
  • Demo manual solo para UX, no para corrección
🔍

Reviews: comportamiento, no estilo

  • ESLint/Prettier resuelven estilo: cero comentarios de formato
  • Foco: regresiones, seguridad, integridad de datos
  • PR template con checklist de comportamiento
  • Time-box: 30 min por PR (< 400 LOC)
Dimensión Proceso Anterior Proceso AI-First Impacto Esperado
Sprint planning ✗ Tareas sin criterios medibles ✓ Definition of Done con evals adjuntas −30 % ciclos de rework
Code review ✗ Naming, indentación, estilo manual ✓ Comportamiento, seguridad, datos −40 % tiempo en review trivial
Validación ✗ Demo manual del autor ✓ Eval suite automatizada en CI −25 % defectos producción
Prompts IA ✗ Ad-hoc, no documentados ✓ Versionados, revisados, reutilizables +50 % consistencia output
Onboarding ~ Documentación implícita ✓ Guía de contratos + prompts + evals −50 % tiempo hasta 1ª PR
2

Requisitos de Arquitectura

Límites explícitos y contratos estables para que los agentes trabajen correctamente

API Gateway
REST/GraphQL OpenAPI 3.1
Auth Middleware JWT types
Rate limiter interface
↓ typed contracts ↓
Dominio
PredictionService typed
RecommendationEngine typed
CustomerSegmenter typed
CatalogSync typed
↓ explicit interfaces ↓
Infra / Data
Postgres zod schema
Redis Cache typed keys
ML Models versioned API
Event Bus schema registry
Principios de arquitectura agent-friendly: Cada módulo expone un contrato tipado (TypeScript interfaces + Zod en runtime). Cero "magia implícita": los agentes de IA fallan en convenciones ocultas; los contratos explícitos les permiten razonar correctamente sobre el sistema. Los módulos de dominio son independientes entre sí: la IA puede modificar uno sin romper los demás.
🔒

Límites explícitos

  • Cada servicio: un directorio, una interfaz pública
  • Imports cruzados prohibidos entre dominios (ESLint rule)
  • Arquitectura documentada en /docs/arch.md (ADRs)
📝

Contratos tipados

  • TypeScript strict mode + noUncheckedIndexedAccess
  • Zod schemas para validación en runtime
  • OpenAPI autogenerado desde tipos (ts-to-openapi)
⚙️

Tests deterministas

  • Sin efectos secundarios en tests unitarios
  • Mocks explícitos con contratos tipados
  • Snapshots de comportamiento, no de implementación
3

Estándar de Code Review

El reviewer revisa comportamiento del sistema, no estilo ni sintaxis

Regresiones
Comportamiento previo preservado Evals de regresión pasan en CI Casos edge documentados
P0 blocker
Seguridad
Input sanitizado en boundary Sin secrets en código Autenticación correcta Rate limiting aplicado
P0 blocker
Integridad datos
Transacciones correctas Idempotencia en writes Migraciones reversibles
P0 blocker
Gestión errores
Errores tipados y propagados Logging adecuado Degradación graciosa
P1 importante
Rollout safety
Feature flags en cambios disruptivos Rollback documentado Métricas de health definidas
P1 importante
Estilo/formato
Delegado 100 % a ESLint + Prettier + CI NO comentar en PR review
Automático
4

Señales de Contratación AI-First

Perfil para los 2 ingenieros nuevos de julio

Señales fuertes Buscar

  • Descompone trabajo ambiguo en tareas concretas y medibles
  • Define criterios de aceptación antes de escribir código
  • Diseña evals y casos de prueba para validar la IA
  • Mantiene controles de riesgo bajo presión de entrega
  • Escribe prompts precisos con contexto y constraints explícitos
  • Revisa código generado buscando comportamiento, no forma

Señales débiles Cuidado

  • Valida código IA solo con "lo probé en local"
  • Considera el estilo de código como la dimensión principal de calidad
  • No puede explicar qué hace el código que generó la IA
  • Confía en la confianza del agente como indicador de corrección
  • No tiene intuición para detectar alucinaciones en contratos de API
  • Omite tests en cambios "pequeños" generados por IA
💬

Pregunta de entrevista recomendada

"Describe un caso donde la IA generó código incorrecto que pasó revisión. ¿Cómo lo detectaste? ¿Qué cambiarías en el proceso?"

Respuesta ideal: menciona evals, contratos, tests de comportamiento o revisión de boundary conditions. No menciona "mirarlo más detenidamente".

📋

Ejercicio práctico de selección

Entregar un módulo de 150 LOC generado con IA + spec de comportamiento. Pedir al candidato:

  • Identificar riesgos sin ejecutar el código
  • Escribir 3 evals críticas para el módulo
  • Proponer refactoring para hacerlo "agent-friendly"
5

Estándar de Testing Elevado

El código generado por IA requiere un listón más alto, no más bajo

Cobertura mínima requerida para código tocado por IA (NovaTech objetivo final)
Línea base actual: ~42 %. Target en 90 días: 75 %.
Tests unitarios — contratos y casos edge
80%
Unitarios Cada función pública, todos los casos edge, mocks tipados
Tests de integración — boundaries
60%
Integración Interfaces entre módulos, DB transactions, event bus
Evals de comportamiento IA
100%
Evals IA Obligatorias en cada dominio que usa outputs de modelo ML
E2E críticos
15%
E2E Solo happy paths de los 5 journeys críticos de negocio
Regresión obligatoria Cualquier PR que toque un dominio debe incluir test de regresión para el comportamiento previo documentado.
Casos edge explícitos Input vacío, límites numéricos, estados de error, concurrencia. La IA tiende a omitir estos casos.
CI gate automático Coverage bajo 75 % bloquea merge. Eval regression > 2 % bloquea merge. Sin excepciones.
→

Plan de Implementación — 90 días

NovaTech Labs: de adopción reactiva a modelo operativo AI-First maduro

Semanas 1–2 Fundamentos
PR template con checklist
ESLint rules de boundaries
TypeScript strict en todos los módulos
Carpeta /ai-prompts en repo
Carpeta /evals con golden datasets iniciales
Semanas 3–5 Proceso
Sprint planning con Definition of Done +evals
Eval gate en CI (coverage + regresión)
Onboarding kit para nuevos ingenieros
ADRs de arquitectura documentados
Primera sesión de calibración de reviews
Semanas 6–10 Escala
Cobertura 75 % en dominios críticos
Onboarding dos nuevos ingenieros
Refactoring módulos con "magia implícita"
Schema registry para Event Bus
Zod schemas en todas las boundaries
Semanas 11–13 Medición
Retroespectiva AI-First: métricas baseline vs t+90
Dashboard de calidad: defectos, eval coverage, review time
Ajuste de estándares según datos reales
Publicar playbook interno v1.0
🎯

KPIs objetivo (90 días)

  • Defectos en producción: −25 % vs baseline
  • Cobertura de tests: 42 % → 75 %
  • Tiempo medio de review: < 30 min/PR
⚡

Quick wins (semana 1)

  • Activar PR template: costo cero, impacto inmediato
  • Bloquear comentarios de estilo en reviews
  • Primera eval de regresión en dominio Prediction
⚠️

Riesgos a mitigar

  • Resistencia al cambio: el equipo acostumbrado al review de estilo
  • Deuda técnica del monolito 80k LOC vs arquitectura explícita
  • Onboarding de 2 nuevos en plena transición
NovaTech Labs SL — Modelo Operativo AI-First v1.0  ·  Generado por CULTIVA IA  ·  Skill: ingenieria-ai-first  ·  2026
⬡ CULTIVA IA