Claude Code: fundamentos

Qué es Claude Code y el bucle agentivo

Claude Code es el agente de código de Anthropic. Vive en tu terminal (también en el IDE y en la web) y, a diferencia del chat, tiene herramientas: leer y escribir archivos, ejecutar comandos de shell, buscar en el código, usar git, consultar la web.

Su funcionamiento es un bucle agentivo:

1. Das un objetivo.
2. Él piensa, elige una herramienta y la llama (leer un archivo, ejecutar un test...).
3. Observa el resultado de la herramienta.
4. Repite hasta alcanzar el objetivo y luego te responde.

Esa es la diferencia fundamental con el chat: Claude Code actúa, observa y corrige de forma autónoma. No dictas cada comando, le das un objetivo y unas restricciones.

Instalación: npm install -g @anthropic-ai/claude-code y luego claude en la carpeta de tu proyecto. Lo primero que lee es tu CLAUDE.md (lección siguiente).

CLAUDE.md: la memoria del proyecto

CLAUDE.md es un archivo markdown ubicado en la raíz de tu proyecto (o de forma global en ~/.claude/) que Claude Code lee automáticamente al iniciarse. Es su memoria persistente de tus convenciones.

Qué incluir en él:

• Los comandos del proyecto (build, test, lint, deploy).
• Las convenciones de código y estilo.
• Las reglas absolutas que nunca deben violarse.
• El enrutamiento hacia otros documentos o subproyectos.

El CLAUDE.md de Pierre es un caso ejemplar: codifica sus reglas no negociables (nunca un guión largo, sin emojis, archivar en lugar de eliminar, la ruta exacta es 00_SEPT TOOLS con guión bajo) y su enrutamiento de inicio de sesión. Estas instrucciones anulan el comportamiento predeterminado del modelo.

Genera un primer borrador con el comando /init: Claude analiza el repositorio y propone un CLAUDE.md. Luego lo refinas. Regla clave: un CLAUDE.md corto y preciso vale más que uno extenso que nadie respeta.

Los comandos slash esenciales

Los comandos slash controlan la sesión. Los esenciales:

• /init: genera el CLAUDE.md analizando el repositorio.
• /clear: reinicia el contexto desde cero. Úsalo entre tareas sin relación para empezar limpio.
• /compact: resume el contexto anterior sin descartarlo todo. Úsalo a mitad de una tarea cuando el contexto se llena pero quieres mantener la continuidad.
• /agents: gestiona los sub-agentes especializados.
• /mcp: conecta y gestiona servidores MCP.
• /hooks: configura los hooks del ciclo de vida.
• /review: revisión de código del diff actual.

La distinción más útil en el día a día: /clear olvida todo, /compact resume. Mucha gente deja que el contexto crezca hasta que la calidad se degrada. El reflejo del profesional: /clear cuando cambias de tema, /compact cuando estás a mitad de una tarea grande.

También puedes crear tus propios comandos slash (plantillas de prompts reutilizables) en .claude/commands/. Esa es la puerta de entrada a los skills (módulo 5).

Permisos y plan mode

Claude Code puede ejecutar comandos reales. El sistema de permisos controla lo que hace sin preguntarte. Cuatro modos principales:

• Ask every time (modo cauteloso por defecto): pregunta antes de cada acción sensible.
• Accept edits: edita archivos sin preguntar, pero pregunta para el resto.
• Plan mode: no actúa, primero propone un plan. Tú lo apruebas y luego lo ejecuta. Ideal para cambios grandes.
• bypassPermissions: actúa sin preguntar nada. Rápido, pero sin control de seguridad.

Este ajuste se configura en settings.json (global o por proyecto), con una lista de permisos precisa: "permitir npm run build y git status sin preguntar, pero preguntar para cualquier rm".

El caso de Pierre es ilustrativo: trabaja en bypassPermissions por defecto (por velocidad), lo que desactiva el control automático sobre rm. Su contramedida no es técnica sino una regla absoluta en el CLAUDE.md: archivar en _ARCHIVES/, nunca eliminar. Lección: cuanta más autonomía concedes, más importan tus reglas escritas.

Instalar Claude Code y primer lanzamiento

Claude Code es el agente de codificación por línea de comandos de Anthropic. Lee tus archivos, escribe código, ejecuta comandos y razona sobre todo tu proyecto, todo desde una terminal. Para usarlo necesitas Node.js (el entorno de ejecución de JavaScript) en versión 18 o superior, y su gestor de paquetes integrado npm (Node Package Manager). Comprueba lo que tienes ejecutando node -v y npm -v en cualquier terminal.

Instala Claude Code de forma global con un solo comando npm para que esté disponible desde cualquier carpeta de tu máquina:

npm install -g @anthropic-ai/claude-code

El indicador -g significa "global": npm coloca el binario claude en la ruta del sistema. Una vez instalado, autentícate una vez ejecutando claude sin argumentos. Claude Code abre una ventana del navegador (o imprime una URL) para que puedas iniciar sesión con tu cuenta de Anthropic. Tus credenciales se almacenan localmente y se reutilizan en cada sesión futura.

El lugar desde donde lanzas Claude Code es importante. El directorio personal es tu carpeta de usuario (por ejemplo C:\Users\yourname en Windows o /Users/yourname en Mac). Iniciar Claude desde ahí carga solo tu memoria y configuración global. El directorio del proyecto es la carpeta que contiene tu código. Iniciar Claude desde dentro de él carga la memoria específica del proyecto y da a Claude Code el contexto completo de esa base de código. Haz siempre cd a tu proyecto primero, luego ejecuta claude.

• Requisito: Node.js 18+ y npm (ambos vienen con una instalación estándar de Node).
• Instalar: npm install -g @anthropic-ai/claude-code
• Primer lanzamiento: ejecuta claude y completa el inicio de sesión en el navegador.
• Cada sesión después de esa: cd tu-proyecto y luego claude.

El campo de entrada: modos y control

El campo de entrada de Claude Code hace mucho más que aceptar texto. Es también un volante que puede tomar en cualquier momento durante una tarea. Entender sus modos le permite mantenerse al control en lugar de esperar sin poder hacer nada a que termine una ejecución larga.

Cuando Claude Code está en ejecución, presionar Escape envía una señal de interrupción (una solicitud de detener la acción actual). Claude Code termina el paso atómico en curso, luego hace una pausa y le devuelve el control. A partir de ahí puede redirigirlo, corregirlo o continuar con una nueva instrucción.

Para la entrada multilínea (varias líneas en un mismo mensaje, útil para pegar una especificación o un bloque de código), presione Shift+Enter para insertar un salto de línea sin enviar. Presione Enter solo para enviar.

Tres modos de entrada permiten configurar cómo responde Claude Code:

• Modo normal: escriba su instrucción y presione Enter. Claude Code elige las herramientas y actúa de forma autónoma.
• Plan mode (--plan): Claude Code elabora un plan paso a paso y espera su aprobación antes de tocar ningún archivo.
• Modo de aceptación automática (--dangerously-skip-permissions): todos los mensajes de permiso se omiten automáticamente. Úselo solo en un entorno seguro, nunca en archivos de producción.

Apuntar a archivos con @

En Claude Code, la referencia @ es la forma de apuntar a un archivo o carpeta sin copiar su contenido. Escriba @ seguido de una ruta y Claude Code leerá ese archivo directamente desde su disco. Esto significa que nunca tiene que pegar bloques de código en el chat.

A medida que escribe @, Claude Code muestra un menú de completado con tabulación con los archivos y carpetas de su proyecto. Presione Tab para recorrer las coincidencias y Enter para confirmar. Puede referenciar varios elementos en un mismo mensaje.

¿Por qué esto supera al pegado? Tres razones:

• Exactitud: Claude lee el archivo tal como existe en el disco, por lo que nada se pierde por errores de copiar y pegar ni por contenido desactualizado en el portapapeles.
• Eficiencia del contexto: Claude Code envía solo lo que necesita del archivo, evitando que la ventana de contexto (la cantidad total de texto que Claude puede mantener en memoria a la vez) se llene innecesariamente.
• Referencias de carpetas: Apuntar a una carpeta con @src/ permite a Claude explorar todo el árbol de directorios y seleccionar por sí mismo los archivos relevantes, lo cual sería poco práctico de pegar manualmente.

Puede combinar referencias @ con instrucciones normales en el mismo mensaje. Por ejemplo: Review @src/auth.js and check @tests/auth.test.js for missing coverage.

Ejecutar comandos de shell

Claude Code puede ejecutar comandos de shell reales en tu máquina a través de su herramienta Bash integrada. Un shell (también llamado terminal o línea de comandos) es la interfaz de texto que controla tu sistema operativo. Cuando le pides a Claude Code que instale un paquete, ejecute pruebas o verifique un archivo, envía esos comandos a la herramienta Bash y lee la salida antes de responder.

Antes de ejecutar cualquier comando, Claude Code te muestra lo que está a punto de ejecutar y espera tu aprobación. Esta solicitud de permiso es tu barrera de seguridad. Puedes aprobar el comando, editarlo o denegarlo. Una vez aprobado, la salida vuelve directamente a Claude Code para que pueda reaccionar a errores o resultados sin que tengas que copiar y pegar nada.

Puedes controlar qué comandos requieren aprobación. La lista de permitidos en tu configuración te permite incluir en lista blanca comandos seguros (como npm test o ls) para que se ejecuten sin interrupción. Las operaciones peligrosas, como eliminar archivos, seguirán solicitando permiso a menos que las autorices explícitamente.

• Lectura de la salida: Claude Code ve stdout y stderr (la salida normal y el flujo de errores) y los analiza.
• Cadenas de varios pasos: puede ejecutar varios comandos en secuencia, usando el resultado de uno para decidir el siguiente.
• Tareas en segundo plano: los comandos de larga duración (como un servidor de desarrollo) pueden lanzarse en segundo plano para que la sesión siga siendo responsive.
• Directorio de trabajo: los comandos se ejecutan en la carpeta de proyecto que abriste, no en una ubicación aleatoria.

Leer y aprobar ediciones

Cuando Claude Code modifica un archivo, muestra un diff (abreviatura de "difference"), una vista en paralelo o en línea donde las líneas marcadas con - se eliminan y las líneas marcadas con + se agregan. Nada se escribe en el disco hasta que usted aprueba.

Claude Code apunta a ediciones quirúrgicas: solo toca las líneas que necesitan cambiar, dejando el resto del archivo intacto. Esto mantiene los diffs pequeños y fáciles de revisar. Si un cambio propuesto parece más grande de lo esperado, es una señal para leer con cuidado antes de aceptar.

Tiene tres respuestas disponibles cada vez que se propone una edición:

• y / yes: aceptar y escribir el cambio en el disco.
• n / no: rechazar y pedirle a Claude Code que intente un enfoque diferente.
• e / edit: abrir el diff en su editor para ajustarlo manualmente antes de guardar.

Si ejecuta Claude Code con el flag --dangerously-skip-permissions (modo aprobación automática), todas las ediciones se escriben de inmediato sin solicitud de confirmación. Use ese flag solo en entornos desechables donde la velocidad importa más que la revisión.

Git desde Claude Code

Claude Code comprende Git (el sistema de control de versiones que registra cada cambio en tu código) de forma nativa. Puedes describir lo que necesitas en lenguaje sencillo y Claude Code ejecutará los comandos Git correctos, explicará el resultado y pedirá confirmación antes de realizar cualquier acción destructiva.

Las cuatro operaciones cotidianas de Git que Claude Code gestiona por ti son: verificar el status (qué ha cambiado), leer un diff (las líneas exactas agregadas o eliminadas), redactar un mensaje de commit (una instantánea guardada con una descripción) y abrir una pull request (una propuesta formal para fusionar tus cambios en el código principal).

Claude Code también administra las ramas (versiones paralelas del código). Puedes pedirle que cree una rama, que cambie a una existente o que fusione cambios, sin necesidad de memorizar flags. Los comandos principales que ejecuta internamente son git status, git diff, git add, git commit, git checkout -b y gh pr create (usando el GitHub CLI).

• Status: "¿Qué archivos he modificado?" Claude Code ejecuta git status y hace un resumen.
• Diff: "Muéstrame qué cambió en auth.js." Claude Code ejecuta git diff auth.js y explica los cambios en lenguaje sencillo.
• Commit: "Haz commit de estos cambios con un buen mensaje." Claude Code prepara los archivos y redacta un mensaje de commit conciso y convencional.
• Rama: "Crea una rama llamada fix/login-bug." Claude Code ejecuta git checkout -b fix/login-bug.
• Pull request: "Abre una PR hacia main con un resumen." Claude Code usa gh pr create y redacta el título y el cuerpo por ti.

La lista de tareas

Cuando le asignas a Claude Code un trabajo complejo con varios pasos, no mantiene el plan completo de forma invisible en su memoria. En cambio, mantiene una lista de tareas: un listado estructurado de subtareas que crea al inicio del trabajo y va actualizando a medida que avanza. Piensa en ella como una pizarra compartida entre tú y el agente.

La lista de tareas cumple dos propósitos. Primero, mantiene a Claude Code en el camino correcto a lo largo de muchas ediciones de archivos, llamadas a herramientas y decisiones. Segundo, te permite seguir el progreso en tiempo real sin necesidad de leer cada línea de salida. Cada elemento pasa de "pendiente" a "en progreso" y luego a "completado" (o "bloqueado") conforme avanza la sesión.

Puedes interactuar con la lista de tareas en cualquier momento:

• Escribe un mensaje de seguimiento para agregar una nueva subtarea o repriorizar las existentes.
• Pide a Claude Code que haga una pausa después de una tarea específica para que puedas revisar antes de que continúe.
• Di "salta el paso 3" o "concéntrate solo en los pasos 1 y 4" y el agente se ajustará.
• Si una tarea está bloqueada (por ejemplo, falta un archivo), Claude Code lo indicará y esperará en lugar de omitirlo en silencio.

En la extensión de VS Code y en la interfaz web, la lista de tareas aparece como un panel lateral plegable. En la CLI (interfaz de línea de comandos, la versión de terminal), se imprime en línea mientras se ejecuta la sesión. En ambos casos, los elementos completados se marcan y el elemento actual queda resaltado.

El modo plan en profundidad

El modo plan es una fase de solo lectura en Claude Code donde el agente analiza tu base de código y propone un plan estructurado antes de escribir o modificar un solo archivo. Piénsalo como una revisión de planos: Claude traza cada paso y nada cambia en el disco hasta que das el visto bueno.

Para activar el modo plan, pasa el flag --plan al iniciar una tarea, o escribe /plan dentro de una sesión activa de Claude Code. Claude leerá los archivos, trazará las dependencias y mostrará una lista de acciones numeradas. Durante esta fase no tiene permisos de escritura, por lo que no puede sobreescribir tu trabajo de forma accidental.

Una vez que aparece el plan, tienes tres opciones:

• Aprobar: escribe yes o presiona Enter para que Claude ejecute cada paso en orden.
• Editar: pega el plan con tus correcciones y luego aprueba la versión revisada.
• Cancelar: escribe no o presiona Ctrl+C para cancelar sin tocar ningún archivo.

Usa el modo plan cuando una tarea afecte múltiples archivos, implique una refactorización arriesgada, o cuando quieras una segunda opinión antes de confirmar los cambios. Requiere un poco más de tiempo al inicio, pero evita errores difíciles de revertir y te proporciona un registro claro de lo que Claude tiene previsto hacer.

Modos de permiso y bypass

Claude Code solicita su aprobación antes de realizar acciones como editar archivos o ejecutar comandos. La frecuencia con que lo hace depende del modo de permiso, una configuración que controla el equilibrio entre seguridad y velocidad.

Hay cuatro modos que debe conocer:

• default: Claude solicita confirmación antes de cada edición de archivo y cada comando shell. El más seguro, pero requiere más interacciones.
• acceptEdits: Claude aplica las ediciones de archivos automáticamente pero aún solicita confirmación antes de ejecutar comandos shell. Un punto medio común para sesiones de desarrollo.
• plan: Claude solo lee y planifica; nunca escribe ni ejecuta nada. Útil cuando se desea revisar una estrategia antes de comprometerse.
• bypassPermissions: Claude actúa sin solicitar ninguna aprobación. Velocidad máxima, mínima red de seguridad.

Puede establecer un modo para una sola sesión con el flag --permission-mode (por ejemplo, claude --permission-mode acceptEdits), o fijarlo para un proyecto agregándolo en .claude/settings.json bajo la clave permissionMode.

La concesión de seguridad es real: bypassPermissions elimina la barrera que detecta eliminaciones accidentales o comandos shell destructivos. Úselo solo en entornos desechables, sandboxes, o cuando disponga de control de versiones y sepa exactamente lo que Claude hará.

La linea de estado

Cada vez que Claude Code responde, aparece una linea de estado en la parte inferior del terminal. Le ofrece una instantanea en tiempo real de tres cosas: cuanto de la ventana de contexto (la memoria total que Claude puede mantener para su sesion) ha utilizado, el costo estimado de la sesion hasta el momento en USD, y el identificador del modelo activo.

El uso del contexto se muestra como una fraccion y un porcentaje, por ejemplo 12 340 / 200 000 tokens (6%). Un token equivale aproximadamente a tres o cuatro caracteres de texto. Cuando se acerca al 100 por ciento, Claude comienza a perder las partes mas antiguas de la conversacion, por lo que vigilar este numero le ayuda a decidir cuando iniciar una sesion nueva con /clear.

La linea de estado esta impulsada por un pequeño script llamado statusline.cjs. Claude Code envia un objeto JSON a ese script despues de cada turno. El objeto incluye estos campos:

• context_window: tokens utilizados y capacidad total.
• cost: costo USD acumulado de la sesion.
• rate_limits: uso acumulado en las ultimas 5 horas y 7 dias (estos campos estan ausentes cuando Claude Code no los emite, por lo que la barra de uso simplemente desaparece en lugar de mostrar datos desactualizados).
• model: el identificador del modelo activo, por ejemplo claude-sonnet-4-6 o claude-opus-4-8.

Puede personalizar completamente lo que muestra la linea de estado editando statusline.cjs en su carpeta de configuracion de Claude Code. Analice el JSON entrante con Node.js (no con jq, que puede no estar instalado) y deje el formato de la cadena de salida a su gusto: codigos de color, campos adicionales, etiquetas abreviadas, o cualquier otra cosa que su terminal admita.

/init e incorporación de un repositorio

Cuando abres un proyecto por primera vez en Claude Code (el agente de desarrollo CLI e IDE), ejecuta /init en el panel de conversación. Claude Code analiza tu repositorio y genera un archivo llamado CLAUDE.md en la raíz del proyecto. Este archivo es la única fuente de verdad que Claude lee al inicio de cada sesión futura, de modo que nunca tiene que redescubrir de qué trata el proyecto.

Durante el análisis, /init inspecciona varios elementos:

• Los manifiestos de paquetes y archivos de bloqueo (package.json, pyproject.toml, go.mod, etc.) para identificar el lenguaje y las dependencias
• Los archivos de configuración de frameworks (Astro, Next.js, Vite, Django, entre otros) para comprender el sistema de compilación
• Los puntos de entrada comunes como src/index.* o main.* para mapear la estructura del proyecto
• Los archivos README o CONTRIBUTING existentes con las convenciones ya documentadas por el equipo

El archivo CLAUDE.md resultante contiene una breve descripción del proyecto, los comandos para ejecutar, probar y compilar el proyecto, las convenciones de código que Claude infirió, y una sección para que agregues manualmente las reglas del equipo. Debes revisar y editar este archivo antes de hacer commit: elimina lo que sea incorrecto, agrega las restricciones que Claude no detectó (variables de entorno, paquetes prohibidos, reglas de estilo), y mantenlo conciso porque Claude lee cada palabra al inicio de cada sesión.

Una vez que CLAUDE.md existe, cada colaborador (humano o agente) que abra el repositorio en Claude Code hereda automáticamente el mismo contexto. Si el proyecto evoluciona, vuelve a ejecutar /init en cualquier momento para actualizar el archivo, o edítalo directamente como cualquier otro archivo de texto.

Atajos de teclado y modo vim

Claude Code se ejecuta dentro de tu terminal, por lo que depende de atajos de teclado en lugar de clics del raton. Aprender un puñado de combinaciones convierte las interacciones lentas y repetitivas en acciones rapidas y fluidas. Los atajos que se muestran a continuacion funcionan en el modo readline predeterminado (la capa estandar de edicion de linea integrada en la mayoria de los shells y terminales de tipo Unix).

Las combinaciones mas utiles durante una sesion son las de navegacion e historial. Ctrl+A mueve el cursor al inicio de la linea actual, Ctrl+E lo mueve al final. Ctrl+U borra todo lo que hay antes del cursor, lo cual es mas rapido que mantener pulsado Retroceso. Ctrl+W elimina la ultima palabra. Para recorrer el historial de invocaciones, usa las teclas de flecha arriba y flecha abajo, o bien Ctrl+P (anterior) y Ctrl+N (siguiente) como alternativa.

Claude Code tambien incluye un modo vim opcional para la entrada de prompts. Vim es un editor de texto controlado por teclado cuyo diseño "modal" permite alternar entre insertar texto y ejecutar comandos de movimiento o edicion. Para activarlo, ejecuta /vim dentro de una sesion de Claude Code. Una vez activo, la entrada comienza en modo Insercion (escribe con normalidad). Pulsa Escape para entrar en modo Normal, donde las teclas individuales se convierten en comandos: h j k l para el movimiento, dd para eliminar una linea, 0 para ir al inicio y $ para ir al final. Pulsa i para volver al modo Insercion. Pulsa Enter en cualquiera de los dos modos para enviar el prompt.

Algunos atajos adicionales son utiles a nivel de sesion:

• Ctrl+C: interrumpe (cancela) la tarea en ejecucion sin cerrar la sesion.
• Ctrl+L: limpia la pantalla del terminal manteniendo la sesion activa.
• Ctrl+R: busqueda inversa en el historial de prompts (escribe un fragmento para encontrar un prompt anterior).
• /clear: comando escrito que reinicia el contexto de conversacion dentro de Claude Code.
• /vim: activa o desactiva el modo vim.