Búsqueda en una base de código con la herramienta Grep integrada de Claude Code
Claude Code incluye herramientas de búsqueda integradas que escanean un repositorio en busca de patrones, nombres de funciones, claves de configuración o cadenas literales y devuelven dónde se encuentra cada coincidencia.
Antes de que Claude Code lea un archivo o proponga una edición, normalmente busca primero, para que actúe sobre el conjunto real de archivos relevantes en lugar de adivinar cuáles son importantes.
Resumen
Las herramientas de búsqueda de Claude Code funcionan como una búsqueda rápida de patrones en todo el repositorio: proporciónales un término o patrón y devolverán cada archivo y línea coincidentes, en tantos archivos como contenga el repositorio.
Esto es distinto de abrir un solo archivo: la búsqueda opera en todo el árbol (o un subconjunto limitado del mismo) en una sola pasada.
La búsqueda es típicamente el paso que se ejecuta antes de que comience el bucle de lectura-edición-ejecución-prueba, porque Claude Code necesita saber qué archivos son realmente relevantes antes de leerlos en su totalidad.
Es especialmente valioso para tareas que abarcan varios archivos: renombrar una función de forma segura requiere conocer primero cada sitio de llamada, y encontrar cada uso de una clave de configuración o una cadena de error requiere la misma vista de todo el repositorio.
Dado que la búsqueda devuelve coincidencias, no archivos completos, es un paso de reconocimiento: Claude Code aún lee el contexto circundante de una coincidencia antes de editar ese archivo.
Receta
Referencia rápida: estas son indicaciones en lenguaje natural que escribes en el prompt de Claude Code. Claude Code decide cuándo invocar sus herramientas de búsqueda basándose en lo que pides.
# Encuentra dónde está definida algo
> ¿Dónde está definida la función calculateTotal en este repositorio?
# Encuentra cada sitio de llamada antes de un renombrado
> Encuentra todos los lugares que llaman a calculateTotal para poder renombrarla de forma segura.
# Encuentra cada uso de una clave de configuración, constante o cadena literal
> Busca en la base de código todas las referencias a la clave de configuración MAX_RETRIES.
# Limita una búsqueda a un subdirectorio o tipo de archivo
> Busca solo en el directorio api/ las llamadas al antiguo middleware de autenticación.Cuándo usar esto:
- Antes de renombrar una función, clase o variable, para conocer todos los sitios de llamada de antemano.
- Antes de eliminar o marcar como obsoleto una clave de configuración, un flag o un símbolo exportado.
- Al rastrear dónde se imprime realmente un mensaje de error o una cadena de registro.
- Cuando eres nuevo en un repositorio y necesitas encontrar el archivo que posee una determinada pieza de comportamiento.
- Antes de una edición en varios archivos, para que Claude Code tenga la lista completa de archivos a modificar en lugar de editar uno y omitir los demás.
Ejemplo de trabajo
Un escenario común: quieres renombrar una función y necesitas asegurarte de capturar primero cada sitio de llamada.
# 1. Inicia Claude Code en la raíz del proyecto
cd mi-proyecto
claude
# 2. Pídele que busque antes de tocar nada
> Encuentra todos los sitios de llamada de calculateTotal, luego renómbrala a computeOrderTotal
> en todas partes, incluyendo su definición y cualquier importación.El paso de búsqueda de Claude Code devuelve algo conceptualmente similar a esto (rutas de archivo y números de línea, uno por coincidencia):
src/orders/pricing.ts:42: export function calculateTotal(items, discounts) {
src/orders/checkout.ts:18: import { calculateTotal } from "./pricing";
src/orders/checkout.ts:57: const total = calculateTotal(cartItems, activeDiscounts);
src/reports/summary.ts:9: import { calculateTotal } from "../orders/pricing";
src/reports/summary.ts:31: const lineTotal = calculateTotal(row.items, []);
tests/pricing.test.ts:12: expect(calculateTotal([], [])).toBe(0);
A partir de esa lista de coincidencias, Claude Code lee cada archivo alrededor de la línea coincidente y luego propone ediciones coordinadas en todos ellos:
- export function calculateTotal(items, discounts) {
+ export function computeOrderTotal(items, discounts) {
- import { calculateTotal } from "./pricing";
+ import { computeOrderTotal } from "./pricing";
- const total = calculateTotal(cartItems, activeDiscounts);
+ const total = computeOrderTotal(cartItems, activeDiscounts);Lo que esto demuestra:
- La búsqueda se ejecuta primero y devuelve una lista de coincidencias en cada archivo afectado, no solo en el que comenzaste.
- La lista de coincidencias, no una suposición, es lo que le dice a Claude Code qué archivos necesitan ediciones.
- Un renombrado solo se considera seguro una vez que la definición, cada importación y cada sitio de llamada se actualizan juntos.
- Las pruebas que hacen referencia al nombre antiguo aparecen en la misma búsqueda, por lo que no quedan rotas.
- El paso de búsqueda y el paso de edición están separados: las coincidencias son ubicaciones de texto, las ediciones aún requieren leer y comprender el código circundante.
Profundización
Cómo funciona
- Las herramientas de búsqueda integradas de Claude Code escanean el contenido de los archivos en todo el repositorio (o en una ruta limitada que le proporciones) en busca de un patrón, nombre o cadena literal.
- Cada coincidencia se devuelve como una ruta de archivo y línea, junto con un poco de contexto circundante, no el archivo completo.
- La búsqueda generalmente respeta las reglas de ignorar del repositorio, por lo que la salida de compilación, las carpetas de dependencias y otros archivos generados generalmente no se devuelven como coincidencias.
- Los resultados se alimentan directamente al siguiente paso del bucle de lectura-edición-ejecución-prueba: Claude Code lee los archivos específicos que coincidieron, en lugar de leer todo el repositorio.
- Dado que la búsqueda es una operación de solo lectura, generalmente tiene menos fricción que un paso que ejecuta un comando o escribe un archivo, por lo que puede ejecutarse temprano y con frecuencia sin interrumpir tu flujo de trabajo.
- La misma maquinaria de búsqueda subyace a varias solicitudes cotidianas: "encontrar la función", "encontrar los llamadores", "encontrar cada uso" y "encontrar el archivo que posee esta cadena" son variaciones del mismo patrón de buscar y luego leer.
Búsqueda vs. Lectura vs. Edición
| Paso | Qué devuelve | Cuándo lo usa Claude Code |
|---|---|---|
| Búsqueda | Coincidencias de archivo + línea para un patrón en muchos archivos | Primero, para descubrir qué archivos son relevantes |
| Lectura | El contenido completo y actual de un archivo específico | Después de que la búsqueda reduce los candidatos, o cuando un archivo ya es conocido |
| Edición | Un diff propuesto contra un archivo que acaba de leer | Al final, una vez que se tienen en mano tanto el archivo correcto como el contexto correcto |
Obtener resultados útiles
# Vago - es probable que devuelva ruido o se pierda la intención
> Busca "total" en el código.
# Específico - nombra el símbolo exacto y qué quieres hacer con los resultados
> Encuentra todos los sitios de llamada de calculateTotal (la función en src/orders/pricing.ts),
> no solo la cadena "total".
# Limitado - reduce la búsqueda cuando el repositorio es grande o el término es común
> Busca solo en src/api/ las referencias a la antigua URL del webhook.Ser específico sobre el nombre exacto y limitar a un directorio o tipo de archivo cuando el término es común, obtiene una lista de coincidencias más limpia y una edición de seguimiento mejor.
Trampas
- Asumir que la búsqueda cubre todo en el árbol de trabajo. Los archivos generados, la salida de compilación y cualquier cosa en las reglas de ignorar del repositorio generalmente no aparecerán como coincidencias. Solución: si realmente necesitas buscar la salida generada, dilo explícitamente para que Claude Code sepa incluirla.
- Usar un término demasiado común. Buscar una palabra corta y genérica como "total" o "config" en un repositorio grande puede devolver una lista de coincidencias abrumadora y mayormente irrelevante. Solución: busca el nombre exacto de la función, clase o clave, y limita a un directorio cuando sea posible.
- Tratar una coincidencia de búsqueda como prueba de una llamada activa. Una coincidencia de patrón puede caer dentro de un comentario, una cadena o código muerto que nunca se ejecuta realmente. Solución: pide a Claude Code que confirme que cada coincidencia es un uso real antes de editar, especialmente para un renombrado que afecta a muchos archivos.
- Esperar que la búsqueda comprenda el uso dinámico o reflexivo. Una coincidencia de patrón solo encuentra texto; no capturará una función invocada por una cadena construida dinámicamente o a través de metaprogramación. Solución: señálalo explícitamente y pide un escrutinio adicional, luego verifica con una ejecución de prueba después de la edición.
- Confiar en un resultado de búsqueda de una etapa anterior de una sesión larga. Si los archivos cambiaron desde que se ejecutó esa búsqueda, la lista de coincidencias puede estar desactualizada cuando ocurra una gran edición en varios archivos. Solución: pide a Claude Code que vuelva a ejecutar la búsqueda inmediatamente antes de una gran edición coordinada en lugar de reutilizar resultados antiguos.
- Confundir "lo encontré" con "lo leí". Una coincidencia solo devuelve una línea y un poco de contexto, no el archivo completo. Solución: espera que Claude Code lea el archivo completo antes de proponer una edición, y no asumas que una coincidencia por sí sola es suficiente base para un cambio.
- Buscar sensible a mayúsculas/minúsculas (o no) sin querer. Un renombrado o una búsqueda de clave de configuración pueden omitir silenciosamente variantes que difieren solo en mayúsculas/minúsculas. Solución: indica explícitamente si deseas una coincidencia exacta o una que no distinga entre mayúsculas y minúsculas.
Alternativas
| Alternativa | Úsala cuando | No la uses cuando |
|---|---|---|
| Ejecutar un comando de búsqueda tú mismo en la terminal | Solo quieres ver las coincidencias en bruto sin que Claude Code actúe sobre ellas | Quieres que Claude Code razone sobre las coincidencias y edite varios archivos en el mismo turno |
| "Buscar en archivos" / búsqueda global de tu editor | Navegación manual rápida mientras ya estás en el IDE | Necesitas que los resultados impulsen una edición automatizada y coordinada en varios archivos |
git log -S<término> o git blame | Necesitas saber cuándo se introdujo una cadena o un símbolo históricamente | Necesitas cada uso actual, no el historial |
| "Buscar referencias" del servidor de lenguaje | Necesitas resolución de referencias a nivel de símbolo, consciente del alcance, en un idioma con un LSP configurado | No hay LSP configurado, o estás buscando claves de configuración, cadenas o patrones en lugar de un símbolo resoluble |
Preguntas frecuentes
¿Qué devuelve realmente la búsqueda integrada de Claude Code?
- Una lista de coincidencias, cada una con una ruta de archivo y número de línea
- Una pequeña cantidad de contexto circundante por coincidencia
- No el contenido completo de cada archivo: eso proviene de un paso de lectura separado
¿Cuándo decide Claude Code buscar en lugar de simplemente leer un archivo que ya conoce?
Si ya conoce exactamente qué archivo y ubicación son relevantes, puede leer directamente.
La búsqueda entra en juego cuando los archivos relevantes aún no se conocen, que es el caso común para renombrados, auditorías de uso y preguntas de "dónde está definido esto".
¿La búsqueda examina todo el repositorio, incluidas las dependencias y la salida de compilación?
Generalmente no. La búsqueda respeta típicamente las reglas de ignorar del repositorio, por lo que carpetas como la salida de compilación o las dependencias instaladas se excluyen de las coincidencias por defecto.
Puedes pedirle a Claude Code que incluya explícitamente una ruta específica si necesitas que se busque de todos modos.
¿Puedo limitar una búsqueda a un directorio específico o tipo de archivo?
Sí. Nombrar un directorio ("busca solo en src/api/") o un tipo de archivo en tu solicitud limita la búsqueda, lo cual es útil en un repositorio grande o cuando el término que buscas es común.
¿Es esto lo mismo que ejecutar un comando de búsqueda manual yo mismo en la terminal?
Conceptualmente similar: ambos buscan un patrón en los archivos, pero la versión de Claude Code está integrada en su flujo de trabajo, por lo que las coincidencias se alimentan directamente a los siguientes pasos de lectura y edición en el mismo turno, sin que copies los resultados de vuelta.
¿La búsqueda encontrará cada sitio de llamada antes de un renombrado?
Encuentra cada coincidencia de texto para el patrón que le das, lo que cubre la gran mayoría de los sitios de llamada reales.
No capturará una llamada construida dinámicamente en tiempo de ejecución (por ejemplo, a través de un nombre de función construido con cadenas), por lo que vale la pena verificar cualquier cosa inusual después de un renombrado.
¿Una coincidencia de búsqueda garantiza que el código allí realmente se ejecuta?
No. Una coincidencia puede caer en un comentario, una cadena literal o código muerto.
Claude Code generalmente lee el contexto circundante antes de editar, que es exactamente la salvaguarda para filtrar las coincidencias que no son usos reales.
¿Cómo encaja la búsqueda en el bucle de lectura-edición-ejecución-prueba de Claude Code?
La búsqueda generalmente ocurre antes de la primera lectura del bucle: identifica qué archivos son relevantes, luego Claude Code lee esos archivos específicos, propone ediciones, ejecuta un comando y verifica el resultado.
¿La búsqueda distingue entre mayúsculas y minúsculas?
El comportamiento puede variar según lo que pidas, por lo que vale la pena ser explícito: indica si deseas una coincidencia exacta o incluir variantes que difieren solo en mayúsculas/minúsculas.
¿Qué pasa si una búsqueda en un repositorio muy grande devuelve demasiados resultados?
Estrecha la solicitud: nombra el símbolo exacto en lugar de una palabra genérica, o limita la búsqueda a un directorio específico o tipo de archivo. Una solicitud más específica generalmente produce una lista de coincidencias más limpia y corta.
¿Puede la búsqueda encontrar una cadena literal, como un mensaje de error, no solo un nombre de función?
Sí. La búsqueda no se limita a nombres de funciones o símbolos: funciona igual de bien para claves de configuración, mensajes de error, cadenas de registro y otro texto literal.
¿La búsqueda necesita mi permiso para ejecutarse, como podría hacerlo un comando de shell?
La búsqueda es una operación de solo lectura, por lo que en la mayoría de las configuraciones de permisos se ejecuta sin el tipo de aviso de aprobación que podría desencadenar un comando con efectos secundarios (como una escritura de archivo o una instalación).
Si ya conozco el archivo y la línea exactos, ¿aún debería pedirle a Claude Code que busque?
No necesariamente: si ya sabes exactamente dónde vive algo, puedes dirigir a Claude Code directamente a él.
La búsqueda se justifica cuando aún no conoces todas las ubicaciones afectadas, que es la mayoría de las veces para cualquier cosa que abarque más de un archivo.
Relacionado
- Cómo Claude Code ejecuta el bucle de lectura-edición-ejecución-prueba - dónde encaja la búsqueda antes del paso de lectura
- Realización de ediciones en varios archivos en un solo turno de Claude Code - qué sucede después de que la búsqueda encuentra cada archivo afectado
- Por qué Claude Code vuelve a leer archivos antes de editarlos - por qué una coincidencia de búsqueda no se trata como una respuesta final
- Navegación por el REPL de Claude Code: Prompts y Comandos Slash - los conceptos básicos de escribir solicitudes como estas en el prompt
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 los detalles actuales en platform.claude.com/docs antes de confiar en ellos.