Higiene de repositorios: elimina redundancia sin romper comportamiento

El problema no es que el agente escriba mucho

El problema aparece cuando cada iteración añade otra capa sin retirar la anterior: wrappers que solo delegan, alias legados sin consumidores, validaciones duplicadas y exports que agrandan el contrato público. Un repositorio puede seguir con tests verdes y, aun así, costar más entenderlo y cambiarlo.

Una publicación de X detectada por el radar de Aulafy sirvió como señal de esta preocupación. La solución técnica de la lección procede de documentación oficial y de un laboratorio reproducible; una experiencia social no demuestra por sí sola que una herramienta cause deuda.

Cinco puertas para una refactorización segura

• Línea base: ejecuta las pruebas y registra el estado de Git antes de editar.
• Contrato: identifica imports, exports, efectos y salidas que deben conservarse.
• Presupuesto: limita archivos y prohíbe nuevas dependencias o abstracciones innecesarias.
• Prueba: exige comportamiento verde y una auditoría estructural separada.
• Diff: explica cada eliminación y comprueba que no se tocaron pruebas para ocultar una regresión.

git status --short
git diff --stat
npm test

# Después del cambio
npm test
npm run auditar
git diff --numstat -- src/tasks.mjs
git diff -- src/tasks.mjs

Tests verdes no significan repositorio limpio

Las pruebas de comportamiento responden «¿sigue funcionando?». Una auditoría estructural puede responder «¿retiramos los wrappers acordados?» o «¿la API pública conserva el tamaño previsto?». Necesitas ambas señales: una métrica de líneas aislada puede premiar código comprimido y una suite aislada puede ignorar código muerto.

Qué pedir al agente

La guía oficial de Codex recomienda declarar objetivo, contexto, restricciones y qué significa terminado; también pide ejecutar controles y revisar el diff. La documentación de Claude Code coincide en dar al agente una forma de verificar su trabajo y mantener las instrucciones de proyecto concisas.

Objetivo: elimina wrappers redundantes sin alterar la API cubierta por tests.
Contexto: lee AGENTS.md, src/tasks.mjs y test/tasks.test.mjs.
Límites: modifica solo src/tasks.mjs; no cambies pruebas ni package.json; no añadas dependencias ni nuevas abstracciones.
Terminado cuando: npm test y npm run auditar pasan; el diff tiene más eliminaciones que adiciones; explica cada eliminación y cualquier riesgo restante.

Cómo revisar el resultado

• Rechaza cambios en pruebas que solo adapten la expectativa a una regresión.
• Busca nuevos nombres para la misma abstracción antigua.
• Comprueba consumidores fuera del archivo antes de retirar un export real.
• No uses «menos líneas» como criterio único: legibilidad y contrato importan.
• Trabaja primero en un repositorio de práctica o una rama reversible.

Laboratorio MIT

El repositorio aulafy/taller contiene un estado inicial funcional pero redundante, una suite sin red ni dependencias, una auditoría que falla al principio y una solución de referencia. Así puedes repetir el proceso con Codex, Claude Code o manualmente y comparar el mismo resultado.