Cómo redactar la instrucción para que Claude Code edite un solo archivo

“Mejora un poco la introducción de este artículo del blog.”

Eso fue lo que escribí un viernes a las diez de la noche. Solo quería que tocara los tres primeros párrafos de un único archivo. Pero a la mañana siguiente, al abrir el diff, había doce archivos modificados. No solo el cuerpo del artículo: también el layout compartido, la lista de etiquetas y, sin saber por qué, hasta el archivo de configuración de publicación. Y me había ido a dormir sin comprobar siquiera si todo seguía funcionando.

Tardé treinta minutos en revertirlo. ¿Qué salió mal? No fue que Claude Code lo hiciera mal. Fue que mi instrucción no decía ni una palabra sobre hasta dónde podía tocar, así que una IA lista interpretó “mejorar la introducción = dejar de paso todo lo relacionado en orden” y se puso a ello.

En este artículo te doy, lista para copiar y pegar, la instrucción para “editar un solo archivo de forma segura” que nació de aquel desastre nocturno. Acotas el alcance, haces que la IA lo verifique al terminar y dejas preparada la forma de revertir si algo falla. Con solo eso, los accidentes de madrugada casi desaparecieron.

Puntos clave

• El trabajo que delegas a la IA se descontrola no porque el modelo sea malo, sino porque no escribiste hasta dónde puede tocar.
• La instrucción debe incluir siempre cinco cosas: “archivos a leer”, “archivos a cambiar”, “qué no tocar”, “comando de comprobación” y “cómo revertir”.
• Si haces que ejecute el comando de verificación antes de reportar éxito, evitas acabar siendo tú quien hace de tester después.
• Empieza por tareas pequeñas con un punto de parada claro: reescribir una intro de blog, ordenar un reporte de bug, retocar el texto de un producto.
• Acotar el alcance no rebaja el valor del artículo ni del resultado. Al contrario: al lector le resulta más fácil trasladarlo a su propio entorno.

Por qué “mejóralo” acaba en accidente

Pedir “mejóralo” no tiene una línea de meta.

Un editor humano, si se lo pides ocupado un viernes por la noche, te preguntaría: “Solo los tres párrafos de la intro, ¿verdad?”. Pero la IA puede arrancar sin preguntar. Y como se le da bien anticiparse, amplía el alcance por su cuenta: “Si voy a mejorar la intro, será más útil ordenar también las etiquetas y añadir algún enlace relacionado”. No hay mala intención. Eso es justo lo más peligroso.

Aquí es donde funciona la idea de escribir el punto de parada dentro de la propia instrucción. No hace falta un prompt largo ni rebuscado. Mejor corto. Lo que sí debes hacer es separar desde el principio, con claridad, qué archivos se pueden tocar y cuáles no. Con eso basta para frenar el descontrol.

Si quieres profundizar en la forma de escribir los prompts en sí, lee también diseño de prompts en Claude Code: así verás cómo este “acotar el alcance” se conecta con otras técnicas.

Los cinco puntos que nunca faltan en la instrucción

La instrucción que uso hoy lleva siempre estos cinco elementos. Y el orden también tiene su porqué.

Elemento	Contenido	Qué pasa si falta
Archivos a leer	El rango que puede leer para entender la situación	Lee sitios que no vienen al caso y propone arreglos fuera de lugar
Archivos a cambiar	Los 1 o 2 archivos que sí puede reescribir	Ocurre el accidente de los doce archivos
Qué no tocar	Configuración, archivos generados, secretos, ajustes de publicación	”Ordena” un archivo que no debía borrarse
Comando de comprobación	El único comando de verificación tras el cambio	Reporta “listo” con todo roto
Cómo revertir	Los pasos para volver atrás si se equivoca	La recuperación tarda 30 minutos

La clave es hacer que devuelva un “plan” antes de empezar a editar. Nada de reescribir de golpe. Que diga primero “qué archivos voy a leer, cuál voy a cambiar y qué se rompería si me equivoco”. Si el plan que devuelve no tiene sentido, lo paras ahí mismo. Sale muchísimo más barato que darte cuenta después de haber reescrito.

Lo que delegas en la IA y lo que decides tú

No hace falta entregárselo todo a la IA. La línea la trazo así.

Lo que puedes dejar en manos de la IA

• Leer archivos para entender la situación.
• Hacer un plan de cambios y ponerlo en palabras.
• Escribir el texto o el código en sí.
• Ejecutar el comando de verificación y reportar el resultado.

Lo que conservas tú

• Qué archivos entran en el alcance del cambio (la decisión del alcance).
• Pulsar el botón de publicar o desplegar a producción.
• La decisión de tocar archivos de configuración o secretos.
• La decisión de detener la publicación cuando la verificación falla.

Esta separación es más importante cuanto menos experiencia tengas delegando trabajo a una IA. Cómo repartir lo que delegas y lo que decides tú aparece también, como idea básica, en Claude Code para no programadores. Mientras te acostumbras, basta con una regla tosca: “leer y escribir lo hace la IA; borrar y publicar lo hace una persona”.

Plantilla de instrucción lista para copiar y pegar

Pégala tal cual y cambia solo los nombres de archivo por los de tu entorno. Tanto en PowerShell como en bash, basta con meter el texto en una variable y comprobarlo.

brief=$(cat <<'EOF'
Objetivo: hacer una sola edición segura en un único punto.
Archivos que puedes cambiar: site/src/content/blog/example.mdx
Qué no tocar: archivos de tipo package, archivos generados, secretos, ajustes de publicación o despliegue.

Antes de empezar a editar, devuelve:
1. Los archivos que vas a leer para entender la situación
2. El único archivo que vas a cambiar
3. Qué se rompería si ese cambio fuera incorrecto
4. El comando de comprobación que ejecutarás tras el cambio

Cuando termines de editar, devuelve:
- Un resumen del diff
- El resultado de ejecutar el comando de comprobación
- Los pasos para revertir
EOF
)

echo "$brief"

Este texto no es vistoso. Su valor está en poner por escrito la frontera antes de empezar a trabajar. Cambia los nombres de archivo, qué no tocar y el comando de comprobación por los de tu repositorio, y pásaselo a Claude Code. Cuando devuelva un buen plan, hazle repetir las mismas restricciones antes de dejar que se ponga a trabajar.

Si escribes las mismas restricciones en tu CLAUDE.md, surten efecto automáticamente sin tener que pegarlas cada vez. Lo explico en buenas prácticas de CLAUDE.md.

Un pequeño script que verifica al terminar

No te creas el “listo”. Este es el segundo pilar.

Cuando termina la edición, comprueba de forma mecánica si de verdad solo se modificó un archivo. El script de abajo cuenta cuántos archivos sin commitear han cambiado y se detiene si son más de los previstos. Funciona tal cual, con comentarios incluidos.

#!/usr/bin/env bash
# Comprueba que solo cambió un archivo. Si son demasiados, se detiene.
set -e

# Numero de archivos que esperas que cambien (1 si editas un solo archivo)
expected=1

# Cuenta los archivos modificados sin commitear
changed=$(git status --porcelain | grep -c .)

echo "Archivos modificados: $changed (previstos: $expected)"

if [ "$changed" -gt "$expected" ]; then
  echo "Han cambiado mas archivos de los previstos. Revisa el diff."
  git status --porcelain
  exit 1
fi

echo "Dentro del alcance previsto."

Si indicas este script como “comando de comprobación” en la instrucción, la IA lo ejecuta ella misma y reporta el resultado. Si hay doce archivos cambiados, salta el texto en rojo en el momento del reporte. No me entero al levantarme por la mañana: se detiene ahí mismo. Eso es lo que marca la diferencia.

Si quieres automatizar más la verificación y la organización del día a día, en técnicas para mejorar la productividad con Claude Code reúno otros patrones.

Tres situaciones donde esto funciona

Todas son tareas con un “punto de parada” claro. Dicho al revés: si una tarea no tiene punto de parada visible, es señal de que todavía no conviene delegarla entera a la IA.

1. Reescribir la intro de un artículo del blog Escribe desde el principio que solo se cambia la introducción de un único archivo. Añade el lector objetivo y el comando de comprobación. Así la IA no extiende la mano al cuerpo entero ni al layout. Mi accidente de los doce archivos no habría ocurrido con solo esa línea.

2. Ordenar un reporte de bug Muéstrale únicamente el archivo de log y una plantilla, y escribe “prohibido ordenar código no relacionado”. Si te refactoriza de paso mientras ordena el reporte, la revisión se vuelve pesadísima de golpe. Al acotar lo que ve, acotas también lo que produce.

3. Probar el texto de una página de producto En lugar de rehacer la página entera, pide solo “una propuesta de eslogan” y “la comprobación de cómo queda tras el cambio”. Como el alcance está fijado a una propuesta, comparar es fácil incluso cuando pruebas en A/B.

Preguntas frecuentes

P. ¿No es engorroso pegar esta instrucción tan larga cada vez? Si escribes las restricciones que más usas en tu CLAUDE.md, surten efecto sin pegarlas cada vez. Lo único que pegarás será “el nombre del archivo que puede tocar esta vez”.

P. ¿Acotar el alcance no mata lo bueno de la IA? Era al revés. Cuanto más estrecho el alcance, más a fondo corrige la IA sin titubear. Una instrucción amplia solo la hace dudar sobre por dónde empezar.

P. ¿Qué comando de comprobación pongo? Al principio basta con “comprobar el número de archivos modificados”. Cuando te acostumbres, vas sumando uno a uno: que la build pase, que los tests no fallen, que no haya enlaces rotos.

P. ¿Y si aun así cambia un archivo inesperado? Si tienes la forma de revertir escrita en la instrucción, solo sigues esos pasos. El truco es meter desde el inicio el comando de rollback, como git restore ., dentro de la propia instrucción.

P. ¿Por dónde conviene empezar? Elige una tarea pequeña que puedas revertir aunque salga mal. Retocar un borrador de artículo o sustituir un texto va muy bien. Si te da inseguridad la operativa básica, empezar por la guía de iniciación a Claude Code te allana el terreno.

Lo que comprobé al probarlo de verdad

Después de aquel accidente de los doce archivos, me acostumbré a escribir siempre la instrucción con “archivos a cambiar”, “qué no tocar” y “comando de comprobación”.

Desde que indico el script de verificación como “comando de comprobación”, los casos en los que se cuela un archivo inesperado se detienen en el acto. De hecho, la semana pasada, al hacerle retocar el texto de una página de producto, la IA empezó a extender la mano hasta un componente compartido; pero en cuanto el número de archivos modificados llegó a 2, el script sacó el rojo y se detuvo. Se acabó eso de palidecer al ver el diff por la mañana.

Lo otro que confirmé es que acotar el alcance no baja la calidad del resultado. Los días en que lo até a “solo los tres párrafos de la intro” me devolvió, más bien, correcciones más certeras. Antes que delegar mucho en una IA lista, pedir poco y hacer que ella misma lo verifique. Parece el camino largo, pero es el más rápido para mí: esa es mi conclusión de hoy.

Si quieres montar en tu empresa un sistema para delegar a la IA la edición y la operativa, en formación y consultoría de implantación lo armamos juntos desde los pasos concretos. Pero antes prueba tú mismo, una vez, una instrucción de un solo archivo.

Por cierto, la información oficial de la herramienta usada aquí está en la documentación oficial de Claude Code.