Claude Code es la herramienta de codificación agéntica más capaz disponible en 2026. Pero como cualquier herramienta, los resultados que obtienes son tan buenos como las instrucciones que le das. Esta guía reúne más de 40 prompts probados en producción para todos los casos de uso principales: debugging, arquitectura, refactoring, testing, documentación e implementación completa de funcionalidades.
Todos los prompts aquí han sido validados para producir un output significativamente mejor que una petición genérica.
Por Qué los Prompts Importan Más con Claude Code
Claude Code opera de forma agéntica — no solo responde preguntas, toma acciones: lee archivos, ejecuta comandos, edita código, instala paquetes. Un prompt mal escrito al inicio de una sesión puede hacer que:
- Refactorice los archivos equivocados
- Instale dependencias que no querías
- Tome decisiones arquitectónicas que rompan otras partes de tu código
- Produzca código que funciona pero no sigue tus patrones existentes
Los prompts que verás a continuación siguen un patrón consistente: contexto → restricción → petición clara.
1. Debugging y Corrección de Errores
Estos son los prompts que más tiempo ahorran en el día a día.
Corregir un error específico
Tengo este error en producción:
[PEGA EL ERROR + STACK TRACE]
El error ocurre en `src/api/payments.ts` al procesar eventos webhook de Stripe.
NO modifiques el schema de base de datos ni ningún otro archivo. Solo corrige la causa raíz de este error.
Muéstrame qué has cambiado y por qué.
Diagnosticar un problema de rendimiento
La función `processUserBatch()` en `src/workers/sync.ts` está tardando 8-12 segundos
para lotes de 500 usuarios. Debería tardar menos de 2 segundos.
Analiza la función e identifica todos los cuellos de botella de rendimiento.
Lista los 3 mejores arreglos ordenados por impacto esperado y luego impleméntalos.
No cambies la firma de la función — se llama en 6 sitios distintos.
Encontrar el origen de una fuga de memoria
El uso de memoria de nuestro servidor Node.js crece de 200MB a 1,2GB en 6 horas y luego
se cae. Analiza `src/server/` y `src/workers/` buscando:
1. Event listeners que nunca se eliminan
2. Closures que retienen referencias a objetos grandes
3. Intervalos o timers que no se limpian
4. Cualquier lógica de caché que crece sin límite
Produce una lista priorizada de sospechosos con el archivo y número de línea de cada uno.
2. Refactoring de Código
Refactorizar sin romper los tests existentes
Refactoriza `src/lib/userService.ts` para:
1. Dividirlo en módulos enfocados: `userAuth.ts`, `userProfile.ts`, `userPermissions.ts`
2. Reemplazar el enfoque basado en clases con funciones puras
3. Añadir tipos TypeScript correctos donde actualmente faltan
Restricciones duras:
- Todos los tests existentes en `__tests__/userService.test.ts` deben seguir pasando
- No cambies ninguna firma de función exportada
- Mantén el mismo archivo para re-exportar todo para que los imports en otros archivos no se rompan
Modernizar código legacy
`src/utils/dataProcessor.js` fue escrito en 2019 con callbacks y sin tipos.
Modernízalo:
1. Convirtiéndolo a TypeScript
2. Reemplazando todos los callbacks con async/await
3. Añadiendo manejo de errores correcto con errores tipados
4. Añadiendo comentarios JSDoc a todas las funciones exportadas
NO añadas ninguna dependencia nueva. Usa solo lo que ya está en package.json.
Extraer un hook reutilizable
En `src/components/Dashboard.tsx` hay lógica de estado + efecto para obtener y cachear
datos paginados (líneas 45-120).
Extrae esto en un hook React reutilizable llamado `usePaginatedFetch` en `src/hooks/`.
El hook debe:
- Aceptar un parámetro de tipo genérico para la forma de los datos
- Aceptar la función de fetch como parámetro, no llamar a la API directamente
- Exponer: `data`, `isLoading`, `error`, `page`, `hasNextPage`, `fetchNextPage`
- Gestionar la limpieza al desmontar
Después de crear el hook, actualiza Dashboard.tsx para usarlo. No cambies el output de UI.
3. Escritura de Tests
Claude Code es excepcional generando tests cuando se le da suficiente contexto.
Generar tests unitarios completos
Escribe tests unitarios completos para `src/lib/pricing.ts` usando Vitest.
Los tests deben cubrir:
- Todas las funciones exportadas
- Casos extremos: valores cero, números negativos, campos opcionales ausentes
- Valores límite: límites del plan gratuito, límites del plan máximo
- Casos de error: tipos de entrada inválidos, campos requeridos ausentes
Usa los patrones de test existentes en `__tests__/auth.test.ts` como referencia de estilo.
Mockea cualquier llamada externa usando `vi.mock()`.
Objetivo: 100% de cobertura de ramas.
Escribir tests de integración
Escribe tests de integración para el endpoint `/api/checkout` en `src/app/api/checkout/route.ts`.
Usa el setup de Supertest existente en `__tests__/integration/setup.ts`.
Cubre estos escenarios:
1. Petición válida con usuario autenticado → 200 + URL de sesión
2. Petición válida con usuario no autenticado → 401
3. priceId inválido → 400 con error de validación
4. Timeout de la API de Stripe → 503 con cabecera retry-after
5. Petición de sesión duplicada (idempotencia) → 200 con sesión existente
Mockea Stripe usando `__mocks__/stripe.ts` (ya existe).
4. Arquitectura y Diseño de Sistemas
Diseñar una nueva funcionalidad
Necesito añadir un sistema de notificaciones en tiempo real a nuestra app Next.js.
Stack actual: Next.js 15, Supabase (Postgres + Auth), despliegue en Vercel.
Restricciones:
- Debe funcionar dentro de los límites serverless de Vercel (sin conexiones persistentes desde API routes)
- Presupuesto: menos de 50€/mes a 10.000 DAU
- Debe soportar: toasts in-app, resúmenes por email, push notifications (futuro)
Diseña la arquitectura. Para cada componente, especifica:
1. Qué hace
2. Qué servicio/librería lo gestiona
3. Por qué lo elegiste frente a las alternativas
4. Cualquier tradeoff que deba conocer
NO escribas ningún código todavía. Quiero revisar el diseño primero.
Revisar y criticar la arquitectura existente
Lee `src/` y `docs/architecture.md`.
Dame una revisión arquitectónica honesta:
1. ¿Cuáles son los 3 mayores riesgos o cuellos de botella arquitectónicos?
2. ¿Qué fallaría primero si escalamos a 10 veces el tráfico actual?
3. ¿Qué partes del codebase serán más difíciles de mantener en 12 meses?
Sé directo. No me digas qué está bien — quiero saber qué necesita atención.
5. Implementación Completa de Funcionalidades
Construir una funcionalidad completa desde la spec
Implementa una funcionalidad de "búsquedas guardadas" para la página de directorio.
Spec:
- Los usuarios pueden guardar cualquier combinación de filtros activa con un nombre personalizado
- Las búsquedas guardadas aparecen en un dropdown bajo la barra de búsqueda (máx 10 por usuario)
- Las búsquedas guardadas persisten en localStorage (sin auth requerida para el MVP)
- Una búsqueda guardada puede eliminarse individualmente o borrarse todas a la vez
- Al hacer clic en una búsqueda guardada se aplican todos sus filtros inmediatamente
- El dropdown se muestra cuando el usuario tiene al menos 1 búsqueda guardada
Archivos a modificar: `src/app/[locale]/directory/page.tsx`, `src/components/directory/FilterBar.tsx`
Nuevos archivos a crear: `src/hooks/useSavedSearches.ts`, `src/components/directory/SavedSearches.tsx`
Sigue los patrones de UI existentes (tarjetas de cristal, acentos teal, clases Tailwind).
Añade tipos TypeScript correctos. Sin nuevas dependencias.
Implementar un endpoint de API
Crea un nuevo endpoint de API: `POST /api/compare`
Debe:
1. Aceptar: `{ toolSlugs: string[] }` — 2 a 4 slugs
2. Validar: los slugs existen en la base de datos de herramientas, longitud del array 2-4
3. Devolver: datos completos de herramienta para cada slug, estructurados para comparación (rating, pricing, highlights)
4. Cachear: resultados en Redis con TTL de 1 hora (usa el existente `src/lib/redis.ts`)
5. Rate limit: 20 peticiones/minuto por IP (usa el middleware existente)
Las respuestas de error deben seguir nuestro formato de error existente de `src/lib/apiError.ts`.
Añade la ruta en `src/app/api/compare/route.ts`.
Escribe los tests del handler en `__tests__/api/compare.test.ts`.
6. Documentación
Generar documentación inline
Añade comentarios JSDoc a cada función y tipo exportado en `src/lib/content.ts`.
Cada comentario debe incluir:
- @description — qué hace la función en inglés simple (1-2 frases)
- @param — todos los parámetros con sus tipos y qué representan
- @returns — qué devuelve la función
- @throws — cualquier error que pueda lanzar
- @example — un ejemplo de uso real
Sigue el estilo de documentación de `src/lib/seo.ts` que ya está documentado.
7. Seguridad y Code Review
Auditoría de seguridad de un archivo específico
Realiza una auditoría de seguridad de `src/app/api/` (todos los route handlers).
Busca:
1. Comprobaciones de autenticación/autorización ausentes
2. Riesgos de inyección SQL (concatenación de queries sin sanitizar)
3. Validación de input ausente o problemas de coerción de tipos
4. Datos sensibles expuestos en respuestas de API
5. Rate limiting ausente en operaciones costosas
6. Mala configuración de CORS
7. Uso inseguro de `eval()` o `new Function()`
Para cada problema encontrado:
- Severidad: Crítica / Alta / Media / Baja
- Archivo + número de línea
- Explicación del riesgo
- Recomendación de solución
No arregles nada todavía. Quiero el informe primero.
8. Base de Datos y Migraciones
Escribir una migración segura
Escribe una migración de Postgres para añadir una columna `subscription_tier` a la tabla `users`.
Requisitos:
- Tipo: ENUM ('free', 'pro', 'enterprise')
- Por defecto: 'free'
- NOT NULL
- La migración debe ser segura para ejecutar en una base de datos de producción activa con cero downtime
- Incluye migraciones `up` y `down`
- Añade un índice si se va a filtrar o hacer join frecuentemente
Archivo: `migrations/0024_add_subscription_tier.sql`
Sigue el formato de las migraciones existentes en `migrations/`.
9. Meta-Prompts para Claude Code
Estos prompts te ayudan a obtener mejores resultados de Claude Code en sí mismo.
Empezar una sesión correctamente
Antes de hacer ningún cambio, lee estos archivos:
- `README.md`
- `src/lib/content.ts` (nuestro modelo de datos)
- `src/app/[locale]/directory/page.tsx` (la página principal que editarás)
Luego resume:
1. Qué hace la app
2. El stack técnico (framework, estilos, gestión de estado)
3. Patrones o convenciones que deba conocer
4. Preguntas que tengas antes de empezar
Espera mi confirmación antes de tocar ningún archivo.
Definir el alcance de una tarea
Tu tarea es ÚNICAMENTE añadir soporte para el toggle de modo oscuro en el componente Navbar.
NO:
- Modifiques ningún archivo de página
- Cambies ningún valor de color en globals.css
- Añadas nuevas dependencias
- Cambies la configuración de Tailwind
Cuando termines, lista cada archivo que hayas cambiado y por qué.
Si crees que algo más necesita cambiar, dímelo — no lo hagas automáticamente.
Pedir un plan antes de ejecutar
Quiero que [DESCRIPCIÓN DE TAREA].
Antes de escribir ningún código:
1. Lista cada archivo que necesitarás leer primero
2. Lista cada archivo que modificarás o crearás
3. Describe tu enfoque en español simple (3-5 frases)
4. Señala cualquier suposición que estés haciendo que deba confirmar
Solo empieza a ejecutar cuando yo diga "adelante".
Consejos Pro para Mejores Sesiones con Claude Code
1. Define siempre qué NO hacer. Claude Code a veces "ayuda" arreglando cosas adyacentes que nota. Añadir No modifiques X previene la expansión de alcance.
2. Referencia patrones existentes. "Sigue el estilo de src/lib/seo.ts" produce output mucho más consistente que pedir código genérico.
3. Pide el plan antes del código. Para tareas complejas, añade siempre "No escribas código todavía, solo dime tu enfoque." Revisa el plan, luego ejecuta.
4. Usa prompts de checkpoint. Después de cada cambio significativo: "Antes de continuar, lista los archivos que has cambiado y verifica que los tests siguen pasando."
5. Dale los mensajes de error reales. Claude Code es dramáticamente mejor cuando le pegas el error real + stack trace frente a describir el error con palabras.
6. Restringe las dependencias. Añade siempre "Sin nuevas dependencias" salvo que quieras específicamente nuevas. Claude Code instalará paquetes libremente si no lo detienes.
Conclusión
La diferencia entre un desarrollador que usa estos prompts y uno que no lo hace no es pequeña. Claude Code con prompts precisos y bien restringidos puede completar en 20 minutos lo que de otro modo llevaría horas. La clave es tratarlo como un contratista muy capaz que necesita un brief preciso — no como un lector de mentes.
Guarda esta página en favoritos. Los prompts se irán actualizando a medida que Claude Code evolucione.