Skip to content

ADR-0012: characterization-tester skill — Verificación de comportamiento legacy

  • Status: Accepted
  • Date: 2026-03-19
  • Updated: 2026-03-19 — v2.0: adaptadores .NET/VB.NET y JVM/Java/Kotlin
  • Deciders: DeAcero Agentic Team

Context

El pipeline de modernización de sistemas legacy depende de que el bdd-writer genere .feature files precisos a partir del análisis del código fuente SQL. Sin embargo, el código fuente solo revela qué hace el sistema — no cómo se comporta en producción con datos reales, casos borde, ni comportamiento indocumentado acumulado en años de operación.

El problema central: no existen tests en los sistemas legacy de DeAcero. Las features generadas por inferencia de código son hipótesis, no especificaciones verificadas. Usar hipótesis sin verificar como contrato de migración introduce riesgo de paridad incorrecta.

El patrón "Characterization Testing" (Feathers, Working Effectively with Legacy Code) resuelve esto: en ausencia de tests, se captura el comportamiento real del sistema tal como existe hoy — sin juzgarlo — y esa captura se convierte en el test de aceptación.

Para SQL Server, este patrón es altamente viable: los Stored Procedures tienen firmas claras (parámetros de entrada, result sets de salida) y pueden ejecutarse en transacciones que se revierten, evitando efectos secundarios sobre los datos de producción.

Decision

Crear el skill software/quality/characterization-tester con soporte multi-adaptador:

El skill selecciona el adaptador correcto por el tag @adapter: en la feature file, o lo infiere del tipo de artefacto presente (output/decompiled/).

Adaptador SQL Server (v1.0 — original)

  1. Lee .feature files marcadas como # status: hypothesis generadas por bdd-writer
  2. Identifica escenarios testables (SPs con inputs/outputs determinísticos)
  3. Genera scripts SQL usando BEGIN TRAN / EXEC sp / SELECT / ROLLBACK — nunca modifica producción
  4. Ejecuta vía SQUIT MCP o conexión directa
  5. Clasifica en VERIFIED / CONFLICT / UNTESTABLE y actualiza las features

Adaptador .NET / VB.NET (v2.0 — nuevo)

  1. Usa el source decompilado (output/decompiled/dotnet/, generado por ilspycmd) para inferir tipos de parámetros y firmas de métodos
  2. Genera tests xUnit (C#) que corren contra el DLL/EXE original — no contra el source re-compilado
  3. Para métodos que tocan BD: envuelve en TransactionScope con rollback automático
  4. Clasifica igual: VERIFIED / CONFLICT / UNTESTABLE
  5. Produce characterization_tests/dotnet/<ClassName>CharacterizationTests.cs

Adaptador JVM / Java / Kotlin (v2.0 — nuevo)

  1. Usa el source decompilado (output/decompiled/java/, generado por CFR/Procyon) para inferir firmas
  2. Genera tests JUnit 5 que corren contra el JAR original en classpath
  3. Para métodos privados: usa reflection (getDeclaredMethod + setAccessible(true))
  4. Para métodos con BD: usa conexión con autoCommit=false y rollback() al final
  5. Produce characterization_tests/jvm/src/test/java/<ClassName>CharacterizationTest.java

Output compartido (todos los adaptadores)

  • Tres clasificaciones: VERIFIED, CONFLICT, UNTESTABLE
  • Features actualizadas con # status:, # verified_at:, # evidence: / # conflict_detail:
  • characterization_tests/REPORT.md como handoff para cornerstone-builder

Flujo en el pipeline

software-archeologist
        ↓
bdd-writer → features/ (status: hypothesis)
        ↓
characterization-tester
        ├── VERIFIED   → features listas para cornerstone-builder
        ├── CONFLICT   → features que requieren revisión de experto de negocio
        └── UNTESTABLE → features que requieren validación manual

Los CONFLICT son el output más valioso del skill: revelan discrepancias entre el código y el comportamiento real — bugs conocidos, workarounds implícitos, o lógica de negocio que nunca fue documentada.

Consecuencias

Positivo

  • Eleva la confianza de las features de "hipótesis" a "especificación verificada"
  • Los scripts generados funcionan como regression suite del sistema legacy
  • Los CONFLICT explicitan deuda técnica y comportamiento indocumentado
  • Crea trazabilidad directa: feature verificada → test SQL → comportamiento legacy → nueva implementación

Negativo

  • Requiere acceso al sistema legacy durante el proceso de arqueología
  • SPs con side effects no reversibles (envío de emails, llamadas a sistemas externos) no pueden caracterizarse automáticamente → requieren wrapper o revisión manual
  • El output no-determinístico (timestamps, GUIDs, números de secuencia) requiere estrategias de enmascaramiento en las aserciones

Dependencias

  • SQUIT MCP (para ejecutar queries contra SQL Server) o conexión directa configurada
  • bdd-writer skill (produce las features de entrada)
  • graph-service MCP (ADR-0010) — ayuda a identificar SPs con side effects inspeccionando sus edges WRITES hacia tablas de auditoría o sistemas externos
  • decompiler_manager.py — produce el source decompilado que los adaptadores .NET/JVM consumen para inferir firmas; requiere ilspycmd (.NET) y CFR/Procyon (JVM)

Alternativas consideradas

Validación manual por experto de negocio: Viable pero no escalable para 2,537 SPs. El characterization-tester automatiza los casos simples y escala la revisión humana solo a los CONFLICT y UNTESTABLE.

No verificar y confiar en el código: Inaceptable para un sistema de facturación con impacto financiero directo. Los bugs silenciosos en la migración son el riesgo más alto del proyecto.