Claude Code: programar con un agente

"Un chat te dice cómo arreglar tu código. Un agente lo arregla, corre los tests y te muestra el diff."

Qué vas a aprender en este capítulo

Hasta acá usaste Claude conversando. Este capítulo introduce un salto de categoría: Claude Code, el agente de programación de Anthropic. La diferencia no es de grado sino de tipo — un agente no solo responde: actúa sobre tu repositorio. Lee tus archivos, los edita, ejecuta comandos, corre tests, itera cuando algo falla y hace commits.

Vas a aprender qué es exactamente un agente, cómo instalar y configurar Claude Code, qué poner en el archivo CLAUDE.md, los cuatro flujos de trabajo típicos, cómo escribir pedidos que funcionan y — la parte que separa a profesionales de aprendices — cómo revisar lo que el agente hace.

No necesitás ser experto en programación: con saber qué es un repositorio y haber usado una terminal alcanza para seguir el capítulo. Avance del proyecto-hilo: configurar Claude Code en un repo tuyo, con su CLAUDE.md.

3.1 De chat a agente: qué cambia

💡 Intuición

Pedir ayuda de programación en un chat es como llamar por teléfono a un mecánico: le describís el ruido del carro, él te dice qué puede ser y qué tocar — pero el que mete las manos al motor sos vos, y si su diagnóstico era para otro modelo de carro, recién lo descubrís con la llave en la mano.

Claude Code es el mecánico que llega a tu casa: ve tu carro (lee tu repo real, no tu descripción de él), trabaja con sus herramientas (edita archivos, ejecuta comandos), prueba que arrancó (corre los tests) y te muestra exactamente qué tocó (el diff). Vos seguís decidiendo si el trabajo se acepta.

📐 Fundamento

Un agente es un modelo de lenguaje en un bucle con herramientas: el modelo decide una acción (leer tal archivo, ejecutar tal comando), la herramienta se ejecuta, el resultado vuelve al modelo, y el ciclo se repite hasta completar la tarea.

Pedido → [el modelo piensa] → acción (leer/editar/ejecutar)
              ↑                        │
              └──── resultado ─────────┘
       (repite hasta terminar la tarea)

Las consecuencias prácticas frente a un chat:

Contexto real, no relatado. El chat sabe lo que vos le contás de tu código (incompleto, a veces equivocado). El agente lee el código en sí: tus imports, tus versiones, tu estructura real.
Verificación incorporada. El agente corre tu programa y tus tests. Si su cambio rompe algo, ve el error y lo corrige — el ciclo escribir-probar-corregir que en el chat hacés vos a mano, copiando y pegando errores.
Tareas multi-archivo. "Renombrá este concepto en todo el proyecto" toca 14 archivos. En chat es una tortura; para un agente es una tarea normal.
Más poder, más responsabilidad. Un agente que edita y ejecuta puede equivocarse con efectos reales. Por eso la sección 3.6 (revisar) no es opcional.

Dónde corre Claude Code: en la terminal (CLI, la forma original), en la web, como app de escritorio y como extensión de IDE (VS Code, JetBrains). La terminal es la experiencia más completa y la que usamos en este capítulo; en el IDE ganás ver los diffs integrados en tu editor.

📜 Historia

Los asistentes de código pasaron por tres eras en menos de una década: el autocompletado inteligente (sugerencias en línea mientras escribís), el chat de código (pegás código en una conversación), y desde 2024-2025 los agentes — herramientas que operan el ciclo completo de desarrollo. Claude Code apareció en 2025 y se volvió rápidamente una de las herramientas favoritas de la industria para esta tercera era. El cambio de fondo: el costo de programar dejó de estar en teclear y pasó a estar en especificar bien y revisar bien — exactamente las dos habilidades que este capítulo entrena.

3.2 Instalación y primer uso

🛠️ En la práctica

Requisitos: una terminal (en Windows, WSL recomendado), Node.js o el instalador nativo según tu plataforma, y una cuenta de Claude. Las instrucciones exactas y actualizadas viven en code.claude.com/docs — instalá desde ahí, no desde tutoriales viejos de YouTube.

Primer uso, paso a paso:

# 1. Entrá a la carpeta de un proyecto tuyo (uno real, con código)
cd ~/proyectos/mi-tarea-de-progra

# 2. Lanzá Claude Code
claude

La primera vez te va a pedir autenticarte con tu cuenta. Después de eso, estás dentro de una sesión interactiva anclada a ese directorio: Claude Code puede leer los archivos del proyecto y trabajar sobre ellos.

Tu primera tarea — solo lectura, cero riesgo:

> Explorá este proyecto y explicame: qué hace, cómo está organizado,
  y por dónde empezarías a leerlo si fueras nuevo en el equipo.

Vas a ver al agente listar archivos, abrirlos, leerlos — y devolverte un mapa del proyecto. Fijate en el detalle clave de la experiencia: Claude Code te pide permiso antes de acciones con efectos (editar archivos, ejecutar comandos). Al inicio, leé cada solicitud de permiso; con confianza ganada irás aflojando.

Segunda tarea — primera edición:

> Agregá comentarios docstring a las funciones de utils.py que no los tengan.
  No cambiés ninguna lógica.

Cuando proponga los cambios, leé el diff completo antes de aceptar. Es el hábito número uno de esta herramienta (sección 3.6).

3.3 CLAUDE.md: la memoria del proyecto

💡 Intuición

Cuando un empleado nuevo llega a un taller, alguien le explica las reglas de la casa: dónde están las herramientas, cómo se prueba el trabajo antes de entregarlo, qué cosas no se tocan. Sin esa inducción, hasta el mejor técnico mete la pata por ignorancia local.

CLAUDE.md es la inducción escrita de tu proyecto. Claude Code lo lee automáticamente al iniciar cada sesión en ese directorio. Todo lo que pongas ahí, el agente lo sabe sin que se lo repitás.

📐 Fundamento

Qué va en un CLAUDE.md (y qué no):

1. Comandos del proyecto. Cómo se corre, cómo se prueba, cómo se construye. Es lo más valioso: le permite al agente verificar su propio trabajo.

2. Convenciones. Estilo de código, idioma de los comentarios, patrones que el equipo sigue, librerías preferidas (y prohibidas).

3. Contexto y arquitectura. Qué hace el proyecto, cómo están organizadas las carpetas, decisiones de diseño que no son obvias leyendo el código.

4. Advertencias. Qué no tocar, qué es frágil, qué archivos se generan automáticamente y no deben editarse a mano.

Qué NO va: documentación exhaustiva (el agente puede leer el código), información que cambia a diario, ni secretos de ningún tipo (es un archivo del repo — se versiona y se comparte).

Ejemplo completo para un proyecto de universidad:

# Sistema de inventario — Proyecto de Programación II

API REST de inventario para una ferretería, en Python/FastAPI con SQLite.

## Comandos
- Correr en desarrollo: `uvicorn app.main:app --reload`
- Tests: `pytest -x` (correlos SIEMPRE después de cualquier cambio)
- Lint: `ruff check .`

## Estructura
- `app/routers/` — endpoints, uno por entidad
- `app/models.py` — modelos SQLAlchemy
- `app/schemas.py` — schemas Pydantic (¡no confundir con models!)
- `tests/` — un archivo de test por router

## Convenciones
- Código y nombres en inglés; comentarios y docstrings en español.
- Todo endpoint nuevo necesita su test correspondiente.
- Usamos Pydantic v2 — no sugerir sintaxis de v1.

## Cuidado
- `data/inventario.db` es la base local — nunca borrarla ni commitearla.
- `app/legacy.py` está en proceso de migración: no agregar código nuevo ahí.

Mantenelo vivo: cuando notés que el agente repite un error ("otra vez usó sintaxis de Pydantic v1"), la solución no es corregirlo en el chat — es agregar la regla al CLAUDE.md para que no vuelva a pasar en ninguna sesión futura.

3.4 Flujos típicos

🛠️ En la práctica — Flujo 1: entender un repo ajeno

El escenario más común del mundo real: heredás código que no escribiste (un proyecto de cátedra de años anteriores, el repo de tu primera pasantía, una librería open source).

> Dame un tour del proyecto: propósito, tecnologías, estructura de carpetas
  y el flujo principal de datos de punta a punta.

> ¿Dónde se maneja la autenticación de usuarios? Mostrame el camino completo
  desde que llega el request hasta que se valida.

> Hay una función llamada process_batch que no entiendo. Explicámela línea
  por línea y decime quién la llama.

Como es solo lectura, este flujo es riesgo cero — perfecto para tus primeras horas con la herramienta. Una semana de leer código ajeno a ciegas se convierte en una tarde de preguntas dirigidas.

🛠️ En la práctica — Flujo 2: arreglar un bug (con test)

El flujo profesional para bugs tiene un orden preciso — primero el test, después el arreglo:

> Hay un bug: cuando un producto tiene stock 0, el endpoint /productos lo
  devuelve con stock negativo después de una venta. Pasos:
  1. Escribí primero un test que reproduzca el bug (debe FALLAR).
  2. Después arreglá el código hasta que ese test pase.
  3. Corré toda la suite para verificar que no rompiste nada.

¿Por qué el test primero? Porque un test que falla demuestra que el bug existe y que entendiste cuál es; cuando pasa, demuestra que se arregló; y queda para siempre vigilando que no regrese. Claude Code puede hacer el ciclo completo solo — tu trabajo es revisar que el test pruebe lo correcto.

🛠️ En la práctica — Flujo 3: construir una feature

Para funcionalidad nueva, el truco es plan antes que código:

> Quiero agregar al sistema de inventario un endpoint de alertas: GET /alertas
  debe devolver los productos con stock por debajo de su umbral mínimo.
  Cada producto tendrá un campo nuevo umbral_minimo (default 5).

  Primero proponeme un plan: qué archivos tocás y qué hacés en cada uno.
  NO escribás código todavía.

Revisás el plan, lo corregís ("el default que sea 10", "no toqués el router de ventas") y solo entonces:

> El plan está bien con esos cambios. Implementalo, con sus tests,
  y corré la suite completa al final.

Separar plan de ejecución te da un punto de control barato: corregir un plan toma un minuto; corregir una implementación equivocada de 8 archivos, una hora.

🛠️ En la práctica — Flujo 4: refactorizar

Refactorizar = mejorar la estructura sin cambiar el comportamiento. La red de seguridad son los tests:

> Quiero refactorizar app/routers/productos.py: tiene funciones de 80 líneas
  con lógica de negocio mezclada con acceso a datos.
  Restricciones:
  - Comportamiento idéntico: la suite de tests debe pasar sin modificar
    NINGÚN test existente.
  - Extraé la lógica de negocio a app/services/.
  - Hacelo en pasos chicos, corriendo los tests después de cada paso.

La restricción "sin modificar ningún test" es la cláusula de oro: si el agente necesita cambiar un test para que pase, no estaba refactorizando — estaba cambiando comportamiento. Y si tu proyecto no tiene tests, ese es el paso previo: "escribí tests de caracterización para este módulo antes de tocarlo".

3.5 El arte de pedir: objetivo + criterio de éxito + restricciones

📐 Fundamento

La fórmula de un buen pedido a un agente tiene tres partes:

Objetivo — qué querés lograr, concreto y acotado.
Criterio de éxito — cómo se sabe que está terminado y bien. Idealmente verificable por el propio agente: "los tests pasan", "el endpoint devuelve X ante Y", "el lint no marca errores".
Restricciones — qué no tocar, qué tecnología usar, qué límites respetar.

Comparemos:

❌ Pedido débil	✅ Pedido fuerte
"Mejorá el rendimiento"	"El endpoint /reportes tarda ~8s con 10k filas. Objetivo: bajarlo de 1s. Criterio: el test de tiempo en tests/perf/ pasa. Restricción: sin agregar dependencias nuevas; sospecho de las queries N+1."
"Hacé que funcione el login"	"El login falla con contraseñas que tienen ñ. Criterio: agregá un test con 'contraseña123' que pase. Restricción: no cambiar el esquema de la base."
"Agregale tests al proyecto"	"Escribí tests para app/services/ventas.py cubriendo: venta normal, venta sin stock, venta con descuento. Criterio: pytest pasa y la cobertura del archivo supera el 80%."

El criterio de éxito es la pieza que más gente omite y la que más rinde: convierte "terminé" (opinión del agente) en algo comprobable. Un agente con criterio verificable se autocorrige; sin él, declara victoria temprano.

Dos hábitos más:

Dividí lo grande. "Construime el sistema completo de facturación" es una receta para un desastre de 40 archivos imposible de revisar. Partilo: modelos → endpoints CRUD → lógica de cálculo → reportes. Un pedido por sesión de revisión.
Decile lo que sabés. "Sospecho que el problema está en el manejo de fechas" o "esto empezó a fallar después del commit de ayer" ahorra media exploración.

3.6 Revisar: tu mitad del contrato

📐 Fundamento

Trabajar con un agente es delegar, y delegar sin revisar no es delegar — es abdicar. Tu checklist:

Leé el diff completo, siempre. No el resumen que te da el agente: el diff. Preguntate en cada bloque: ¿entiendo por qué este cambio? ¿toca algo que no pedí?
Corré los tests vos también. El agente dice que pasan; verificalo. Es un comando.
Probá el caso real. Tests verdes no garantizan que la feature haga lo que querías — levantá la app y usala 2 minutos.
Buscá lo que sobra. Los agentes a veces "aprovechan" para mejorar cosas que no pediste. Cambio no pedido = cambio que se pregunta o se revierte.
Entendé antes de commitear. Regla del examen oral: si no podés explicar cada cambio del commit, no estás listo para commitearlo. En la universidad esto es literal — tu profesor TE va a preguntar a vos, no al agente.

⚠️ Trampa común

Aceptar todo sin leer. El agente trabaja rápido y suena seguro; tentador darle "aceptar, aceptar, aceptar" como quien firma papeles sin leerlos. Los riesgos, de menor a mayor: código que no entendés (y te toca defender), cambios laterales que no pediste, comportamiento sutilmente distinto al que querías, y en el extremo, borrar o romper algo valioso.

Antídotos concretos: trabajá siempre sobre una rama de git (git checkout -b feature-alertas antes de empezar — cualquier desastre se descarta con borrar la rama); diffs chicos mediante pedidos chicos; y la regla del examen oral de arriba.

⚠️ Trampa común

El pedido gigante sin dividir. "Hacé una app completa de gestión para mi iglesia con usuarios, eventos, donaciones y reportes" puede producir... algo. Algo grande, que compila, y que es imposible de revisar — con decisiones de diseño tomadas por el agente que descubrirás (mal) tres semanas después.

Antídoto: ningún pedido cuyo diff no puedas revisar con atención en ~15 minutos. Si el plan del agente lista más de 6-8 archivos a tocar, pedile que lo divida en etapas y entregá una por una. Bonus: cada etapa revisada es contexto de calidad para la siguiente.

3.7 Avance del proyecto-hilo

🛠️ En la práctica — Claude Code en tu repo

Tu tarea de este capítulo, en orden:

Elegí un repo tuyo real — la tarea más reciente de programación, tu proyecto personal, lo que tengás. Si no tenés ninguno, creá uno con cualquier código de tus cursos.
Asegurá la red: git init si no lo tiene, commit de todo lo actual, y una rama de trabajo.
Instalá Claude Code (code.claude.com/docs) y corré el tour de lectura del Flujo 1.
Escribí el CLAUDE.md con la plantilla de la sección 3.3. Truco meta: pedile al propio Claude Code un borrador — "explorá el proyecto y proponé un CLAUDE.md" — y editalo vos (vos sabés cosas que el código no dice).
Una tarea real con la fórmula completa: objetivo + criterio de éxito + restricciones. Revisá el diff con el checklist de 3.6 antes de aceptar.

Con esto, tu centro de productividad ya tiene dos alas: Proyectos en claude.ai para estudiar (cap. 2) y Claude Code para programar. Falta la tercera: construir tus propias herramientas con la API (cap. 4).

Resumen visual

Mermaid

flowchart TD A[Tarea de código] --> B{¿Qué tipo?} B -->|Entender código ajeno| C[Tour de lectura
riesgo cero] B -->|Bug| D[1. Test que falla
2. Arreglo
3. Suite completa] B -->|Feature nueva| E[1. Pedir PLAN
2. Revisar plan
3. Implementar] B -->|Refactor| F[Tests como red:
sin modificar ninguno] C & D & E & F --> G[Revisar el diff completo] G --> H{¿Entendés cada cambio?} H -->|Sí| I[Correr tests + probar
→ commit] H -->|No| J[Preguntar / pedir cambios
o revertir]

Concepto	Lo esencial
Agente	Modelo + herramientas en bucle: lee, edita, ejecuta, itera
Claude Code	Terminal, web, escritorio e IDE; pide permiso para acciones con efecto
`CLAUDE.md`	Inducción del proyecto: comandos, convenciones, contexto, advertencias
Buen pedido	Objetivo + criterio de éxito verificable + restricciones
Revisión	Diff completo, tests propios, regla del examen oral
Seguridad	Rama de git siempre; pedidos chicos; nada que no entiendas

Ejercicios

✏️ Ejercicio 1 — Chat vs agente

Para cada tarea, decidí si un chat (claude.ai) alcanza o si conviene Claude Code, y por qué: (a) "¿qué hace el método .reduce() en JavaScript?"; (b) "renombrá la entidad Cliente a Socio en todo mi proyecto"; (c) "¿por qué este fragmento de 10 líneas lanza IndexError?"; (d) "los tests de mi repo fallan desde ayer y no sé por qué".

✅ Solución

(a) Chat — pregunta conceptual, sin contexto de proyecto. Claude Code sería matar moscas a cañonazos.
(b) Claude Code — tarea multi-archivo sobre el repo real; un chat no puede ni ver ni editar tus archivos.
(c) Chat — el fragmento cabe pegado en la conversación; con eso alcanza.
(d) Claude Code — necesita correr los tests, leer los errores reales, inspeccionar el historial de cambios e iterar. Es el caso agéntico por excelencia.

Patrón: si la tarea requiere leer mucho contexto del repo o ejecutar algo, agente; si cabe en un mensaje, chat.

✏️ Ejercicio 2 — Mejorá el pedido

Este pedido es débil: "arreglá los errores del proyecto". Reescribilo con la fórmula objetivo + criterio de éxito + restricciones, inventando un contexto plausible (proyecto de inventario de la sección 3.3).

✅ Solución

Una versión fuerte:

"Al correr pytest -x fallan 3 tests de tests/test_ventas.py, todos con TypeError: unsupported operand — empezó después de agregar el campo descuento [objetivo con contexto]. Arreglá el código (no los tests) hasta que pytest pase completo [criterio de éxito verificable, con la cláusula anti-trampa de no tocar los tests]. Restricciones: no modifiqués el esquema de la base ni el router de productos; si el problema está en el diseño del campo descuento, proponé el cambio antes de implementarlo" [restricciones + punto de control].

Nota la cláusula "no los tests": sin ella, el camino más corto hacia "los tests pasan" podría ser cambiar los tests. Los criterios de éxito se escriben pensando en cómo podrían cumplirse mal.

✏️ Ejercicio 3 — Tu CLAUDE.md

Escribí el CLAUDE.md de un proyecto tuyo real (o del proyecto de inventario como ejercicio). Debe incluir las cuatro secciones: comandos, estructura, convenciones y advertencias. Después contestá: ¿qué regla pondrías para prevenir el error que MÁS cometés vos al programar en ese proyecto?

✅ Solución

La estructura debe seguir la plantilla de la sección 3.3. Sobre la pregunta final — ejemplos de reglas anti-error-personal que estudiantes reales agregan:

"Las rutas de archivos siempre relativas a la raíz del proyecto, nunca absolutas" (el clásico código-que-solo-corre-en-mi-máquina).
"Toda función que toque la base de datos debe manejar el caso de conexión fallida".
"Nunca usar print() para depurar: usar el logger configurado en app/log.py".

El punto del ejercicio: CLAUDE.md no es solo documentación — es donde codificás las lecciones aprendidas para que el agente (y vos) no las repitan.

✏️ Ejercicio 4 — Auditoría de un diff

Le pediste al agente "agregá validación de email al registro de usuarios". El diff que propone: (1) agrega la validación en routers/usuarios.py ✓; (2) agrega un test ✓; (3) actualiza la versión de Pydantic en requirements.txt; (4) reformatea completo models.py (140 líneas cambiadas, "mejoras de estilo"); (5) borra una función validar_telefono que "no se usa". ¿Qué hacés con cada cambio?

✅ Solución

(1) y (2): aceptar — es lo pedido, con su test. Igual leé la validación: ¿maneja mayúsculas, espacios, dominios raros?
(3): preguntar antes de aceptar — ¿por qué hizo falta subir Pydantic? Si la validación lo requiere, ok, pero un cambio de dependencia afecta TODO el proyecto y merece justificación explícita.
(4): rechazar (pedir que lo revierta) — reformateo masivo no pedido. Contamina el diff (imposible distinguir lo importante), genera conflictos con compañeros y no tiene relación con el objetivo. Si querés reformatear, que sea un commit aparte, dedicado.
(5): rechazar y verificar — "no se usa" según el agente, pero ¿buscó usos en todo el repo, incluyendo strings y configs? Borrar código es un pedido en sí mismo, no un efecto lateral. Pedile que lo restaure; si de verdad sobra, lo borrarás conscientemente otro día.

Moraleja: de 5 cambios, solo 2 se aceptan directo. Esto es lo normal, y es exactamente por esto que se lee el diff.

Para profundizar

Documentación oficial de Claude Code: code.claude.com/docs — instalación por plataforma, configuración, referencia completa de CLAUDE.md y buenas prácticas.
Plataforma: platform.claude.com/docs — los conceptos de agentes y herramientas, por si querés entender la maquinaria de abajo.
Capítulo 4 de este libro — la API: el siguiente paso es que TUS programas llamen a Claude.

← Anterior claude.ai a fondo Siguiente → Tu primera app con la API

Reportar error en este capítulo · Patrocinar este libro