Realizar ediciones en varios archivos en un solo turno de Claude Code
Claude Code puede renombrar una función, agregar un campo a un tipo compartido o mover un módulo y actualizar cada archivo que lo utiliza, todo en un solo turno, sin dejar importaciones rotas o sitios de llamada obsoletos.
Resumen
Una "edición en varios archivos" es cualquier cambio que no está contenido en un solo archivo: un renombramiento, un cambio de firma, un nuevo campo requerido, un módulo movido. Cada uno de estos tiene un radio de explosión: cada lugar que importa, llama o construye la cosa que estás cambiando.
Claude Code maneja esto tratando la búsqueda como un primer paso, no como una ocurrencia tardía. Antes de tocar nada, localiza cada uso en todo el repositorio para que el plan de edición cubra todo el radio de explosión, no solo el archivo que mencionaste.
También relee cada archivo inmediatamente antes de editarlo, lo cual es más importante en un turno de varios archivos que en uno solo: para cuando Claude llega al archivo cinco, los archivos del uno al cuatro ya han cambiado, y el archivo cinco en sí mismo puede haber sido tocado por una herramienta de compilación, un formateador o el usuario en otra terminal.
El turno no termina en la última edición. El bucle principal de Claude Code es leer, editar, ejecutar, verificar, por lo que después de que las ediciones se aplican, normalmente ejecuta un comando de compilación, lint o prueba para detectar cualquier cosa que la búsqueda haya omitido, como una ruta de importación construida dinámicamente o un sitio de llamada en un archivo que el patrón de búsqueda no coincidió.
Esta página recorre ese flujo de principio a fin: encontrar cada uso, editar a través de archivos en orden y verificar que nada se rompió.
Receta
Tarjeta de receta de referencia rápida: el patrón de solicitud que obtiene una edición limpia en varios archivos.
Renombra la función `calculateTotal` a `calculateOrderTotal` en todas partes
donde está definida y llamada. Actualiza todas las importaciones y sitios de llamada.
Luego ejecuta la suite de pruebas para confirmar que nada se rompió.# Después de que Claude Code proponga y aplique las ediciones, verifica tú mismo también:
npm test
npm run build
grep -rn "calculateTotal(" src/ # no debería devolver nadaCuándo usar esto:
- Renombrar una función, método o variable exportada utilizada en más de un archivo.
- Agregar o eliminar un campo en un tipo/interfaz/esquema que se construye o lee en varios lugares.
- Mover o dividir un módulo y necesitar que todas las rutas de importación se arreglen.
- Cambiar la firma de una función (nuevo argumento requerido, parámetros reordenados) en todos los sitios de llamada.
- Cualquier cambio donde "grep el nombre antiguo" devolvería más de un archivo.
Ejemplo de trabajo
Digamos que un tipo User gana un campo requerido role, y tres archivos lo tocan: la definición del tipo, una función de fábrica que construye usuarios y un componente que lee el campo.
# 1. Pide a Claude Code el cambio, nombrando explícitamente el tipo compartido
claude "Agrega un campo requerido `role: 'admin' | 'member'` al tipo User
en types/user.ts. Actualiza cada lugar que construye un User para pasar un rol,
y cada lugar que lee campos de User para manejar el nuevo. Busca en todo el
repositorio primero, luego muéstrame el plan antes de editar."El primer movimiento de Claude Code es una búsqueda en todo el repositorio de usos de User: la definición del tipo, constructores y sitios de lectura, antes de proponer algo. Una vez que confirmas, edita cada archivo en orden. Un diff representativo a través de los tres archivos:
--- a/types/user.ts
+++ b/types/user.ts
export type User = {
id: string;
name: string;
+ role: 'admin' | 'member';
};--- a/lib/create-user.ts
+++ b/lib/create-user.ts
-export function createUser(id: string, name: string): User {
- return { id, name };
+export function createUser(id: string, name: string, role: User['role']): User {
+ return { id, name, role };
}--- a/lib/format-user.ts
+++ b/lib/format-user.ts
export function formatUser(user: User): string {
- return `${user.name} (${user.id})`;
+ return `${user.name} (${user.id}) - ${user.role}`;
}# 2. Claude Code (o tú) ejecuta la compilación/pruebas para detectar cualquier cosa que la búsqueda haya omitido
npm run build
npm testLo que esto demuestra:
- La búsqueda se ejecuta antes de cualquier edición, por lo que el plan ya tiene en cuenta el constructor y el lector, no solo la definición del tipo.
- Cada archivo se edita para que coincida con su propia responsabilidad: el tipo gana un campo, el constructor gana un parámetro, el lector gana un caso de visualización, en lugar de un simple buscar y reemplazar.
- El turno se cierra con una ejecución de compilación/prueba, que es lo que detectaría un cuarto sitio de llamada que el patrón de búsqueda no coincidió (un acceso dinámico a propiedades, por ejemplo).
- Nada aquí es especulativo: cada línea cambiada es utilizada por código real en el mismo turno, sin "TODO: manejar esto más tarde".
Profundización
Cómo funciona
- Buscar primero. La herramienta de búsqueda integrada de Claude Code, similar a grep, localiza cada definición de función, sitio de llamada, importación o uso de tipo que coincida con el objetivo antes de que se abra ningún archivo para editar. Esto es lo que convierte "renombrar esta función" en "renombrar esta función y sus N sitios de llamada" en lugar de "renombrar esta función en el único archivo que miré".
- Ediciones ordenadas y secuenciales. Los archivos se editan uno a la vez dentro del turno, típicamente comenzando desde la definición (tipo, función, módulo) y moviéndose hacia afuera hacia sus consumidores, en lugar de hacerlo todo a la vez, ya que la corrección de cada edición puede depender de lo que cambió justo antes.
- Releer antes de cada escritura. Inmediatamente antes de editar un archivo determinado, Claude Code lo relee en lugar de confiar en la copia que leyó durante el paso de búsqueda. En un turno de varios archivos, esto protege contra dos cosas: un archivo que cambia entre el paso de búsqueda y el paso de edición, y un archivo que se edita dos veces en el mismo turno (una vez para el renombramiento, otra para algo incidental) donde la segunda edición necesita el resultado de la primera edición, no la versión previa al turno.
- Verificar con comandos reales, no solo con inspección. Después de las ediciones, el bucle principal de Claude Code pasa a ejecutar un comando de compilación, tipo, lint o suite de pruebas y lee la salida. Una importación rota o un sitio de llamada omitido generalmente aparecen aquí, incluso si no eran visibles solo desde el código fuente (por ejemplo, un archivo "barrel" de reexportación que importa el nombre antiguo).
- Iterar sobre fallos. Si el paso de ejecución informa un error, Claude Code lo trata como nueva información y vuelve a editar, en lugar de tratar el primer pase como final.
Reglas de un vistazo
| Paso | Qué sucede | Por qué importa para ediciones en varios archivos |
|---|---|---|
| Búsqueda | Localiza cada uso en todo el repositorio | Define el radio de explosión real antes de tocar cualquier archivo |
| Plan | Enumera los archivos que necesitan cambiar | Te permite detectar un archivo faltante antes de que comiencen las ediciones |
| Edición | Relee, luego escribe, un archivo a la vez | Evita trabajar con una copia obsoleta a mitad del turno |
| Ejecución | Compilar, lint o probar | Detecta usos que el patrón de búsqueda no coincidió |
| Iterar | Corregir y volver a ejecutar en caso de fallo | Cierra el ciclo en lugar de detenerse en "ediciones aplicadas" |
Darle a Claude Code un mejor prompt para varios archivos
Malo: "Renombra calculateTotal a calculateOrderTotal."
Bueno: "Renombra calculateTotal a calculateOrderTotal en todas partes donde está
definida y llamada (busca en el repositorio primero), actualiza las
importaciones y ejecuta la suite de pruebas cuando hayas terminado."Nombrar explícitamente el paso de búsqueda y el paso de verificación no es obligatorio (Claude Code hace ambos por defecto), pero mencionarlos desde el principio tiende a producir un plan que puedes revisar antes de que comiencen las ediciones, lo cual vale la pena en un cambio que afecta a más de dos o tres archivos.
Posibles problemas
- Nombres de destino vagos subestiman los usos. Pedir renombrar algo con un nombre genérico (
get,Data,Item) puede omitir símbolos no relacionados que comparten el nombre, o coincidir de manera demasiado amplia. Solución: da el símbolo exacto y completamente calificado (calculateTotalenlib/pricing.ts, no solo "la función total") y pide a Claude Code que busque antes de editar. - Referencias dinámicas no aparecen en una búsqueda de texto. Una llamada construida a partir de una cadena (
window[fnName](), una búsqueda basada en reflexión, una tabla de rutas indexada por cadena) no coincidirá con un grep del nombre antiguo. Solución: menciónalo explícitamente en el prompt y confía en el paso de ejecución/prueba: un sitio de llamada dinámico fallará en tiempo de ejecución incluso cuando la búsqueda lo omita estáticamente. - Se omiten los barriles/archivos index que reexportan. Un archivo que hace
export { calculateTotal } from './pricing'es en sí mismo un sitio de llamada para el nombre de exportación, y es fácil pasarlo por alto. Solución: pide a Claude Code que busque el nombre como una cadena literal, no solo como una llamada a función, para que se capturen tanto los patronesexport { name }comoimport { name }. - Interrumpir a mitad de turno deja el repositorio medio editado. Si detienes Claude Code después de que haya editado tres de cinco archivos, los otros dos ahora discrepan con los primeros tres. Solución: deja que un turno de varios archivos termine, o si debes detenerlo, pide a Claude Code un resumen de exactamente qué archivos se cambiaron y cuáles no antes de continuar en otro lugar.
- Omitir el paso de verificación oculta una ruptura real. Un renombramiento que "parece completo" en cada diff aún puede fallar al compilar si un sitio de llamada utilizó un orden de argumentos diferente o un alias reexportado. Solución: siempre deja (o pide) que Claude Code ejecute el comando de compilación/prueba/lint como parte del mismo turno, no como un paso manual separado que podrías olvidar.
- Cambios grandes y no relacionados en varios archivos son más difíciles de revisar. Agrupar un renombramiento con un pase de formato no relacionado en los mismos archivos hace que el diff sea mucho más grande que el cambio real. Solución: pide primero solo el renombramiento, revísalo, luego solicita el formato u otra limpieza como un turno separado.
Alternativas
| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| Un turno de Claude Code por archivo, revisado individualmente | El cambio es genuinamente local al archivo (una corrección de error en una función sin llamadores externos) | Los archivos están acoplados: un renombramiento o cambio de campo necesita que se muevan juntos para mantenerse limpios al compilar |
| Herramienta de refactorización "renombrar símbolo" nativa del editor | Tu IDE tiene información de tipo completa y el renombramiento es un cambio de identificador puro sin lógica que ajustar | El cambio también requiere decisiones por sitio de llamada (por ejemplo, un nuevo campo requerido necesita un valor predeterminado diferente en cada sitio de construcción) |
| Buscar y reemplazar manual en todo el repositorio | Un intercambio de cadenas trivial y sin ambigüedades (una clave de configuración renombrada utilizada solo como literal) | El nombre del símbolo podría colisionar con texto no relacionado, o los usos necesitan un manejo diferente según el contexto |
| Un solo turno de Claude Code que abarque todos los archivos afectados | El cambio tiene un radio de explosión claro que Claude Code puede buscar y los archivos necesitan aterrizar juntos | El cambio es lo suficientemente grande como para que revisar un diff gigante sea más difícil que revisar varios turnos pequeños y secuenciales |
Preguntas frecuentes
¿Cómo sabe Claude Code qué archivos cambiar para un renombramiento?
- Ejecuta una búsqueda en todo el repositorio (su herramienta integrada similar a grep) para el símbolo antes de editar nada.
- La búsqueda cubre la definición, las importaciones y los sitios de llamada.
- Nombrar el símbolo exacto y su archivo en tu prompt reduce la búsqueda y disminuye las coincidencias falsas.
¿Claude Code edita todos los archivos a la vez o uno a la vez?
Uno a la vez, en secuencia, usualmente comenzando desde la definición y moviéndose hacia afuera hacia los consumidores, no una escritura masiva simultánea.
¿Por qué Claude Code relee un archivo justo antes de editarlo, si ya lo leyó durante la búsqueda?
Porque el archivo puede haber cambiado desde esa primera lectura, ya sea por una edición anterior en el mismo turno de varios archivos o por algo completamente ajeno al turno. Editar desde una copia obsoleta corre el riesgo de descartar silenciosamente esos cambios.
¿Qué impide que una edición en varios archivos rompa silenciosamente un sitio de llamada que la búsqueda omitió?
El paso de ejecución. Después de editar, el bucle principal de Claude Code ejecuta un comando de compilación, lint o prueba y lee la salida, lo que típicamente revela una importación rota o una llamada desajustada, incluso cuando la búsqueda de código fuente no la detectó.
¿Qué debo hacer si el plan de edición de Claude Code omite un archivo que sé que necesita cambiar?
Dilo antes de que comience a editar: nombra el archivo y el símbolo faltantes directamente. Revisar el plan antes de que las ediciones aterricen es el punto más barato para corregir un radio de explosión subestimado.
¿Puede fallar un turno de edición en varios archivos a mitad de camino?
Sí, si lo interrumpes, o si una edición posterior depende de un archivo que Claude Code no pudo resolver. El resultado es un repositorio medio editado, por lo que es mejor dejar que el turno termine o pedir un resumen de lo que cambió y lo que no antes de continuar.
¿Claude Code detectará un sitio de llamada construido dinámicamente, como una búsqueda de función con clave de cadena?
No de manera confiable solo con la búsqueda, ya que una búsqueda de texto no puede coincidir con un nombre construido en tiempo de ejecución. Señala las referencias dinámicas explícitamente en tu prompt y confía en la ejecución de pruebas/compilación para detectar lo que la búsqueda estática no puede ver.
¿Debo pedir un renombramiento y una limpieza no relacionada en el mismo turno?
No, agruparlos hace que el diff sea más difícil de revisar y más difícil de revertir si algo está mal. Pide solo el renombramiento primero, revísalo, luego solicita la limpieza por separado.
¿Cuál es el prompt mínimo para una edición limpia en varios archivos?
Nombra el símbolo exacto y su archivo, indica que todos los usos en el repositorio deben actualizarse y pide un plan de búsqueda primero más una ejecución de verificación al final. Ejemplo: "Renombra X en path/to/file en todas partes donde se usa, luego ejecuta las pruebas."
¿Cuenta un archivo barril/índice que reexporta una función renombrada como un sitio de llamada?
Sí, export { name } from './module' hace referencia al nombre de exportación al igual que una importación, y es fácil pasarlo por alto si solo estás escaneando llamadas a funciones en lugar del identificador literal.
¿En qué se diferencia esto de una edición de un solo archivo?
El bucle principal (leer, editar, ejecutar, verificar) es el mismo, pero el paso de búsqueda se vuelve fundamental: una edición de un solo archivo no necesita descubrir un radio de explosión, mientras que la corrección de una edición de varios archivos depende completamente de encontrar todos los archivos afectados de antemano.
¿Cuál es una buena manera de verificar que el renombramiento realmente eliminó todas las referencias antiguas?
Ejecuta un simple grep para el nombre antiguo después de que el turno se complete: grep -rn "oldName(" src/ debería devolver nada (aparte de comentarios o registros de cambios que dejaste intencionalmente).
Relacionados
- Búsqueda en una base de código con la herramienta Grep integrada de Claude Code - el paso de búsqueda que define el radio de explosión de una edición en varios archivos.
- Por qué Claude Code relee archivos antes de editarlos - por qué la relectura importa más una vez que hay varios archivos en juego.
- Cómo Claude Code ejecuta el bucle Leer-Editar-Ejecutar-Probar - el paso de verificación que detecta lo que la búsqueda sola no puede.
- Una lista de verificación para revisar los diffs propuestos por Claude Code - qué verificar en un diff de varios archivos antes de aceptarlo.
- Generación de subagentes paralelos para tareas de investigación aisladas - dividir el trabajo entre archivos cuando no necesita aterrizar como un turno coordinado.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026: Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica las especificaciones actuales en platform.claude.com/docs antes de confiar en ellos.