Decirle a Claude Code el fichero, el síntoma y qué es «arreglado» suele ahorrar correcciones

Tu caso. Le pides algo a Claude Code y construye otra cosa, o te dice que ha terminado y no ha terminado, o tienes que corregirle dos veces lo mismo. La documentación de Claude Code dice que casi siempre falta lo mismo: algo que Claude no podía saber leyendo tu repositorio. V

Qué lo decide. Lo que pones en el prompt, el texto con el que le encargas el trabajo. Claude empieza cada tarea leyendo tu código, y de ahí saca la estructura de carpetas, tus convenciones, con qué se prueba y cómo están hechas las piezas que ya existen. Lo que no saca es lo que nunca estuvo en el repositorio: una decisión que tomó tu equipo en una reunión, un proceso de despliegue que solo conoce una persona, la variable de entorno que necesitan tus pruebas. V La documentación propone dos preguntas antes de escribirle nada: si podría encontrarlo leyendo el código, y si de verdad iría a mirarlo. Si las dos respuestas son sí, sobra. V

Para un encargo concreto, eso se traduce en tres datos que conviene dar desde el principio: qué fichero o qué carpeta, qué síntoma ves, y cómo sabrás que está arreglado. V La documentación lo enseña con un ejemplo: en lugar de pedir que arregle el fallo del inicio de sesión, contarle que los usuarios dicen que el inicio de sesión falla cuando la sesión caduca, que mire cómo se renueva la credencial de acceso en src/auth/, que escriba una prueba que reproduzca el fallo y que después lo arregle. V Y si entre dos soluciones razonables tienes preferencia, dila también, porque eso no está en el código. V

Cómo se lo das. Si ya tienes lo que necesita, dáselo en lugar de describirlo. Hay tres formas, según lo que tengas a mano: V

• Un fichero: escribe @ y la ruta en tu mensaje, y su contenido entra en el encargo.
• Una imagen: pega en el mensaje la captura del diseño o del error.
• La salida de una orden: pásala desde el terminal con una tubería, como cat error.log | claude -p "qué está pasando aquí".

Qué hace de fábrica. Sin preparar nada, en la mayoría de los casos tu primera petición sencilla en una sesión nueva ya hace lo correcto. V Pero Claude tiende a leer el encargo de forma conservadora y a construir lo mínimo que lo cumple, porque no puede ver cuánto esperabas. V

Qué pasa si das esos datos. Nombrar el fichero, el síntoma y qué es «arreglado» suele ahorrarte una ronda de correcciones más tarde: la que habrías gastado en explicarle después lo que no te había entendido. V La documentación no da una cifra de cuánto tiempo es eso, y nosotros no la hemos medido. Si quieres la versión completa y no la mínima, dilo: la frase que la documentación cita como útil es pedirle expresamente que sea ambicioso y decir qué entra, por ejemplo los estados vacíos y de error, el guardado conectado y el manejo con teclado, no solo la maqueta. Eso le cuenta el alcance, que solo sabes tú. V Y cuando estás explorando y no arreglando algo concreto, un encargo vago como «¿qué mejorarías de este fichero?» vale: corregirás algo más por el camino. V

Cuando todavía no sabes qué quieres. No hace falta resolverlo antes de escribir. Puedes pedirle que te entreviste hasta tener la especificación y que la escriba en un fichero, por ejemplo SPEC.md. Claude vuelve con preguntas de opciones sobre lo que no has decidido —límites por usuario o por clave, qué pasa con lo que se pasa del límite, qué queda fuera— hasta que las respuestas dan para una especificación. Después, la documentación recomienda abrir una sesión nueva para construir a partir de ese fichero, que empieza con el contexto limpio y con lo que significa «terminado» por escrito. V

Cuando se desvía. Mira el primer minuto. Esc lo para y conserva lo hecho hasta ahí, y /rewind devuelve el código, la conversación o los dos a una petición anterior. Si ya le has corregido lo mismo dos veces y sigue mal, la documentación aconseja /clear y un encargo nuevo que recoja lo aprendido, en lugar de una tercera corrección, porque la tercera se suma a una conversación que ya contiene dos intentos fallidos que Claude sigue releyendo. V

Lo que ya puedes dejar de escribir. La documentación da por superados cuatro hábitos de encargo, y dice por qué: V

• MAYÚSCULAS o la palabra «IMPORTANTE» en lo que no cumple. Los modelos actuales siguen una línea escrita con normalidad, y el énfasis amontonado hace sobre todo que apliquen la norma de más.
• Pedirle que piense mucho o que sea minucioso. Son texto corriente que empuja al modelo dentro de su nivel de esfuerzo; lo que de verdad lo cambia es /effort. La excepción es ultrathink, que pide razonar más en ese turno.
• Decirle que siga hasta acabar o que no sea vago. Los modelos actuales terminan la tarea acordada sin que se lo digas, y esas frases provocan antes trabajo de más. Darle una comprobación que tenga que pasar sí sirve.
• Describir la arquitectura y las carpetas en el CLAUDE.md. Claude lee el repositorio. Solo hay que escribir lo que no está en él.

Por dónde empezar. I Propuesta nuestra, a partir de lo anterior: antes de mandar un encargo de arreglo, comprueba que lleva tres líneas, una por dato. Dónde está el problema, qué ves exactamente, y qué tiene que pasar para darlo por bueno, que si puede ser es una prueba que ejecutar. Si te falta la tercera, todavía no sabes qué quieres, y es el momento de pedirle la entrevista.

• V Lo que un encargo no garantiza. Lo que escribes en el prompt, en el CLAUDE.md o en una skill lo lee el modelo, y el modelo decide qué hace con ello: suele cumplirlo, pero no hay garantía. Lo que tiene que pasar siempre, o no pasar nunca, va en algo que Claude Code ejecuta sin preguntar al modelo: un hook, una regla que prohíbe o un ajuste gestionado. Si añades énfasis a una línea del CLAUDE.md y Claude sigue saltándosela, la documentación lo toma como señal de que esa línea pide un hook. Lo contamos en la guía de hooks.
• V «Hecho» se comprueba, no se pregunta. Cuando Claude dice que ha terminado y no es así, suele ser porque no tenía forma de comprobar su trabajo. Por eso el tercer dato del encargo, cómo sabrás que está arreglado, vale más si es algo que Claude puede ejecutar: una prueba, una compilación.
• V Forma de la respuesta. Cuando lo que necesitas es que la respuesta salga con una forma fija, para que la lea un programa, eso no se pide en el encargo: se pide con un esquema. Lo contamos en la guía de salida estructurada.

1. Claude Code — Buenas prácticas: di lo que Claude no puede ver, guía la sesión y lo que ya puedes dejar de hacer · consultado 28-oct-2026