Cómo evitar la deuda técnica al integrar agentes de IA en el desarrollo
Dominicode¿Y si la velocidad que te vendieron como progreso es, en realidad, el motor que va a deshacer tu arquitectura?
Tiempo estimado de lectura: 8 min
- Ideas clave:
- Integrar agentes de IA sin capturar intención produce deuda técnica a escala.
- Necesitas trazar decisiones → requerimiento → test → código y hacerla canónica.
- Una herramienta como Plum no pinta paredes; convierte intención volátil en artefactos persistentes.
- Gobernanza debe vivir fuera del agente: hooks, CI y aprobaciones humanas son imprescindibles.
Introducción
¿Y si la velocidad que te vendieron como progreso es, en realidad, el motor que va a deshacer tu arquitectura?
Poca gente lo dice sin rodeos: integrar agentes de IA para escribir código sin un sistema que capture la intención es una receta perfecta para deuda técnica a escala industrial. Y no hablo de “posibles problemas”. Hablo de que, hoy, el código puede crecer más rápido de lo que cualquier humano puede leer —y eso duele en producción.
This is her code. This is what she was managing. This is her VS code.
Margaret Hamilton sujetó esa complejidad con una pila de impresiones. Ella no tenía prompts; tenía procedimientos. Nosotros tenemos prompts y convicciones ingenuas.
Vamos al punto.
Resumen rápido (lectores con prisa)
Plum es una herramienta de gobernanza que intercepta commits, extrae decisiones y las convierte en artefactos trazables. Úsala cuando quieras que las decisiones que toman agentes o developers queden registradas y enlazadas a specs, tests y código. Importa porque previene deuda técnica acelerada por IA y funciona mediante git hooks, diffs, y un flujo de aprobación humana.
1) El problema (simple y aterrador)
Si un Product Manager edita una regla en producción, ¿el resto del sistema cambia con ella?
En la práctica, no.
Los hotfixes saltan directo al trunk.
Los tests se rompen en silencio.
Las specs siguen siendo documentos en Markdown que nadie actualiza.
Y cuando introduces agentes de IA en ese mix, la cosa se acelera: los LLMs toman micro-decisiones en chats, tú implementas, haces commit y la “intención” se evapora.
Resultado: código con autoría pero sin porqué. Comportamiento sin contrato. Equipos que arreglan cosas por intuición y no por diseño.
2) Por qué los tests y specs no bastan
Un test valida un output. No captura intención.
Un spec define un contrato —hasta que alguien lo ignora.
La implementación revela límites: casos borde, problemas de estado, compromisos de rendimiento. La única forma real de enriquecer una spec es escribir el maldito código. Implementar obliga a decidir. Y esas decisiones deben quedar registradas.
3) ¿Qué hace falta?
- Capturar decisiones. No dejar que vivan en el chat.
- Vincular decisión → requerimiento → test → código.
- Hacer que esa trazabilidad sea canónica y no opcional.
Sin eso, tus agentes son obreros hiperproductivos que construyen habitaciones sin planos. Velocidad sin planos = casa que se cae.
4) Plum: la plomada que no pinta paredes
No es mágica. No genera código bonito.
Plum hace otra cosa muchísimo más valiosa: transforma intención volátil en artefacto persistente.
Qué hace Plum (sí, práctico)
- Intercepta commits via git hooks.
- Lee diffs y scans de traces de agentes.
- Extrae decisiones (qué, por qué, quién).
- Deduplica lógicas repetidas.
- Te obliga a aprobar/rechazar/editar antes de permitir el commit.
- Si apruebas, actualiza specs Markdown y genera un .jsonl con la decisión, autoría y trazas.
- Ejecuta un sync que mapea spec ↔ tests ↔ código y muestra huecos de cobertura.
Metáfora: la plomada cuelga del trípode y te dice si la pared está vertical. Plum no pinta; evita derrumbes.
5) Por qué esto no puede ser una “skill” dentro del agente
Una skill vive dentro del agente. Es una sugerencia.
Un control de gobernanza tiene que vivir fuera. Debe poder bloquear commits, correr en CI y ser determinista.
Si la herramienta fuera sólo otra respuesta del LLM, se ignoraría. Punto.
6) Problemas reales a resolver (y por qué no es trivial)
- Umbral de interrupción: si cada hotfix genera cinco decisiones para revisar, los devs odian la herramienta. Necesitas tolerancias dinámicas: que el sistema sólo te despierte para decisiones vagas, peligrosas o contradictorias.
- Dedupe y fuzzy decision ID: identificar decisiones no es binario; es difuso y repo-específico. Necesitamos algoritmos ajustables y feedback humano.
- Rollbacks automáticos: si rechazas una decisión, el sistema debería revertir el cambio relevante o pedir al agente que rehaga la tarea coherentemente. Hoy eso no está pulido.
- Spec sharding: las specs crecen. Hay que fragmentarlas en requisitos testables. Un LLM puede ayudar a shardear, pero hay que diseñarlo.
- Integración de test runners: en la versión actual Plum está acoplado a pytest. Necesitamos soporte agnóstico: conformance tests, runners multi-lenguaje, harnesses de integración.
- Escalabilidad: en proyectos monolíticos gigantes aún no sabemos si el approach escala. Téstealo en una rama pequeña antes de clonar tu repo legacy.
7) Cómo se gana valor real (dejando de ser postura)
- Haz que cada decisión importante deje rastro. No excepciones.
- Exige aprobación humana para decisiones con impacto.
- Vuelve la spec viva: que el archivo Markdown no sea un monumento a la intención, sino el contrato vigente.
- Los tests deben describir intención, no solo outputs. Property tests e invariantes sistémicas son tus nuevos héroes.
- Si un agente necesita leer 50 archivos para cambiar una función, rehace la arquitectura: modularidad extrema, boundaries claros.
8) Diseño técnico inteligente (lo que aprendí construyéndolo)
- Usa git hooks como checkpoint. Si el commit no pasa la validación de decisiones, el commit falla.
- Mantén un .plumignore para no disparar reviews por cambios triviales (README, docs, etc.).
- Almacena estado y config en una carpeta oculta (.plum). Versiona el .jsonl.
- Deduping y parsing de specs: estructura las llamadas LLM con DSPy para hacerlas más deterministas y testables.
- Router de modelos: no todo exige GPT-costoso. En dedupe puedes usar un modelo OSS rápido. La experiencia del dev gira alrededor de latencia.
- Diseña la UX: permitir modos (silent, strict, dangerously-approve) para distintos contextos.
9) Ejemplo mínimo de flujo (para que lo pruebes en 15 minutos)
- pip install plum-dev
- cd repo (with specs.md and pytest suite)
- plum init → apunta a folder de specs y a tests
- Haz cambios con tu agente y commit
- Si hay decisiones, git commit fallará y te pedirá revisión
- Aprobar actualiza spec; reject detona rollback o workflow manual según tu configuración
10) Umbral y gobernanza: políticas prácticas
- En sistemas críticos: tolerancia cero. Todo pasa por aprobación humana.
- En prototipos: modo “agile fast-lane” para no morir de fricción.
- En equipos mixtos: definir perfiles por carpetas/paquetes. Modules core = strict; UI experimental = lenient.
- Pipeline: bloquear merges si spec↔tests↔código no están sync. Es duro, sí. Necesario, también.
11) Cultura y disciplina
No se automatiza cultura. Se diseña.
Pide que cada PR incluya:
- ¿Qué decisión justificó este cambio?
- ¿Qué requisitos se actualizaron?
- ¿Qué tests nuevos cubren la decisión?
Y deja que la herramienta coja esos metadatos y los convierta en .jsonl rastreables.
12) Lo práctico y lo urgente
- Si ya usas agentes y no tienes este tipo de control, estás acelerando una deuda técnica que no podrás pagar. No es dramático; es inevitable.
- Prioridad de adopción:
- 1. Empezar a capturar traces.
- 2. Agregar hooks que bloqueen commits sin revisión de intención.
- 3. Transformar specs en contratos testables.
- 4. Automatizar sync y coverage mapping.
13) ¿Qué pasa si no lo haces?
Velocidad hoy = caos mañana.
Cuando un bug crítico aparezca a las 2 AM, nadie sabrá por qué la regla se cambió. Commits huérfanos. Blame que no sirve. Migraciones peligrosas. Equipos quemados. Clientes enfadados.
14) No todo es miedo: oportunidades enormes
- Auditoría real sobre decisiones: útil para compliance y seguridad.
- Mejor onboarding: nuevos devs leen el árbol de decisiones para comprender el porqué.
- Menos discusiones eternas en PRs: si la decisión está bien documentada, la discusión baja y la calidad sube.
- Productividad con control: velocidad + gobernanza = ventaja competitiva.
15) Cierre con acción concreta
Instala la plomada. Prueba en una rama pequeña. No por postureo. Por supervivencia técnica.
Si quieres:
- Te mando un template de .jsonl para decisiones.
- Te paso un flujo de PR que puedes pegar en tu repo.
- Te doy el checklist para integrar Plum en CI en 15 minutos.
Respóndeme este mensaje con “Mándame el template” o corre ahora:
- pip install plum-dev
- cd tu-repo
- plum init
- haz un commit con un agente y observa qué decisiones aparecen.
Esto no acaba aquí.
Si no empiezas a capturar intención hoy, tus agentes construirán un legado que nadie querrá mantener mañana. Empieza por un archivo .jsonl. Empieza por una regla dura en tu CI. Haz que la próxima vez que alguien pregunte “¿por qué esto existe?” la respuesta esté en el repo y no en el recuerdo difuso de una conversación vieja.
¿Quieres el checklist y el template ahora? Dímelo. Y mientras lo instalas, piensa en esto: velocidad sin plomada es solo una forma elegante de cavar tu propia trampa.
Para quien está explorando gobernanza de agentes y workflows, una continuación lógica es revisar investigaciones y herramientas de integridad técnica desarrolladas por equipos que experimentan con estos retos. Consulta Dominicode Labs como punto de referencia para materiales y experimentos relacionados con trazabilidad de decisiones y automatización segura.
FAQ
- ¿Qué es Plum y para qué sirve?
- ¿Por qué no bastan los tests y las specs?
- ¿Cómo se integra Plum en el flujo de trabajo?
- ¿Qué pasa si rechazo una decisión durante el commit?
- ¿Plum afecta la experiencia del desarrollador?
- ¿Es Plum dependiente de un test runner?
- ¿Cómo empezar con Plum sin romper el equipo?
¿Qué es Plum y para qué sirve?
Plum es una herramienta de gobernanza que intercepta commits, extrae decisiones desde diffs y trazas de agentes, obliga a revisarlas y las convierte en artefactos persistentes (.jsonl) y actualizaciones en specs Markdown. Sirve para capturar intención y vincularla con tests y código.
¿Por qué no bastan los tests y las specs?
Porque un test valida un output y una spec es un contrato que puede quedarse desactualizado. La implementación revela decisiones operacionales que deben quedarse registradas; solo ejecutar y aprobar esos cambios garantiza que la spec refleje intención real.
¿Cómo se integra Plum en el flujo de trabajo?
Plum se integra mediante git hooks que interceptan commits, revisan diffs y traces, y requieren aprobación humana para cambios con decisión. Si se aprueba, Plum actualiza specs y genera el registro .jsonl; si no, puede revertir o pedir una re-ejecución coherente.
¿Qué pasa si rechazo una decisión durante el commit?
Según la configuración, el rechazo puede detonar un rollback automático del cambio relevante o iniciar un workflow manual que pida al agente rehacer la tarea coherentemente. El comportamiento exacto depende de la policy definida.
¿Plum afecta la experiencia del desarrollador?
Sí: introduce una fricción intencional para decisiones relevantes. Para evitar rechazo por exceso de ruido, Plum debe soportar tolerancias dinámicas (modos silent, strict, dangerously-approve) y un .plumignore para cambios triviales.
¿Es Plum dependiente de un test runner?
En su versión inicial Plum está acoplado a pytest, pero el objetivo es soportar runners multi-lenguaje y conformance tests para ser agnóstico respecto al ecosistema de pruebas.
¿Cómo empezar con Plum sin romper el equipo?
Prueba en una rama pequeña, habilita modos lenientes para partes experimentales del repo y aplica tolerancia cero solo en módulos críticos. Empieza por capturar traces y agregar hooks progresivamente.