Agentes de IA
Entropía del código: cómo los controles de CI frenan el legacy que acumula la IA
La ley según la cual la complejidad del código crece sola sigue vigente con la IA, que solo acelera ese crecimiento. Estos son siete niveles de controles de CI que impiden que se acumule legacy, en el orden en que los añado.
La entropía crece sola. En física, es el segundo principio de la termodinámica. En el desarrollo de software pasa algo parecido: el desorden se acumula sin esfuerzo, y el orden exige trabajo.
Siempre ha sido así. A medida que un proyecto crece, crece su complejidad: se acumula legacy, el proyecto cuesta más de mantener, cada cambio pesa más y el riesgo de romper algo no deja de aumentar. En 1974 Manny Lehman lo dejó por escrito como una ley de la evolución del software: la complejidad de un sistema aumenta salvo que se trabaje para reducirla. La IA no lo ha cambiado. Solo ha hecho que el legacy se acumule más rápido.
Lo que quieres es mantener el código lo más simple posible, y aquí es donde ayudan los controles de CI.
- 1Código muertohace fallar el build
- 2Linters y formateadoreshace fallar el build
- 3Análisis estáticohace fallar el build
- 4Tests unitarios y coberturahace fallar el build
- 5Complejidad y duplicaciónhace fallar el build
- 6Arquitectura y acoplamientohace fallar el build
- 7Reglas escritas (AGENTS.md)el CI no lo hace cumplir
1. Código muerto
El paso más sencillo es borrar lo que ya no se usa. También se puede automatizar: pon en el CI un detector de código muerto (vulture para Python, knip para JS/TS) y el código sin usar simplemente hace fallar el build.
2. Linters y formateadores
Después viene el linter: phpcs para PHP, ruff para Python, ESLint y Prettier para JS/TS, y así sucesivamente. Cada lenguaje tiene su estilo de código, y da igual cuál elijas. Lo que importa es no gastar tiempo y dinero leyendo código y escribiendo comentarios de revisión como «cambia las comillas dobles por simples». Acuerda el estilo con tu equipo una vez y, a partir de ahí, el CI lo comprueba automáticamente.
3. Análisis estático
El siguiente nivel son los analizadores estáticos: PHPStan para PHP, mypy para Python, tsc para JS/TS. Una comprobación estática de tipos estricta detecta errores simples: pasar una cadena donde se esperaba un número, u olvidar que un valor puede estar vacío. No revisa tu lógica, pero elimina toda una clase de errores. Los valores vacíos son el caso clásico: Tony Hoare, que inventó la referencia nula, la llamó su «error de mil millones de dólares», y según los datos de Harness de 2020, NullPointerException seguía entre las 10 excepciones más frecuentes en el 70 % de los entornos de producción Java que analizaron.
4. Tests unitarios y un 80 % de cobertura
¿Por qué? Porque el código malo es muy difícil de cubrir con tests unitarios. Para que el código se pueda cubrir con tests unitarios, tienes que dividirlo en clases y funciones separadas, pensar en el acoplamiento y en las interfaces, decidir qué es público y qué es privado, usar inyección de dependencias y evitar el estado global. Claro que no es una garantía al 100 %, sobre todo porque la IA infla fácilmente la cobertura con tests que no comprueban casi nada. Pero, de un modo u otro, el umbral pone restricciones al diseño y aumenta las probabilidades de tener buen código.
5. Complejidad y duplicación
La memoria de trabajo humana solo retiene unos pocos elementos independientes a la vez: George Miller contó 7 ± 2 en 1956, y Nelson Cowan lo afinó a unos cuatro en 2001. Todo lo que pasa de ahí se vuelve difícil y se va a la memoria de intercambio. No he visto estudios sobre esto para la IA, pero si el código es comprensible para una persona, aumentan las probabilidades de que la IA no alucine. Y si el código está tan enredado que una persona no puede seguirlo, lo más probable es que la IA apile encima nuevas capas de legacy.
Por eso fijo límites estrictos a las métricas de duplicación y de complejidad. Se supera el límite → falla el CI → toca refactorizar y extraer código a métodos y clases separados. Para Python, complexipy es un ejemplo.
Así se ve en un proyecto real. En una plataforma en la que trabajé, los agentes de IA escribieron la mayor parte del backend. A las seis semanas, antes de que existiera ninguno de estos controles, la primera medición encontró 143 funciones con una complejidad superior a 10 y 202 fragmentos copiados y pegados, cerca del 5 % del código. Más adelante, cuando se introdujo un techo estricto, la peor función procesaba recibos, es decir, manejaba dinero: 490 líneas con una complejidad de 73. En cuanto ese techo empezó a hacer fallar el build, pasó de 73 a 30 en cuatro días de refactorización, una función por commit. En los dos meses siguientes a la primera medición, la duplicación bajó a cerca del 3 %.
Si el legacy ya se ha acumulado, puedes empezar desde donde estás: fija el límite en tu función más compleja y, como mínimo, las cosas no empeorarán. Pero eso no hace desaparecer la deuda. La pagas aparte: reserva tiempo para refactorizar y baja el límite después de cada paso para consolidar el resultado. Los controles solo impiden que el desorden crezca; la limpieza sigue siendo cosa tuya.
6. Arquitectura y acoplamiento
Los límites estrictos también reducen la complejidad, un nivel más arriba. Es como el encapsulamiento en la POO: el sistema se construye con bloques grandes cuyo interior no hace falta tener en la cabeza; basta con conocer su contrato. Y la implementación de un bloque se puede sustituir cuando haga falta sin reescribir el resto del sistema. En lugar de decenas de clases y conexiones, razonas sobre unos pocos bloques grandes. De nuevo reduces el número de cosas que tienes que tener en la cabeza a la vez, esta vez en cada nivel de la arquitectura.
En la práctica, esto significa Clean Architecture y arquitectura hexagonal: el código se divide en capas y las dependencias entre ellas están estrictamente limitadas. El dominio no sabe nada de la base de datos, de HTTP ni de las APIs externas, y el código exterior llega a él a través de interfaces predefinidas. Esto también se comprueba automáticamente (con import-linter para Python, por ejemplo): aparece un import prohibido y falla el CI.
7. Reglas escritas
El último nivel son las reglas escritas. Antes eran guías y documentación para desarrolladores; ahora son un archivo AGENTS.md y documentación para la IA. A diferencia de los controles anteriores, aquí el resultado no es determinista: la IA puede leer una regla y aun así saltársela. Por eso las reglas escritas son la última milla. Solo contienen lo que no se ha podido cubrir con controles. En igualdad de condiciones, olvídate de la prosa y escribe un control estricto en código.
La IA intenta una y otra vez desactivar el control en lugar de arreglar el código: subir el límite, añadir una excepción, silenciar la regla con un comentario. Por eso mi archivo de reglas lo dice en una línea aparte: debilitar un control para que pase es un parche que deja el problema donde estaba.
Las herramientas, por lenguaje
| Nivel | Python | PHP | JS/TS |
|---|---|---|---|
| Código muerto | vulture | shipmonk/dead-code-detector (PHPStan) | knip |
| Linters y formateadores | ruff | PHP_CodeSniffer (phpcs) | ESLint + Prettier |
| Análisis estático | mypy (strict) | PHPStan | tsc (strict) |
| Tests unitarios y cobertura | pytest + coverage | PHPUnit | Jest / Vitest |
| Complejidad | complexipy | PHPMD, cognitive-complexity (PHPStan) | ESLint complexity |
| Duplicación | pylint duplicate-code | jscpd | jscpd |
| Arquitectura y acoplamiento | import-linter | Deptrac | dependency-cruiser |
También hay una versión paso a paso de este artículo escrita para agentes de programación, en inglés: el CI guardrails playbook. Para aplicarlo a un repositorio, dile a tu agente: Apply https://sg4.tech/blog/code-entropy-ci-checks-ai-legacy/playbook.md to this repository.
En resumen
La entropía crecerá de todos modos; la única cuestión es quién la frena. Cuantas más reglas pasan de las guías escritas a los controles automáticos de CI, menos depende todo de que una persona preste atención en la revisión. La IA ejecuta ella misma los controles, ve qué ha fallado y lo arregla: puede saltarse una línea de AGENTS.md, pero no puede saltarse un CI en rojo. Y cuantos más controles de este tipo tienes, con más tranquilidad puedes dejarle el código.
Si eres fundador y no lees código, esta lista te sirve igualmente como batería de preguntas para tu equipo: ¿cuáles de estos niveles hacen fallar el build de verdad? Cada respuesta del tipo «eso lo detectamos en la revisión» es una regla que depende de la atención de alguien un día concreto. Por qué el código escrito por agentes necesita estos controles es otra historia: gestionar la IA como a un junior.
Una plantilla para Python
El enfoque no depende del lenguaje. Para Python lo he empaquetado todo en una plantilla lista para usar; úsala con total libertad: python-guardrails-template.
Incluye:
- todos los controles de este artículo detrás de un único comando
make verifyen Docker, y el mismo comando en GitHub Actions; - capas de arquitectura con comprobación de imports;
- un escáner de secretos en cada commit;
- un AGENTS.md en el que casi cada regla apunta al control que la hace cumplir;
- un pequeño ejemplo, para que los controles pasen nada más crear el proyecto.
Un proyecto nuevo se crea con un solo comando:
copier copy gh:sg4tech/python-guardrails-template my-projectY cuando la plantilla se actualiza, copier update lleva los controles nuevos a los proyectos existentes y conserva tus cambios. Se acabó configurarlo todo desde cero en cada proyecto nuevo.
Preguntas frecuentes
¿Unos controles de CI estrictos no frenarán al equipo?
Los controles llevan el coste de la revisión y de producción a un build que falla, que es donde sale más barato. En un proyecto legacy empiezas desde el nivel actual, así que el primer día no se bloquea nada.
¿Puedo añadir estos controles a un proyecto legacy que ya existe?
Sí: congela el nivel actual como límite para que nada empeore y luego bájalo paso a paso a medida que refactorizas.
¿No basta con la revisión de código para detectar esto?
La revisión depende de la atención y no escala al ritmo al que escriben código los agentes. Un control se ejecuta en cada cambio y falla siempre de la misma manera.
¿Necesito los siete niveles a la vez?
No. Añádelos en orden: primero el código muerto, el formato y los tipos, porque son baratos. Los límites de complejidad y de arquitectura compensan cuando el código crece.