SereneCode: verifica tu código Python con IA
REQ-001: La función calcular_total() nunca debe devolver un número negativo.
Precondition: lista de precios > 0
Postcondition: resultado >= 0
Invariant: suma(precios) >= 0 El agente IA las lee, genera una implementación, y SereneCode verifica que REQ-001 se cumple automáticamente. Si alguien más tarde refactoriza calcular_total() y quebranta la invariante, fallaría el test.
Esto importa para cumplimiento regulatorio. Si sos una fintech en Argentina y una auditoría fiscal te pide “demuestran que cada requisito de cálculo está testeado”, la traceabilidad te cubre el culo. Tenés documentación ejecutable.
Herramientas integradas: mypy, Hypothesis y Z3
SereneCode no inventa la rueda. Se apoya en herramientas que ya existen y funcionan bien, cada una especializada en un aspecto:
mypy — Type checking estático
mypy es el verificador de tipos de Python. Corre sin ejecutar el código. Detecta errores de tipos que normalmente no ves hasta runtime. Por ejemplo, si pasás un string donde la función espera un int, mypy te lo dice antes de que el código corra.
Hypothesis — Property-based testing
Hypothesis es una biblioteca que genera automáticamente datos de prueba aleatorios para encontrar edge cases. Vos definis una propiedad (“el largo de la lista nunca cambia”) y Hypothesis intenta quebrantarla con cientos de inputs diferentes. Es como un fuzzer, pero inteligente.
Z3 / CrossHair — Ejecución simbólica
Z3 es un SMT solver de Microsoft. CrossHair es una interfaz Python que lo usa. Juntas, pueden probar que para todas las entradas posibles, una postcondición se cumple. No es probabilístico como Hypothesis. Si Z3 dice “probado”, es probado. Más contexto en herramientas modernas para desarrollo IA.
Lo poderoso: cuando las tres herramientas trabajan juntas, se complementan. Mypy atrapa tipos malos. Hypothesis encuentra edge cases prácticos. Z3 prueba garantías matemáticas. Un atacante tendría que quebrantar código que pasó las tres verificaciones.
Cuándo necesitás SereneCode — Casos de uso prácticos
No todo código necesita verificación formal. Eso sería lento y overkill. Pero hay escenarios donde es obligatorio:
Fintech y sistemas de pagos
Si el código procesa dinero, un bug es dinero perdido o robado. Reguladores (Banco Central, Comisión Nacional de Valores) exigen trazabilidad. Una función de cálculo de intereses, comisiones, o reconciliación de cuentas debe ser verificable formalmente.
Healthcare y sistemas críticos
Código que dosifica medicinas o controla tratamientos. Un error en la lógica de cálculo de dosis mata gente. Los reguladores (FDA en USA, ANMAT en Argentina) esperan prueba documentada de correctitud.
Infraestructura y automático
Código en vehículos autónomos, drones, sistemas industriales. Si el código falla, personas se lastiman o equipo caro se rompe. Acá no hay “rollback” fácil.
Datos sensibles y cumplimiento
Si procesás datos personales (GDPR, CCPA, leyes de protección de datos argentinas), código que maneja encriptación, anonimización, o purga de datos necesita ser verificable. Una fuga de datos por un bug es costosa legalmente.
Código que vive años sin cambios
Un cálculo que escribiste hace tres años, nadie toca, pero es crítico. Refactorizar sin guarantías es peligroso. Con SereneCode, cambios futuros se verifican automáticamente contra invariantes que definiste.
Cómo empezar — Setup y convenciones del proyecto
El workflow es simple, pero requiere disciplina:
1. Instalar y crear SERENECODE.md
Cloná el repositorio de SereneCode, instalá la librería Python, y creá un archivo SERENECODE.md en tu proyecto con convenciones: patrones de nombres para requisitos, ejemplos de precondiciones, postcondiciones, invariantes que usás.
2. El AI agent lee las convenciones
Cuando generas código con Claude, ChatGPT o el modelo que uses, le pasás como contexto el SERENECODE.md. El agente entiende tus estándares y genera implementaciones que ya incluyen contratos (tipos, precondiciones, postcondiciones). Te puede servir nuestra cobertura de plataformas de control de versiones.
3. Escribir contratos explícitamente
No basta con código. Necesitás especificar qué la función promete. Ejemplo:
def transferir_fondos(cuenta_origen: str, cuenta_destino: str, monto: float) -> bool:
"""
REQ-042: Transferencia válida de fondos.
Precondition: monto > 0, cuenta_origen existe, saldo >= monto
Postcondition: saldo_origen disminuyó en monto, saldo_destino aumentó en monto
Invariant: suma(saldos_globales) antes == suma(saldos_globales) después
""" Escribirlo así no cuesta nada extra, y ahora SereneCode puede verificarlo.
4. Correr el verificador en CI/CD
Antes de mergear, tu CI corre SereneCode en el nivel que corresponda (L2, L4, o L6). Si falla, PR no mergea.
Errores comunes
Creer que SereneCode reemplaza testing manual
No. Verifica que la lógica es correcta, pero no testea usabilidad, performance, o integración entre sistemas. Seguís necesitando QA, testing de integración, smoke tests. SereneCode es una capa adicional de certeza sobre correctitud lógica.
Escribir contratos que son imposibles de cumplir
Si decís “una función debe siempre devolver un valor positivo” pero la entrada es “dinero adeudado que puede ser negativo”, ya fallaste. Los contratos deben ser realistas. Si Z3 dice “contraejemplo: entrada -10”, quizás tu postcondición estaba mal definida.
Correr L6 (ejecución simbólica) en cada commit
Z3 es lento. Una función complicada puede tomar horas. Usá L6 solo en pre-release o ramas críticas. Para CI/CD cotidiano, L4 es generalmente suficiente.
Preguntas Frecuentes
¿Qué diferencia hay entre SereneCode y simplemente escribir tests?
Tests verifican casos específicos que vos escribís. Si no pensaste en un edge case, no lo testeas. SereneCode usa matemática (Z3) para probar que todos los casos posibles cumplen una propiedad. No necesitás adivinar qué testear. El solver busca contraejemplos automáticamente.
¿Puedo usarlo si genero código con GPT/Claude?
Exactamente para eso fue diseñado. Los LLMs generan código rápido pero sin garantías. Pasas SereneCode encima y obtenés garantías. Incluí el SERENECODE.md como contexto cuando pidas al modelo que genere código, y le dará más estructura. Luego SereneCode verifica que respetó la estructura.
¿Cuánto tiempo agrega a mi pipeline?
Depende del nivel. L2 (type checking): segundos. L4 (property-based): minutos. L6 (simbólico): puede ser horas para funciones complejas. En un pipeline CI/CD típico, L4 en cada commit (toma 2-5 min) es razonable. L6 solo antes de release o en ramas críticas.
¿Qué pasa si la verificación formal falla?
Z3 te dice exactamente por qué: te devuelve una entrada (contraejemplo) que quebranta la postcondición. Revisás el código, arreglás el bug o ajustás el contrato si el contrato estaba mal definido. Iterás hasta que pase.
¿Necesito ser experto en verificación formal para usarlo?
No. La interfaz Python es estándar. Escribís tipos de dato claros, pre/postcondiciones como comentarios o docstrings, y SereneCode hace el resto. El paper técnico (en arXiv) es denso, pero no necesitás leerlo para usarlo.
Conclusión
SereneCode resuelve un problema real: los modelos de lenguaje generan código rápido pero sin garantías de correctitud. Para código que simplemente itera sobre una lista o renderiza un componente, testing tradicional es suficiente. Pero si el código procesa dinero, medicinas, o infraestructura crítica, necesitás algo más que fe.
La verificación formal no es nueva (viene de los 70s), pero hasta ahora era cara, lenta, y requería expertos. SereneCode democratiza el acceso combinando herramientas existentes (mypy, Hypothesis, Z3) en un workflow Python que cualquier desarrollador puede usar. Si generás código con IA para sistemas críticos, vale la pena experimentar con él.
Lo que cambió: antes, debías elegir entre velocidad (IA genera rápido, confías a ciegas) o seguridad (manual, lento). Ahora podés tener ambas. Generates code con IA, verificás formalmente, y shippeás con confianza.
Fuentes
- SereneCode – Repositorio oficial en GitHub
- Paper técnico en arXiv sobre verificación formal de código generado por IA
- Martin Kleppmann – AI y verificación formal (análisis de experto)
- Medium – Cómo verificar código generado por IA automáticamente
- Logical Intelligence – Coding AI y garantías formales
SereneCode es un framework de verificación formal que valida código Python generado por inteligencia artificial comparando la implementación contra especificaciones ejecutables. Combinando type checking estático, property-based testing y ejecución simbólica, detecta que el código no solo funciona en casos comunes sino que maneja correctamente bordes, precondiciones y postcondiciones definidas por el desarrollador. Particularmente útil para código crítico (fintech, healthcare, sistemas embebidos) donde un error podría costar dinero, privacidad o seguridad.
En 30 segundos
- SereneCode valida código Python generado por IA usando verificación formal (no solo tests convencionales)
- Mapea requisitos a implementación y tests: cada REQ-xxx debe estar implementado y probado
- Ofrece 6 niveles de verificación: desde análisis estructural (AST) hasta ejecución simbólica (Z3)
- Integra mypy (type checking), Hypothesis (property-based testing) y CrossHair (SMT solver)
- Necesario cuando el código será usado años, procesa dinero/datos sensibles, o debe cumplir normativas
¿Qué es SereneCode? — Framework de verificación formal para código Python
Imaginate que le pedís a Claude o ChatGPT que escriba una función para procesar pagos. El modelo te devuelve código que se ve bien, funciona en tus tests locales, y lo shippeás a producción. Tres meses después, un cliente reporta que una transacción de USD 0.01 se procesó como USD 100 por un bug en el manejo de decimales. Eso no debería haber pasado — el code review lo hubiera atrapado, pero nadie checkea cada edge case.
Eso es lo que SereneCode resuelve. No reemplaza testing tradicional. Lo complementa. Dándole al framework una especificación formal (requisitos, pre/postcondiciones, invariantes), SereneCode prueba automáticamente que la implementación las cumple en todos los casos posibles, no solo en los que vos escribiste en los tests.
Viene como una suite Python importable (disponible en GitHub) que integrás en tu flujo CI/CD. El equipo de desarrollo define convenciones en un archivo SERENECODE.md, el agente IA las lee, y los tests de verificación validán qué escribió el modelo.
El problema: velocidad vs correctitud en código generado por IA
Los modelos de lenguaje son rápidos. Escriben código en segundos que a un humano le tomaría horas. Pero “escrito rápido” ≠ “escrito bien”. Ojo con esto:
- Omisión de casos edge: Un LLM genera validación para un email pero nunca consideró el caso donde el string tiene 1000 caracteres. El test de “happy path” pasa. Producción falla.
- Manejo de errores incompleto: La función asume que una API siempre responde. ¿Qué pasa si timeout? El modelo no lo cubrió.
- Especificaciones no ejecutables: Un desarrollador le dice al modelo “asegúrate de que el costo nunca sea negativo”. El modelo lo ignora o lo implementa mal porque no es un test explícito.
- Deuda técnica acumulada: Funciona hoy, pero en seis meses alguien refactoriza una función helper y rompe una invariante silenciosa que el código dependía.
En aplicaciones donde safety importa — una red de pagos, un sistema de medicinas, código en un vehículo autónomo, infraestructura crítica — estos problemas no son “aceptables riesgos”. Son bloqueadores legales o de seguridad.
Ahí entra la verificación formal. No es testing. Es una prueba matemática de que la implementación cumple su especificación.
Cómo funciona SereneCode — Los 6 niveles de verificación
SereneCode no te obliga a una única forma de verificar. Ofrece un pipeline gradual. Cada nivel agrega rigor, pero también tiempo de ejecución. Elegís cuál necesitás.
Nivel 1: Análisis sintáctico (AST)
¿El código es Python válido? ¿Importan correctamente los módulos? Sí, un LLM a veces genera imports que no existen. Este nivel los ataja. En ejecutar agentes de IA sin API profundizamos sobre esto.
Nivel 2: Type checking estático (mypy)
¿Los tipos encajan? Si la función dice que retorna int, ¿todos los return paths devuelven un int? Mypy corre automáticamente contra la implementación.
Nivel 3: Cobertura de código
¿Qué porcentaje del código fue ejecutado por los tests? Si una rama nunca se ejecutó, ¿por qué no?
Nivel 4: Property-based testing (Hypothesis)
Este es interesante. Vos definís una propiedad (ej: “para cualquier lista, la función retorna una lista del mismo largo”) y Hypothesis genera cientos de inputs aleatorios para encontrar contraejemplos. No escribís cada test case, la herramienta lo hace.
Nivel 5: Ejecución simbólica (Z3 / CrossHair)
Aquí es donde la magia realmente sucede. Z3 es un SMT solver (Satisfiability Modulo Theories) que puede razonar sobre código sin ejecutarlo. Le preguntás: “¿existe una entrada que viole esta postcondición?” Z3 busca matemáticamente una respuesta. Si encuentra una, te la devuelve. Si no, probó que la postcondición siempre se cumple.
Nivel 6: Análisis arquitectónico
¿Las dependencias entre módulos respetan la arquitectura definida? ¿No hay ciclos inesperados? Esto valida estructura de proyecto, no solo funciones individuales.
Tres niveles de profundidad: L2, L4 y L6
En práctica, no necesitás correr todos los 6. SereneCode agrupa en tres perfiles de ejecución según dónde corra el código y cuánto riesgo toleras.
L2 (Herramientas internas / MVP)
Corre los primeros dos niveles: análisis sintáctico y type checking. Rápido. Toma segundos. Usalo para código que generás internamente, baja criticidad, iteración rápida. Ataja errores obvios sin retrasar el desarrollo.
L4 (Sistemas en producción)
Levels 1-4: tipo estático, cobertura, property-based testing. Balance entre cobertura y tiempo. Toma minutos, no horas. Es para código que va a producción pero no es financiero ni de seguridad crítica. Un CRUD en una SaaS, un microservicio interno, una API REST estándar. Cubrimos ese tema en detalle en seguridad y privacidad en código.
L6 (Aplicaciones críticas)
Todos los niveles, incluyendo ejecución simbólica y análisis arquitectónico. Lento — puede tomar horas para funciones complejas — pero da garantías matemáticas. Para fintech, healthcare, automotriz, infraestructura crítica. Si el código procesá dinero o vidas, pagás el tiempo.
Traceabilidad de requisitos — De la especificación al test
Un concepto clave en SereneCode es requirement traceability. Cada requisito debe tener un camino verificable desde la especificación hasta la implementación hasta el test.
Vos escribís convenciones en SERENECODE.md:
REQ-001: La función calcular_total() nunca debe devolver un número negativo.
Precondition: lista de precios > 0
Postcondition: resultado >= 0
Invariant: suma(precios) >= 0 El agente IA las lee, genera una implementación, y SereneCode verifica que REQ-001 se cumple automáticamente. Si alguien más tarde refactoriza calcular_total() y quebranta la invariante, fallaría el test.
Esto importa para cumplimiento regulatorio. Si sos una fintech en Argentina y una auditoría fiscal te pide “demuestran que cada requisito de cálculo está testeado”, la traceabilidad te cubre el culo. Tenés documentación ejecutable.
Herramientas integradas: mypy, Hypothesis y Z3
SereneCode no inventa la rueda. Se apoya en herramientas que ya existen y funcionan bien, cada una especializada en un aspecto:
mypy — Type checking estático
mypy es el verificador de tipos de Python. Corre sin ejecutar el código. Detecta errores de tipos que normalmente no ves hasta runtime. Por ejemplo, si pasás un string donde la función espera un int, mypy te lo dice antes de que el código corra.
Hypothesis — Property-based testing
Hypothesis es una biblioteca que genera automáticamente datos de prueba aleatorios para encontrar edge cases. Vos definis una propiedad (“el largo de la lista nunca cambia”) y Hypothesis intenta quebrantarla con cientos de inputs diferentes. Es como un fuzzer, pero inteligente.
Z3 / CrossHair — Ejecución simbólica
Z3 es un SMT solver de Microsoft. CrossHair es una interfaz Python que lo usa. Juntas, pueden probar que para todas las entradas posibles, una postcondición se cumple. No es probabilístico como Hypothesis. Si Z3 dice “probado”, es probado. Más contexto en herramientas modernas para desarrollo IA.
Lo poderoso: cuando las tres herramientas trabajan juntas, se complementan. Mypy atrapa tipos malos. Hypothesis encuentra edge cases prácticos. Z3 prueba garantías matemáticas. Un atacante tendría que quebrantar código que pasó las tres verificaciones.
Cuándo necesitás SereneCode — Casos de uso prácticos
No todo código necesita verificación formal. Eso sería lento y overkill. Pero hay escenarios donde es obligatorio:
Fintech y sistemas de pagos
Si el código procesa dinero, un bug es dinero perdido o robado. Reguladores (Banco Central, Comisión Nacional de Valores) exigen trazabilidad. Una función de cálculo de intereses, comisiones, o reconciliación de cuentas debe ser verificable formalmente.
Healthcare y sistemas críticos
Código que dosifica medicinas o controla tratamientos. Un error en la lógica de cálculo de dosis mata gente. Los reguladores (FDA en USA, ANMAT en Argentina) esperan prueba documentada de correctitud.
Infraestructura y automático
Código en vehículos autónomos, drones, sistemas industriales. Si el código falla, personas se lastiman o equipo caro se rompe. Acá no hay “rollback” fácil.
Datos sensibles y cumplimiento
Si procesás datos personales (GDPR, CCPA, leyes de protección de datos argentinas), código que maneja encriptación, anonimización, o purga de datos necesita ser verificable. Una fuga de datos por un bug es costosa legalmente.
Código que vive años sin cambios
Un cálculo que escribiste hace tres años, nadie toca, pero es crítico. Refactorizar sin guarantías es peligroso. Con SereneCode, cambios futuros se verifican automáticamente contra invariantes que definiste.
Cómo empezar — Setup y convenciones del proyecto
El workflow es simple, pero requiere disciplina:
1. Instalar y crear SERENECODE.md
Cloná el repositorio de SereneCode, instalá la librería Python, y creá un archivo SERENECODE.md en tu proyecto con convenciones: patrones de nombres para requisitos, ejemplos de precondiciones, postcondiciones, invariantes que usás.
2. El AI agent lee las convenciones
Cuando generas código con Claude, ChatGPT o el modelo que uses, le pasás como contexto el SERENECODE.md. El agente entiende tus estándares y genera implementaciones que ya incluyen contratos (tipos, precondiciones, postcondiciones). Te puede servir nuestra cobertura de plataformas de control de versiones.
3. Escribir contratos explícitamente
No basta con código. Necesitás especificar qué la función promete. Ejemplo:
def transferir_fondos(cuenta_origen: str, cuenta_destino: str, monto: float) -> bool:
"""
REQ-042: Transferencia válida de fondos.
Precondition: monto > 0, cuenta_origen existe, saldo >= monto
Postcondition: saldo_origen disminuyó en monto, saldo_destino aumentó en monto
Invariant: suma(saldos_globales) antes == suma(saldos_globales) después
""" Escribirlo así no cuesta nada extra, y ahora SereneCode puede verificarlo.
4. Correr el verificador en CI/CD
Antes de mergear, tu CI corre SereneCode en el nivel que corresponda (L2, L4, o L6). Si falla, PR no mergea.
Errores comunes
Creer que SereneCode reemplaza testing manual
No. Verifica que la lógica es correcta, pero no testea usabilidad, performance, o integración entre sistemas. Seguís necesitando QA, testing de integración, smoke tests. SereneCode es una capa adicional de certeza sobre correctitud lógica.
Escribir contratos que son imposibles de cumplir
Si decís “una función debe siempre devolver un valor positivo” pero la entrada es “dinero adeudado que puede ser negativo”, ya fallaste. Los contratos deben ser realistas. Si Z3 dice “contraejemplo: entrada -10”, quizás tu postcondición estaba mal definida.
Correr L6 (ejecución simbólica) en cada commit
Z3 es lento. Una función complicada puede tomar horas. Usá L6 solo en pre-release o ramas críticas. Para CI/CD cotidiano, L4 es generalmente suficiente.
Preguntas Frecuentes
¿Qué diferencia hay entre SereneCode y simplemente escribir tests?
Tests verifican casos específicos que vos escribís. Si no pensaste en un edge case, no lo testeas. SereneCode usa matemática (Z3) para probar que todos los casos posibles cumplen una propiedad. No necesitás adivinar qué testear. El solver busca contraejemplos automáticamente.
¿Puedo usarlo si genero código con GPT/Claude?
Exactamente para eso fue diseñado. Los LLMs generan código rápido pero sin garantías. Pasas SereneCode encima y obtenés garantías. Incluí el SERENECODE.md como contexto cuando pidas al modelo que genere código, y le dará más estructura. Luego SereneCode verifica que respetó la estructura.
¿Cuánto tiempo agrega a mi pipeline?
Depende del nivel. L2 (type checking): segundos. L4 (property-based): minutos. L6 (simbólico): puede ser horas para funciones complejas. En un pipeline CI/CD típico, L4 en cada commit (toma 2-5 min) es razonable. L6 solo antes de release o en ramas críticas.
¿Qué pasa si la verificación formal falla?
Z3 te dice exactamente por qué: te devuelve una entrada (contraejemplo) que quebranta la postcondición. Revisás el código, arreglás el bug o ajustás el contrato si el contrato estaba mal definido. Iterás hasta que pase.
¿Necesito ser experto en verificación formal para usarlo?
No. La interfaz Python es estándar. Escribís tipos de dato claros, pre/postcondiciones como comentarios o docstrings, y SereneCode hace el resto. El paper técnico (en arXiv) es denso, pero no necesitás leerlo para usarlo.
Conclusión
SereneCode resuelve un problema real: los modelos de lenguaje generan código rápido pero sin garantías de correctitud. Para código que simplemente itera sobre una lista o renderiza un componente, testing tradicional es suficiente. Pero si el código procesa dinero, medicinas, o infraestructura crítica, necesitás algo más que fe.
La verificación formal no es nueva (viene de los 70s), pero hasta ahora era cara, lenta, y requería expertos. SereneCode democratiza el acceso combinando herramientas existentes (mypy, Hypothesis, Z3) en un workflow Python que cualquier desarrollador puede usar. Si generás código con IA para sistemas críticos, vale la pena experimentar con él.
Lo que cambió: antes, debías elegir entre velocidad (IA genera rápido, confías a ciegas) o seguridad (manual, lento). Ahora podés tener ambas. Generates code con IA, verificás formalmente, y shippeás con confianza.
