Biblioteca de Prompts
Plantillas de prompts listas para tu agente de codificación con IA (Claude Code, Cursor, Aider, Codex, Antigravity y más) — solo rellena los <MARCADORES> y empieza.
Stand / as of: 2026-07-14
🔧 Refactorización
Refactorización Segura en Pequeños Pasos
Cuando quieres reestructurar código existente sin cambiar su comportamiento.
Refactoriza <ARCHIVO/MÓDULO> para mejorar <OBJETIVO, p.ej. legibilidad/estructura>. Reglas: - NO cambies el comportamiento externo (input/output, API, efectos secundarios deben quedar idénticos) - Trabaja en pasos pequeños y revisables uno por uno - Después de cada paso, ejecuta las pruebas (<COMANDO DE PRUEBA>) y muéstrame el resultado - Detente y pregunta si un paso cambiaría el comportamiento Al final, resume todos los pasos y los resultados de las pruebas como evidencia.
💡 Mantén los diffs pequeños — revisar un paso a la vez es más fácil que revisar todo de golpe.
Extraer Función sin Cambiar el Comportamiento
Cuando una función/método es demasiado grande o está demasiado anidada y quieres extraer una parte de forma limpia.
En <ARCHIVO>, función <NOMBRE DE FUNCIÓN>: extrae el bloque de código que hace <DESCRIPCIÓN DE LA PARTE> en una función propia, con un nombre claro. - El comportamiento debe quedar exactamente igual (mismos inputs -> mismos outputs, mismos casos de error) - Sigue las convenciones de nombres/estilo ya existentes en el archivo - Si no existe ningún test: escribe primero uno que asegure el comportamiento actual, luego refactoriza - Ejecuta las pruebas después y muéstrame el resultado Explica brevemente por qué la nueva estructura es más clara.
💡 ¿No hay ningún test? Escribe primero un test de caracterización (ver las plantillas de Pruebas), luego refactoriza.
Migrar un Patrón/Dependencia, Archivo por Archivo
Cuando migras una librería, un patrón o una versión de API a lo largo de varios archivos.
Migra <PATRÓN/LIBRERÍA ANTIGUO> a <PATRÓN/LIBRERÍA NUEVO> en <ALCANCE, p.ej. carpeta/módulo>. - Primero lista TODOS los archivos afectados antes de cambiar nada - Migra un archivo tras otro (los archivos interdependientes como un grupo pequeño), muestra cada cambio por separado - Después de cada archivo, ejecuta las pruebas/el build (<COMANDO DE PRUEBA>) y muestra el resultado - Si tienes dudas (p.ej. comportamiento antiguo poco claro): detente y pregunta en vez de adivinar Al final: lista de los archivos migrados más los casos pendientes que queden abiertos.
💡 Si hay muchísimos archivos: prueba primero con 2-3, afina el prompt y luego aplícalo al resto.
Claude Code: Best practices ↗ · Anthropic: Building Effective Agents ↗
🐛 Depuración
Búsqueda Sistemática de Errores con Hipótesis
Cuando aparece un bug y la causa no es obvia.
Bug: <DESCRIPCIÓN DEL ERROR / MENSAJE DE ERROR> Área probable: <ARCHIVO/MÓDULO, si se conoce> Procede así: 1. Formula 2-3 hipótesis concretas sobre cuál podría ser la causa 2. Comprueba cada hipótesis de forma deliberada (lee código, logs, un test pequeño) — no adivines 3. Escribe un test que reproduzca el bug ANTES de arreglarlo 4. Corrige la causa raíz, no solo el síntoma (nada de ocultar errores con try/catch) 5. Muestra el test fallando antes y en verde después Detente y pregunta si ninguna hipótesis explica el bug.
💡 "Causa raíz, no síntoma" — no te limites a capturar el error, corrige lo que lo provoca.
Detectar un Test Inestable (Flaky)
Cuando un test falla de forma intermitente y quieres encontrar la causa (timing, orden, estado compartido).
El test <NOMBRE DEL TEST/ARCHIVO> es inestable (falla de vez en cuando). - Ejecuta el test <N, p.ej. 20> veces de forma aislada (<COMANDO DE PRUEBA>) y anota éxito/fallo - Revisa las causas típicas: estado compartido entre tests, race conditions, dependencia de tiempo/orden, llamadas externas sin mockear - Formula una hipótesis sobre la causa y respáldala con un test de reproducción específico - Propón un fix que corrija la causa (no solo un retry/skip) - Después del fix: vuelve a ejecutar el test varias veces y muestra el resultado Si no se encuentra una causa clara: resume qué se descartó y qué habría que revisar a continuación.
💡 La lógica de retry o @skip no es un fix — solo es un parche que este prompt descarta a propósito.
Primero Reproducir, Luego Arreglar
Cuando un usuario/informe reporta un bug pero todavía no tienes una forma segura de reproducirlo.
Bug reportado: <DESCRIPCIÓN, p.ej. de un ticket/soporte> Comportamiento esperado: <QUÉ DEBERÍA PASAR> Comportamiento real: <QUÉ PASA EN SU LUGAR> 1. Encuentra la ruta de código relevante (punto de partida: <ÁREA RELEVANTE, p.ej. src/auth/>) 2. Escribe un test que falle y reproduzca el bug exactamente 3. Muéstrame el test fallando ANTES de escribir el fix — yo confirmo que es el bug correcto Si no puedes reproducir el bug: detente e informa qué has comprobado y descartado. 4. Solo entonces: implementa el fix, el nuevo test debe pasar en verde y toda la suite de tests debe seguir en verde
💡 La pausa de confirmación antes del fix evita que se arregle el bug equivocado.
🔎 Revisión
Auto-Revisión Adversarial
Antes de marcar un cambio como terminado — deja que una instancia nueva lo revise con espíritu crítico.
Usa un subagente/una sesión nueva para revisar el diff de <ALCANCE, p.ej. PR/branch/archivo> contra <PLAN/REQUISITO, p.ej. PLAN.md o la descripción del ticket>. El revisor recibe SOLO el diff y el requisito — no la justificación de por qué el cambio se hizo así. Comprueba: - ¿Está realmente implementado cada requisito? - ¿Hay casos límite del requisito sin test? - ¿Se cambió algo fuera del alcance? Reporta solo las brechas que afecten a la corrección o a los requisitos — no meras preferencias de estilo.
💡 Un revisor al que se le pide buscar brechas casi siempre encuentra alguna — no persigas cada hallazgo, solo los que realmente afectan a la corrección.
Revisión de PR con Niveles de Severidad
Cuando quieres revisar un pull request/diff de forma estructurada en vez de con una lista larga y desordenada.
Revisa el diff en <ALCANCE, p.ej. PR #123 / nombre del branch>. Clasifica cada hallazgo en exactamente un nivel: - CRITICAL: bug, brecha de seguridad o riesgo de pérdida de datos - MAJOR: comportamiento incorrecto en un caso realista, manejo de errores ausente - MINOR: estilo, nombres, mejoras pequeñas Para cada hallazgo: archivo:línea, cuál es el problema, propuesta de fix concreta. Sin comentarios de elogio genéricos. Si no se encuentra nada, dilo explícitamente en vez de inventar hallazgos.
💡 Los niveles explícitos evitan que un detalle menor tenga el mismo peso que un bug real.
Verificar la Implementación contra el Plan
Después de implementar una tarea planificada — comprobar si realmente se hizo todo lo del plan.
Compara la implementación actual en <ALCANCE> con el plan en <FUENTE DEL PLAN, p.ej. PLAN.md o el ticket>. Crea una checklist a partir del plan y repásala punto por punto: - Implementado y probado - Implementado, pero sin test - No implementado - Hecho de más (no está en el plan, pero sí en el diff) Respalda cada punto con una referencia a archivo/línea o un resultado de test, sin suposiciones.
💡 Úsalo como criterio de parada — la tarea solo se considera terminada cuando todos los puntos están 'implementados y probados'.
🗺️ Planificación
Primero el Plan, Luego el Código
Para tareas que afectan a varios archivos, tienen un enfoque poco claro, o cuando el módulo te resulta desconocido.
Antes de cambiar nada: lee <ÁREA RELEVANTE, p.ej. src/auth/> y entiende cómo funciona actualmente <TEMA, p.ej. login/sesiones>. Después crea un plan para <OBJETIVO/FEATURE>: - ¿Qué archivos deben cambiar? - ¿Qué orden de pasos tiene sentido? - ¿Qué casos límite/riesgos ves? - ¿Cómo se verificará al final (qué tests/checks)? Muéstrame el plan primero. Empieza a programar solo después de que yo confirme el plan.
💡 Para cambios pequeños y obvios (una errata, una línea) el paso de planificación no vale la pena — deja que lo implemente directamente.
Dividir un Feature en Etapas
Cuando un feature es demasiado grande para un solo intento y hay que dividirlo en piezas comprobables.
Quiero construir <DESCRIPCIÓN DEL FEATURE>. Divide el feature en etapas, donde cada etapa: - funciona/se puede probar por sí sola (sin estados intermedios a medio romper) - tiene una verificación clara (test, build, comprobación manual) Lista las etapas en orden con 1-2 frases de descripción cada una. Implementa SOLO la etapa 1, ejecuta la verificación y muéstrame el resultado antes de pasar a la siguiente etapa.
💡 Así cada etapa se mantiene revisable, en vez de terminar con un diff gigante al final.
Claude Code: Best practices ↗ · Anthropic: Building Effective Agents ↗
Dejar que te Entrevisten Primero, Luego Escribir la Spec
Para features grandes/nuevos donde tú mismo aún no has pensado todos los detalles.
Quiero construir <IDEA BREVE DEL FEATURE>. Entrevístame en detalle sobre esto antes de construir nada. Pregunta sobre la implementación técnica, UX, casos límite y tradeoffs — nada de preguntas obvias, ve a los puntos difíciles que quizá se me hayan pasado por alto. Sigue preguntando hasta que todo lo importante quede aclarado. Después escribe una spec completa (archivos/interfaces implicados, qué queda explícitamente FUERA del alcance, un paso de verificación final) en <ARCHIVO DE SPEC, p.ej. SPEC.md>.
💡 Para la implementación real, empieza una sesión nueva y limpia usando la spec terminada como contexto.
🧪 Pruebas
Tests de Caracterización para Código Legacy
Cuando tienes que tocar código legacy desconocido/sin tests y primero quieres asegurar el comportamiento actual.
El archivo/módulo <ARCHIVO/MÓDULO> actualmente no tiene tests (suficientes) y pronto tengo que modificarlo. Escribe primero tests de caracterización: tests que documenten y aseguren el comportamiento ACTUAL — incluyendo casos límite y de error, aunque el comportamiento parezca extraño. - Ningún cambio de comportamiento en el código mismo en este paso - Ejecuta los tests y muestra que están en verde - Enumera brevemente qué comportamiento resultó sorprendente/cuestionable (para aclararlo más adelante)
💡 Estos tests son tu red de seguridad para el siguiente paso de refactorización — no los borres, ni siquiera cuando el comportamiento se cambie más adelante a propósito.
Test-First para un Bugfix
Cuando arreglas un bug concreto y quieres asegurarte de que no vuelva a aparecer.
Bug: <DESCRIPCIÓN/MENSAJE DE ERROR> en <ARCHIVO/MÓDULO> 1. Escribe primero un test que actualmente falle y reproduzca exactamente este bug 2. Muéstrame el test fallando 3. Solo entonces implementa el fix 4. El nuevo test debe pasar en verde, todos los tests existentes deben seguir en verde Casos de ejemplo que el test debe cubrir: <CASOS DE TEST, p.ej. la entrada X da Y>
💡 El test se queda en el repo después del fix — evita que el mismo bug vuelva silenciosamente (regresión).
📖 Comprender
Visión General de la Codebase en 3 Niveles
Al entrar en una codebase o un módulo nuevo/desconocido.
Dame una visión general de <ALCANCE, p.ej. este repo / la carpeta src/payments> en 3 niveles: 1. Panorama general: qué hace el sistema, cuáles son los bloques principales (1 párrafo + lista) 2. Estructura: las carpetas/módulos más importantes y su responsabilidad 3. Detalles: para <PARTE ESPECÍFICA, p.ej. el flujo de una petición>: paso a paso, qué archivos/funciones están implicados Usa solo lo que realmente está en el código, sin suposiciones — donde algo no esté claro, dilo explícitamente.
💡 Después pregunta de forma puntual en vez de pedirlo todo de golpe — así mantienes el contexto pequeño.
Rastrear el Flujo de Datos de una Función
Cuando quieres entender de dónde vienen los datos y hacia dónde fluyen en un proceso concreto.
Rastrea el flujo de datos a partir de <PUNTO DE PARTIDA, p.ej. función/endpoint X>. - ¿De dónde vienen los datos de entrada (quien llama, request, BD, etc.)? - ¿Qué funciones/módulos procesan los datos y en qué orden? - ¿Dónde se modifica el estado (state, escrituras en BD, efectos secundarios)? - ¿Dónde termina el flujo (respuesta, almacenamiento, entrega)? Presenta esto como una lista numerada paso a paso con referencias archivo:línea. Si un paso no está claro/es ambiguo, márcalo en vez de adivinar.
💡 Para flujos más complejos, pide además un breve diagrama Mermaid junto a la lista.
Fuentes: Template patterns from the linked official best practices; adapt templates to your project.