Cómo escribir buenos prompts para Claude Code

Hola, bienvenido. En esta lección empezamos una sección nueva, la de cómo trabajar con Claude Code en el día a día, después de cerrar la de modelos y coste con fast mode en la lección anterior. Vamos a ver cómo escribir prompts que Claude pueda cumplir sin adivinar: la diferencia entre un prompt de exploración y uno de tarea, cómo acotar el alcance, qué restricciones conviene poner y cómo cerrar cada petición con una verificación que Claude pueda ejecutar. Y lo vamos a hacer preparando la primera tarea real del proyecto, el modelo Task, que en la siguiente lección pasaremos por plan mode.

Escribir lo que quieres no siempre basta, y la documentación de Claude Code lo resume en una frase: Claude puede deducir tu intención, pero no te puede leer la mente. Y hay un segundo motivo menos evidente: Claude se detiene cuando el trabajo parece terminado. Si no le das una forma de comprobarlo, «parece terminado» es la única señal que tiene, y el que acaba haciendo de verificación eres tú, revisando cada fallo a mano. Es lo que vimos en la primera lección con el ejemplo de «arregla los tests»: un prompt ambiguo se puede cumplir de formas que no querías.

Para seguir esta lección necesitas el proyecto con los contenedores de Sail levantados y una sesión de Claude Code abierta en su raíz, como la que abrimos en la lección Tu primer prompt con Claude Code en un proyecto Laravel.

No todos los prompts tienen que ser precisos. Los de exploración sirven para entender antes de cambiar nada, y ahí un prompt abierto puede ser justo lo que necesitas: la documentación dice que los prompts vagos son útiles cuando estás explorando y te puedes permitir corregir el rumbo, porque una pregunta como «¿qué mejorarías en este archivo?» puede sacar cosas en las que no habrías pensado. La recomendación es hacerle a Claude las mismas preguntas que le harías a un compañero senior que conoce el proyecto: cómo funciona el registro de logs, cómo se crea un endpoint nuevo o qué casos límite cubre una clase.

Los prompts de tarea son otra cosa, porque ahí Claude va a crear y editar archivos. Y lo más práctico es encadenarlos: antes de pedir la tarea, una pasada de exploración para que tanto Claude como tú sepáis qué hay en el proyecto. Este es el prompt de exploración que vamos a usar antes de pedir el modelo Task:

Fíjate en las referencias con @. En lugar de describir dónde está el código, escribes @ y la ruta, y Claude Code incluye el contenido del archivo en la conversación antes de que Claude responda. Al escribir @ se abre un menú con sugerencias de rutas, y puedes referenciar varios archivos en el mismo mensaje. Además, el prompt está acotado a 3 archivos: la documentación incluye entre los errores habituales la exploración infinita, cuando pides investigar algo sin límites y Claude lee cientos de archivos que te llenan el contexto.