Prompts para programar con agentes: Claude Code, Copilot y Cursor

Pedir código a un agente no es escribir una frase y esperar un milagro: es especificar una tarea como lo harías con un desarrollador senior. La diferencia entre un prompt que produce código útil y uno que produce ruido está en cuatro elementos: tarea específica, contexto de archivos y stack, criterios de aceptación y límites. Esta guía cubre esos cuatro elementos, los patrones más usados (refactor, test, bug fix, feature) y cuándo conviene activar plan mode en Claude Code, Copilot o Cursor.

La estructura de un prompt de programación

El prompt mínimo que funciona tiene esta forma:

Tarea: {qué hay que hacer, en una frase, sin ambigüedad}

Contexto:
- Archivos relevantes: {rutas y por qué importan}
- Stack: {lenguaje, framework, versiones, gestor de paquetes}
- Convenciones del repo: {estilo, testing, branch policy}

Criterios de aceptación:
- {resultado observable 1}
- {resultado observable 2}

Límites:
- No tocar {archivos o módulos fuera de alcance}
- {restricciones: compatibilidad, rendimiento, seguridad}

La tarea "arregla el login" no es una tarea: no dice qué falla, dónde, ni cómo saber que quedó bien. "El login con Google devuelve 500 en producción después del deploy de ayer; revisa la ruta /api/auth/google, compara con el cambio del PR #482 y corrige la causa" sí lo es.

Contexto: lo que el agente no puede adivinar

Los agentes de programación leen tu repo, pero no leen tu mente. El contexto que más mejora las respuestas:

• Rutas exactas: "el bug está en src/lib/auth.ts, líneas 40-60, y el test en tests/auth.test.ts".
• Stack y versiones: "Next.js 16 con App Router, pnpm, TypeScript estricto, tests con Vitest". La documentación de Claude Code recomienda describir el entorno porque las herramientas del agente usan ese contexto para elegir comandos correctos.
• Convenciones: "los componentes van en PascalCase, las queries SQL en archivos separados, no se usan any".
• Qué ya intentaste: "probé cambiar X pero rompe Y" ahorra vueltas enteras.

La diferencia entre pedir "haz X" y especificar es exactamente esta: el primer prompt delega la decisión, el segundo la informa. Con GitHub Copilot el contexto del archivo abierto ya pesa en la respuesta, así que nombrar archivos y abrir los relevantes antes de preguntar cambia el resultado desde el primer intento.

Los cuatro patrones que cubren el 90% de los pedidos

Refactor — pide comportamiento intacto y estructura nueva:

Refactoriza src/services/pagos.ts: extrae la lógica de validación
de tarjetas a src/services/validacion.ts, mantén el comportamiento
exacto, sin cambios de API pública. Los tests existentes deben
pasar sin modificarlos. Después de refactorizar, agrega un test
para el caso de tarjeta vencida.

Bug fix — pide diagnóstico antes que parche:

La función calcular_total() devuelve montos negativos cuando el
descuento supera el subtotal en src/lib/carrito.ts. Reproduce el
caso con un test primero, identifica la causa raíz, corrígela y
verifica que el test nuevo pase junto con los existentes.

Test — pide cobertura con criterios:

Escribe tests para src/api/usuarios.ts con Vitest: casos felices,
errores de validación, usuario inexistente y rate limit. Usa mocks
de la base de datos, no una base real. Los tests deben correr con
pnpm test y quedar verdes.

Feature — pide el camino completo:

Agrega un endpoint GET /api/stock que devuelva stock disponible
por sku desde la tabla productos. Sigue el patrón de los endpoints
existentes en src/api/, valida el parámetro sku, devuelve 404 si
no existe y documenta el formato de respuesta en el README.

En los cuatro, el criterio de aceptación es observable: tests que pasan, comportamiento que no cambia, endpoints que responden. Eso convierte la sesión en algo verificable en vez de una conversación.

Cuándo usar plan mode

Claude Code y Cursor tienen un modo de plan: el agente investiga y propone antes de tocar código. Úsalo cuando:

• El cambio toca varios archivos y quieres revisar el alcance antes de que escriba.
• El problema está mal definido y necesitas que el agente explore el repo y te diga qué encontró.
• El cambio es caro de revertir: migraciones, cambios de schema, refactors grandes.

La regla: si aceptarías el plan de un colega antes de que empiece, pídele el plan al agente. Si es un cambio de una función y un test, ve directo a ejecutar. El modo plan no es para todo, pero para cambios grandes es la diferencia entre revisar una propuesta y deshacer un desastre.

Errores que encarecen las sesiones

• Pedir sin contexto: el agente adivina el stack, genera código con dependencias que no existen y pierdes dos vueltas.
• Aceptar la primera versión: verifica el output siempre; los agentes escriben código que compila y falla en runtime.
• Mezclar varias tareas: tres features en un prompt = tres features a medio hacer. Una tarea por prompt.
• Ignorar los límites: si no dices "no toques la API pública", el agente la cambiará cuando le convenga.
• No pedir tests: el código sin tests que pasa hoy rompe mañana sin avisar.

Verificación antes de dar por terminado

Después de cada cambio del agente, corre tu propia lista:

1. Los tests pasan y cubren el caso que motivó el cambio.
2. El código sigue las convenciones del repo (lint, formato, nombres).
3. No se tocaron archivos fuera del alcance declarado.
4. El comportamiento se verificó con una ejecución real, no solo compilando.
5. El diff se revisó línea por línea antes de hacer commit.

El prompt de programación es una habilidad, no un truco: entre mejor especifiques tarea, contexto, criterios y límites, más barato y confiable se vuelve cada cambio. La base de cómo estructurar esas instrucciones está en la guía de prompt engineering para agentes, y para dominar la herramienta, la guía de Claude Code desde cero en español te deja el entorno configurado. El hub de guías de construcción de agentes reúne más patrones de agentes de desarrollo.