La mayoría de la gente le da prompts a Claude Code igual que a ChatGPT. Ese es el bug.

ChatGPT es un motor de preguntas y respuestas. Claude Code es un agente. La forma de una buena pregunta no es la forma de un buen objetivo.

Después de un año ejecutando Claude Code en bases de código de producción, lo he reducido a cuatro partes que siempre tienen que estar en el prompt:

• Objetivo — cómo se ve el éxito.
• Restricciones — lo que no debe cambiar.
• Definition of Done — cómo sabe el agente que terminó.
• Contexto — punteros a los archivos / tickets / errores relevantes.

Salta cualquiera y obtienes deriva. Incluye las cuatro y el agente correrá tranquilo durante 5 minutos y volverá con un diff limpio.

El prompt malo

> Refactoriza el servicio de usuarios para rendimiento.

Por qué falla:

• "Rendimiento" no está definido. ¿Latencia? ¿Memoria? ¿Throughput?
• Sin restricciones — podría reescribir tu esquema de DB.
• Sin definition of done — para cuando se aburre.
• Sin contexto — tiene que adivinar qué archivo es "el servicio de usuarios".

Recibirás algo que parece trabajo pero no lo es.

El prompt bueno

> Objetivo: Reducir la latencia p95 de GET /api/users/:id de 240 ms a menos de 80 ms.
>
> Restricciones:
> - NO cambiar la forma de la API pública.
> - NO añadir nuevas dependencias.
> - Mantener el código en app/api/users — sin nuevas capas.
>
> Definition of Done:
> - Los tests existentes pasan.
> - Añadir un load test (50 llamadas concurrentes × 100 iteraciones).
> - p95 < 80 ms en local con Node 20.
> - Añadir una descripción de PR de un párrafo.
>
> Contexto:
> - app/api/users/route.ts es el punto de entrada.
> - lib/db/users.ts tiene el query N+1 lento.
> - Usamos Postgres 15 y drizzle ORM.

Misma tarea. Resultado distinto. El agente va a:

1. Leer los dos archivos.
2. Identificar el N+1.
3. Escribir el fix con un único query batched.
4. Añadir el load test.
5. Ejecutar el test, confirmar el número.
6. Devolver un diff con descripción de PR.

Eso es delegación, no autocompletar.

Por qué importa cada parte

Objetivo

Escríbelo como resultado, no como acción. "Reducir p95 a 80 ms" es resultado. "Refactorizar las llamadas a la DB" es acción — y un agente flojo hará la acción sin alcanzar el resultado.

Restricciones

Las restricciones son lo que te sorprendería. Si un junior reescribiendo ese archivo te sorprendería cambiando la forma de la API, escríbelo. Si te sorprendería añadiendo Redis, escríbelo.

La mayoría de las historias "Claude Code hizo algo raro" son restricciones que faltaban, no inteligencia que faltaba.

Definition of Done

La parte más infrautilizada de cualquier prompt. Sin ella, el agente para cuando cree que la tarea está hecha — normalmente tras escribir el código, antes de ejecutar los tests.

Buenas DoD son testeables:

• "Los tests existentes pasan."
• "El nuevo endpoint devuelve 201 y un header Location válido."
• "lighthouse-ci no muestra regresión en la home."

Si no puedes escribir una DoD, la tarea no está lista para delegar.

Contexto

No hace falta pegar archivos. Bastan punteros:

• app/api/users/route.ts — punto de entrada.
• tests/api/users.test.ts — tests existentes.
• "Vimos la regresión en el PR #842."

Claude Code sabe leer y buscar. Solo necesita que apuntes al barrio correcto.

La plantilla 80/20 que guardo en .claude/commands/

# /goal — pega esta plantilla, rellena los huecos

Objetivo: <resultado con número si es posible>

Restricciones:
- <cosa que no debe cambiar>
- <regla de dependencia>
- <regla de estilo o arquitectura>

Definition of Done:
- <comando de test que pasa>
- <chequeo de rendimiento o corrección>
- <descripción de PR en 1 párrafo>

Contexto:
- <archivo o carpeta>
- <ticket / error / log relacionado>

Aliasarlo como slash command hace que un nuevo prompt de feature lleve 90 segundos. Cubrimos slash commands a fondo en el artículo 4.

Anti-patrones para abandonar hoy

• "Hazlo más limpio." ¿Más limpio según qué métrica? Elige: líneas de código, complejidad ciclomática o una regla de lint concreta.
• "Arregla el bug." ¿Qué bug? ¿Cuál es el comportamiento esperado? ¿Y el actual?
• "Refactoriza por legibilidad." Legibilidad es gusto. Elige un patrón concreto: "extraer a funciones puras", "reemplazar ifs anidados con early returns".

Prompts vagos producen código vago. El agente es un espejo.

Un último truco: el "ejemplo negativo"

A veces la forma más limpia de restringir a un agente es enseñarle qué no hacer.

> NO añadas una nueva capa de abstracción.
> El intento anterior añadió una clase UserRepository — la quitamos.
> El fix debería ser ~20 líneas en lib/db/users.ts, no 200.

Brutalmente eficaz. Estás anticipando el modo de fallo más común de un agente sobreentusiasta: construir un reino cuando una sola función bastaba.

---

Próximo artículo: Slash commands — cómo convertir la plantilla de prompt anterior en un comando /feature de una sola pulsación, y cómo encadenar /init, /agents, /compact para construir un esqueleto de proyecto completo en una sesión.