Saltar al contenido principal
Arquitectura y Calidad de IA
12 min de lectura

Harness de Calidad para IA Autónoma: Desarrollo Dirigido por Especificaciones (SDD), Invariantes AST y Pruebas Auto-Reparables en Next.js 16

Arquitectura de un entorno de calidad para agentes autónomos de IA: combinación de fases SDD, verificación de invariantes AST con TypeScript Compiler API y ciclos de auto-reparación en Vitest para eliminar alucinaciones y regresiones en Next.js 16.

AY
Artur Yusupov
Arquitecto Fullstack Principal e Ingeniero de Entornos de IA
Harness de Calidad para IA Autónoma: Desarrollo Dirigido por Especificaciones (SDD), Invariantes AST y Pruebas Auto-Reparables en Next.js 16

Harness de Calidad para IA Autónoma: Desarrollo Dirigido por Especificaciones (SDD), Invariantes AST y Pruebas Auto-Reparables en Next.js 16

A medida que los agentes de codificación basados en modelos de lenguaje (LLM) evolucionan desde simples asistentes de autocompletado hacia ingenieros de software autónomos capaces de generar módulos completos en cientos de archivos, los equipos de ingeniería afrontan un desafío crítico: el desvío arquitectónico y el colapso de la verificación.

Sin límites deterministas, los agentes de IA introducen fallos sutiles:

  • Debilitan la tipificación estricta de TypeScript introduciendo tipos any o aserciones inseguras.
  • Violan las fronteras de los módulos importando utilidades internas en lugar de usar fachadas públicas.
  • Generan pruebas frágiles que validan tautologías en lugar de reglas de negocio reales.
  • Pierden el contexto durante sesiones extensas, reintroduciendo regresiones ya resueltas.

En este artículo analizamos la arquitectura de un Harness de Calidad para IA Autónoma diseñado para Next.js 16. Mediante la integración de Desarrollo Dirigido por Especificaciones (SDD), verificación de invariantes en árboles sintácticos abstractos (AST) con la API del compilador de TypeScript y bucles de auto-reparación en Vitest, este sistema asegura rigor matemático y cero deuda técnica.

Matriz de decisión rápida de arquitectura: Metodologías de calidad para agentes de IA

Modelo de calidad de ingeniería
Prompting libre (Sin restricciones)
Riesgo de desvío arquitectónico
Crítico (Viola límites de módulos y tipos)
Verificación de invariantes de tipado
Cero (Introduce tipos any y tests vacíos)
Capacidad de auto-reparación
Nula (Alucina sintaxis defectuosa)
Madurez para producción
Inaceptable para empresas
Modelo de calidad de ingeniería
CI tradicional (Solo Lint/Prettier)
Riesgo de desvío arquitectónico
Moderado (Detecta sintaxis, no arquitectura)
Verificación de invariantes de tipado
Bajo (Errores detectados tras el commit)
Capacidad de auto-reparación
Manual (Exige revisión de código humana)
Madurez para producción
Frágil para flujos multifichero
Modelo de calidad de ingeniería
Harness SDD Autónomo (Recomendado)
Riesgo de desvío arquitectónico
Cero (AST gatekeeper + máquina de estados)
Verificación de invariantes de tipado
100% Estricto (AST rechaza violaciones)
Capacidad de auto-reparación
Autónoma (Bucles Vitest auto-reparables)
Madurez para producción
Nivel Enterprise (Determinista)

1. Esquema Arquitectónico del Ciclo Cerrado de Calidad

El harness de calidad rodea al agente de IA con barreras de verificación innegociables. El agente no edita archivos de producción de manera directa; sus herramientas de escritura están gestionadas por una máquina de estados que impone una progresión estricta: especificación, planificación, validación estática y pruebas.

CODE
+-----------------------------------------------------------------------------------+
|                        Trayectoria del Agente Autónomo de IA                      |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| Fase 1: Barrera Formal de Especificaciones (SDD)                                  |
| - Verificación de spec.md (Requisitos, historias de usuario, criterios de éxito)   |
| - Verificación de plan.md (Límites arquitectónicos, esquemas y pasos de prueba)    |
| - Verificación de tasks.md (Grafo de tareas atómicas para control automático)     |
+-----------------------------------------------------------------------------------+
                                          | Supera la barrera
                                          v
+-----------------------------------------------------------------------------------+
| Fase 2: Entorno Aislado de Modificación                                           |
| - Cambios permitidos únicamente en ramas de características designadas            |
| - Prohibición estricta de secretos, fugas de datos y tipos any                    |
+-----------------------------------------------------------------------------------+
                                          | Intento de escritura en archivo
                                          v
+-----------------------------------------------------------------------------------+
| Fase 3: Motor de Invariantes AST (TypeScript Compiler API)                        |
| - Análisis de nodos AST frente a las reglas del repositorio                       |
| - Rechazo de tokens prohibidos (AnyKeyword, signos de puntuación no admitidos)    |
| - Control de fronteras de importación (capa de cliente no puede importar la BD)   |
+-----------------------------------------------------------------------------------+
                                          | AST validado con éxito
                                          v
+-----------------------------------------------------------------------------------+
| Fase 4: Bucle de Pruebas Auto-Reparables (Vitest + Red-Green-Refactor)            |
| - Ejecución de pruebas unitarias y de regresión                                   |
| - Intercepción de fallos -> Extracción de trazas de error -> Corrección autónoma  |
| - Límite estricto de bucle (máximo 3 iteraciones) para evitar consumo excesivo    |
+-----------------------------------------------------------------------------------+
                                          | Todas las pruebas aprobadas
                                          v
+-----------------------------------------------------------------------------------+
| Fase 5: Verificación de Producción e Integración Fast-Forward                     |
| - Comprobación de tipos (tsc --noEmit) + ESLint + Compilación SSG (next build)    |
| - Fusión fast-forward en la rama master con firma digital                         |
+-----------------------------------------------------------------------------------+

2. Máquina de Estados de Desarrollo Dirigido por Especificaciones (SDD)

El enfoque de Desarrollo Dirigido por Especificaciones transforma las intenciones humanas y las reglas de diseño en una máquina de estados determinista. En el desarrollo convencional, los agentes reciben instrucciones ambiguas y comienzan de inmediato a editar archivos fuente, generando caos en el repositorio.

Con SDD, el sistema exige la presencia obligatoria de tres documentos antes de permitir cualquier modificación en el código:

1
`spec.md`: Requisitos funcionales, flujos de usuario y estándares de accesibilidad (WCAG 2.2 AA / EAA 2026).
2
`plan.md`: Restricciones técnicas, límites arquitectónicos y presupuestos de rendimiento.
3
`tasks.md`: Lista de tareas atómicas estructurada como un grafo acíclico dirigido (DAG).

Antes de ejecutar escrituras en disco, el agente valida el cumplimiento de las fases:

TYPESCRIPT
// scripts/sdd-spec-gate.ts
import * as fs from 'node:fs'
import * as path from 'node:path'

export interface SddPhaseStatus {
  hasSpec: boolean
  hasPlan: boolean
  hasTasks: boolean
  isGated: boolean
  errors: string[]
}

export function validateSddGating(featureSlug: string): SddPhaseStatus {
  const specDir = path.resolve(process.cwd(), 'specs', featureSlug)
  const errors: string[] = []

  if (!fs.existsSync(specDir)) {
    return {
      hasSpec: false,
      hasPlan: false,
      hasTasks: false,
      isGated: false,
      errors: [`Spec directory does not exist: ${specDir}`],
    }
  }

  const specPath = path.join(specDir, 'spec.md')
  const planPath = path.join(specDir, 'plan.md')
  const tasksPath = path.join(specDir, 'tasks.md')

  const hasSpec = fs.existsSync(specPath)
  const hasPlan = fs.existsSync(planPath)
  const hasTasks = fs.existsSync(tasksPath)

  if (!hasSpec) errors.push('Missing required spec.md artifact')
  if (!hasPlan) errors.push('Missing required plan.md architectural blueprint')
  if (!hasTasks) errors.push('Missing required tasks.md execution checklist')

  return {
    hasSpec,
    hasPlan,
    hasTasks,
    isGated: errors.length === 0,
    errors,
  }
}

3. Control de Invariantes de Código mediante TypeScript Compiler API

Las reglas tradicionales de ESLint a menudo son anuladas por agentes de IA mediante comentarios // eslint-disable-next-line. Para asegurar la integridad estructural, nuestro sistema incorpora un AST Invariant Guard que utiliza directamente la API oficial del compilador de TypeScript.

El analizador recorre el árbol sintáctico de cada archivo modificado para detectar infracciones:

TYPESCRIPT
// scripts/ast-invariant-guard.ts
import ts from 'typescript'
import * as fs from 'node:fs'

export interface AstViolation {
  filePath: string
  line: number
  character: number
  rule: string
  message: string
}

export function auditSourceFile(filePath: string): AstViolation[] {
  const fileContent = fs.readFileSync(filePath, 'utf8')
  const sourceFile = ts.createSourceFile(
    filePath,
    fileContent,
    ts.ScriptTarget.Latest,
    true
  )

  const violations: AstViolation[] = []

  function visit(node: ts.Node) {
    // Invariante 1: Cero tipos any (Strict Zero-Any)
    if (node.kind === ts.SyntaxKind.AnyKeyword) {
      const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
      violations.push({
        filePath,
        line: line + 1,
        character: character + 1,
        rule: 'STRICT_ZERO_ANY',
        message: 'Explicit "any" type detected. AI agents must use strict generic types or "unknown".',
      })
    }

    // Invariante 2: Cortafuegos de fronteras de importación
    if (ts.isImportDeclaration(node)) {
      const moduleSpecifier = node.moduleSpecifier.getText(sourceFile).replace(/['"]/g, '')
      if (filePath.includes('/components/') && moduleSpecifier.includes('/server/db')) {
        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
        violations.push({
          filePath,
          line: line + 1,
          character: character + 1,
          rule: 'BOUNDARY_VIOLATION',
          message: `Client component cannot import database modules directly: "${moduleSpecifier}"`,
        })
      }
    }

    // Invariante 3: Prohibición de la raya em dash (uso exclusivo de guion estándar)
    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
      if (node.text.includes('\u2014')) {
        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
        violations.push({
          filePath,
          line: line + 1,
          character: character + 1,
          rule: 'FORBIDDEN_EM_DASH',
          message: 'Em dash (\u2014) is forbidden across the codebase. Use standard hyphen (-).',
        })
      }
    }

    ts.forEachChild(node, visit)
  }

  visit(sourceFile)
  return violations
}

4. Pruebas Auto-Reparables con Intercepción de Fallos en Vitest

Cuando el código generado por un agente falla en una aserción, el desarrollador suele verse obligado a revisar el registro y redactar un nuevo prompt. En un flujo autónomo, esta intervención manual representa un cuello de botella sustancial.

El módulo SelfHealingReporter intercepta los fallos de prueba en Vitest, genera un diagnóstico estructurado y activa de forma automática el ciclo de remediación:

TYPESCRIPT
// test-harness/vitest-self-healing-reporter.ts
import type { Reporter, TestCase, TestResult } from 'vitest/node'
import * as fs from 'node:fs'
import * as path from 'node:path'

export class SelfHealingReporter implements Reporter {
  private failedTests: Array<{
    name: string
    file: string
    errorMessage: string
    stack?: string
  }> = []

  onTestFinished(testCase: TestCase, result: TestResult) {
    if (result.state === 'fail') {
      const firstError = result.errors?.[0]
      this.failedTests.push({
        name: testCase.name,
        file: testCase.file?.name || 'unknown',
        errorMessage: firstError?.message || 'Assertion failed',
        stack: firstError?.stack,
      })
    }
  }

  async onFinished() {
    if (this.failedTests.length === 0) return

    const payload = {
      timestamp: new Date().toISOString(),
      failureCount: this.failedTests.length,
      failures: this.failedTests,
      instruction:
        'Self-Healing Trigger: Review the failing assertions above. Generate an atomic, minimal diff fixing the implementation without modifying test assertions.',
    }

    const reportPath = path.resolve(process.cwd(), '.system_generated', 'healing-task.json')
    fs.mkdirSync(path.dirname(reportPath), { recursive: true })
    fs.writeFileSync(reportPath, JSON.stringify(payload, null, 2), 'utf8')
  }
}

5. Validación Determinista de Invariantes y Registros Dorados

Para asegurar la estabilidad en monorrepositorios de gran envergadura, el sistema valida propiedades matemáticas clave:

1
Monotonía: Incrementar elementos en el carrito no puede reducir el importe total ni el peso acumulado.
2
Paridad de claves: Añadir una clave en en requiere de forma obligatoria su presencia idéntica en ua y es.
3
Idempotencia: Ejecutar el formateo de código de manera consecutiva produce un diff de cero bytes.

6. Métricas de Producción e Impacto en Ingeniería

La implementación de este entorno de calidad en plataformas de producción con Next.js 16 y más de 70 módulos complejos generó mejoras cuantificables:

Métrica de Calidad
Aprobación de PR en primer intento
Agente de IA sin Restricciones
38.4%
Entorno Autónomo SDD y AST
94.6%
Diferencia en Producción
+56.2% de mejora
Métrica de Calidad
Aparición de tipos `any` no detectados
Agente de IA sin Restricciones
14 casos / 100 commits
Entorno Autónomo SDD y AST
0 casos (Rechazados por AST)
Diferencia en Producción
100% eliminación
Métrica de Calidad
Violación de fronteras arquitectónicas
Agente de IA sin Restricciones
9 casos / mes
Entorno Autónomo SDD y AST
0 casos (Cortafuegos de importación)
Diferencia en Producción
100% eliminación
Métrica de Calidad
Tiempo medio de corrección de pruebas
Agente de IA sin Restricciones
18.5 minutos (manual)
Entorno Autónomo SDD y AST
1.7 minutos (Auto-reparación)
Diferencia en Producción
10.8 veces más rápido
Métrica de Calidad
Reversiones de despliegues por regresión
Agente de IA sin Restricciones
4.2% de lanzamientos
Entorno Autónomo SDD y AST
0.0% (Cero regresiones)
Diferencia en Producción
Cero incidentes en prod

Conclusión Arquitectónica

Los agentes autónomos de IA aceleran la velocidad de desarrollo, pero la generación sin restricciones degrada la base de código. Al implementar Desarrollo Dirigido por Especificaciones (SDD), verificación de invariantes AST con TypeScript Compiler API y pruebas auto-reparables en Vitest, los equipos de ingeniería pueden delegar tareas complejas con absoluta seguridad, rigor tipográfico y cero deuda técnica.

Implementación real en producción

Dónde funciona esta arquitectura en proyectos reales

Estas soluciones no son teoría abstracta: están desplegadas y verificadas en los siguientes productos reales:

Auditoría de Arquitectura

¿Planeas una migración técnica o nuevo proyecto?

Consulta los requerimientos de tu proyecto con el asistente de IA o solicita una evaluación técnica directa.

Contactar directamente