Flujo de trabajo del agente

Cada herramienta que Claude Code tiene a su disposición — Read, Glob, Grep, Edit, Write, Bash, Agent, WebFetch — se usa en un momento concreto del ciclo. Entender ese mapa convierte un agente que "más o menos funciona" en un agente que rinde como un senior.

Objetivos

• Conocer las 8 herramientas internas más usadas y cuándo elige cada una.
• Distinguir la fase Read (búsqueda) de la fase Edit (escritura).
• Saber cuándo usar plan mode, auto mode y default mode.
• Guiar al agente con prompts que provoquen un buen ciclo (no atajos).
• Reconocer cuándo el agente está perdido y cómo redirigirlo.

3.1 Herramientas del agente

Claude Code expone al modelo un conjunto de herramientas (tools) que el modelo decide invocar. Tú no las llamas directamente — el modelo lo hace en función de tu prompt. Pero conocerlas te permite escribir mejores prompts.

Read vs Bash(cat) — por qué importa

Aunque cat archivo.ts y Read archivo.ts dan información parecida, Claude Code prefiere Read porque:

• Devuelve líneas numeradas (clave para Edit).
• Trunca de forma controlada con offset/limit.
• Maneja PDF, imágenes, notebooks Jupyter de forma nativa.
• Queda registrado en el transcript como "lectura" (auditoría).

Si pides "muéstrame el archivo X" y el agente usa cat, es una pista de que el prompt es ambiguo o el modelo está cogiendo atajos.

3.2 Cómo busca un buen agente

Cuando le pides un cambio, Claude Code no salta a editar. Antes hace una fase Read típica de tres pasos:

1. Glob para acotar archivos candidatos por patrón.
2. Grep para localizar el símbolo / función / cadena exacta dentro de esos archivos.
3. Read de los ficheros relevantes, leyendo solo los rangos que importan.

Ejemplo: pides "renombra getUserById a fetchUser". Pulsa Reproducir y verás cómo lo encadena el agente:

Si la búsqueda fuese ambigua (un nombre muy genérico, p. ej. handle), el agente delega a un sub-agente Explore antes de decidir — verás esto en el Módulo 6.

Cuándo Read NO es suficiente

Read tiene un límite de líneas por llamada (2000 por defecto). Para ficheros enormes — un log de 80 MB, un dump SQL — el agente usa Bash con wc -l, grep, tail, jq según el formato. Es la herramienta correcta para volumen masivo, no Read.

3.3 Plan mode

Por defecto Claude Code va directo de Read a Edit. Si quieres que se detenga y te enseñe el plan antes de tocar nada, activa plan mode.

> /plan

Mientras estés en plan mode, todas las herramientas de escritura (Edit, Write, Bash con efectos secundarios) están bloqueadas. El agente puede leer todo lo que quiera, pero termina entregando un plan estructurado:

Plan propuesto

  1. Refactor de PaymentService.ts
     - Extraer validación a PaymentValidator.ts
     - Mover el cálculo de comisión a CommissionCalculator.ts

  2. Tests
     - Mover tests existentes al nuevo módulo PaymentValidator.test.ts
     - Añadir 4 tests nuevos para CommissionCalculator

  3. Verificación
     - npm run lint
     - npm test

¿Aprobar plan? (sí / no / cambia)

Tú apruebas, ajustas o rechazas. Solo cuando apruebas se sale de plan mode y empieza la fase Edit.

3.4 Auto mode

El opuesto a plan mode. Activado con:

> /auto

En auto mode el agente asume permisos por defecto y procede sin pedirte confirmación a cada paso. Útil para tareas largas y mecánicas: regenerar 200 schemas, formatear archivos, actualizar imports.

Auto mode no es licencia para hacer cualquier cosa. Sigue:

• Pidiendo confirmación para acciones destructivas (rm, drop tables, force push).
• Respetando la deny list del settings.json.
• Aplicando los hooks de seguridad que tengas configurados.

Comparativa de los 3 modos

3.5 Buenos vs malos prompts

El mismo agente con el mismo modelo rinde radicalmente distinto según cómo le pidas. Cuatro patrones que separan al usuario novato del experto:

1. Decir el qué Y el porqué

2. Acotar el alcance

3. Pedir verificación explícita

4. Decir lo que NO debe hacer

3.6 Cuándo el agente se pierde

Tres síntomas habituales y cómo recuperar:

Síntoma A · "Sigue editando archivos que no le he pedido"

Causa: el prompt era ambiguo, el agente está siendo proactivo. Recuperación: detén con Ctrl+C, ejecuta git checkout . para descartar lo que no quieras, y reformula con scope estricto ("toca solo este fichero").

Síntoma B · "Da vueltas, no termina"

Causa: la tarea es demasiado grande para una sola pasada. Recuperación: parte la tarea en sub-tareas explícitas. Ejemplo: en lugar de "migra todo el módulo a Vue 3", pide "lista los 12 componentes que hay que migrar" en una sesión, y luego migra uno a uno.

Síntoma C · "Inventa archivos que no existen"

Causa: contexto pobre o instrucciones contradictorias. Recuperación: ejecuta /clear, ejecuta /init si no hay CLAUDE.md, y reformula. Si persiste, es señal de que el repo tiene una arquitectura no estándar — añade más contexto al CLAUDE.md.

3.7 Verificar bien

El paso Verify suele ser el más débil del ciclo. Cosas que un buen prompt incluye:

• Test unitarios. "Ejecuta npm test y solo declara terminado si pasan."
• Build. "Asegúrate de que npm run build compila sin errores."
• Lint. "Pasa npm run lint. Si hay warnings nuevos, decídelo conmigo."
• Type check. "Verifica con tsc --noEmit que no se rompe el typing."
• Comportamiento. "Para cambios de UI: arranca el dev server, abre la URL en Chrome, haz una acción, comprueba el resultado." (vía MCP — Módulo 7).

Práctica

Test de comprensión

Resumen

• Read, Glob, Grep, Bash, Edit, Write, Agent, WebFetch — las 8 tools que mueven el ciclo.
• El agente busca en orden Glob → Grep → Read antes de tocar.
• Plan mode = leer y proponer; Auto mode = avanzar sin confirmaciones; Default = el equilibrio.
• Buen prompt = qué + dónde + por qué + cómo verificar + qué no hacer.
• Si el agente se pierde: /clear, partir la tarea, mejorar CLAUDE.md.

En el siguiente módulo profundizamos en los slash commands, el sistema de permisos y cómo configurar Claude Code para tu organización.