Cómo escribir buenos prompts para Claude Code

Hola, bienvenido. En la lección anterior cerramos la sección de modelos y coste con fast mode, y con esta lección empezamos una sección nueva, la de cómo trabajar con Claude Code en el día a día. 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 de claude-tasks, el modelo Task, que en la siguiente lección pasaremos por plan mode.

¿Por qué hace falta una lección sobre esto, si al final es escribir lo que quieres? Porque la documentación de Claude Code lo resume en una frase muy clara: 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 veíamos 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 claude-tasks con los contenedores de Sail levantados y una sesión de Claude Code abierta en la raíz del proyecto, 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. Y fíjate también en que 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.