El mismo agente, con el mismo modelo, rinde el doble — o el triple — según cómo le pidas. Este módulo desmenuza la anatomía de un buen prompt, los patrones que funcionan en empresa y los anti-patrones que sabotean a los equipos.
Objetivos
Conocer los 5 elementos de un prompt profesional (qué + dónde + por qué + verificación + restricciones).
Aplicar los 7 patrones que más rinden en código real.
Detectar y corregir 8 anti-patrones frecuentes.
Escribir prompts para tareas exploratorias, deterministas y arquitecturales.
Iterar un prompt en lugar de empezar desde cero.
6.1 Los 5 elementos del prompt profesional
Un prompt productivo incluye, idealmente, los cinco:
Elemento
Pregunta que responde
Ejemplo
1 · Qué
¿Qué acción concreta?
"Refactoriza", "Añade", "Migra", "Diagnostica"
2 · Dónde
¿Sobre qué archivos / módulos?
"En src/api/users.ts y sus callsites"
3 · Por qué
¿Cuál es la motivación?
"Para alinear con la convención fetchX del resto del módulo"
4 · Verificación
¿Cómo sabemos que funciona?
"Ejecuta npm test y comprueba que pasan los 8 tests"
5 · Restricciones
¿Qué NO debe pasar?
"No cambies la signature pública. No añadas dependencias."
Los 5 no siempre son obligatorios — un cambio trivial de copy no necesita "Por qué" — pero cuanto más arriesgada o ambigua sea la tarea, más elementos debes incluir.
Ejemplo de prompt completo
> Refactoriza la función processOrder() en src/services/orders.ts
para que acepte un objeto de opciones en lugar de 6 argumentos sueltos.
Motivación: la signature actual es fuente de bugs por orden invertido
(vimos uno la semana pasada). Mantén la API pública del módulo igual:
solo cambia internos. Cuando termines:
1. Ejecuta npm test y comprueba que los 23 tests del módulo pasan.
2. Pasa npm run lint y resuelve cualquier warning nuevo.
NO toques otros archivos. NO añadas dependencias nuevas.
NO commitees — yo reviso el diff.
Este prompt cubre los 5 elementos en ~80 palabras. Tarda 30 segundos extra escribirlo y ahorra 10 minutos discutiendo con el agente sobre alcance, motivación y verificación.
6.2 Los 7 patrones que más rinden
Patrón 1 · "Lee primero, decide después"
Cuando el agente debe descubrir cosas:
> Antes de proponer nada, lee src/services/, dime qué dependencias
externas tiene y luego decidimos cómo aislar las pruebas.
Forzar la fase Read explícita reduce alucinaciones.
Patrón 2 · "Dame opciones, no solución"
Para decisiones de diseño:
> Dame 3 opciones para implementar rate-limiting en este endpoint.
Por cada opción: pros, contras, complejidad relativa. NO escribas
código. Decidiremos juntos qué implementar.
El modelo discrimina mejor cuando se le obliga a comparar.
Patrón 3 · "Hazlo en plan mode primero"
Antes de cambios grandes:
> /plan
> Migra el módulo Auth a passkeys. Quiero el plan completo antes
de tocar nada — qué archivos, qué decisiones, qué riesgos.
Patrón 4 · "Define qué es éxito"
Termina cada prompt importante con un criterio:
... Solo declara terminado cuando:
- npm test pase 100%.
- npm run build no produzca warnings.
- La función nueva tenga al menos 4 tests.
Patrón 5 · "Prohibido inventar"
Cuando el modelo tiende a fabricar APIs o nombres:
> Si no encuentras un fichero, di "no existe", no inventes uno.
Si no recuerdas el nombre exacto de una API, hazme grep antes.
Patrón 6 · "Iterar mediante referencia"
En lugar de reescribir un prompt grande, parte del trabajo previo:
> Usa el mismo enfoque que aplicaste en src/services/billing.ts
pero ahora para src/services/shipping.ts. Mismas convenciones,
mismo formato de tests.
Patrón 7 · "Cierra el ciclo"
Pídele que te enseñe el diff antes de declarar terminado:
> Cuando termines, hazme git diff y resúmeme los cambios en una
lista de bullets. NO commitees.
6.3 Los 8 anti-patrones
✗ "Arregla los bugs"
Sin alcance, sin definición de bug, sin criterio. El agente alucina.
✓ "Diagnostica el bug del NaN en el dashboard de pedidos"
Concreto, acotado, comprobable.
✗ "Hazlo mejor"
Mejor según qué eje. El agente adivina y suele acertar lo equivocado.
✓ "Mejora la legibilidad sin tocar performance ni cambiar API"
Eje claro y restricciones explícitas.
✗ "Refactoriza el módulo Auth"
Demasiado abierto. Termina tocando 30 archivos.
✓ "Refactoriza Auth.login() para extraer la validación a un helper"
Tarea unidad de cambio.
✗ "Y de paso optimiza esto y limpia esto otro"
Diluye la atención. PR mezcla tres cosas, code review imposible.
✓ "Solo el refactor. Anota lo otro como tarea pendiente"
Una unidad por sesión.
Otros anti-patrones a evitar
"Confío en ti, hazlo". El agente NO sabe el contexto de tu negocio. Tienes que dárselo.
Prompts en bloque sin saltos de línea. El modelo lee mejor texto estructurado.
"Y haz lo que veas conveniente". Sin restricciones, el modelo reinventa más de la cuenta.
"Ya lo dijimos antes". Si el contexto se compactó, "antes" puede haberse perdido. Reitera.
6.4 Prompts para tareas distintas
Tarea exploratoria
"Quiero entender" más que "quiero cambiar":
> Lee src/auth/ y descríbeme cómo funciona el flow de login actual.
Diagrama secuencia simple en ASCII si ayuda. NO modifiques código.
Identifica los puntos donde podríamos meter passkeys más adelante.
Tarea determinista
Cuando hay UNA respuesta correcta:
> En src/utils/dates.ts, la función parseISO acepta string. Cámbiala
para que acepte Date | string. Si recibe Date, devuélvelo tal cual.
Si recibe string, parsea con la lógica actual. Mantén tipos exactos.
Tests existentes deben seguir pasando sin modificar.
Tarea arquitectural
Cuando el coste de equivocarse es alto:
> /plan
> Estamos pensando en separar el monolito en dos servicios:
api-public (puerto 3000) y api-admin (puerto 3001). El admin solo
lo usa el panel interno. Quiero un plan completo:
1. ¿Qué endpoints van a cada servicio?
2. ¿Cómo compartimos modelos / DB?
3. ¿Qué orden de migración minimiza el riesgo?
4. ¿Qué rollback es viable en cada paso?
NO ejecutes nada. Solo el plan.
Tarea de debugging
Cuando hay un síntoma sin causa:
> Síntoma: en producción, /api/orders/list devuelve 500 los lunes
por la mañana. Logs adjuntos en logs/error-monday.log. Lee los
logs, busca el patrón, identifica si es código o infra. Propón
hipótesis ordenadas por probabilidad. NO toques código aún.
6.5 Iterar sin reescribir
Cuando el agente entrega algo cerca pero no del todo, no reescribas el prompt entero. Itera:
Estrategia A · Refinar
> Casi. Tres ajustes:
1. La función debe devolver Result<T, Error>, no throw.
2. El test del caso "lista vacía" no contempla null vs [].
3. Falta JSDoc en los parámetros.
Estrategia B · Pivotar
> Olvida el approach de class. Hagámoslo con función pura y cierre
para mantener estado. Mismo comportamiento, otro estilo.
Estrategia C · Pedir explicación antes de cambiar
> Antes de tocar nada, explícame por qué elegiste useRef en lugar
de useState aquí. Quiero entender tu razonamiento antes de pedir
cambios.
Iterar sin contexto fresco: si el chat se ha alargado mucho y la respuesta degrada, mejor abrir sesión nueva con el resumen del progreso ("ya tenemos hecho X, falta Y, restricciones Z") que seguir tirando del hilo.
6.6 Práctica · 2 horas guiadas
Ejercicio guiado · escribe el prompt para esta tarea
Escenario: en un repo Node + Express, hay un middleware src/middleware/auth.ts con la función verifyToken(). Has detectado que cuando el JWT está expirado devuelve 500 en lugar de 401. Quieres que el agente:
Diagnostique el bug.
Proponga el cambio (nada de implementar todavía).
Escriba al menos un test que reproduzca el bug.
NO toque otros middlewares ni la lógica de signing.
Escribe el prompt aplicando los 5 elementos. Te evaluamos: extensión adecuada, alcance claro, criterio de verificación, motivación, y ausencia de frases vagas.
Ejercicio 6.1 · Identifica los anti-patrones
De estos 5 prompts, identifica el anti-patrón principal de cada uno y reformúlalo:
"Mejora el código del backend"
"Refactoriza Auth y de paso optimiza el dashboard"
"Si encuentras algo raro arréglalo"
"Haz lo que ya hablamos hace una hora"
"Escribe los tests que falten"
Ejercicio 6.2 · Tres tipos de tarea
Para tu repo actual, escribe un prompt de cada tipo:
Exploratorio: descubrir cómo funciona algo del repo que no conoces bien.
Determinista: añadir un campo a una clase y propagarlo a sus consumidores.
Arquitectural: decidir entre dos opciones de diseño con plan mode.
Compara con un compañero — los prompts buenos son sorprendentemente parecidos.
Test de comprensión
1. ¿Cuáles son los 5 elementos de un prompt profesional?
Modelo, temperatura, top-p, max_tokens, system
Qué, dónde, por qué, verificación, restricciones
Read, plan, edit, verify, commit
Allow, deny, ask, plan, auto
Respuesta correcta: B. Acción + alcance + motivación + criterio de éxito + qué no debe pasar.
2. Estás a punto de pedir una migración grande. ¿Qué patrón aplicas primero?
Patrón 1 · "Lee primero"
Patrón 3 · "Hazlo en plan mode primero"
Patrón 5 · "Prohibido inventar"
Patrón 7 · "Cierra el ciclo"
Respuesta correcta: B · plan mode. Para cambios grandes, plan mode antes de tocar es la norma. Los demás patrones también aplican, pero plan mode es el primero.
3. El agente entrega algo a un 80% de lo que querías. ¿Qué haces?
Reescribir el prompt original desde cero
Iterar con un mensaje de refinamiento corto
Cambiar de modelo
Aceptarlo y pulir tú lo que falte
Respuesta correcta: B. Iterar es más eficiente. Reescribir solo si el approach es radicalmente equivocado.
4. ¿Cuál de estos prompts es MÁS profesional?
"Arregla los bugs en el módulo Auth"
"En src/auth/login.ts, el handler devuelve 500 en token expirado en vez de 401. Diagnostica, propón fix y test que lo cubra. No toques signing. No commitees."
"Mira a ver qué pasa con Auth"
"Hazlo perfecto"
Respuesta correcta: B. Cubre los 5 elementos en menos de 50 palabras.
Resumen del módulo
Los 5 elementos: qué + dónde + por qué + verificación + restricciones.
Los 7 patrones que rinden, los 8 anti-patrones que sabotean.
Tres tipos de tarea (exploratoria, determinista, arquitectural) con plantillas.
Iterar es más eficiente que reescribir; sesión nueva si el contexto está saturado.
Un buen prompt tarda 30 segundos extra y ahorra 10 minutos de discusión.
Siguiente módulo: Skills — encapsular conocimiento reutilizable que el modelo carga por sí mismo.