# Claude Code para principiantes: análisis y edición de proyectos en la práctica > Guía práctica completa para dominar Claude Code: exploración de código con Read, Glob y Grep, auditorías de código locales, ediciones multi-archivo y reversión segura de cambios. ## 1. Cómo explora y lee el código Claude Code A diferencia de las herramientas de chat web de IA donde el programador debe copiar y pegar fragmentos en una ventana de conversación, Claude Code es un agente de terminal nativo. Dispone de acceso directo al sistema de archivos local de tu repositorio y selecciona de forma autónoma herramientas especializadas para navegar por la base de código. El agente no vuelca la totalidad del repositorio en memoria de golpe (lo que saturaría instantáneamente el límite de tokens de contexto), sino que emplea una estrategia de exploración quirúrgica y progresiva. ```mermaid flowchart TD A["Pregunta del desarrollador:
'¿Cómo funciona la autenticación?'"] --> B["Claude Code CLI"] B --> C["Glob
(Búsqueda de archivos auth/*, login.*)"] B --> D["Grep
(Búsqueda de términos createSession, jwt)"] C & D --> E["Evaluación de rutas encontradas"] E --> F["Read
(Lectura focalizada de archivos clave)"] F --> G["Respuesta sintetizada con referencias exactas"] ``` ### Arsenal principal de herramientas de exploración ![Herramientas de navegación de Claude Code](/api/guides-media/automation/claude-code-practice-guide-for-beginners/images/claude-code-practice-guide-for-beginners-extra-01.webp) | Herramienta | Qué realiza | Ejemplo común de uso | | :--- | :--- | :--- | | **`Read`** | Abre y lee el contenido de un archivo en una ruta concreta | `Read src/auth/login.ts` para examinar la lógica del componente | | **`Glob`** | Localiza archivos y rutas según patrones de máscara o extensión | Encontrar todos los `**/*.config.{js,ts}` o tests `*.test.ts` | | **`Grep`** | Ejecuta búsquedas de texto y expresiones regulares en el código | Buscar sitios de invocación de funciones o anotaciones `TODO` | | **`Bash(ls)`** | Examina la jerarquía de carpetas y los módulos disponibles | Inspeccionar el contenido del directorio `src/components/` | > [!NOTE] > No es necesario invocar estas herramientas manualmente. Plantea tu consulta de ingeniería en lenguaje natural y Claude Code coordinará la secuencia adecuada por sí mismo. --- ## 2. Onboarding rápido en proyectos desconocidos Al clonar un repositorio grande por primera vez, dedicar horas a revisar carpetas a ciegas resulta muy ineficiente. Claude Code permite obtener una radiografía arquitectónica precisa en cuestión de segundos. ### Formulación del prompt de diagnóstico arquitectónico Sitúate en la raíz del repositorio, inicia `claude` y comienza con una pregunta general de descubrimiento: ```text Give me an overview of this project. What does it do, what is the tech stack, and how is the code organized? ``` ### Qué acciones ejecuta el agente durante el escaneo 1. **Lectura de manifiestos de dependencias:** revisa `package.json`, `Cargo.toml`, `go.mod` o `requirements.txt` para identificar librerías y frameworks esenciales. 2. **Revisión de documentación:** consulta `README.md`, `ARCHITECTURE.md` o especificaciones de la API. 3. **Evaluación de la estructura de carpetas:** analiza la distribución de responsabilidades (`src/api`, `src/components`, `src/services`, `prisma`). 4. **Generación del informe:** presenta un resumen estructurado con módulos clave, puntos de entrada y comandos para el entorno de desarrollo. > [!TIP] > Las explicaciones de Claude se fundamentan en el código real almacenado en tu disco, evitando la desinformación de documentaciones obsoletas. --- ## 3. Investigación focalizada: rastreo de flujos de datos y peticiones Tras comprender la arquitectura general, llega el momento de profundizar en los flujos de negocio. Una de las mayores virtudes de Claude Code radica en su capacidad para trazar la cadena completa de llamadas (Call Trace) entre las diferentes capas de la aplicación. :::tabs @tab Autenticación ```text How does authentication work in this project? Trace the lifecycle of a request from the login form submission through JWT validation to the protected database query. ``` @tab Proceso de Compra ```text What happens when a user submits the checkout form? Trace the request flow from the frontend form to payment gateway processing and email notification dispatch. ``` @tab Recepción de Webhooks ```text Trace how incoming Stripe webhooks are received, verified for signature integrity, and processed in our database transaction worker. ``` ::: ### Cómo traza Claude las cadenas de interacción Cuando solicitas «rastrear un flujo», el agente: - Localiza el formulario o botón en la interfaz mediante `Grep`. - Identifica el controlador y el endpoint de API asociado. - Revisa la ruta en el backend, analizando los middleware de validación y seguridad. - Inspecciona las consultas al ORM o base de datos y entrega un diagrama lógico paso a paso con los números de línea correspondientes. --- ## 4. Búsqueda profunda de patrones y refactorización de importaciones Mediante los motores internos `Grep` y `Glob`, Claude Code lleva a cabo búsquedas milimétricas de usos de funciones, tipos e importaciones sin saturar la consola con volcados de terminal ilegibles. ### Ejemplos prácticos de búsqueda ```bash # Localizar todos los archivos que consumen un módulo de autenticación Which files import from @/lib/auth or use the useSession hook? # Descubrir deudas técnicas y recordatorios pendientes Show me all TODO, FIXME, and HACK comments across the codebase with file paths # Encontrar puntos de invocación de una función concreta Where is the calculateDiscount function called, and what parameters are passed to it? # Listar migraciones de base de datos recientes List all migration files in the prisma/migrations/ directory created in the last month ``` Claude organiza los resultados por categorías semánticas y resume el contexto de cada hallazgo, en lugar de limitarse a mostrar una lista plana de líneas. --- ## 5. Análisis y deconstrucción de código complejo Frente a código heredado intrincado, expresiones regulares indescifrables o máquinas de estado reactivas complejas, pide a Claude un análisis pormenorizado. ### Prompts de deconstrucción técnica ```text # Explicación de una cadena de middlewares Explain the middleware execution pipeline in src/server/middleware.ts. What does each middleware do, and in what exact order are they executed? # Desglose de expresiones regulares complejas This regex in src/utils/validators.ts is hard to read. Break it down part by part and provide examples of matching and non-matching strings. # Auditoría del ciclo de vida de un componente The state management in UserDashboard.tsx looks overly complex. Explain the state flow, what triggers each useEffect, and where race conditions might occur. ``` El asistente no se limita a parafrasear el código, sino que detecta casos límite (edge cases), fugas de memoria y posibles condiciones de carrera. --- ## 6. Realización de Code Reviews y análisis de Git Diff Claude Code actúa como un revisor de código incansable antes de consolidar cambios en un commit o abrir un Pull Request. ### Flujos de trabajo de revisión de código ```bash # 1. Auditoría rápida de cambios preparados (staged) antes de commitear git diff --staged | claude -p "Review this diff for bugs, edge cases, security issues, and style problems. Be concise." # 2. Comprobación de divergencias entre la rama actual y main git diff main...feature-branch | claude -p "Perform a code review of this branch. Focus on performance regressions and breaking changes." ``` ### Revisión interactiva durante la sesión Si ya te encuentras dentro de una sesión interactiva de Claude, basta con introducir: ```text Review the changes I made in the last commit. Look for logic bugs, missing error handling, and potential production bottlenecks. ``` Claude examina el delta de Git, detecta posibles excepciones no gestionadas y propone soluciones antes de que el código llegue a tus compañeros. --- ## 7. Herramientas de modificación: Edit, Write y Bash Comprender la mecánica con la que Claude Code modifica tus archivos locales es vital para trabajar con total seguridad. Para alterar el código, el agente emplea tres herramientas: `Edit`, `Write` y `Bash`. ```mermaid flowchart LR subgraph Modificacion_del_Disco["Herramientas de edición"] E["Edit Tool
(Reemplazo quirúrgico de líneas)"] W["Write Tool
(Creación / sobrescritura)"] B["Bash Tool
(Comandos, dependencias, tests)"] end E --> D["Previsualización de Diff coloreado"] W --> D B --> D D --> U{"Confirmación del usuario"} U -->|Y| S["Guardado en el disco"] U -->|N| R["Descarte de la propuesta"] ``` ### Herramienta Edit: reemplazos quirúrgicos de líneas `Edit` aplica cambios puntuales sin reescribir todo el archivo. Localiza un bloque unívoco de código y lo sustituye por la versión actualizada, preservando el resto del archivo intacto. ```diff // Ejemplo de diff visualizado en la terminal de Claude Code: async function fetchUser(id: string) { - const response = await fetch(`/api/users/${id}`); - return response.json(); + try { + const response = await fetch(`/api/users/${id}`); + if (!response.ok) { + throw new Error(`Failed to fetch user: ${response.status}`); + } + return await response.json(); + } catch (error) { + console.error('Error fetching user:', error); + throw error; + } } ``` Siempre dispondrás de una previsualización clara en formato diff antes de autorizar la modificación. ### Herramienta Write: creación de nuevos módulos `Write` se emplea para generar archivos nuevos desde cero o actualizar completamente archivos de configuración: ```text Create a new utility module at src/lib/formatters.ts with helpers for currency formatting, relative timestamps, and phone numbers. Include JSDoc comments. ``` ### Herramienta Bash: ejecución y comprobación en el sistema `Bash` habilita al agente para interactuar con el sistema operativo: instalar paquetes, aplicar migraciones, compilar el proyecto y ejecutar tests: ```text Install zod and create a registration form schema in src/schemas/auth.ts, then run typecheck to make sure types align. ``` --- ## 8. Modificaciones transversales en múltiples archivos en un solo prompt La mayor ventaja de Claude Code frente a chats convencionales es su capacidad para coordinar refactorizaciones integrales que abarcan múltiples capas de la aplicación en una sola orden. ```text Add a 'phoneNumber' field to the User entity. Update the Prisma schema, generate the migration, update the registration API route, and add the input field to the Profile form component. ``` ### Cómo coordina Claude los cambios multi-archivo 1. **Modificación del esquema:** actualiza `schema.prisma` utilizando `Edit`. 2. **Lanzamiento de la migración:** invoca `npx prisma migrate dev` mediante `Bash`. 3. **Ajuste de validación backend:** incorpora las reglas del campo en el esquema Zod de `src/app/api/user/route.ts`. 4. **Adaptación de la interfaz:** añade el elemento input correspondiente en `src/components/ProfileForm.tsx`. 5. **Verificación de tipos:** ejecuta `npm run typecheck` para asegurar la coherencia en todo el stack. Cada una de estas acciones solicita tu autorización individual, garantizando un control riguroso del proceso. --- ## 9. Refinamiento iterativo y reversión segura de cambios El trabajo con Claude Code es una conversación interactiva. Si una propuesta no se ajusta exactamente a lo que buscas, puedes redefinirla al instante sin tener que reiterar todo el contexto previo. ### Ajustes dialógicos en la sesión ```text # Ajustar el estilo del código That looks good, but please replace the if/else statements with a concise switch statement. # Incorporar documentación Great, now add comprehensive JSDoc comments to all exported functions in this file. # Optimizar rendimiento Can we memoize this calculation with useMemo to avoid re-computations on each render? ``` ### Vías para deshacer cambios imprevistos Si has aceptado una modificación y luego decides descartarla, cuentas con dos caminos directos: 1. **Indicárselo a Claude:** ```text Undo the last changes you made to src/lib/validation.ts and return the file to its previous state. ``` 2. **Utilizar Git en la consola:** ```bash # Revertir un archivo concreto git checkout -- src/lib/validation.ts # Descartar todos los cambios no confirmados del proyecto git reset --hard HEAD ``` > [!TIP] > Realiza un commit limpio en Git antes de iniciar refactorizaciones transversales de gran envergadura. Así podrás retornar al punto de partida con un simple `git checkout`. --- ## 10. Buenas prácticas de ingeniería y lista de verificación final Aplicar prácticas de ingeniería sólidas convierte a Claude Code en un socio excepcional para el pair programming. ### Cuatro hábitos para maximizar la productividad 1. **Una tarea por prompt:** Evita condensar múltiples objetivos dispares (*«Añade autenticación, maqueta el navbar y borra los tests antiguos»*). Divide el trabajo en pasos modulares y atómicos. 2. **Validación constante con tests:** Al concluir un bloque de cambios, solicita al asistente que ejecute las comprobaciones: `Run npm test and npm run typecheck to make sure everything compiles cleanly`. 3. **Conocer el funcionamiento de las herramientas:** Recuerda que las modificaciones quirúrgicas usan `Edit`, los archivos nuevos `Write` y los comandos del sistema `Bash`. Pensar en estos términos te ayudará a formular mejores instrucciones. 4. **Higiene de la ventana de contexto:** Al completar una funcionalidad extensa y pasar a un asunto no relacionado, usa `/compact` o reinicia la sesión para purgar logs innecesarios. ### Autoevaluación rápida > **1. ¿Qué herramienta utiliza Claude Code para realizar reemplazos selectivos sin reescribir todo el archivo?** > > > [!TIP] > > **Respuesta:** La herramienta `Edit`. Detecta el bloque de líneas coincidente y aplica la sustitución ofreciendo un diff coloreado. > **2. ¿Por qué Claude Code no carga todos los archivos del repositorio en memoria al arrancar?** > > > [!TIP] > > **Respuesta:** Para preservar los límites de contexto y evitar latencias altas. En su lugar, explora selectivamente mediante `Glob`, `Grep` y lecturas dirigidas con `Read`. > **3. ¿Cómo se puede solicitar una revisión rápida de los cambios de una rama frente a main con Claude Code?** > > > [!TIP] > > **Respuesta:** Ejecutando en la terminal `git diff main...feature-branch | claude -p "Code review this PR"`. ### Lista de verificación de práctica diaria - [ ] Utilizar prompts de visión general al explorar por primera vez un proyecto nuevo. - [ ] Rastrear flujos de trabajo completos mediante prompts del tipo *"Trace the flow from UI to database"*. - [ ] Efectuar code reviews previos al commit en los cambios preparados con `claude -p`. - [ ] Examinar con atención el diff coloreado en la terminal antes de confirmar cada llamada a `Edit`. - [ ] Crear un commit en Git como punto de restauración antes de acometer refactorizaciones transversales. - [ ] Finalizar cada ciclo de desarrollo verificando los tests y los tipos mediante `Bash`.