Mapa de la ruta
Contenido detallado
🧭 Qué es Claude Code
Entiende qué diferencia a un agente de IA de un chatbot y por qué Claude Code vive en el terminal.
Un agente es un programa que percibe el entorno, toma decisiones y actúa de forma autónoma para alcanzar un objetivo, a diferencia de un chatbot que solo responde preguntas.
Entender esta diferencia es fundamental para saber qué esperar de Claude Code y cómo pedir tareas de forma eficiente.
Percepción → Decisión → Acción; ciclo autónomo; objetivo frente a respuesta única; contexto persistente.
La terminal es la interfaz de texto que da acceso directo al sistema operativo: archivos, procesos, red. Es donde el agente ejecuta comandos reales.
Las interfaces gráficas son lentas y difíciles de automatizar. En la terminal, Claude Code puede leer, escribir, ejecutar y buscar en segundos.
Shell, stdin/stdout, pipe, permisos de archivo, PATH, proceso hijo.
Claude Code usa herramientas concretas: Read (lee archivos), Edit (modifica archivos), Bash (ejecuta comandos), Search (busca patrones en el código).
Saber qué herramientas existen ayuda a entender qué puede y qué no puede hacer el agente en cada tarea.
Read, Edit, Write, Bash, Glob, Grep — las herramientas nativas de Claude Code.
Refactorizar código, crear funciones, escribir pruebas, migrar APIs, corregir errores, generar documentación — todo sin salir del terminal.
Delimitar el alcance de uso aumenta la efectividad. Saber «dónde destaca el agente» ahorra tiempo y evita frustraciones.
Tareas de código, automatización de repositorios, CI/CD, generación de boilerplate, análisis de logs.
Un chatbot responde texto. Un agente ejecuta acciones en el mundo real: crea archivos, ejecuta pruebas, hace commits. Claude Code es un agente.
Cambiar el enfoque mental de "preguntar" a "delegar tareas" transforma la forma de usar la herramienta.
Acción vs. respuesta; efecto secundario; permiso de ejecución; autonomía controlada.
El primer contacto: abrir la terminal, escribir claude, pedir una tarea sencilla y observar cómo trabaja el agente paso a paso.
Ver al agente en acción — con las herramientas apareciendo en tiempo real — es la mejor forma de asimilar el concepto.
Sesión interactiva, modo headless, claude --help, primera tarea delegada.
🧠 Cómo piensa el agente
Descubre el ciclo interno del agente: cómo planifica, elige herramientas y decide cuándo pedir permiso.
El agente ejecuta un ciclo continuo: Pensar (razonar sobre qué hacer), Usar herramienta (acción en el mundo real), Observar (leer el resultado) y repetir.
Entender el ciclo ayuda a formular mejores tareas y a saber por qué el agente hace ciertas preguntas o toma ciertas decisiones.
Bucle ReAct, "chain of thought", observación del entorno, iteración hasta completar.
Las herramientas son las «manos» del agente: Read (lee archivos), Edit (edita archivos), Bash (ejecuta comandos), Glob (lista archivos), Grep (busca texto).
Cada herramienta tiene costos, permisos y alcances diferentes. Conocerlas permite entender los logs y optimizar el flujo.
Llamada a herramienta, resultado de herramienta, permiso explícito vs. implícito, costo en tokens por herramienta.
Antes de actuar, el agente razona internamente: divide el problema en pasos, identifica dependencias y elige la herramienta adecuada para cada etapa.
Dar suficiente contexto en la tarea permite que el plan sea más preciso y reduce idas y vueltas innecesarias.
Descomposición de tareas, plan explícito vs. implícito, bloc de notas interno, seguimiento del progreso.
El agente pide confirmación antes de realizar acciones destructivas (eliminar archivos, ejecutar comandos peligrosos) o cuando no tiene suficiente contexto.
Saber cuándo el agente hará una pausa y pedirá ayuda evita sorpresas y ayuda a configurar correctamente los permisos en settings.json.
allowlist, denylist, confirmación interactiva, modo autónomo, --dangerously-skip-permissions.
El agente no navega por sitios, no hace clic en interfaces gráficas (sin plugins), no tiene memoria entre sesiones de forma predeterminada y no tiene acceso a Internet sin herramientas externas.
Conocer los límites evita expectativas equivocadas y ayuda a complementar con otras herramientas cuando sea necesario.
Sin memoria persistente nativa, sin acceso a GUI, con sandboxing y alcance limitado al proyecto local.
Durante la ejecución, Claude Code muestra cada herramienta que se invoca, lo que se leyó y lo que se modificó — el registro visible del razonamiento en tiempo real.
Leer los logs ayuda a entender las decisiones, detectar errores antes y confiar más en lo que hace el agente.
Salida verbose, registro de herramientas, razonamiento explícito, verificación humana, interrupción segura (Ctrl+C).
🪟 Contexto, tokens y ventana
Entiende cómo el agente "recuerda" las cosas, por qué esa memoria tiene un límite y cómo no desperdiciarla.
El contexto es todo lo que el modelo "sabe" en ese momento: la conversación, los archivos leídos y el resultado de las herramientas. Es la memoria de trabajo activa de la sesión.
Si no entiendes el contexto, no sabrás por qué el agente «olvidó» algo o por qué sus respuestas se volvieron extrañas al final de la sesión.
Prompt, historial de conversación, resultados de herramientas en el contexto, CLAUDE.md como contexto persistente.
Los tokens son fragmentos de texto (≈ 4 caracteres en inglés, ≈ 3 en pt-BR). Cada palabra se convierte en 1-3 tokens. Los modelos procesan y cobran por tokens.
Entender los tokens ayuda a estimar costos, controlar el uso de la ventana y evitar superar el límite que degrada las respuestas.
Token de entrada, token de salida, tokenizer, costo por 1M tokens, longitud del archivo en tokens.
La ventana de contexto es el límite máximo de tokens que el modelo procesa de una vez. Claude 3 Sonnet tiene 200K tokens — unas 500 páginas de texto.
Cuando la ventana se llena, el agente empieza a «olvidar» partes de la conversación o el sistema trunca el contexto automáticamente.
200K tokens, truncamiento automático, degradación del rendimiento, ventana deslizante.
El contexto se llena por estos motivos: archivos grandes leídos completos, historial extenso, respuestas verbosas y muchas llamadas a herramientas acumuladas en la misma sesión.
Identificar al culpable permite actuar: dividir sesiones, usar /clear o cambiar la estrategia para leer archivos.
Archivo grande, historial extenso, resultados de herramientas acumulados, lectura innecesaria de archivos binarios.
El comando /compact reanuda la conversación anterior y libera espacio en la ventana. Claude Code también compacta automáticamente cuando es necesario.
Saber cuándo y cómo compactar evita perder contexto crítico y mantiene la eficacia del agente en sesiones largas.
/compact, /clear, tipos en
Prácticas como usar CLAUDE.md para instrucciones fijas, dividir las tareas grandes en sesiones más pequeñas y evitar leer archivos innecesarios ahorran tokens y mejoran la calidad.
Un contexto conciso significa respuestas más precisas, menor costo y sesiones más largas antes de la degradación.
CLAUDE.md, sesiones cortas y enfocadas, lectura selectiva, evita copiar código completo en los mensajes.
⌨️ Terminal y CLI para principiantes
De cero a la terminal: carpetas, rutas, comandos esenciales y seguridad básica para quienes nunca han usado la terminal.
La terminal es un programa que interpreta comandos de texto. En Mac: Terminal o iTerm2. En Windows: PowerShell o WSL. En Linux: cualquier emulador.
Claude Code solo funciona en la terminal. Sin saber abrir y usar la terminal, ni siquiera es posible iniciar el agente.
Shell (bash/zsh), prompt ($), emulador de terminal, stdin/stdout, código de salida 0 = éxito.
El sistema de archivos es un árbol. Ruta absoluta: /home/user/projeto. Ruta relativa: ./src. El punto de partida es el directorio actual.
Claude Code opera en el directorio desde el que lo inicias. Entender las rutas es esencial para indicar al agente cuáles son los archivos correctos.
Raíz (/), home (~), ruta absoluta, ruta relativa, . (actual), .. (padre).
cd (cambiar de carpeta), ls (listar), mkdir (crear carpeta), pwd (dónde estoy), cat (ver archivo), cp/mv/rm.
Claude Code usa estos comandos en casi todas las tareas. Reconocerlos en los logs ayuda a seguir lo que está haciendo el agente.
cd, ls -la, mkdir -p, pwd, cat, cp, mv, rm -rf (¡cuidado!), man (ayuda).
CLI (Command-Line Interface) es un programa que controlas mediante texto en la terminal: git, npm, python, claude son CLIs.
Claude Code ES una CLI. Entender cómo funcionan las CLI (flags, subcomandos, --help) te ayuda a usar cualquier herramienta de línea de comandos.
Flags (--flag), argumentos posicionales, subcomandos, --help, código de retorno.
Los gestores de paquetes instalan CLIs: npm install -g @anthropic-ai/claude-code (Node), brew install (Mac), apt install (Linux).
Instalar Claude Code es el primer paso práctico. Entender cómo funcionan los gestores de paquetes evita errores de instalación.
npm, Node.js, PATH, versión global vs. local, which claude, actualización.
Nunca ejecutes comandos copiados de internet sin entender qué hacen. rm -rf /, curl | bash sin verificar, y sudo lo innecesario son riesgos reales.
La terminal tiene poder real sobre el sistema. Un comando incorrecto puede borrar archivos, exponer credenciales o instalar malware.
Leer antes de ejecutar, usar sudo con moderación, proteger los secretos en las variables de entorno y agregar .env a .gitignore.