Cómo funciona Claude Code
📚 Navegación de la serie: El artículo anterior 02 · Instalación y uso te guió para instalar y ejecutar Claude Code. Este artículo levanta la tapa para ver exactamente cómo funciona: por qué puede leer código, modificar archivos y ejecutar comandos por sí mismo, en lugar de simplemente chatear.
Al usar Claude Code por primera vez, a menudo te encontrarás con una conversación como esta:
Tú: "¿Por qué falló esta prueba?" Claude: "Primero ejecutaré la suite de pruebas para echar un vistazo." (Comienza a ejecutar el comando) Claude: "El error dice que
validateEmaildevolvió undefined, iré a ver esta función." (Lee el archivo) Claude: "Lo encontré, aquí falta un return. Lo modificaré y luego volveré a ejecutar la prueba para confirmar." (Modifica y ejecuta de nuevo) Claude: "La prueba pasó."
Al ver esto, es fácil confundirse un poco: Hiciste solo una pregunta, ¿cómo es que ejecutó comandos por sí mismo, leyó archivos por sí mismo, hizo modificaciones por sí mismo y también las verificó por sí mismo?
Para decirlo sin rodeos, esta es la mayor diferencia entre Claude Code y un cuadro de chat de IA normal. El cuadro de chat solo "te responderá con un texto", mientras que Claude Code actuará por sí mismo. Detrás de esto hay un mecanismo de trabajo fijo, que explicaremos a fondo hoy.
Después de leer este artículo, obtendrás:
- Una imagen para entender el "ciclo de agente" de Claude Code: las tres acciones repetitivas que hace para cualquier tarea.
- Comprender qué pueden hacer las 5 categorías de "herramientas" que tiene a su disposición y cómo decide cuál usar.
- Saber exactamente qué puede ver en tu computadora y qué no puede ver (relacionado con la seguridad).
- Un pequeño experimento que puedes seguir para ver con tus propios ojos cómo completa un ciclo completo.
01 Ciclo de Agente: Pensar → Actuar → Observar
Primero la conclusión: Para cualquier tarea que haga Claude Code, repite tres acciones: recopilar contexto, tomar acción y verificar resultados. Oficialmente, este mecanismo se llama "ciclo de agente (agentic loop)".
Dicho de una manera más sencilla: Pensar → Actuar → Observar.
- Pensar (Recopilar contexto): Primero, entender la situación: leer archivos relevantes, mirar errores, verificar el estado de git.
- Actuar (Tomar acción): Poner manos a la obra: modificar código, ejecutar comandos, crear nuevos archivos.
- Observar (Verificar resultados): Comprobar si lo que acaba de hacer es correcto: ejecutar pruebas, mirar la salida; si no es correcto, empezar otra ronda.
Analogía: Un mecánico de autos confiable. Llevas el auto al taller y dices "el volante vibra"; el mecánico no empezará a desarmar de inmediato. Primero da una vuelta y hace una prueba de manejo (Pensar), luego usa la llave inglesa (Actuar), y después de arreglarlo, conduce un poco para confirmar que ya no vibra (Observar). Si aún vibra, vuelve al primer paso para revisar de nuevo. Claude Code es ese mecánico, solo que arregla tu código.
Volviendo a la conversación del principio, compárala y lo entenderás:
| Lo que dice Claude | A qué paso del ciclo corresponde |
|---|---|
| "Primero ejecutaré la suite de pruebas" | Pensar (Recopilar contexto) |
| "El error dice undefined, iré a ver esta función" | Pensar (Continuar recopilando) |
| "Aquí falta return, lo modificaré" | Actuar (Tomar acción) |
| "Luego volveré a ejecutar la prueba para confirmar" | Observar (Verificar resultados) |
| "La prueba pasó" | Fin del ciclo |
Él encadena estos tres pasos en una secuencia, donde el resultado de un paso determina lo que hará en el siguiente. Arreglar un bug puede requerir varias rondas de ciclos, mientras que preguntar "¿qué significa este código?" podría requerir solo el paso de "Pensar". La cantidad de ciclos la determina la complejidad de la tarea, no está codificada.
La imagen de arriba muestra el ciclo que hace Claude Code cada vez que trabaja: de "Pensar" a "Actuar" a "Observar"; si no está satisfecho, vuelve de "Observar" a "Pensar" para otra ronda. Puedes presionar Esc en cualquier momento para detenerlo.
Aquí hay un punto clave del que muchas personas no se dan cuenta: Tú también eres parte de este ciclo. Si él se desvía, puedes intervenir en cualquier momento para corregirlo; hablaremos de esto en detalle en la siguiente sección.
Lo que impulsa este ciclo son dos cosas: el modelo se encarga de "Pensar", las herramientas se encargan de "Actuar" y "Observar".
El modelo es el cerebro de Claude: Sonnet es suficiente para la programación diaria, Opus tiene un razonamiento más fuerte y es adecuado para arquitecturas complejas. Puedes cambiarlo en cualquier momento ingresando /model en la sesión, o al iniciar con claude --model sonnet.
💡 Resumen en una frase: Claude Code no es "te respondo con un texto", sino "Pensar → Actuar → Observar" girando en ciclo hasta terminar el trabajo; esta es su diferencia esencial con un cuadro de chat.
02 Tú también estás en el ciclo: Puedes interrumpir en cualquier momento
Al final de la sección anterior se dijo: tú también eres parte de este ciclo. Profundicemos en esto. El chat de IA normal es "tú preguntas una vez, él responde un párrafo, se acaba el turno". Claude Code es diferente: cuando está ejecutando un ciclo por sí mismo, no tienes que esperar sin hacer nada, puedes intervenir en cualquier momento.
Por ejemplo, si le pides que refactorice un módulo y ves que se ha desviado y está a punto de modificar un montón de archivos, simplemente presiona Esc, se detendrá de inmediato y el comando que se estaba ejecutando también se cancelará. Agrega una frase como "No toques ese archivo, solo modifica esta función", y continuará siguiendo la nueva instrucción.
Hay dos formas de interrumpir y debes distinguir la diferencia:
| Operación | Efecto | Cuándo usarlo |
|---|---|---|
Presionar Esc | Se detiene inmediatamente, la llamada a la herramienta que se estaba ejecutando se cancela, espera tu próxima instrucción | Se desvió, lo que iba a hacer estaba mal, hay que detenerlo rápido |
Escribir + Enter | No interrumpe la operación actual, envía un suplemento, lo leerá cuando termine lo que tiene entre manos | Solo quieres agregar algo de contexto, darle un recordatorio, no hay prisa por detenerlo |
No necesitas contenerte para pensar un "prompt perfecto". Primero dale una dirección general, mira lo que hace y corrígelo si se equivoca: esto es una conversación, no un comando de una sola vez.
Estas palabras son originales de la documentación oficial y vale la pena recordarlas. Al empezar, la gente siempre quiere "decir todos los requisitos en una sola frase" y se contiene durante mucho tiempo. En realidad, no es necesario: lanza una dirección general, si lo hace mal, detenlo; iterar es mucho más rápido que preparar un gran golpe.
💡 Resumen en una frase: Él trabaja de forma autónoma, pero siempre sigue tus órdenes: parada de emergencia con
Esc, suplementos escribiendo; el volante siempre está en tus manos.
03 Herramientas: La razón por la que realmente puede actuar
La sección anterior dijo que el modelo es responsable de "Pensar". Entonces, ¿de qué dependen "Actuar" y "Observar"? De las herramientas.
Esta es la frase más importante para recordar sobre Claude Code: Sin herramientas, Claude solo puede responderte con texto; con herramientas, realmente puede leer tu código, modificar tus archivos y ejecutar tus comandos.
Analogía: Un asistente con una pulsera inteligente. Un asistente que solo sabe hablar solo puede dar ideas; si le das equipos para abrir puertas, escribir a máquina y buscar información, entonces realmente podrá hacer cosas por ti. Las herramientas son las "manos" de Claude Code.
Oficialmente, las herramientas integradas se dividen en 5 categorías. Te las enumeraré en lenguaje sencillo:
| Categoría de Herramienta | Qué puede hacer | A qué operación tuya equivale |
|---|---|---|
| Operación de archivos | Leer archivos, modificar código, crear archivos, renombrar, reorganizar | Tú abriendo, escribiendo y guardando en un editor |
| Búsqueda | Buscar archivos por nombre, usar expresiones regulares para buscar en el contenido, revisar todo el repositorio | Tú presionando Ctrl+F o usando grep |
| Ejecución | Ejecutar comandos shell, iniciar servidores, ejecutar pruebas, usar git | Tú escribiendo un comando en la terminal y presionando Enter |
| Red | Buscar en la web, obtener documentos, revisar mensajes de error | Tú abriendo el navegador para buscar un error |
| Inteligencia de código | Ver errores y advertencias de tipo, saltar a la definición, buscar referencias | El "Ir a definición" o "Buscar referencias" del IDE |
⚠️ Nota: La 5ª categoría, "Inteligencia de código", requiere instalar complementos adicionales (discover-plugins) para estar disponible; las primeras 4 categorías vienen listas para usar. Toma la documentación oficial como estándar.
Entonces, ¿cómo decide cuál usar? No eres tú quien lo especifica, es el propio modelo quien elige según lo que dices y el progreso actual.
Para dar un ejemplo oficial, si dices "Arregla la prueba fallida", internamente el flujo sería aproximadamente así:
- Ejecuta la suite de pruebas para ver cuál falló — usó Ejecución
- Lee la salida del error — Ejecución
- Busca los archivos fuente relevantes — Búsqueda
- Lee estos archivos para entender la lógica — Operación de archivos
- Modifica el archivo para arreglar el bug — Operación de archivos
- Vuelve a ejecutar la prueba para verificar — Ejecución
¿Lo ves? Estos 6 pasos son el despliegue del ciclo "Pensar → Actuar → Observar" a nivel de herramientas. Cada vez que usa una herramienta, obtiene nueva información, que se alimenta al modelo para que decida el siguiente paso; así es como el ciclo gira.
Hay un escenario muy típico: pídele que "aclare la estructura del directorio" de un proyecto antiguo sin documentación. No necesitas alimentarle con ningún archivo, él mismo hará ls, usará grep para buscar palabras clave, leerá siete u ocho archivos y finalmente dibujará un diagrama de estructura. En todo el proceso no especificas ni un solo archivo: a esto se refiere el equipo oficial con "delega, no des instrucciones": dale la dirección, y él se encargará de los detalles.
En cuanto a Skill, MCP, Hook, Subagent, etc., son capas de extensión construidas sobre estas 5 categorías de herramientas integradas, que permiten a Claude saber más y conectarse a más servicios externos. En los siguientes artículos de esta serie los explicaremos uno a uno; por ahora, solo debes saber que existen.
💡 Resumen en una frase: Las herramientas son las "manos" de Claude Code, las 5 categorías se encargan de su respectiva área; él mismo decide cuál usar y cuántas veces usarla, tú solo di el objetivo.
04 Qué puede ver en tu computadora
Esta sección tiene que ver con la seguridad y hay que dejarlo claro. Muchas personas al usarlo por primera vez tendrán dudas: ¿Revisó todo mi disco duro y lo envió por ahí? No.
Solo recuerda una frase: El "campo de visión" de Claude Code es básicamente igual a lo que puede tocar la terminal en ese directorio. Si escribiste claude en una carpeta, su rango de actividad está centrado ahí.
Según la documentación oficial, cuando ejecutas claude en un directorio, puede acceder a:
- Tu proyecto: Los archivos en el directorio actual y subdirectorios (para archivos en otros lugares necesita que le des permiso para tocarlos).
- Tu terminal: Cualquier comando que tú puedas ejecutar: herramientas de construcción, git, gestores de paquetes, scripts. Lo que pueda hacer la línea de comandos, él también puede.
- Tu estado de git: Rama actual, cambios no confirmados, historial de commits reciente.
- Tu
CLAUDE.md: El manual exclusivo de tu proyecto que escribiste, lo leerá en cada sesión (hablaremos de este archivo en un artículo dedicado más adelante). - Tus extensiones configuradas: Cosas como MCP, Skill, Subagent.
Precisamente porque puede ver todo el proyecto, y no solo el archivo que tienes abierto actualmente, puede coordinar modificaciones en varios archivos. Si dices "arregla el bug de inicio de sesión", puede buscar varios archivos relevantes, modificarlos juntos y luego ejecutar la prueba para verificar. Esto no es lo mismo que los plugins de autocompletado en línea que solo ven el archivo actual.
Entonces, ¿cómo se garantiza la seguridad? Hay dos compuertas:
La primera: Puntos de control (checkpoints), el equivalente a guardar una partida. Antes de modificar cualquier archivo, tomará una instantánea del contenido actual. Si lo estropea, presiona Esc dos veces seguidas con el cuadro de entrada vacío (o escribe /rewind), aparecerá un "Menú de retroceso"; selecciona "Restaurar código" y el archivo volverá a su estado anterior; también puedes decirle directamente "Deshaz el cambio que acabas de hacer".
Los puntos de control solo cubren los archivos que Claude modifica con herramientas de edición; los comandos bash y los efectos secundarios externos no están incluidos. Operaciones como bases de datos, APIs o despliegues en producción que "una vez hechas no se pueden deshacer", no se pueden guardar. Por eso Claude te preguntará primero antes de ejecutar este tipo de comandos con impacto externo.
Aquí hay una trampa común: a veces modifica cinco o seis archivos, y cuando lo miras, la dirección es completamente incorrecta. Antes tenías que usar git checkout manualmente uno por uno para revertir, ahora presionas Esc dos veces, seleccionas "Restaurar código" en el menú emergente, y los cinco archivos regresan limpios a su estado anterior a la modificación. Con este truco, puedes dejar que modifique el código con mucha más tranquilidad.
La segunda: Modo de permisos, el equivalente a si el pasante te pregunta antes de actuar. Presiona Shift+Tab para alternar entre ellos:
| Modo de Permisos | Comportamiento de Claude |
|---|---|
| Predeterminado | Te pregunta antes de modificar archivos o ejecutar comandos |
| Aceptar ediciones automáticamente | No pregunta para modificaciones de archivos y comandos comunes (como mkdir, mv), pero pregunta para otros comandos |
| Modo Plan (Plan Mode) | Puede leer archivos y ejecutar comandos exploratorios, pero no edita el código fuente; primero te da un plan, y solo actúa si lo apruebas |
| Modo Automático | Usa verificaciones de seguridad en segundo plano para evaluar todas las operaciones (Experimental, actualmente en vista previa de investigación, sujeto a cambios) |
El hábito más valioso que puedes cultivar es usar el Plan Mode: para tareas complejas, primero presiona Shift+Tab dos veces para entrar, pídele que "solo analice, proponga una solución, no actúe"; revisa la solución, modifícala, y cuando la confirmes, déjalo ejecutar. Esto te ahorrará muchos retrabajos por "equivocarse de dirección y cambiar a medias": revisar los planos antes de construir es mucho más fácil que construir y modificar al mismo tiempo.
¿Te molesta que te pregunte cada vez? Puedes agregar comandos de confianza (como npm test, git status) a una lista blanca en el archivo .claude/settings.json de tu proyecto para que no te pregunte en el futuro. Los detalles de configuración se explicarán en un artículo dedicado.
💡 Resumen en una frase: Su visión ≈ tus permisos de terminal en ese directorio; los puntos de control sirven para "deshacer si se estropea", los modos de permisos determinan "si pregunta antes de actuar"; con estas dos compuertas, puedes usarlo con tranquilidad.
05 Práctica: Mira con tus propios ojos cómo completa un ciclo
Entender la teoría sin verla no sirve de mucho, ejecuta un experimento mínimo para ver con tus propios ojos cómo gira de "Pensar → Actuar → Observar". Este experimento no depende de ningún proyecto existente, puedes crear una carpeta vacía para hacerlo.
Primer paso: Crea un directorio vacío, entra en él e inicia Claude Code.
Ejecuta en la terminal (Mac / Linux; en Windows usa PowerShell y cambia mkdir -p por mkdir):
mkdir -p ~/cc-demo && cd ~/cc-demo
claudeSegundo paso: Una vez dentro, cambia primero al modo Plan para ver cómo "Piensa".
Presiona Shift+Tab dos veces, la parte inferior de la interfaz indicará que has entrado en el Plan Mode (Modo Plan). Luego escríbele esta frase:
Ayúdame a escribir un script de Python add.py, con una función add(a, b) que devuelva la suma de dos números,
luego escribe algunos casos de prueba para verificarlo y finalmente ejecuta la prueba. Primero dame un plan, no empieces a trabajar de inmediato.Lo que deberías ver: Él no creará archivos de inmediato, sino que primero te responderá con un plan, aproximadamente así:
Plan:
1. Crear add.py, implementar add(a, b)
2. Crear pruebas (usando assert o pytest)
3. Ejecutar pruebas, confirmar que todas pasen
¿Necesitas que empiece?Esto es "Pensar": aclaró su línea de pensamiento antes de actuar. Nota que se detuvo a esperar tu aprobación, esta es la característica del Modo Plan.
Tercer paso: Aprobar y ver cómo "Actúa" + "Observa".
Responde "Sí, empieza". A continuación, verás que él en orden:
- Crea el archivo (Herramienta de operación de archivos) — puede aparecer una confirmación de permisos, dale a aceptar.
- Después de escribir, ejecuta las pruebas (Herramienta de ejecución), por ejemplo, ejecutando
python add.pyopytest. - Pega la salida de la prueba para ti, se espera que sea algo similar a:
Prueba aprobada: add(2, 3) == 5 ✓ add(-1, 1) == 0 ✓ add(0, 0) == 0 ✓Llegados a este punto, has visto un ciclo completo: Pensar (dar plan) → Actuar (crear archivo, escribir código) → Observar (ejecutar pruebas y reportar resultados).
Cuarto paso (Opcional): Crea intencionalmente un "Re-ciclo".
Dile: "Cambia add a resta, pero no cambies el nombre de la función, y luego vuelve a ejecutar la prueba."
Verás que modifica el código y vuelve a ejecutar la prueba; si la aserción de la prueba sigue siendo para la suma, la prueba fallará, él se dará cuenta por sí mismo del fallo y volverá a modificar. Esta es la esencia del ciclo: al ver que algo está mal, comienza automáticamente otra ronda.
Todos los principiantes deberían hacer este experimento una vez. En comparación con leer diez veces las palabras "ciclo de agente", ver con tus propios ojos cómo se detiene para dar un plan, luego actúa, luego verifica, te hace entender mucho más rápido.
💡 Resumen en una frase: Al ejecutar este experimento mínimo, verás con tus propios ojos el giro de "Pensar → Actuar → Observar", especialmente el momento en que descubre un error por sí mismo y comienza automáticamente otra ronda.
06 Resumen
Este artículo aclaró una sola cosa: Por qué Claude Code puede trabajar por sí mismo.
Repasemos los puntos clave:
| Punto Clave | Recuerda esto en una frase |
|---|---|
| Ciclo de Agente | Pensar → Actuar → Observar, girando hasta terminar; esta es su diferencia esencial con un cuadro de chat |
| Modelo + Herramientas | El modelo se encarga de pensar, las herramientas se encargan de actuar y observar |
| 5 Categorías de Herramientas | Archivos / Búsqueda / Ejecución / Red / Inteligencia de código, él mismo elige cuál usar |
| Qué puede ver | ≈ Tus permisos de terminal en ese directorio, puede coordinar a través de múltiples archivos |
| Dos compuertas de seguridad | Puntos de control (deshacer si se daña) + Modos de permisos (preguntar o no antes de actuar) |
Ahora deberías poder entender qué está pasando en la pantalla cuando Claude Code ejecuta una tarea: cada archivo que lee y cada comando que ejecuta es un paso en el ciclo; también sabes cómo usar Esc para una parada de emergencia, usar el Modo Plan para ver la propuesta primero y depender de los puntos de control para dejarle modificar con confianza.
Una vez entendido este mecanismo, tu mentalidad al usarlo será completamente diferente: no es un pozo de los deseos, sino un compañero que puede pensar, actuar y comprobar por sí mismo; tu trabajo es darle la dirección, establecer los criterios de aceptación y corregirlo cuando se desvíe.
Siguiente artículo 04 · Configuración de API: Claude Code está instalado y los principios se entienden, pero necesita conectarse a un modelo para trabajar realmente. El próximo artículo te guiará para configurar la API: solo con este paso completado, el ciclo y las herramientas que aprendimos antes podrán empezar a funcionar.