Cómo mejorar la gobernanza del código en proyectos con IA

¿Te das cuenta de lo que está pasando cuando la IA escribe más código del que puedes leer?

Tiempo estimado de lectura: 6 min

Introducción

No es una exageración. Es la nueva crisis del software. Otra vez. Solo que ahora la fábrica es un LLM y la producción no para.

This is her code. This is what she was managing. This is her VS code. Eso era Margaret Hamilton sujetando la complejidad con una plomada humana. Hoy esa plomada se perdió en un mar de commits y prompts.

Vamos al grano: la IA te da velocidad. No te da contexto ni responsabilidad. Y velocidad sin control es deuda técnica que crece sin pedir permiso.

1 línea: si no sincronizas spec, tests y código, la IA no te salva. Te hunde más rápido.

Por qué la vieja receta falla

• La industria ya tropezó con esto en los 60 y 70. Entonces el problema eran máquinas que permitían programas inmensos. Hoy el problema es que los modelos permiten escribir esos programas a ritmo industrial.
• Waterfall nació como orden. Agile llegó como contramedida. CI/CD vino a resolver la paranoia. Ahora la IA devuelve el caos a velocidad Agile.
• Resultado: waterfall x volumen a la cadencia de Agile. Y nadie puede revisarlo todo.

¿La lección? No es un problema técnico nuevo. Es el mismo problema con otro disfraz: la incapacidad humana para gobernar la complejidad.

El triángulo que nadie respeta

Imagina un triángulo. Tres vértices: Spec, Tests, Código.

• Spec = contrato. El porqué.
• Tests = garantías. El qué.
• Código = ejecución. El cómo.

Antes actuábamos como si fuera una ecuación: Spec + Tests + Agente = Código. Falso. Eso es una línea recta donde la realidad acaba por doblarte.

La verdad: es un feedback loop. Código modifica spec. Código revela tests faltantes. Tests exponen specs rotas. Y si no cierras ese bucle, cada commit es una pequeña traición al diseño original.

Regla: si tocas el código, el spec y los tests deben moverse contigo. Si no, estás plantando bombas de tiempo.

Hamilton’s law (versión para hoy)

Cuando no puedes ver sobre tu código, no puedes supervisarlo.

Padre orgulloso inventa ley. Útil. Si no puedes leer tu repo entero en una revisión razonable, no puedes asumir la responsabilidad de lo que contiene. Punto.

Agentes, decisiones y chats

Los agentes generan decisiones. Esas decisiones viven en chats.

• Un agente escribe una función.
• Tú validas rápido.
• Commit.
• ¿Dónde quedó la decisión sobre “por qué” se implementó así?

En chats. En traces. En el aire.

Eso es la falla: la intención desaparece. El código queda, la intención no. Y meses después, nadie recuerda por qué se hizo X. Sí, tú pensarás “lo vi en el chat”. Lo crees hasta que el repo explota.

Plum: la plomada digital

Plum no genera código. Hace otra cosa menos sexy y mucho más necesaria: captura intención.

¿Idea? Cada vez que comprometes cambios:

1. Plum mira el diff.
2. Plum revisa los traces del agente (conversaciones, prompts, respuestas).
3. Extrae decisiones —qué se decidió y por qué— y las dedupea.
4. Te las presenta: “Estas son las decisiones. ¿Las apruebas?”
5. Si sí, actualiza el spec (Markdown) y genera un registro inmenso en JSONL.
6. Ejecuta un sync y te muestra las brechas entre spec, tests y código.

Es la plomada que te dice si estás recto.

Por qué eso importa: intención como artefacto

• Commit messages son basura para auditar intención.
• PRs son discusiones, no contratos.
• El archivo .jsonl que genera Plum es una línea de tiempo de decisiones: pregunta, respuesta, autor (humano o LLM), rama y timestamps.

Es trazabilidad con “blame” real. No “quién hizo el commit”, sino “quién decidió y por qué”.

No es mágico. Es gobernanza.

• Plum hoy está atado a pytest para cobertura. Sí, limitación.
• Funciona mejor si la spec está delante del código. Backfilling grande es doloroso.
• No reemplaza la validación humana. La aprobación es obligatoria.

Open source y la ilusión del milagro colectivo

Hay una tentación: “Si lo estructuro perfecto, cualquiera podrá contribuir y la IA hará el resto”. Suena bonito.

La verdad: incluso en proyectos con specs decentes y tests que pasan, los PRs discuten implementaciones por 20 comentarios. Un test verde no significa que la solución sea correcta o mantenible.

Implementar el código mejora el spec. Siempre. Esa es la bendita contradicción: la única forma de refinar la especificación es ensuciándote con la implementación.

Cómo deberían trabajar los equipos que usan agentes

Si adoptas agentes sin cambiar proceso, vas a crear un legado ilegible. ¿Quieres hacerlo bien? Empieza por esto:

1. Spec antes que código
   • Especificaciones en Markdown en el repo.
   • Incluye ejemplos, invariantes y casos límite.
   • Hazlas contractibles: comportamientos verificables, no promesas.
2. Tests que describan intención
   • Tests no solo para pasar; tests que documenten el contrato.
   • Integración y properties (property tests) para invariantes sistémicos.
3. Captura de traces como estándar
   • Logs estructurados de conversaciones con agentes.
   • Relaciona cada trace a un commit o PR.
4. Herramienta de reconciliación
   • Plum u otra: extrae decisiones, pide aprobación, actualiza spec.
   • Registro en JSONL: fuente de verdad para auditorías.
5. Pipeline de bloqueo
   • Si spec↔tests↔código no están en sync, bloqueo del merge.
   • Preferible a permitir que la deuda técnica se vaya multiplicando.
6. Modularity or die
   • Si un agente necesita entender 50 archivos para cambiar un feature, rehace la arquitectura.
   • Componentes pequeños, contratos claros, dependencia explícita.

El rol del Tech Lead ahora

• Olvídate del dev que “código, push, listo”. Tu rol debe mutar.
• Menos escribir, más editar.
• Menos features, más criterios de aceptación inquebrantables.
• Más auditoría de decisiones y menos aprobación de slips superficiales.
• Ser la defensora/defensor de la intención del producto.

No confíes únicamente en LLMs para refactorizar la spec

Los LLMs ayudan a detectar incoherencias locales. Muy bien. Pero carecen de visión de largo plazo del negocio. No delegues la validación del contrato a una IA. Debe haber alguien con criterio humano que apruebe la intención.

Checklist mínimo para empezar hoy

• Specs en repo. (Sí, en Markdown y versionadas).
• Tests automatizados en CI. (Sí, pytest al menos para Plum).
• Traces guardados. (JSON logs o similar).
• Plum instalado en la máquina de desarrollo y en el CI.
• Política de aprobación humana para decisiones extraídas.
• Sync obligatorio en cada PR.

Si no puedes hacer todo esto ahora: empieza por uno. Empieza por capturar traces. Eso cambiará cómo miras los PRs.

Metáfora final (porque me encantan)

Piensa en tu repo como un edificio. La IA es una flota de obreros hiperactivos que pueden añadir habitaciones a ritmo industrial. Sin planos actualizados y sin quien firme los cambios, terminarás con una casa que se cae por el techo.

Plum es la plomada. Te dice si las paredes están verticales. No construye. No pinta. Sólo te evita derrumbes.

Urgencia práctica

Si tu equipo ya usa agentes y no tiene un proceso de reconciliación, estás acelerando la creación de un legado que nadie entenderá. Hoy es el día para dejar de creer que la velocidad soluciona cosas.

Haz esto ahora:

• pip install plum-dev
• cd a un repo con spec en Markdown y tests con pytest
• plum init
• plum sync en una rama de feature

No es glamour. Es gobernanza. Es aburrido. Y exactamente lo que separa a equipos que escalan de equipos que pagan deuda técnica por décadas.

¿Quieres que te pase un template de JSONL para registrar decisiones y un flujo de PR que puedas copiar en tu repo? Responde este mensaje y te lo mando. Porque esto no acaba aquí.

Dominicode Labs

Si buscas recursos y experimentos sobre procesos con agentes, automatización y gobernanza técnica, puedes revisar Dominicode Labs. Es una continuación lógica para explorar patrones de concilación entre spec, tests y código en entornos con IA.

FAQ

• ¿Qué problema principal resuelve Plum?
• ¿Por qué son insuficientes los commit messages y los PRs?
• ¿Qué debo capturar en los traces?
• ¿Cómo se integra Plum con pytest?
• ¿Qué acciones bloquea el pipeline propuesto?
• ¿Qué sigue si no puedo implementar todo el checklist ahora?
• ¿Quién debe aprobar las decisiones extraídas?