shadcn/improve es uno de esos repositorios pequeños en apariencia, pero con una idea de fondo muy potente: no usar el modelo de IA más caro para escribir código directamente, sino para pensar mejor. Su propuesta consiste en auditar un repositorio, detectar mejoras reales, priorizarlas y generar planes técnicos detallados para que después los ejecute otro agente más barato o un desarrollador humano.
El enfoque llega en un momento en el que los equipos de desarrollo están descubriendo la parte menos vistosa de la programación con IA: el coste, el ruido y la falta de control. Un agente puede escribir código, sí, pero también puede tocar demasiado, romper pruebas, salirse del alcance o gastar muchos tokens en tareas que no necesitaban tanta inteligencia. shadcn/improve intenta ordenar ese proceso con una idea casi obvia: usar el modelo más capaz para analizar y planificar, y reservar la ejecución para modelos más económicos.
Un repositorio abierto, gratuito y pensado para integrarse
La primera virtud de shadcn/improve es que es open source y se publica bajo licencia MIT. Esto significa que cualquier desarrollador puede revisarlo, instalarlo, adaptarlo, aprender de su enfoque o integrarlo en sus propios flujos sin depender de una plataforma cerrada. En un momento en el que muchas herramientas de IA para desarrollo llegan como productos SaaS de pago, este tipo de repositorio abierto tiene un valor especial.
La instalación también es directa: npx skills add shadcn/improve. El proyecto funciona con agentes compatibles con el formato Agent Skills, y sus resultados no quedan atrapados en una interfaz propietaria. Los planes que genera son archivos Markdown normales, guardados en una carpeta plans/. Eso permite que los lea otro agente, un desarrollador, un responsable técnico o cualquier herramienta interna del equipo.
| Característica | Valor para el desarrollador |
|---|---|
| Repositorio abierto | Permite revisar cómo funciona y adaptarlo |
| Licencia MIT | Facilita uso personal, profesional y empresarial |
Instalación con npx | Entrada sencilla sin configuración compleja |
| Planes en Markdown | Salida portable, legible y fácil de versionar |
| No modifica el código directamente | Reduce riesgos durante la auditoría |
| Compatible con otros agentes | No ata el flujo a un único ejecutor |
| Publicación como issues | Permite llevar los planes al backlog de GitHub |
Que la salida sea Markdown puede parecer un detalle menor, pero es una de las mejores decisiones del proyecto. En vez de crear otro formato cerrado, shadcn/improve produce documentación que encaja con la cultura de desarrollo ya existente: pull requests, issues, revisiones, checklists, comandos de test y decisiones trazables.
El modelo caro piensa, el barato ejecuta
La idea central del repositorio es separar dos fases que muchas herramientas mezclan: auditoría y ejecución. La primera requiere comprensión profunda. El modelo debe mapear el repositorio, entender la arquitectura, detectar convenciones, revisar zonas delicadas y decidir qué merece la pena arreglar. Esa parte sí justifica usar un modelo potente.
La segunda fase es distinta. Si el plan está bien escrito, implementar una corrección concreta puede ser una tarea mucho más mecánica: cambiar un archivo, eliminar una duplicación, añadir un test, ajustar una migración, ejecutar comandos y verificar salidas. Ahí puede entrar un modelo más barato o incluso un desarrollador junior con una guía clara.
| Fase | Quién debería hacerla | Motivo |
| Leer y mapear el repositorio | Modelo potente | Requiere comprensión global |
| Detectar problemas reales | Modelo potente | Necesita juicio técnico |
| Priorizar hallazgos | Modelo potente o tech lead | Hay que valorar impacto y esfuerzo |
| Escribir planes | Modelo potente | La calidad del plan define la ejecución |
| Implementar pasos acotados | Modelo barato o humano | Tarea más guiada y verificable |
| Revisar el diff | Modelo potente o humano senior | Control final de alcance y calidad |
Este patrón puede ayudar a controlar costes. En vez de dejar que un modelo caro implemente, pruebe, falle, vuelva a intentar y consuma más tokens, se le pide que haga aquello donde más valor aporta: razonar. La ejecución queda encapsulada en instrucciones precisas.
Planes autocontenidos para evitar improvisaciones
Uno de los puntos más interesantes de shadcn/improve es cómo escribe los planes. No se limita a decir “mejora el rendimiento de esta función” o “refactoriza este módulo”. Cada plan debe incluir contexto suficiente para que un ejecutor que no ha visto la auditoría original pueda trabajar.
Eso incluye rutas exactas de archivos, extractos del código actual, convenciones del repositorio, comandos de verificación, salidas esperadas, criterios de finalización y condiciones de parada. Estas condiciones son clave: si la realidad del código no coincide con lo descrito en el plan, el agente debe detenerse y reportarlo en vez de improvisar.
| Elemento del plan | Por qué importa |
| Rutas exactas | Evita búsquedas innecesarias |
| Extractos de código | Da contexto sin depender de la sesión previa |
| Comandos de test/lint/build | Convierte el éxito en algo verificable |
| Salidas esperadas | Reduce ambigüedad |
| Criterios de finalización | Define cuándo una tarea está hecha |
| Límites de alcance | Evita cambios laterales |
| Condiciones de parada | Impide que un modelo pequeño invente soluciones |
| Commit de referencia | Detecta si el plan se ha quedado desfasado |
Este diseño es especialmente útil para modelos pequeños. Un agente menos capaz falla más cuando tiene que decidir por su cuenta. Si recibe un plan con pasos concretos, límites claros y pruebas verificables, la probabilidad de que se salga del camino baja mucho.
Auditorías con evidencias del repositorio
shadcn/improve no pretende generar recomendaciones genéricas. Su auditoría se reparte por áreas como corrección, seguridad, rendimiento, tests, deuda técnica, dependencias, experiencia de desarrollador, documentación y dirección del proyecto. Cada hallazgo debe apoyarse en evidencias del propio código, con referencias a archivos y líneas.
Eso reduce uno de los problemas habituales de la IA aplicada al desarrollo: los falsos positivos. Muchos modelos tienden a sobrerreportar, detectar riesgos teóricos o sugerir mejoras que no encajan con el proyecto. Aquí el flujo obliga a revisar los hallazgos antes de convertirlos en planes. Si algo no es un problema real, se rechaza y queda registrado para que no vuelva a aparecer en la siguiente ejecución.
| Categoría | Ejemplos de hallazgos útiles |
| Corrección | Casos borde, errores lógicos, validaciones incompletas |
| Seguridad | Riesgos con evidencia en código |
| Rendimiento | Algoritmos caros, consultas repetidas, bucles innecesarios |
| Tests | Zonas críticas sin cobertura |
| Deuda técnica | Duplicaciones, abstracciones deterioradas, TODOs antiguos |
| Dependencias | Migraciones pendientes o paquetes problemáticos |
| DX | Comandos confusos, mala documentación de entorno |
| Documentación | Guías desactualizadas o incompletas |
| Producto | Sugerencias justificadas por el estado real del repositorio |
El resultado se presenta como una tabla priorizada por impacto, esfuerzo y confianza. Después el usuario elige qué hallazgos quiere convertir en planes. Esta parte mantiene el control humano: la IA propone, pero el equipo decide qué merece entrar en el backlog.
Útil para equipos, no solo para pruebas individuales
Aunque el proyecto puede usarse en repositorios personales, su valor real aparece en equipos con bases de código vivas. Un monorepo grande, una aplicación con deuda técnica acumulada o un producto con varios módulos pueden beneficiarse de una herramienta que convierte hallazgos dispersos en planes revisables.
También puede servir antes de una pull request. El comando /improve branch limita la auditoría a los cambios de la rama actual, lo que permite detectar problemas antes de pedir revisión humana. Para equipos que ya trabajan con GitHub Issues, la opción --issues puede publicar los planes directamente como tareas.
| Caso de uso | Cómo ayuda shadcn/improve |
| Auditoría inicial de un repo | Detecta problemas y los ordena |
| Revisión antes de PR | Analiza solo cambios de la rama |
| Reducción de deuda técnica | Convierte problemas en planes accionables |
| Seguridad | Focaliza la revisión en riesgos concretos |
| Rendimiento | Busca cuellos de botella con evidencia |
| Backlog técnico | Publica planes como issues |
| Trabajo con agentes baratos | Les da instrucciones claras y verificables |
| Revisión de planes existentes | Critica y mejora especificaciones previas |
La opción /improve reconcile también es importante. Sirve para revisar qué planes siguen vigentes, cuáles quedaron bloqueados, cuáles se arreglaron por otra vía y cuáles deben actualizarse porque el repositorio cambió. En proyectos reales, esta función puede ser tan útil como la auditoría inicial, porque el backlog técnico envejece rápido.
Más proceso y menos “vibe coding”
La popularidad del desarrollo asistido por IA ha traído una fase de entusiasmo en la que muchos programadores prueban a pedir cambios amplios a un agente y aceptar el resultado si parece funcionar. Ese estilo puede ser útil para prototipos, pero no siempre encaja con software mantenido por equipos, con tests, seguridad, convenciones y responsabilidades claras.
shadcn/improve propone una alternativa más disciplinada. No elimina la creatividad ni la velocidad de los agentes, pero los coloca dentro de un proceso. Primero se audita. Luego se prioriza. Después se planifica. Más tarde se ejecuta en un entorno aislado. Finalmente se revisa y el humano decide si se integra.
Esto conecta con una idea que cada vez se verá más en el desarrollo con IA: los mejores resultados no vendrán de agentes que hagan todo sin control, sino de flujos donde cada modelo tenga una función concreta. El modelo caro actúa como arquitecto o tech lead. El modelo barato actúa como ejecutor. Las pruebas actúan como juez automático. El desarrollador mantiene la decisión final.
Un repo pequeño con una idea grande
Lo bueno de shadcn/improve no es que prometa sustituir a un equipo de ingeniería. Es precisamente lo contrario: asume que el equipo existe, que el código importa, que las pruebas importan y que el control humano sigue siendo necesario. Su valor está en reducir el caos de la IA aplicada al desarrollo y convertirlo en planes que se pueden leer, discutir, ejecutar y revisar.
Que sea abierto y gratuito hace que la idea sea todavía más atractiva. Cualquier equipo puede probarlo sin comprometerse con una nueva plataforma, sin comprar una herramienta cerrada y sin cambiar por completo su forma de trabajar. Si encaja, se integra. Si no, los planes siguen siendo Markdown y el aprendizaje queda.
La IA para programar no necesita más magia. Necesita mejores flujos. shadcn/improve apunta en esa dirección con una propuesta sencilla: no dejes que el modelo más caro pierda tiempo picando piedra; úsalo para pensar, priorizar y escribir buenos planes. Después deja que otro ejecute, con límites claros y pruebas delante.
Preguntas frecuentes
¿Qué es shadcn/improve?
Es una Agent Skill abierta y gratuita que audita un repositorio, detecta mejoras y genera planes de implementación en Markdown para que otros agentes o humanos los ejecuten.
Por qué es interesante que sea open source?
Porque permite revisar cómo funciona, adaptarlo a flujos propios y usarlo sin depender de una plataforma cerrada. Además, se publica bajo licencia MIT.
Implementa cambios directamente en el código?
No. La skill escribe planes en la carpeta plans/. La ejecución puede delegarse después a otro agente en un worktree aislado, pero el merge queda en manos del usuario.
Qué problema resuelve frente a otros agentes de código?
Reduce improvisación y costes: usa el modelo más capaz para auditar y planificar, y permite que modelos más baratos ejecuten tareas bien definidas con verificaciones claras.
