El uso de agentes de inteligencia artificial en programación está entrando en una fase más madura. Ya no se trata solo de pedir a un modelo que escriba código y esperar que acierte, sino de organizar mejor qué parte del trabajo debe hacer el modelo más capaz, qué parte puede ejecutar un modelo más barato y dónde debe intervenir el desarrollador humano. En ese contexto aparece shadcn/improve, una skill para agentes que plantea una idea sencilla: usar el modelo más potente para auditar un proyecto y escribir planes de mejora, pero no para implementar directamente los cambios.
La propuesta encaja con un problema cada vez más habitual en equipos técnicos. Los modelos avanzados son buenos entendiendo bases de código complejas, detectando deuda técnica, priorizando riesgos y escribiendo especificaciones. Pero también son caros. Si se usan para cada cambio menor, cada refactor o cada ajuste repetitivo, la factura puede crecer muy rápido. shadcn/improve intenta separar la inteligencia de la ejecución: el modelo caro piensa y planifica; otro agente, más económico, implementa bajo instrucciones precisas.
El plan como producto, no el código generado
La filosofía de shadcn/improve se resume en una frase: el plan es el producto. La skill no modifica el código fuente del proyecto. Su trabajo consiste en inspeccionar el repositorio, identificar hallazgos, priorizarlos y generar planes de implementación autocontenidos en Markdown dentro de una carpeta plans/. Después, otro agente o un desarrollador humano puede ejecutar esos planes.
Este matiz es importante porque cambia la forma de usar la IA en desarrollo. En lugar de delegar una tarea completa a un agente que improvisa sobre la marcha, el sistema obliga primero a documentar el problema, citar rutas de archivos, incluir fragmentos relevantes del estado actual, definir pasos verificables, indicar comandos de prueba y marcar condiciones de parada. Es una forma de convertir el uso de IA en un flujo más parecido al trabajo de un tech lead: revisar, priorizar, especificar y después ejecutar con control.
| Comando | Uso principal |
|---|---|
/improve | Auditoría completa del repositorio, hallazgos priorizados y planes |
/improve quick | Revisión rápida y barata de puntos críticos |
/improve deep | Auditoría exhaustiva por paquetes y categorías |
/improve security | Revisión enfocada en seguridad |
/improve branch | Auditoría limitada a los cambios de la rama actual |
/improve next | Sugerencias de evolución del proyecto basadas en evidencias |
/improve plan <descripción> | Crear un plan concreto sin auditoría previa |
/improve review-plan <archivo> | Criticar y ajustar un plan existente |
/improve execute <plan> | Delegar la ejecución a un agente más barato y revisar su trabajo |
/improve reconcile | Actualizar el backlog de planes, verificar, desbloquear o retirar |
La instalación se plantea con un comando directo: npx skills add shadcn/improve. Funciona en agentes compatibles con el formato Agent Skills y genera planes en texto plano. Esto facilita que el resultado no quede encerrado en una sesión concreta del modelo. Un plan puede leerlo otro agente, otro desarrollador o el propio equipo en una revisión interna.
Por qué separar auditoría y ejecución puede ahorrar dinero
El enfoque tiene sentido económico. En programación asistida por IA, las partes más caras suelen ser las que requieren más comprensión: leer el repositorio, entender convenciones, evaluar impacto, detectar problemas reales y evitar falsos positivos. Ahí un modelo de alto nivel puede aportar más valor. En cambio, implementar una lista de pasos concreta, ejecutar tests, aplicar cambios mecánicos o corregir una duplicación localizada puede delegarse a un modelo más barato si el plan está bien escrito.
Esto no significa que cualquier modelo barato pueda hacer cualquier cambio. La clave está en la calidad de la especificación. shadcn/improve escribe planes para “el ejecutor más débil plausible”, es decir, para un agente que no ha visto la conversación previa y que puede tener mucha menos capacidad de razonamiento. Por eso incluye contexto, rutas exactas, extractos de código, comandos de verificación, criterios de finalización y límites explícitos.
| Fase | Modelo recomendado | Motivo |
| Reconocimiento del repositorio | Modelo potente | Necesita entender arquitectura, stack y convenciones |
| Auditoría de problemas | Modelo potente | Requiere juicio técnico y priorización |
| Escritura del plan | Modelo potente | Debe producir instrucciones completas y verificables |
| Implementación guiada | Modelo más barato o humano | Sigue pasos definidos y acotados |
| Ejecución de tests | Agente barato o entorno local | Trabajo mecánico con salidas verificables |
| Revisión final | Modelo potente o desarrollador senior | Comprueba intención, alcance y calidad del diff |
El ahorro no viene solo de usar menos el modelo caro. También puede venir de reducir iteraciones fallidas. Muchos costes de IA en desarrollo aparecen cuando el agente cambia demasiado, rompe pruebas, se sale del alcance o inventa una solución porque no entendió el contexto. Si el plan incluye condiciones de parada, comandos esperados y límites de alcance, el ejecutor tiene menos margen para desviarse.
Auditoría con evidencia, no recomendaciones genéricas
Otro aspecto relevante es que la skill no busca producir listas genéricas de “mejores prácticas”. Durante la auditoría, reparte subagentes por categorías como corrección, seguridad, rendimiento, cobertura de tests, deuda técnica, dependencias, experiencia de desarrollador, documentación y dirección del producto. Cada hallazgo debe apoyarse en evidencias del propio repositorio, con referencias a archivos y líneas.
Después, el asesor vuelve a leer los puntos citados antes de mostrarlos. Esta segunda revisión intenta reducir falsos positivos, corregir atribuciones erróneas y registrar rechazos para que no reaparezcan en futuras ejecuciones. En el ejemplo compartido por el proyecto, una supuesta alerta de SSRF asociada a una variable https_proxy se rechaza como comportamiento esperado, porque sigue una convención estándar usada por muchas herramientas CLI.
| Categoría de auditoría | Qué puede detectar |
| Corrección | Errores lógicos, casos borde o comportamientos inconsistentes |
| Seguridad | Riesgos reales con evidencia en código |
| Rendimiento | Algoritmos caros, consultas ineficientes o trabajo duplicado |
| Tests | Zonas críticas sin cobertura suficiente |
| Deuda técnica | Duplicaciones, abstracciones rotas o migraciones incompletas |
| Dependencias | Actualizaciones, incompatibilidades o paquetes problemáticos |
| DX | Fricciones para desarrollar, probar o desplegar |
| Documentación | Instrucciones incompletas o desactualizadas |
| Dirección | Ideas de producto justificadas por el estado del repositorio |
Esta insistencia en la evidencia es útil porque uno de los mayores problemas de los agentes de código es el ruido. Un modelo puede detectar “problemas” que en realidad son decisiones deliberadas, deuda aceptada o patrones propios del proyecto. Si cada hallazgo tiene que citar código concreto y superar una revisión interna, la salida se parece más a una auditoría técnica y menos a una lista de consejos genéricos.
Planes pensados para sobrevivir fuera de la sesión
Los planes generados por shadcn/improve son autocontenidos. Incluyen el commit contra el que se escribieron, de modo que el ejecutor puede hacer una comprobación de deriva antes de tocar nada. Si el código cambió demasiado, el plan debe detenerse y reportar el problema en lugar de improvisar.
También incorporan “verification gates”. Cada paso termina con un comando y una salida esperada. Esto convierte el éxito en algo más medible. El agente no tiene que decidir si “parece terminado”; debe cumplir pruebas, lint, compilación u otros criterios definidos por el propio repositorio.
| Propiedad del plan | Valor para el equipo |
| Contexto inline | El ejecutor no depende de la conversación original |
| Rutas exactas | Reduce exploración innecesaria |
| Extractos de código | Aclara el estado actual antes del cambio |
| Comandos verificados | Usa las herramientas reales del repositorio |
| Criterios de finalización | Evita cierres ambiguos |
| Condiciones de parada | Impide que un modelo pequeño improvise |
| Commit de referencia | Detecta si el plan quedó desactualizado |
| Límites de alcance | Reduce cambios laterales no deseados |
Este enfoque puede encajar bien en equipos que ya usan issues, pull requests y revisiones. Los planes pueden publicarse como GitHub issues con --issues, de modo que el trabajo aterriza donde el equipo ya gestiona su backlog. Para organizaciones que quieren introducir agentes sin perder control, esta es una idea práctica: la IA no sustituye el proceso, sino que escribe mejor el trabajo que después entra en el proceso.
Ejecución aislada y revisión del resultado
La skill también incluye /improve execute <plan>, que despacha un ejecutor más barato en un worktree aislado, le entrega el plan y después revisa el resultado. El flujo vuelve a pasar por los criterios de finalización, comprueba que el diff respeta el alcance y emite un veredicto: aprobar, pedir revisión o bloquear y refinar el plan.
La fusión del cambio queda en manos del usuario. Esto es importante desde el punto de vista de seguridad y control. El agente puede preparar una propuesta, pero no toma la decisión final de integrarla. Para muchos equipos, esta separación puede ser la diferencia entre usar IA como asistente y dejar que modifique un producto sin supervisión suficiente.
| Regla dura | Por qué importa |
| La skill no modifica código fuente | Reduce riesgo en la fase de auditoría |
Solo escribe en plans/ | Limita el alcance de sus cambios directos |
| No ejecuta comandos que muten el working tree | Evita efectos secundarios durante el análisis |
| No reproduce secretos | Solo señala ubicación y tipo de credencial |
| Los ejecutores trabajan en worktrees desechables | Aísla cambios y facilita revisión |
| El merge queda en manos del usuario | Mantiene control humano sobre el repositorio |
También existe /improve reconcile, pensado para limpiar el backlog: verificar planes ya ejecutados, investigar bloqueos, refrescar planes que quedaron desactualizados y retirar hallazgos que se arreglaron por otra vía. Esta parte es menos llamativa que el comando inicial, pero puede ser una de las más útiles. Los planes de mejora envejecen rápido si el repositorio se mueve cada día.
Una señal de hacia dónde van los agentes de código
shadcn/improve no es solo una herramienta curiosa para usuarios de Claude Code, Codex u otros entornos compatibles. Representa una tendencia más amplia: los agentes de desarrollo necesitan procesos, límites y productos intermedios. Pedir “arregla mi repo” es demasiado abierto. Pedir “audita, prioriza, escribe planes verificables y deja que otro ejecute” es mucho más controlable.
Este patrón se parece a cómo trabajan los equipos humanos. Un arquitecto o tech lead no suele implementar todos los cambios. Analiza, decide prioridades, escribe tickets, revisa propuestas y valida resultados. La IA puede aportar valor en ese rol si tiene acceso al repositorio, entiende convenciones y produce planes que otros puedan ejecutar.
La idea también encaja con la guerra de precios en modelos de IA. Si los modelos más capaces siguen siendo caros, las empresas tendrán que reservarlos para las tareas donde su razonamiento marca la diferencia. La ejecución mecánica, los cambios repetitivos y las pruebas pueden moverse a modelos más baratos o a herramientas automáticas.
No reemplaza una revisión técnica, pero puede elevar el suelo
La utilidad real dependerá de cada repositorio. Un proyecto pequeño quizá no necesite una auditoría tan estructurada. Un monorepo grande, con deuda técnica, migraciones pendientes y varios equipos, puede sacar más partido. También dependerá de la calidad del modelo usado como asesor y de la disciplina del equipo revisando los planes antes de ejecutarlos.
No conviene presentar este tipo de herramienta como sustituto de un senior. Sí puede actuar como multiplicador. Puede encontrar duplicaciones, convertir hallazgos dispersos en planes claros, generar issues accionables y evitar que un agente barato trabaje sin contexto. Para muchos equipos, ese ya es un salto relevante.
La programación con IA está dejando atrás la fase de los prompts improvisados. El siguiente paso será diseñar flujos donde los modelos caros razonen, los modelos baratos ejecuten, las pruebas verifiquen y los humanos mantengan la decisión final. shadcn/improve apunta justo a ese modelo: menos magia, más proceso y planes que se puedan revisar.
Preguntas frecuentes
¿Qué es shadcn/improve?
Es una Agent Skill que audita un repositorio, detecta mejoras y escribe planes de implementación en Markdown para que otros agentes o humanos los ejecuten.
Cómo se instala?
El proyecto indica que puede instalarse con el comando npx skills add shadcn/improve en entornos compatibles con el formato Agent Skills.
Implementa cambios en el código?
No directamente. La skill escribe planes en la carpeta plans/. La ejecución puede delegarse a otro agente en un worktree aislado, pero la fusión final queda en manos del usuario.
Por qué puede ahorrar costes en IA?
Porque permite usar un modelo caro para entender y planificar, y modelos más baratos para ejecutar tareas bien acotadas con comandos de verificación y límites claros.
