Módulo 1: Qué es Claude Code y por qué importa

Cómo Funciona Claude Code

Descripción

Claude Code es un agente de IA que combina tres componentes: un modelo de lenguaje (LLM), un conjunto de herramientas (tools), y una interfaz de terminal. Entender cómo estos tres componentes trabajan juntos es la base para usar Claude Code de forma efectiva.

Esta cápsula te lleva por dentro de la arquitectura. Vas a entender qué pasa cuando le das un prompt a Claude Code: cómo lee tu codebase, cómo razona sobre la tarea, cómo decide qué herramientas usar, cómo pide permisos antes de actuar, y cómo itera hasta completar el trabajo. También vas a conocer exactamente qué puede y qué no puede hacer — para que tus expectativas sean precisas, no mágicas.

Al final de esta cápsula, la frase "agente en tu terminal" no será una abstracción. Será un modelo mental concreto que puedes usar para predecir cómo se comportará Claude Code ante cualquier tarea.

La Arquitectura: LLM + Tools + Terminal

Claude Code tiene tres capas que funcionan en conjunto:

┌───────────────────────────────────────────────┐
│                  TU TERMINAL                   │
│                                               │
│  Tú escribes un prompt                        │
│         │                                     │
│         ▼                                     │
│  ┌─────────────────────────────────────────┐  │
│  │            CLAUDE CODE (agente)          │  │
│  │                                         │  │
│  │  ┌───────────┐    ┌──────────────────┐  │  │
│  │  │    LLM    │    │     TOOLS        │  │  │
│  │  │           │    │                  │  │  │
│  │  │ Opus 5    │◄──►│ Read files       │  │  │
│  │  │ Sonnet 5  │    │ Write files      │  │  │
│  │  │ Haiku 4.5 │    │ Run commands     │  │  │
│  │  │ Razona    │    │ Search patterns  │  │  │
│  │  │ Planifica │    │ Web requests     │  │  │
│  │  │ Decide    │    │ Git operations   │  │  │
│  │  └───────────┘    └──────────────────┘  │  │
│  │                                         │  │
│  └─────────────────────────────────────────┘  │
│         │                                     │
│         ▼                                     │
│  Resultado en tu terminal                     │
└───────────────────────────────────────────────┘

El LLM: el cerebro

El LLM es el componente que entiende tu código, razona sobre problemas, y genera soluciones. Claude Code usa los modelos de Anthropic:

Opus 5: El modelo más capaz. Hasta 1M de tokens de contexto, 128K de output. Razonamiento profundo, ideal para tareas complejas.
Sonnet 5: El mejor balance entre velocidad e inteligencia. Hasta 1M de tokens de contexto, 64K de output. Ideal para tareas de coding diarias.
Haiku 4.5: El más rápido y económico. 200K de contexto, 64K de output. Ideal para tareas simples donde la velocidad y el costo importan más que la profundidad de razonamiento.

El LLM no ejecuta código directamente. Razona sobre qué hacer y decide qué herramientas usar. Es el "cerebro" que analiza, planifica, y toma decisiones.

Las Tools: las manos

Las tools son las acciones concretas que Claude Code puede realizar en tu sistema. El LLM decide cuándo y cómo usarlas:

Tool	Qué hace
`Read`	Leer archivos de tu proyecto
`Write`	Crear o sobrescribir archivos
`Edit`	Modificar secciones específicas de un archivo
`Bash`	Ejecutar comandos en tu terminal (npm, git, python, etc.)
`Glob`	Buscar archivos por patrón (ej: `*.tsx`)
`Grep`	Buscar texto dentro de archivos
`WebFetch`	Obtener contenido de una URL específica
`WebSearch`	Buscar en la web
`Agent`	Crear subagentes con su propio context window para tareas delegadas
`LSP`	Inteligencia de código: ir a definiciones, encontrar referencias, reportar errores de tipo
`Monitor`	Stream de events en background — Claude puede tailear logs y reaccionar en vivo (abril 2026)
`Computer Use`	Controlar mouse/teclado/screen — abrir apps, navegar GUI, verificar cambios visualmente (Desktop marzo 2026, CLI abril 2026 research preview)

Esta tabla muestra las tools principales. Claude Code tiene 30+ tools en total, incluyendo herramientas para gestión de tareas, notebooks Jupyter, skills, y más. Cada tool es una acción atómica. Claude Code las combina para realizar tareas complejas: leer un archivo, entender su estructura, hacer un cambio, ejecutar los tests, verificar que pasan, y hacer commit.

Nota sobre Computer Use: Anteriormente Computer Use vivía solo en Claude Cowork. En marzo-abril 2026 se expandió a Claude Code Desktop (GA) y CLI (research preview). Permite a Claude abrir apps nativas, hacer clic en UI, y verificar cambios visualmente — útil para automatizar apps sin API, verificar flujos end-to-end, o drive herramientas solo-GUI.

La Terminal (y otras interfaces): donde interactúas

Tu terminal es la interfaz original de Claude Code. Tú escribes prompts en lenguaje natural. Claude Code responde con texto, código, y acciones. Es la misma terminal donde ejecutas git, npm, python — Claude Code opera en el mismo entorno.

# Tú abres Claude Code en tu directorio de proyecto
cd my-project
claude

# Tú escribes un prompt
> Encuentra el bug en la función de autenticación y corrígelo

# Claude Code:
# 1. Lee los archivos relevantes (auth.ts, middleware.ts, etc.)
# 2. Analiza el código
# 3. Identifica el bug
# 4. Propone un fix
# 5. Te pide permiso para aplicarlo
# 6. Edita el archivo
# 7. Ejecuta los tests para verificar

Pero la terminal no es la única forma de usar Claude Code. Actualmente está disponible en 5 plataformas:

Plataforma	Descripción
CLI (terminal)	La interfaz original. Máxima flexibilidad y control.
VS Code extension	Integrado directamente en VS Code como panel lateral.
JetBrains extension	Para usuarios de IntelliJ, WebStorm, PyCharm, etc.
Desktop app	Aplicación nativa para Mac y Windows.
Web app (claude.ai/code)	Acceso desde el navegador sin instalación local.

Todas las plataformas comparten el mismo motor agéntico, las mismas tools, y el mismo sistema de CLAUDE.md. La diferencia es la interfaz, no la capacidad. En esta guía nos enfocamos en la CLI porque es la más flexible y la que te da el mayor control sobre el agente.

El Loop Agéntico

Cuando le das un prompt a Claude Code, se activa un ciclo que se repite hasta completar la tarea:

┌──────────────────────────────────────────────┐
│              EL LOOP AGÉNTICO                │
│                                              │
│  1. PROMPT ─── Tú das una instrucción        │
│       │                                      │
│  2. LECTURA ── Claude lee archivos           │
│       │        relevantes de tu proyecto     │
│       │                                      │
│  3. RAZONAMIENTO ── Claude analiza,          │
│       │              planifica, decide       │
│       │                                      │
│  4. ACCIÓN ──── Claude propone acciones:     │
│       │         editar archivo, ejecutar     │
│       │         comando, crear archivo...    │
│       │                                      │
│  5. PERMISO ── Tú apruebas o rechazas       │
│       │                                      │
│  6. EJECUCIÓN ── Claude ejecuta la acción    │
│       │                                      │
│  7. VERIFICACIÓN ── ¿Se completó la tarea?   │
│       │                                      │
│  ┌────┴───┐                                  │
│  │ ¿Listo? │                                 │
│  └────┬───┘                                  │
│   No  │  Sí                                  │
│   │   └──── Resultado final                  │
│   │                                          │
│   └──── Vuelve al paso 2 (itera)            │
│                                              │
└──────────────────────────────────────────────┘

Paso 1: Prompt

Tú das una instrucción en lenguaje natural. Puede ser tan general como "mejora la performance de esta app" o tan específica como "cambia el color del botón de submit a #3B82F6 en Header.tsx".

Paso 2: Lectura

Claude Code lee archivos de tu proyecto para entender el contexto. No lee todo el codebase a ciegas — usa heurísticas para decidir qué archivos son relevantes. Si le pides arreglar un bug en la autenticación, busca archivos relacionados con auth, middleware, login, etc.

Paso 3: Razonamiento

El LLM analiza el contexto (tu prompt + los archivos que leyó) y planifica qué hacer. Este paso es invisible para ti — pero es donde ocurre el "pensamiento" del agente. A mayor esfuerzo de razonamiento (controlado por /effort), más profundo es este análisis.

Paso 4: Acción

Claude Code propone una o más acciones concretas: editar un archivo, crear uno nuevo, ejecutar un comando. Te muestra exactamente qué va a hacer antes de hacerlo.

Paso 5: Permiso

Por defecto, Claude Code te pide aprobación antes de ejecutar acciones que modifican tu sistema. Esto incluye escribir archivos y ejecutar comandos en la terminal. Tú puedes aprobar, rechazar, o modificar la acción propuesta.

Paso 6: Ejecución

Una vez aprobada, Claude Code ejecuta la acción en tu sistema real. El archivo se edita, el comando se ejecuta, el test corre.

Paso 7: Verificación e iteración

Claude Code evalúa el resultado. Si el cambio introdujo un error (un test falla, un lint warning aparece), vuelve al paso 2 y corrige. Este ciclo de iteración es lo que hace que un agente sea diferente de un generador de código: no solo produce — verifica y corrige.

Qué Claude Code PUEDE Hacer

Lectura y análisis

Leer cualquier archivo de tu proyecto (código, configs, markdown, JSON, etc.)
Buscar patterns en tu codebase (grep, glob, regex)
Analizar la estructura del proyecto (directorios, dependencias, imports)
Entender relaciones entre archivos (quién importa qué, dónde se usa cada función)

Escritura y edición

Crear archivos nuevos (código, tests, configs, documentación)
Editar archivos existentes con cambios precisos (no reescribe todo, modifica lo necesario)
Refactoring multi-archivo (renombrar una función y actualizar todos los imports)
Generar boilerplate (componentes, rutas, modelos, migraciones)

Ejecución de comandos

npm/yarn/pnpm: Instalar dependencias, ejecutar scripts, build
git: Add, commit, push, crear branches, resolver conflictos
python: Ejecutar scripts, tests, instalar paquetes con pip
Tests: Ejecutar suites de testing (pytest, jest, vitest, etc.)
Linters/formatters: Ejecutar eslint, prettier, black, ruff
Docker: Build, run, compose
Cualquier comando que puedas ejecutar en tu terminal

Creación de contenido

Generar tests para código existente
Escribir documentación (README, docstrings, comments)
Crear configuraciones (tsconfig, eslint, Docker, CI/CD)

Ejemplo básico

> Crea un componente React llamado UserCard que reciba nombre y email como props

Claude Code:
1. Lee la estructura del proyecto para entender convenciones
2. Identifica si usas TypeScript o JavaScript
3. Detecta el estilo de componentes existentes (functional, class, hooks)
4. Crea el archivo UserCard.tsx con el componente
5. Agrega tipos si el proyecto usa TypeScript
6. Sigue las convenciones que detectó

Ejemplo intermedio

> El endpoint /api/users devuelve 500 cuando el usuario no existe. 
> Debería devolver 404. Arréglalo y agrega un test.

Claude Code:
1. Busca archivos relacionados con /api/users (routes, controllers, handlers)
2. Lee el código del endpoint
3. Identifica dónde falla (no hay manejo de "not found")
4. Edita el handler para devolver 404 cuando el usuario no existe
5. Lee los tests existentes para entender el patrón
6. Crea un test nuevo que verifica el 404
7. Ejecuta los tests para confirmar que pasan
8. Te muestra el resultado

Qué Claude Code NO PUEDE Hacer

Conocer los límites es tan importante como conocer las capacidades.

No tiene memoria conversacional entre sesiones

Cada sesión nueva empieza con un context window limpio. Claude Code no recuerda el historial de conversación de sesiones anteriores.

Mitigación: Claude Code tiene dos sistemas de memoria persistente que compensan esto: (1) CLAUDE.md — instrucciones que tú escribes sobre tu proyecto, y (2) Auto memory — notas que Claude escribe automáticamente mientras trabajas (comandos de build, patrones de debugging, tus preferencias). Ambos se cargan al inicio de cada sesión. También puedes retomar sesiones anteriores con claude --continue o claude --resume. Se cubre en profundidad en el Módulo 03.

No accede a servicios externos sin configuración

Claude Code no puede acceder a tu base de datos, tu API en producción, o servicios externos a menos que configures las herramientas necesarias (MCP servers, Módulo 07).

No actúa sin permiso (por defecto)

El modelo de permisos de Claude Code está diseñado para que tú mantengas el control. Por defecto, te pide aprobación antes de modificar archivos o ejecutar comandos. Puedes relajar esto con configuración (Módulo 05), pero el default es seguro.

No accede a archivos fuera del proyecto (por defecto)

Claude Code opera dentro del directorio donde lo ejecutas. No va a leer archivos de otros proyectos ni del sistema a menos que se lo permitas explícitamente.

No es infalible

Claude Code se equivoca. Puede generar código con bugs. Puede malinterpretar tu intención. Puede proponer soluciones subóptimas. Tu rol como developer es supervisar, evaluar, y corregir cuando sea necesario. Es pair-programming, no piloto automático.

No reemplaza el entendimiento

Si no entiendes el código que Claude Code produce, no deberías aceptarlo. Si no puedes evaluar si una solución es correcta, necesitas aprender más sobre el dominio antes de delegar. Claude Code amplifica tu capacidad — no la sustituye.

El Context Window

El context window es la cantidad de información que Claude Code puede "ver" y procesar simultáneamente. Es la memoria de trabajo del agente.

┌─────────────────────────────────────────────┐
│           CONTEXT WINDOW                     │
│                                             │
│  ┌────────────────────────────────────────┐  │
│  │  Tu prompt                            │  │
│  │  + Archivos leídos                    │  │
│  │  + Resultados de comandos             │  │
│  │  + Historial de la conversación       │  │
│  │  + CLAUDE.md (si existe)              │  │
│  │  + Respuestas anteriores              │  │
│  │                                       │  │
│  │  TODO esto debe caber en la ventana   │  │
│  └────────────────────────────────────────┘  │
│                                             │
│  Opus 5:     ████████████████  1M tokens    │
│  Sonnet 5:   ████████████████  1M tokens    │
│  Haiku 4.5:  ████             200K tokens   │
│                                             │
└─────────────────────────────────────────────┘

Tamaños de contexto

Modelo	Context window	En términos prácticos
Opus 5	1M tokens	~750K palabras
Sonnet 5	1M tokens	~750K palabras
Haiku 4.5	200K tokens	~150K palabras

¿Qué es un token?

Un token es aproximadamente 3/4 de una palabra en inglés, o ~4 caracteres. El código tiende a ser más "denso" en tokens que el texto natural debido a la sintaxis.

"Hello world"       → ~2 tokens
"console.log('hi')" → ~5 tokens
Un archivo de 100 líneas → ~500-1500 tokens (varía)

Qué pasa cuando se llena

Cuando el context window se llena, Claude Code usa compaction — un proceso que resume el historial de la conversación para liberar espacio. No pierdes el contexto por completo, pero el detalle se reduce. Esto se cubre en profundidad en el Módulo 04.

Implicación práctica

Con Opus 5 y Sonnet 5, ambos con ventana de 1M tokens, puedes analizar codebases completos de tamaño mediano sin preocuparte por el límite. Con Haiku 4.5 a 200K tokens, necesitas ser más selectivo sobre qué archivos incluir en el contexto. Nota: la disponibilidad del contexto de 1M depende del plan — en algunos planes requiere configuración adicional (se cubre en Módulo 02).

El Modelo de Tool Use

Claude Code no elige herramientas al azar. El LLM analiza tu prompt y decide qué tools necesita para completar la tarea:

Prompt: "¿Qué archivos hay en src/?"
→ Tool: Bash (ls src/)

Prompt: "Encuentra todas las funciones que usan fetch"
→ Tool: Grep (pattern: "fetch", directory: src/)

Prompt: "Arregla el typo en el README"
→ Tool: Read (README.md) → Edit (README.md)

Prompt: "Instala express y crea un servidor básico"
→ Tool: Bash (npm install express)
→ Tool: Write (server.js)

Prompt: "Refactoriza UserService para usar async/await"
→ Tool: Read (UserService.ts)
→ Tool: Read (archivos que importan UserService)
→ Tool: Edit (UserService.ts)
→ Tool: Edit (archivos que importan UserService)
→ Tool: Bash (npm test)

El LLM decide la secuencia de tools dinámicamente. No sigue un script — evalúa el resultado de cada tool y decide el siguiente paso.

El Modelo de Permisos

Claude Code pide permiso antes de actuar. Esto es un feature de seguridad fundamental.

Acciones que requieren permiso

Escribir/editar archivos     → "¿Puedo modificar auth.ts?"
Ejecutar comandos shell      → "¿Puedo ejecutar npm test?"
Crear archivos nuevos        → "¿Puedo crear UserCard.tsx?"
Eliminar archivos            → "¿Puedo eliminar temp.js?"

Modos de permiso

Claude Code tiene varios modos que controlan cuánta aprobación necesita. Puedes ciclar entre ellos con Shift+Tab:

Modo	Comportamiento
Default	Pide permiso para ediciones de archivos y comandos shell
Auto-accept edits	Acepta ediciones automáticamente, sigue pidiendo para comandos
Plan mode	Solo lectura — Claude analiza pero no modifica nada
Auto mode	Auto-aprueba con verificaciones de seguridad en background (research preview)

Opciones al recibir una petición de permiso

y (yes)           → Aprobar esta acción
n (no)            → Rechazar esta acción
a (always allow)  → Aprobar esta acción y todas las similares en esta sesión

Checkpoints: deshaciendo cambios

Cada edición de archivo es reversible. Antes de editar cualquier archivo, Claude Code toma un snapshot del estado actual. Si algo sale mal, puedes presionar Esc dos veces para revertir a un estado anterior, o pedirle a Claude que deshaga los cambios. Los checkpoints son locales a tu sesión y separados de git.

Ejemplo en práctica

> Formatea todos los archivos TypeScript con Prettier

Claude Code:
"Voy a ejecutar: npx prettier --write 'src/**/*.ts'"
Allow? [y/n/a]

> y

Running: npx prettier --write 'src/**/*.ts'
✓ 23 files formatted

Personalización del modelo de permisos

En el Módulo 05 aprenderás a configurar el permission system para automatizar aprobaciones en contextos de confianza (ej: permitir siempre ejecutar tests, pero siempre pedir permiso para delete). También puedes configurar reglas específicas por tool en .claude/settings.json.

Comparación: Claude Code vs un Developer Humano

Aspecto	Claude Code	Developer humano
Velocidad de lectura	Lee 1000 archivos en segundos	Lee 1 archivo por vez
Velocidad de escritura	Genera código en segundos	Escribe línea por línea
Contexto simultáneo	Hasta 1M tokens	~7 items en memoria de trabajo
Consistencia	Aplica convenciones uniformemente	Puede olvidar o variar
Creatividad	Patrones aprendidos	Insight y experiencia
Juicio	Probabilístico	Basado en experiencia real
Conocimiento del dominio	Amplio pero superficial	Profundo en su área
Depuración	Busca patterns y errores comunes	Intuición y experiencia
Fatiga	No se cansa	Se cansa y comete más errores
Responsabilidad	Ninguna	Total

La conclusión no es "Claude Code es mejor" o "un humano es mejor". Es: la combinación de ambos es más poderosa que cualquiera solo. Claude Code aporta velocidad, amplitud, y consistencia. Tú aportas juicio, experiencia, y responsabilidad.

El Paradigma "Agéntico"

Autocomplete (Copilot)

Tú escribes:  function calculateTax(
Copilot sugiere: amount) { return amount * 0.21; }

→ Reactivo: sugiere DESPUÉS de que tú empiezas
→ Scope: la línea actual o la función actual
→ Sin contexto del proyecto completo
→ Sin ejecución

Chat (ChatGPT)

Tú preguntas: "¿Cómo hago autenticación con JWT en Express?"
ChatGPT responde: "Aquí tienes un ejemplo..."

→ Genera texto sobre código
→ No ve tu proyecto
→ No ejecuta nada
→ Tú copias y adaptas manualmente

Agente (Claude Code)

Tú dices: "Implementa autenticación con JWT en mi API Express"
Claude Code:
  1. Lee tu codebase (rutas, modelos, middleware)
  2. Analiza la estructura existente
  3. Diseña la implementación
  4. Instala dependencias (jsonwebtoken, bcrypt)
  5. Crea el middleware de auth
  6. Modifica las rutas protegidas
  7. Genera tests
  8. Ejecuta los tests
  9. Todo pasa → listo

→ Proactivo: explora, planifica, ejecuta
→ Scope: todo el codebase
→ Contexto completo del proyecto
→ Ejecuta y verifica en tu entorno real

La diferencia es fundamental: un agente no genera código — construye software. Lee tu proyecto real, opera en tu entorno real, y produce cambios que funcionan en tu sistema real.

Patterns Comunes

Pattern 1: Exploración de codebase nuevo

> Analiza este proyecto. ¿Qué tecnologías usa, cuál es la 
> estructura, y cuáles son los principales componentes?

Claude Code lee los archivos clave (package.json, estructura de
directorios, archivos principales) y te da un resumen estructurado.

Pattern 2: Bug fix con contexto

> El endpoint POST /api/orders devuelve 500 cuando items es un 
> array vacío. Encuentra el bug y arréglalo.

Claude Code busca el handler, lee el código, identifica que no 
valida arrays vacíos, agrega la validación, y ejecuta tests.

Pattern 3: Refactoring multi-archivo

> Renombra la función getUser a fetchUserById en todo el proyecto.

Claude Code busca todos los usos, actualiza cada archivo, verifica
imports, y ejecuta tests para confirmar que nada se rompió.

Pattern 4: Generación de tests

> Genera tests unitarios para src/services/PaymentService.ts

Claude Code lee el servicio, entiende los métodos y sus 
signatures, genera tests con mocks apropiados, y los ejecuta.

Pitfalls y Edge Cases

Pitfall 1: Tratar a Claude Code como chatbot

Malo:
> ¿Cómo se hace un for loop en Python?

Mejor:
> Refactoriza processItems() para usar list comprehension 
> en lugar del for loop actual

Claude Code brilla cuando opera en tu código real, no cuando explica conceptos genéricos.

Pitfall 2: Prompts ambiguos

Malo:
> Mejora este código

Mejor:
> Optimiza la función searchUsers en users.ts: 
> está haciendo N+1 queries a la base de datos

Mientras más específico tu prompt, mejor el resultado.

Pitfall 3: No verificar los cambios

Claude Code se equivoca. No aceptes cambios a ciegas:

Lee los diffs que propone
Ejecuta los tests
Verifica que el comportamiento es el esperado

Pitfall 4: Ignorar el context window

Si llevas muchas interacciones en una sesión, el contexto se llena y se compacta. La calidad de las respuestas puede degradarse. A veces, iniciar una sesión nueva es la mejor opción.

Pitfall 5: Esperar perfección

Claude Code es una herramienta probabilística. Produce resultados que son correctos la mayoría del tiempo, pero no siempre. Tu rol es supervisar, no confiar ciegamente.

Ejemplo Completo Integrado

Escenario: Agregar un endpoint nuevo a una API Express existente

> Agrega un endpoint GET /api/products/:id que devuelva un 
> producto por ID. Si no existe, devuelve 404. Incluye 
> validación del ID y un test.

Lo que hace Claude Code (paso a paso):

1. LECTURA
   → Lee package.json (confirma Express + TypeScript)
   → Lee src/routes/ (entiende el patrón de rutas)
   → Lee src/models/Product.ts (entiende el modelo)
   → Lee src/controllers/ (entiende el patrón de controllers)
   → Lee tests/ (entiende el patrón de tests)

2. RAZONAMIENTO
   → "El proyecto usa Express + TypeScript"
   → "Las rutas están en src/routes/, usan controllers separados"
   → "Necesito: ruta, controller, validación de ID, test"
   → "El ID debe ser un número válido (validación)"

3. ACCIÓN — Crear el controller
   → Escribe src/controllers/productController.ts
   → Implementa getProductById con validación y manejo de 404

4. ACCIÓN — Agregar la ruta
   → Edita src/routes/products.ts
   → Agrega router.get('/:id', getProductById)

5. ACCIÓN — Crear el test
   → Escribe tests/products.test.ts
   → Tests: producto encontrado (200), no encontrado (404), 
     ID inválido (400)

6. EJECUCIÓN
   → Ejecuta npm test
   → Los 3 tests pasan ✓

7. RESULTADO
   → "Listo. Agregué GET /api/products/:id con validación y 
   → tests. Los 3 tests pasan."

Este es el loop agéntico en acción: lectura → razonamiento → acción → verificación → resultado.

Ejercicios Prácticos

Ejercicio 1: Identifica los componentes

Dado el siguiente escenario, identifica qué componente de la arquitectura (LLM, Tools, Terminal) está actuando en cada paso:

1. Le dices a Claude Code: "Lista todos los archivos .py en src/"
2. Claude Code ejecuta un comando para listar archivos
3. Claude Code analiza el resultado y te lo presenta organizado

Solución

Terminal — tú ingresas el prompt a través de la interfaz de terminal
Tools — Claude Code usa la tool Bash (o Glob) para listar archivos. El LLM decidió que esa era la tool correcta.
LLM — analiza el output crudo del comando y lo organiza en una respuesta legible. La respuesta se muestra a través de la Terminal.

Cada interacción involucra las tres capas: la terminal como interfaz, el LLM como cerebro que decide y comunica, y las tools como manos que ejecutan.

Ejercicio 2: Predice el comportamiento

Para cada prompt, predice qué tools usaría Claude Code y en qué orden:

"¿Qué hace la función calculateTotal en utils.ts?"
"Instala lodash y úsalo en helpers.ts para deep clone"
"Encuentra todos los console.log en el proyecto y elimínalos"

Solución

Prompt 1: "¿Qué hace la función calculateTotal en utils.ts?"

Tool 1: Read (utils.ts) — lee el archivo
El LLM analiza la función y te explica
No se necesitan más tools — es una pregunta de lectura

Prompt 2: "Instala lodash y úsalo en helpers.ts para deep clone"

Tool 1: Bash (npm install lodash) — instala la dependencia
Tool 2: Read (helpers.ts) — lee el archivo actual
Tool 3: Edit (helpers.ts) — agrega el import y el uso de _.cloneDeep

Prompt 3: "Encuentra todos los console.log en el proyecto y elimínalos"

Tool 1: Grep (pattern: console.log, directory: proyecto) — encuentra ocurrencias
Tool 2-N: Edit (cada archivo con console.log) — elimina cada ocurrencia
Tool final: Bash (npm test o lint) — verifica que nada se rompió

Ejercicio 3: Capacidades vs limitaciones

Clasifica cada tarea como "Claude Code PUEDE hacer esto" o "Claude Code NO puede hacer esto (sin configuración adicional)":

Leer un archivo CSV en tu proyecto y analizarlo
Conectarse a tu base de datos PostgreSQL en producción
Crear un branch de git y hacer push
Recordar lo que hiciste en la sesión de ayer
Ejecutar un script de Python que usa requests
Acceder a la API de Slack de tu empresa

Solución

PUEDE — Read tool lee el archivo, el LLM lo analiza
NO PUEDE (sin configuración) — necesita un MCP server o acceso directo configurado
PUEDE — usa Bash tool para ejecutar comandos de git
PARCIALMENTE — no recuerda la conversación exacta, pero sí puede retener aprendizajes entre sesiones vía auto memory y CLAUDE.md. También puedes retomar sesiones con claude --resume. Se cubre en Módulo 03.
PUEDE — usa Bash tool para ejecutar python script.py
NO PUEDE (sin configuración) — necesita un MCP server para Slack o credenciales configuradas

La regla general: si puedes hacerlo desde tu terminal con un comando, Claude Code puede hacerlo. Si requiere acceso a servicios externos, necesita configuración adicional.

Ejercicio 4: Context window en práctica

Tu proyecto tiene 500 archivos TypeScript, cada uno con ~200 líneas. Calcula:

¿Cuántos tokens aproximados tiene tu codebase?
¿Cabe completo en Opus 5 o Sonnet 5 (1M tokens)?
¿Cabe completo en Haiku 4.5 (200K tokens)?

Solución

Cálculo:

500 archivos × 200 líneas = 100,000 líneas de código
~10 tokens por línea (promedio para TypeScript)
100,000 × 10 = ~1,000,000 tokens

Respuestas:

~1M tokens (estimado)
Justo en el límite de Opus 5 y Sonnet 5 (ambos 1M). Cabrá la mayoría, pero hay que considerar que el context window también necesita espacio para el prompt, el historial de conversación, y las respuestas.
No cabe en Haiku 4.5 (200K). Necesitarías ser selectivo sobre qué archivos incluir.

Implicación práctica: Para codebases grandes, la selección de modelo importa. Opus 5 y Sonnet 5 (ambos 1M) pueden manejar la mayoría de proyectos reales. Haiku 4.5 (200K) requiere que Claude Code sea selectivo en qué lee — y lo es, porque no lee todo a ciegas sino lo relevante al prompt.

Ejercicio 5: Loop agéntico en acción

Describe los pasos del loop agéntico que seguiría Claude Code para este prompt:

"El build está fallando. Diagnostica y arregla."

Solución

PROMPT: "El build está fallando. Diagnostica y arregla."
LECTURA: Lee package.json para entender el build command. Lee archivos de configuración (tsconfig, webpack, vite, etc.)
ACCIÓN: Ejecuta el build command (npm run build) para ver el error exacto
RAZONAMIENTO: Analiza el output del error. Identifica el archivo y la línea del problema.
LECTURA: Lee el archivo donde ocurre el error
RAZONAMIENTO: Determina la causa raíz (type error, import faltante, syntax error, etc.)
ACCIÓN: Edita el archivo para corregir el error
VERIFICACIÓN: Ejecuta npm run build de nuevo
ITERACIÓN: Si hay más errores, repite desde el paso 4. Si el build pasa, reporta éxito.

El punto clave: Claude Code no adivina la solución — ejecuta el build, lee el error real, y trabaja con información concreta.

Resumen

Arquitectura: Claude Code = LLM (cerebro) + Tools (manos) + Terminal (interfaz)
LLM: Opus 5 (1M tokens, razonamiento profundo), Sonnet 5 (1M tokens, balance velocidad/inteligencia), o Haiku 4.5 (200K tokens, el más rápido y económico)
Tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Agent, LSP, y 20+ más — acciones concretas en tu sistema
Loop agéntico: Prompt → Lectura → Razonamiento → Acción → Permiso → Ejecución → Verificación → Iteración
Puede: Leer/escribir archivos, ejecutar comandos, buscar patterns, git, tests, cualquier cosa que hagas en terminal
No puede: Recordar conversaciones entre sesiones (pero tiene auto memory para aprendizajes), acceder a servicios externos sin configuración, actuar sin permiso, ser infalible
Context window: Opus 1M tokens, Sonnet 1M tokens, Haiku 200K tokens — determina cuánto puede "ver" a la vez
Permisos: Claude Code pide aprobación antes de modificar tu sistema
Paradigma agéntico: No genera texto sobre código — opera en tu código real, en tu sistema real
Tu rol: Supervisar, evaluar, corregir. Claude Code amplifica tu capacidad, no la sustituye.

Siguiente cápsula: 03 - Landscape de AI coding tools — cómo se compara Claude Code con Cursor, Copilot, Cline, y otras herramientas. Y cuándo usar cada una.

Recursos Adicionales

How Claude Code Works — Loop agéntico, tools, y cómo interactúa con tu proyecto
Tools Reference — Lista completa de tools disponibles y permisos requeridos
Configure Permissions — Sistema de permisos, modos, y reglas de configuración
Model Configuration — Modelos disponibles, aliases, effort levels, y contexto extendido
Explore the Context Window — Simulación interactiva de cómo se llena el context window
Claude Code Best Practices — Patrones recomendados para uso efectivo
Building Effective Agents — Anthropic Blog — Paper sobre patrones de diseño para agentes de IA

← AnteriorMódulo 1: Qué es Claude Code y Por Qué Importa Siguiente →Landscape de AI Coding Tools