Ingeniería de prompts para desarrolladores

¿Por qué importa el prompt engineering para desarrolladores?

El prompt engineering no es solo para expertos en IA — es una habilidad fundamental para cualquier desarrollador que use herramientas como Claude, GitHub Copilot o ChatGPT en su flujo de trabajo diario. La diferencia entre un prompt genérico y uno bien estructurado puede ser la diferencia entre recibir código inutilizable y obtener exactamente la solución que necesitas.

Como desarrollador, ya piensas de forma estructurada: defines interfaces, escribes especificaciones y documentas requisitos. El prompt engineering aplica esa misma mentalidad a la comunicación con modelos de IA.

Estructura de un buen prompt

Un prompt efectivo tiene cuatro componentes principales:

1. Contexto: ¿Cuál es la situación? ¿Qué tecnologías usas? ¿Qué existe ya?
2. Tarea: ¿Qué quieres que haga exactamente?
3. Formato: ¿Cómo quieres la respuesta? ¿Código, explicación, lista?
4. Restricciones: ¿Qué debe evitar? ¿Qué limitaciones hay?

Ejemplo: prompt débil

Haz un formulario de contacto

Ejemplo: prompt efectivo

Contexto: Estoy trabajando en una app Next.js 15 con App Router,
React 19, TypeScript estricto y Tailwind CSS. Uso react-hook-form
para formularios y zod para validación.

Tarea: Crea un componente ContactForm que tenga campos para
nombre, email y mensaje. El formulario debe enviar los datos
via POST a /api/contact.

Formato: Un componente client-side con "use client", tipado
completo, y validación con zod schema.

Restricciones: No uses bibliotecas adicionales. Sigue el patrón
de componentes funcionales. Incluye estados de loading y error.
Usa clases de Tailwind para el estilo.

El archivo CLAUDE.md como prompt persistente

Si trabajas con Claude Code, el archivo CLAUDE.md actúa como un prompt que se carga automáticamente en cada sesión. Esto significa que no necesitas repetir el contexto de tu proyecto en cada interacción.

Un buen CLAUDE.md incluye:

• Stack tecnológico y versiones.
• Estructura del proyecto.
• Convenciones de código (naming, patterns, estilo).
• Comandos frecuentes de desarrollo.
• Restricciones explícitas (qué no hacer).

# CLAUDE.md

## Stack
- Next.js 15 (App Router)
- React 19 + TypeScript 5
- Tailwind CSS 3.4
- react-hook-form + zod

## Convenciones
- Componentes: PascalCase, funcionales, "use client" solo cuando sea necesario
- Siempre incluir atributos de accesibilidad (aria-label, role)
- Usar cn() de utils/classNames para clases condicionales

## No hacer
- No añadir dependencias sin justificación
- No debilitar TypeScript strict mode
- No crear archivos de test

Al tener este contexto siempre disponible, tus prompts individuales pueden ser más concisos porque Claude ya conoce el contexto de tu proyecto.

Patrones útiles de prompting

Chain of Thought (Cadena de pensamiento)

Pide a Claude que razone paso a paso antes de dar una solución. Esto es especialmente útil para problemas de debugging o decisiones de arquitectura.

Analiza paso a paso por qué este componente se renderiza
infinitamente. Primero identifica las dependencias del useEffect,
luego verifica si alguna se recrea en cada render, y finalmente
propón una solución.

Few-Shot (Aprendizaje por ejemplos)

Proporciona ejemplos concretos del patrón que quieres que siga. Esto es mucho más efectivo que describir el patrón en abstracto.

Crea un hook personalizado siguiendo este patrón existente:

// hooks/useScroll.ts
export const useScroll = () => {
  const [scrollY, setScrollY] = useState(0);
  useEffect(() => {
    const handler = () => setScrollY(window.scrollY);
    window.addEventListener("scroll", handler);
    return () => window.removeEventListener("scroll", handler);
  }, []);
  return { scrollY };
};

Ahora crea un hook useMediaQuery que siga la misma estructura
y convenciones.

Role Prompting

Asigna un rol o perspectiva específica para obtener respuestas más enfocadas.

Actúa como un experto en rendimiento web. Revisa este componente
React y sugiere optimizaciones enfocadas en Core Web Vitals,
especialmente LCP y CLS.

Contexto efectivo: qué incluir y qué no

Qué SÍ incluir

• Código relevante: El componente o función específica con la que estás trabajando.
• Mensajes de error: El error completo, incluyendo stack trace.
• Comportamiento esperado vs actual: Qué debería pasar y qué pasa realmente.
• Tecnologías y versiones: "Next.js 15 con App Router" es muy diferente de "Next.js 12 con Pages Router".
• Intentos previos: Qué has probado ya y por qué no funcionó.

Qué NO incluir

• Código irrelevante: No pegues todo el archivo si el problema está en una función específica.
• Histórico innecesario: No cuentes la historia completa de tu proyecto si no es relevante para la tarea actual.
• Secretos: Nunca incluyas API keys, contraseñas o tokens de acceso en tus prompts.

Prompts para tareas comunes de desarrollo

Debugging

Este endpoint devuelve 500 en producción pero funciona en local.
Aquí está el código del Route Handler y el error del log de Vercel.
Analiza las posibles causas considerando diferencias entre
entornos (variables de entorno, conexiones de red, timeouts).

Refactoring

Refactoriza este componente de 200 líneas en componentes más
pequeños y reutilizables. Mantén la misma funcionalidad.
Extrae la lógica de negocio a un custom hook. Asegúrate de
que los tipos TypeScript se mantengan estrictos.

Code Review

Revisa este PR como si fueras un senior developer. Enfócate en:
1. Posibles bugs o edge cases no manejados
2. Rendimiento (re-renders innecesarios, memory leaks)
3. Accesibilidad
4. Seguridad (XSS, inyección, datos no sanitizados)
5. Adherencia a las convenciones del proyecto

Errores comunes al dar instrucciones a Claude

• Ser demasiado vago: "Mejora este código" no le da a Claude criterios claros sobre qué mejorar. Especifica: rendimiento, legibilidad, tipado, accesibilidad.
• Asumir contexto implícito: Claude no sabe qué proyecto estás usando a menos que se lo digas (o lo tenga en CLAUDE.md). Siempre proporciona el stack tecnológico.
• Pedir demasiado de una vez: "Crea toda la autenticación del proyecto" es demasiado amplio. Divide en pasos: modelo de usuario, login endpoint, middleware de sesión, etc.
• No especificar restricciones: Si no quieres que use cierta librería o patrón, dilo explícitamente. Claude elegirá lo que considere mejor si no le das restricciones.
• Ignorar el formato de salida: Si necesitas un componente React, dilo. Si necesitas SQL, dilo. Si necesitas una explicación sin código, dilo. El formato importa tanto como el contenido.

Tips avanzados

Conversaciones multi-turn

Aprovecha las conversaciones largas de forma estratégica. Empieza con el contexto general, luego profundiza en cada aspecto. Claude recuerda todo lo que se ha dicho en la sesión:

Turno 1: "Estoy construyendo un e-commerce con Next.js 15.
         Aquí está la estructura general del proyecto..."

Turno 2: "Ahora enfoquémonos en el carrito de compras.
         Quiero usar React Context para el estado..."

Turno 3: "El carrito funciona, pero necesito persistirlo
         en localStorage. ¿Cómo adapto el context?"

Sub-agentes

En Claude Code, puedes usar sub-agentes para delegar investigación o tareas paralelas. El agente principal puede pedir a un sub-agente que busque en el codebase mientras sigue trabajando en otra cosa:

Busca en todo el proyecto dónde se usa el componente Button
y crea una lista de todas las variantes de props que recibe.
Luego usa esa información para crear una interfaz TypeScript
unificada que cubra todos los casos de uso existentes.

Modo plan

Antes de pedir a Claude que implemente algo complejo, pídele que primero cree un plan:

Antes de escribir código, crea un plan detallado para implementar
el sistema de notificaciones push. Incluye:
- Qué archivos se crearán o modificarán
- Qué dependencias se necesitan
- El flujo de datos completo
- Posibles riesgos o decisiones de diseño

No escribas código todavía, solo el plan.

Una vez que revises y apruebes el plan, puedes pedir que lo ejecute paso a paso. Esto reduce errores y te da control sobre la dirección de la implementación.

Recuerda: El prompt engineering es una habilidad que se perfecciona con la práctica. Experimenta con diferentes estructuras y patrones, y observa cómo cambian las respuestas. Con el tiempo, desarrollarás un instinto para comunicar tus necesidades de forma clara y eficiente.