Cómo preguntar y dar instrucciones: Hablarle a Claude al corazón
📚 Navegación de la serie: El artículo anterior [14 Interfaz e interacciones o sus atajos / Keyboard Shortcuts] te enseñó a poner los dedos en el lugar correcto: ya dominas el cursor, Enter, Esc y los comandos de barra diagonal. Este artículo cambia de nivel: la mano ya sabe dónde presionar, ahora la boca tiene que saber qué decir. Para una misma necesidad, dependiendo de lo bien que te expreses, el trabajo que hace Claude será de la noche al día.
A decir verdad y aunque no suene muy bien: muchos, cuando recién empiezan a usar Claude Code, lo tratan como si fuera un motor de búsqueda.
Imagina esta escena: hay un error en una función del proyecto, le sueltas de golpe un «arregla este bug», sin decir qué archivo es ni cuál es el error, presionas Enter y te sientas a ver el espectáculo. El resultado es que "adivina" lo que él cree que es el error, modifica tres archivos y ninguno es el lugar que realmente querías arreglar. Te quedas mirando la pantalla llena de diffs con cara de tonto, y aún murmuras «esta IA no sirve».
Si lo piensas bien lo entenderás: no es que él no sirva. El problema no es de Claude, es que esa frase era malísima: la cantidad de información es casi nula, así que solo le queda inventar. Si inventa y se equivoca, ¿de quién es la culpa?
Pongámoslo así: el límite máximo de lo que puede hacer Claude Code está en gran medida bloqueado por tu forma de preguntar. Con el mismo modelo y el mismo proyecto, el que sabe pedir lo que necesita lo consigue en tres frases; el que no sabe, da cinco vueltas rehaciendo cosas y se llena de rabia. Hoy vamos a explicar a fondo esta regla universal de «cómo explicar claramente una necesidad en una frase»: no se trata de enseñarte plantillas de memoria, sino de enseñarte a entender "qué necesita saber Claude exactamente para no desviarse del camino".
Después de leer este artículo, obtendrás:
- Una tabla comparativa de «Mala pregunta vs Buena pregunta»; si la sigues para corregir, la tasa de retrabajo caerá en picado.
- Cuatro principios básicos para dar instrucciones: ser específico, dar contexto, dar criterios de aceptación, y hacer que planifique primero las tareas complejas.
- La forma correcta de usar
@para referenciar archivos y acotar el alcance con precisión. - Un experimento que puedes replicar de «una misma necesidad, dos formas de decirla», para ver la diferencia con tus propios ojos.
01 Dónde falla exactamente una mala pregunta
Analicemos el desastre del que hablamos antes. La frase «arregla este bug», desde el punto de vista de Claude, carece de información de forma absurda:
- ¿Qué bug? Tiene que adivinar por sí mismo a qué parte te refieres.
- ¿Qué archivo? Tiene que rebuscar por todo el proyecto.
- ¿Cuál es el comportamiento correcto esperado? No lo sabe en absoluto, solo puede inventar basándose en «lo que generalmente debería ser».
Analogía: Guiar a un novato. Le dices a un becario recién contratado «arregla eso de ahí», y será un milagro si lo hace bien. En cambio, si le dices «cambia el color de ese botón de inicio de sesión en la esquina superior derecha de la página de inicio, de gris al azul de la marca #1A73E8», lo hará bien con los ojos cerrados. Cuanto más específica sea la instrucción, menos se desviará el novato; cuanto más le sueltes frases vagas, más tendrá que adivinar, y mayor será la probabilidad de que adivine mal. Claude es exactamente igual.
Mira esta comparación que la documentación oficial enfatiza repetidamente (traducida al español según la intención oficial):
| Escenario | ❌ Mala pregunta | ✅ Buena pregunta |
|---|---|---|
| Arreglar bug | «Arregla el error de inicio de sesión» | «Un usuario reporta que el inicio de sesión falla después del tiempo de espera de la sesión. Revisa el flujo de autenticación en src/auth/, centrándote en la actualización del token. Primero escribe una prueba fallida que pueda reproducir el problema, luego arréglalo» |
| Escribir pruebas | «Añade pruebas a foo.py» | «Escribe pruebas para foo.py, cubriendo los casos límite donde el usuario ya ha cerrado sesión, no uses mock» |
| Preguntar sobre código | «¿Por qué el diseño de esta API basura ExecutionFactory es así?» | «Revisa el historial de git de ExecutionFactory y resume cómo evolucionó su API paso a paso hasta llegar a lo que es ahora» |
| Añadir función | «Añade un componente de calendario» | «Primero mira cómo están implementados los componentes existentes en la página de inicio, HotDogWidget.php es un buen ejemplo. Sigue ese patrón para implementar un componente de calendario que permita al usuario seleccionar el mes y cambiar de año hacia adelante y hacia atrás. Aparte de las bibliotecas que ya están en la base de código, no importes bibliotecas nuevas» |
¿Ves el truco? Las buenas preguntas hacen todas una misma cosa: darle por adelantado a Claude todo lo que de otro modo tendría que adivinar.
💡 Resumen en una oración: Una mala pregunta falla en que «las lagunas de información dependen de la invención de Claude»; una buena pregunta es explicarle por adelantado lo que él tendría que adivinar.
Este «Antes/Después» pone lado a lado dos formas de preguntar sobre una misma necesidad: a la izquierda, pregunta vaga, Claude solo puede inventar y hacer un montón de contrapreguntas; a la derecha, se le da el paquete completo (alcance, contexto (@archivo), criterios de aceptación), acierta a la primera y pasa las pruebas directamente. La diferencia no está en Claude, sino en cómo hablas.
02 Principio 1: Específico > Vago
Este es el principio más importante de los cuatro, sin lugar a dudas.
Hay una frase en la documentación oficial que vale la pena recordar especialmente, la frase original es:
Cuanto más precisas sean tus instrucciones, menos correcciones necesitarás.
Traducido a un lenguaje llano: Añade una frase más al principio y te ahorrarás tres rondas de retrabajo después. Crees que estás «ahorrando esfuerzo» escribiendo unas cuantas palabras menos, pero en realidad, esas palabras de menos se convertirán en un costo doble en idas y venidas.
¿Hasta qué punto ser específico? Llena estos tres aspectos:
Primero, acotar el alcance: qué archivo, qué función, qué escenario. No le hagas buscar una aguja en el pajar por todo el proyecto.
Segundo, aclarar las restricciones: «no importes bibliotecas nuevas», «mantén la compatibilidad hacia atrás», «no toques los archivos de prueba». Si no se lo dices, lo hará según sus propias preferencias, que puede que no sean de tu agrado al final.
Tercero, indicar una referencia: «sigue el patrón de HotDogWidget.php». En la práctica, este truco es el que más tranquilidad da: en lugar de describir el estilo que quieres con palabras, es mejor darle un ejemplo ya hecho con el que estés satisfecho; si lo copia, rara vez fallará.
Aquí hay una excepción contraintuitiva que hay que aclarar: Una pregunta vaga no está absolutamente mal. Cuando estás en la «fase de exploración» y tú mismo no tienes clara la dirección, una pregunta abierta como «¿Qué crees que se podría mejorar en este archivo?» puede hacer saltar cosas que ni se te habían ocurrido preguntar. La regla oficial lo llama «los prompts vagos pueden ser útiles cuando estás explorando y puedes corregir el rumbo». La regla es: cuando quieras resultados, sé extremadamente específico; cuando busques inspiración, deja espacios en blanco a propósito.
Es muy fácil toparse con este límite al crear una herramienta pequeña: al principio solo quieres ver cómo Claude entiende ese código desordenado y haces una pregunta muy genérica, y los puntos de mejora que da realmente te inspiran; pero una vez que tienes un objetivo claro en mente, usar preguntas vagas es un puro desperdicio de turnos, porque cada vez tiene que volver a adivinar qué es lo que realmente quieres.
💡 Resumen en una oración: Si quieres un resultado seguro, sé específico hasta la médula (alcance + restricciones + referencia); solo deja espacios en blanco a propósito cuando busques inspiración activamente.
03 Principio 2: Dar contexto, no le dejes adivinar a ciegas
Además de ser específico, el segundo truco es ponerle la «comida» directamente en la boca, en lugar de decirle con palabras dónde está la «comida».
Recordar estas dos acciones más frecuentes será suficiente para la mayoría de los casos:
Primera, usa @ para referenciar archivos. Escribe @ en el cuadro de entrada y aparecerá el autocompletado de la ruta del archivo; una vez seleccionado, el contenido completo de ese archivo se introducirá directamente en la conversación: Claude no tiene que ir a buscarlo primero y luego leerlo, lo que ahorra un paso y evita que se equivoque de archivo.
Revisa las definiciones de tipos en @src/types/user.ts y añade anotaciones de tipo a UserServiceEsto es diez mil veces más fiable que decir «hay un archivo de tipos de usuario en el proyecto, ve a buscarlo». La documentación oficial dice explícitamente que la referencia @ «lee el contenido completo de un archivo antes de responder».
Analogía: Un puerto USB. @ es como conectar directamente una «memoria USB de archivos» a la mesa de trabajo de Claude: plug and play, los materiales que necesita están ahí en un segundo; si solo usas la boca para decir «los materiales están en el segundo cajón de la sala de archivos del tercer piso», él tendrá que hacer el viaje, y si se equivoca, será peor.
Segunda, pega el error completo directamente. Vale la pena que esto se convierta en memoria muscular: cuando te encuentres con un traceback (rastreo de pila), no resumas «me dio un null pointer», pega la pila completa tal cual:
Me dio este error al ejecutar, ayúdame a localizar la causa:
TypeError: Cannot read properties of null (reading 'userId')
at getUserProfile (src/services/user.ts:42:18)
at async ProfileController.getProfile (src/controllers/profile.ts:15:20)¿Por qué pegar todo? Porque en la pila están todos los nombres de archivo, números de línea y la cadena de llamadas. Siguiendo user.ts:42, Claude puede localizarlo con precisión. Si lo resumes, estás borrando todas estas coordenadas clave, y él tendrá que empezar a adivinar desde el principio.
| La información que quieres dar | ❌ Describir con la boca | ✅ Dársela directamente |
|---|---|---|
| El contenido de un archivo | «Hay un archivo en el proyecto que maneja la autenticación» | @src/auth/session.ts |
| Un error | «Dio un error de undefined» | Pegar el traceback completo tal cual |
| Un problema de UI | «La posición del botón está mal» | Pegar directamente la captura de pantalla (Claude puede leer imágenes) |
| Una especificación de interfaz | «Sigue nuestra especificación de API» | @docs/api-spec.md |
En una palabra: Todo lo que se pueda «pegar», no se debe «decir». Para Claude, leer el material original siempre es más preciso que leer tu resumen de segunda mano de ese material.
💡 Resumen en una oración: Usa
@para archivos, pega los errores y las capturas de pantalla directamente en su cara, no le dejes adivinar siguiendo tus descripciones.
04 Principio 3: Dar un criterio de éxito «verificable»
Esta regla se olvida fácilmente, pero su poder es inmenso: Tienes que hacerle saber a Claude «qué cuenta como un trabajo bien hecho», y es mejor si él mismo puede verificar ese criterio.
¿Por qué es clave? La documentación oficial revela la lógica subyacente:
Claude se detiene cuando el trabajo parece estar terminado. Sin comprobaciones que pueda ejecutar, "parece estar terminado" es la única señal disponible y tú te conviertes en el bucle de validación: cada error está esperando a que tú lo notes.
¿Qué significa esto? Si no le das un criterio, Claude se detendrá basándose en la sensación de que «ya casi está», y la persona que realmente hace la validación final eres tú, tienes que atrapar cada agujero personalmente. Pero una vez que le das una comprobación que arroja un «aprobado / fallido», este ciclo se cierra por sí solo: termina el trabajo → ejecuta la comprobación → ve el resultado → si no aprueba, sigue modificando; no tienes que estar vigilándolo.
Compara esto para entenderlo:
| Tarea | ❌ Sin criterio de aceptación | ✅ Con criterio verificable dado |
|---|---|---|
| Escribir función | «Implementa una función para validar correos» | «Escribe una función validateEmail. Casos de prueba: user@example.com es verdadero, invalid es falso, user@.com es falso. Ejecuta las pruebas al terminar» |
| Modificar UI | «Haz que este panel de control se vea mejor» | «[Pegar diseño] Implementa según esto, luego haz una captura de pantalla del resultado, compárala con el original, enumera las diferencias y arréglalas» |
| Arreglar build | «El build (compilación) ha fallado» | «El build da este error: [Pegar error]. Arréglalo y verifica que el build pase. Resuelve la causa raíz, no te limites a ocultar el error» |
Ojo a esa última línea: «Resuelve la causa raíz, no te limites a ocultar el error» — esta es una frase que se aprende a añadir a base de golpes. Si no la escribes, a veces por conveniencia te envuelve todo en un try/except directamente, o añade un @ts-ignore para quitar la línea roja; el error desaparece, pero la enfermedad sigue ahí.
Truco avanzado: Usa /goal para convertir el criterio de aceptación en un «no se termina hasta cumplir el objetivo». (Requiere Claude Code v2.1.139 o superior) Escribir el criterio de aceptación en una pregunta normal es «ejecútalo esta ronda»; pero con /goal fijas el criterio como el objetivo de toda la sesión: tras cada ronda, un modelo pequeño (Haiku por defecto) revisará según tu condición; si no se cumple, abrirá automáticamente la siguiente ronda, sin devolverte el control, hasta que se cumpla la condición.
/goal Todas las pruebas en test/auth pasan, y el paso de lint está limpioHay un detalle clave al usar /goal para no caer en trampas: ese pequeño modelo evaluador solo mira lo que Claude «muestra» en la conversación, no ejecutará comandos ni leerá archivos por sí mismo. Así que tu condición debe ser algo que la propia salida de Claude pueda demostrar: la razón por la que «todas las pruebas en test/auth pasan» funciona, es porque Claude realmente ejecutará las pruebas, y el resultado se imprimirá en la conversación para que el modelo evaluador pueda leerlo. Si escribes «la calidad del código es muy alta», algo que no se puede ver desde la salida, no podrá evaluarlo.
💡 Resumen en una oración: Dale una comprobación que arroje aprobado / fallido (pruebas, comparación de capturas, código de salida del build) y el ciclo se cerrará por sí solo; si quieres que «no suelte la presa hasta cumplir», usa
/goal.
05 Principio 4: Tareas complejas, que planifique primero antes de actuar
La última regla es especialmente para los «trabajos grandes»: Cuando te encuentres con tareas que implican grandes cambios, que abarcan varios archivos, o de las que ni tú mismo estás seguro de la dirección, no le dejes empezar a escribir a ciegas; que haga un plan primero, échale un vistazo y luego dale luz verde.
Se dieron pistas sobre esto en el artículo 06 (Planes y facturación), aquí explicaremos por qué a fondo. El diagnóstico de la documentación oficial es tajante:
Pedirle a Claude que salte directamente a programar puede generar código que resuelva el problema equivocado.
Dicho de forma sencilla: Explorar primero, planificar después y finalmente programar: separa el «pensarlo bien» del «ponerse manos a la obra», para evitar que corra como loco en la dirección equivocada y, cuando te des cuenta, ya haya cambiado un montón de cosas.
Analogía: En una reforma, primero los planos, luego a tirar paredes. Ningún obrero de confianza agarra el mazo y empieza a tirar un muro de carga sin más. Primero tiene que confirmar contigo: «Tiramos esta pared, los cables van por aquí, cambiamos las tuberías así»; cuando tú asientes, empieza la obra. El plan es ese plano que Claude te entrega antes de empezar a tirar la pared: si ves un error en el plano, el coste de corregirlo con dos trazos es mucho menor que reconstruir la pared tirada.
¿Cómo hacer que primero te dé los planos? Hay dos formas:
Forma uno, decírselo claramente con palabras: «No cambies nada todavía». Añade una restricción en una conversación normal:
Quiero añadir un interruptor de modo oscuro a la página de ajustes.
Dime primero qué archivos vas a tocar y cuál es la idea del cambio,
en este paso, no modifiques ningún código todavía.Forma dos, cambiar a Plan Mode (Modo Plan). Esta es la marcha de «solo lectura y planificación» específica de Claude Code: leerá archivos, propondrá soluciones, pero no escribirá ni una palabra en el disco hasta que lo apruebes. Para entrar: en la sesión, presiona Shift + Tab (una o dos veces para ciclar hasta el Modo Plan), el modo rotará entre default → acceptEdits → plan. Si solo quieres que un prompt se ejecute en Modo Plan sin cambiar toda la sesión, añade el prefijo /plan antes del mensaje.
No obstante, la documentación oficial también da una advertencia muy sensata, no te vayas al extremo de querer planificar todo:
Para tareas con un alcance claro y correcciones pequeñas (como corregir errores ortográficos, añadir una línea de registro o renombrar una variable), pídele a Claude que las ejecute directamente. La planificación es más útil cuando no estás seguro del método, cuando los cambios afectan a varios archivos o cuando no estás familiarizado con el código que se va a modificar. Si puedes describir el diff en una frase, sáltate la planificación.
El truco más práctico es justo esa última media frase: «¿Puedes explicar en una sola frase cómo se verá esto después del cambio?» Si puedes, hazlo directamente; si te atascas, significa que el trabajo es lo suficientemente complejo y deberías hacer que él haga un plan primero. Pasar por el Modo Plan para corregir una falta de ortografía es complicarse la vida sin necesidad.
💡 Resumen en una oración: Tareas de las que no estás seguro / que cruzan múltiples archivos / en código desconocido → haz que haga un plan primero (añade «no cambies nada todavía» o usa
Shift+Tabpara entrar en Modo Plan); las tareas pequeñas donde el diff se puede explicar en una frase, hazlas directamente.
06 Manos a la obra: Una misma necesidad, probemos dos formas de decirla para ver la verdad
Escuchar la teoría no calma la sed, hagamos un pequeño experimento donde puedas ver la diferencia con tus propios ojos. Solo necesitas preparar un archivo de juguete de tres líneas, no depende de ningún proyecto que ya tengas.
Paso 1: Crea un archivo de juguete con una «trampa» (Mac / Linux)
mkdir prompt-demo
cd prompt-demo
echo 'def average(nums):
return sum(nums) / len(nums)' > stats.pyUsuarios de Windows: escribe mkdir prompt-demo, cd prompt-demo, usa el Bloc de notas para crear stats.py y pega esas dos líneas.
Esta función tiene una trampa: cuando le pasas una lista vacía [], len(nums) es 0, lo que desencadenará un cuelgue por «división por cero». La usaremos como nuestro campo de pruebas.
Paso 2: Inicia Claude en el directorio del proyecto
claudeResultado esperado: Aparece la pantalla de bienvenida con el cuadro de entrada en la parte inferior.
Paso 3: Primero usa la «Mala pregunta» para ver cómo adivina
@stats.py ayúdame a modificar esta funciónResultado esperado: Es muy probable que Claude «adivine» lo que quieres hacer: tal vez añadir anotaciones de tipo, tal vez añadir un docstring, pero no sabe que lo que realmente te importa es el cuelgue por la lista vacía, la dirección depende puramente de la suerte. Este es el precio de una pregunta vaga: él está tomando decisiones por ti.
Paso 4: Cambia a la «Buena pregunta» con el kit completo (Específico + Contexto + Criterio de aceptación)
La función average en @stats.py tiene un error: cuando se le pasa una lista vacía,
falla por división por cero.
El comportamiento esperado es que una lista vacía devuelva 0.
Ayúdame a solucionarlo y añade una prueba: average([]) debería devolver 0,
average([2, 4]) debería devolver 3.
Al terminar, ejecuta las pruebas y confirma que pasan.Resultado esperado: Esta vez la cadena de acciones de Claude es clarísima: localiza la rama de la lista vacía → añade la comprobación de nulos y devuelve 0 → escribe los dos casos de prueba que mencionaste → ejecuta las pruebas de verdad → te muestra el resultado de éxito. Ya no adivina qué quieres, porque tú has dejado cerrado todo: «dónde arreglar, cómo cambiarlo y qué cuenta como éxito».
Paso 5: Salir y ver si los cambios se han aplicado
cat stats.py(En Windows PowerShell usa type stats.py)
Resultado esperado: En stats.py ha aparecido la validación para la lista vacía (algo como if not nums: return 0). Si coincide con lo que pediste en el paso cuatro = ya le has pillado el tranquillo a «hablar claro».
Poniendo las dos preguntas una al lado de la otra, la diferencia salta a la vista:
| Paso 3 ❌ Mala pregunta | Paso 4 ✅ Buena pregunta | |
|---|---|---|
| Qué cambiar | No se dice, él adivina por todo el archivo | Especifica la función average |
| Cambiar a qué | No se dice, a su discreción | Lista vacía devuelve 0, bien claro |
| Qué cuenta como éxito | No hay criterio, él se detiene cuando «cree» que terminó | Dos casos de prueba + ejecución para validar |
| Tu experiencia | Miras el diff y piensas «esto no es lo que quería» | Actúa según tu guion y a la primera |
💡 Resumen en una oración: Con el mismo archivo y el mismo error, una mala pregunta hace que Claude tome decisiones por ti; una buena pregunta cierra todo: «dónde arreglar, a qué cambiarlo y qué cuenta como éxito». Ejecutar estos dos pasos tú mismo te mostrará la diferencia de forma más directa que leer la teoría diez veces.
07 Resumen
Este artículo solo ha tratado de una cosa: cómo decir la necesidad de una frase para que Claude la reciba con precisión.
Cerramos con los cuatro principios; si no puedes memorizarlos, recuerda esta tabla:
| Principio | En una frase | Cómo aplicarlo |
|---|---|---|
| Específico > Vago | Aclara el alcance + las restricciones + la referencia | «Modifica average, no importes bibliotecas nuevas, sigue el patrón de xxx» |
| Dar contexto | Lo que se pueda pegar, no se describe | @archivo, pegar errores enteros, pegar capturas |
| Dar criterio de aceptación | Que pueda comprobar si «ha funcionado» | Dar casos de prueba, pedirle que los ejecute; si eres estricto, usa /goal |
| Planificar primero | Tareas grandes: primero los planos, luego tirar la pared | Añade «no cambies nada todavía» o pulsa Shift+Tab para entrar al Plan Mode |
Ahora deberías ser capaz de: Traducir un vago «ayúdame a modificar» en una necesidad que Claude realmente pueda atrapar: definir el alcance, dar contexto suficiente, dar criterios de éxito verificables y, para cosas complejas, hacer que planifique primero. Este conjunto de reglas para hablar es la «fuerza interior» de todas tus operaciones futuras con Claude Code: por muy vistosas que sean las funciones, si lo que introduces es malo, el resultado tampoco será bueno.
A la inversa, te dejo una pregunta para pensar: Dado que «hablar claro» es tan importante, ¿tendrás que repetir cada vez algunas reglas (como «este proyecto no puede importar bibliotecas nuevas bajo ninguna circunstancia» o «las pruebas siempre van en el directorio
tests/»)? ¿Hay alguna forma de que Claude lo «recuerde» para que no tengas que ser un loro todos los días?
El próximo artículo será 16 «Flujos de trabajo comunes (Workflows)»: este artículo ha enseñado las reglas universales de «cómo hablar claro», el próximo las aplicará a las cuatro tareas específicas más frecuentes: explorar bases de código desconocidas, arreglar bugs, refactorizar y escribir pruebas. Para cada tipo te daré un patrón estándar que podrás copiar directamente. Ya tienes los principios, es hora de ver los movimientos.