Claude Code: Construir agentes en producción que escalan de verdad

Prefacio

1. Por qué este libro
2. ¿Para quién es este libro?
3. Cómo leer este libro
4. Agradecimientos

Capítulo 1. El bucle del agente, en serio

1. Objetivos de aprendizaje
2. 1.1 El bucle mínimo
3. 1.2 Qué añade Claude Code encima
4. 1.3 Dónde vive realmente el Estado
5. 1.4 Ejemplo resuelto: un agente de screening de medios adversos
6. 1.5 La versión de pizarra de diez minutos
7. 1.6 Una nota sobre el vocabulario
8. Resumen
9. Ceremonias
10. Notas

Capítulo 2. Qué es Claude Code en abril de 2026

1. 2.1 El CLI como verdad sobre el terreno
2. 2.2 Superficies IDE: VS Code, JetBrains y la nueva ola
3. 2.3 Superficies de CI: Acciones de GitHub
4. 2.4 Superficies de chat: Slack
5. 2.5 Otras superficies y lo que este libro no cubre
6. 2.6 Cómo se propagan las versiones
7. 2.7 Lo que necesitas saber antes de comprometerte con una superficie
8. Resumen
9. Ceremonias
10. Notas

Capítulo 3. La familia de modelos y por qué es importante para el bucle

1. 3.1 Los tres tamaños
2. 3.2 Ventanas de contexto y cómo fallan
3. 3.3 Almacenamiento en caché rápido y por qué cambia el juego
4. 3.4 Forma del coste, no coste por token
5. 3.5 La matriz de selección de modelos
6. 3.6 Desempeño y línea base del SWE-Bench
7. Resumen
8. Ceremonias
9. Notas

Capítulo 4. El contexto como recurso de primera clase

1. 4.1 La anatomía de un turno
2. 4.2 CLAUDE.md como sistema de verdad
3. 4.3 Automemoria y cuándo miente
4. 4.4 La transcripción de la sesión y la acumulación de contexto
5. 4.4a Configuración de memoria automática y compactación
6. 4.5 Hoja de trabajo de presupuesto contextual
7. 4.6 Ejemplo resuelto: un agente de monitoreo de cumplimiento
8. Resumen
9. Ceremonias
10. Notas

Capítulo 5. La definición de producción

1. 5.1 Cinco propiedades de un agente de producción
2. 5.2 Observable: pistas de auditoría y razonamiento
3. 5.3 Reversible: Deshacer y corregir
4. 5.4 Evaluable: Métricas y medición
5. 5.5 Gobernable: control de cambios y rendición de cuentas
6. 5.6 La rúbrica de preparación
7. 5.7 Ejemplo resuelto: el agente de screening de medios adversos
8. 5.8 En qué ayudará y en qué no ayudará este libro
9. Resumen
10. Ceremonias
11. Notas

Parte II: La pila de primitivos

Capítulo 6. Herramientas como superficie API

1. Objetivos de aprendizaje
2. 6.1 Qué es realmente una herramienta
3. 6.2 Las tres categorías de herramientas
4. 6.3 Manejo de errores y qué aprende el modelo en caso de falla
5. 6.4 Herramientas de versionado sin agentes disruptores
6. 6.5 Limitación de tarifas y atribución de costes
7. 6.6 Ejemplo resuelto: el conjunto de herramientas de detección
8. 6.7 Esquemas de herramientas como gobernanza
9. Resumen
10. Ceremonias
11. Notas

Capítulo 7. Subagentes y el modelo de delegación

1. Objetivos de aprendizaje
2. 7.1 Qué es y qué no es un subagente
3. 7.2 El contrato padre-hijo
4. 7.3 Cuándo lanzar frente a cuándo incrustar
5. 7.4 Aislamiento de contexto y por qué importa
6. 7.5 El patrón fan-out
7. 7.6 Configuración de subagentes
8. 7.7 Usos indebidos comunes
9. 7.8 Cuándo usar qué: una guía de decisión en toda la pila de primitivos
10. 7.9 Ejemplo desarrollado: un agente de consultas de cumplimiento con subagentes
11. Resumen
12. Ejercicios
13. Notas

Capítulo 8. Hooks, el único supervisor que tienes

1. Objetivos de aprendizaje
2. 8.1 Qué es y qué no es un hook
3. 8.2 Patrones de matching de hooks
4. 8.3 Escribir un hook PreToolUse
5. 8.4 Escribir un hook PostToolUse
6. 8.5 El patrón de hook four-eyes
7. 8.6 Dónde viven los hooks
8. 8.7 Hooks como herramienta de depuración
9. 8.8 Ejemplo desarrollado: un agente de screening de cumplimiento con four-eyes
10. Resumen
11. Ejercicios
12. Notas

Capítulo 9. Slash commands y skills

1. Objetivos de aprendizaje
2. Objetivos de aprendizaje (continuación)
3. 9.1 Qué es una skill
4. 9.2 Anatomía del archivo de skill
5. 9.3 Escribir instrucciones que los agentes puedan seguir
6. 9.4 Auto-invoke frente a manual invoke
7. 9.5 Versionado de skills y trazas de auditoría
8. 9.6 Ejemplo desarrollado: una skill de screening
9. 9.7 Skills, herramientas y hooks
10. Resumen
11. Ejercicios
12. Notas

Capítulo 10. MCP y el plano de integración

1. Objetivos de aprendizaje
2. 10.1 Qué es realmente MCP
3. 10.2 Cómo funciona MCP
4. 10.3 Mecanismos de transporte: stdio y HTTP
5. 10.4 Escribir un servidor MCP
6. 10.5 Seguridad de MCP: autenticación, rate limiting y PII
7. 10.6 Cuándo MCP es la opción correcta
8. 10.7 Ejemplo desarrollado: un servidor MCP para medios adversos
9. Resumen
10. Ejercicios
11. Notas

Capítulo 11. Plugins y marketplaces

1. Objetivos de aprendizaje
2. 11.1 Qué contiene un plugin
3. 11.2 Instalación y ciclo de vida
4. 11.3 Confianza y procedencia
5. 11.4 El modelo de marketplace
6. 11.5 Construir un plugin para tu equipo
7. 11.6 El plugin de cumplimiento de FS: un ejemplo trabajado
8. 11.7 Resumen
9. Ejercicios
10. Notas al pie

Capítulo 12. Colocar la pila juntos: un agente de monitoreo de cumplimiento finaliza

1. Objetivos de aprendizaje
2. 12.1 El volumen de trabajo en detalle
3. 12.2 La arquitectura del agente
4. 12.3 Avanzado de sesión: proyección de un cliente
5. 12.4 La pila de gobernanza en acción
6. 12.5 Orquestación multientidad
7. 12.6 Atribución de costes y gestión del presupuesto
8. 12.7 Ejemplo de seguimiento de auditoría
9. 12.8 Lo que este capítulo no cubre (y dónde encontrarlo)
10. Resumen
11. Ejercicios
12. Notas

Capítulo 13. Cuándo salir de la CLI y cómo integrarla cuando lo hagas

1. Objetivos de aprendizaje
2. 13.1 Los cinco buenos motivos
3. 13.2 Los quince falsos positivos
4. 13.3 El patrón de subproceso: la CLI desde el SDK
5. 13.4 Diagrama de decisión en prosa
6. 13.5 Ejemplo desarrollado: un manejador de consultas de screening con auditoría
7. 13.6 Despliegue empresarial: de la CLI a Kubernetes
8. Resumen
9. Ejercicios
10. Notas al pie

Capítulo 14. El SDK de una sentada

1. Objetivos de aprendizaje
2. 14.1 La función query
3. 14.2 Opciones y configuración
4. 14.3 Tipos de mensaje
5. 14.4 Registro de herramientas y esquemas
6. 14.5 El agente mínimo funcional en cincuenta líneas (Python)
7. 14.6 El mismo agente en TypeScript
8. 14.7 Lo que el SDK no hace
9. Resumen
10. Ejercicios
11. Notas al pie

Capítulo 15. Herramientas, ganchos y subagentes del lado SDK

1. Objetivos de aprendizaje
2. 15.1 Herramientas de registro con esquemas
3. 15.2 Semántica PreToolUse y PostToolUse
4. 15.3 Gancho que coincide en el SDK
5. 15.4 Subagentes de cosecha
6. 15.5 Ejemplo de trabajo: manejador de investigación de cumplimiento
7. Resumen
8. Ejercicios
9. Notas de pie de página

Capítulo 16. Sesiones, estado y durabilidad

1. Objetivos de aprendizaje
2. 16.1 Modelo del sesión
3. 16.2 Opciones de almacenamiento y compensaciones
4. 16.3 Patrones de Durabilidad
5. 16.4 Replay de sesión para depurar
6. 16.5 Ejemplo trabajado: manejo de la investigación a través de cambios analistas
7. Resumen
8. Ejercicios
9. Notas de pie de página

Capítulo 17. El modelo de permisos: léelo dos veces

1. Objetivos de aprendizaje
2. Los tres modos de permisos
3. Permisos por herramienta
4. Permisos a escala: despliegues contenedorizados
5. Restricciones de rutas de archivos
6. El problema de escalada de permisos
7. Denegación por defecto como único punto de partida sensato
8. Auditoría de permisos
9. Ejemplo trabajado de servicios financieros: el incidente de la lista de sanciones
10. Resumen
11. Ejercicios
12. Notas

Capítulo 18. Sandboxing y la pregunta del radio de impacto

1. Objetivos de aprendizaje
2. Sandboxing a nivel de SO: límites de sistema de archivos, proceso y red
3. Aislamiento basado en contenedores
4. El marco del radio de impacto
5. Configuración de sandbox entre entornos
6. Reducir el radio de impacto: patrones prácticos de diseño
7. Medir el radio de impacto
8. Ejemplo trabajado de servicios financieros: análisis de radio de impacto para un agente de cumplimiento con acceso a PII de clientes
9. Resumen
10. Ejercicios
11. Notas

Capítulo 19. Egreso de red, secretos y límites de datos

1. Objetivos de aprendizaje
2. Listas de permitidos de red
3. Patrones de inyección de secretos: dónde y cómo gestionar claves API, tokens y credenciales
4. Higiene de variables de entorno
5. Clasificación de datos y el agente
6. PII en ventanas de contexto
7. La prueba de estrés de la carga de trabajo de screening
8. Ejemplo trabajado de servicios financieros: un agente de screening que registra PII en un endpoint de observabilidad
9. Resumen
10. Ejercicios
11. Notas

Capítulo 20. Política como código: managed settings, auditoría y linaje

1. Objetivos de aprendizaje
2. La anatomía de managed-settings.json
3. Desplegar settings a escala
4. Versionado de políticas: el repositorio de políticas
5. Logging de auditoría: qué capturar y dónde enviarlo
6. Linaje: rastrear una decisión hacia atrás a través de las llamadas de herramienta del agente
7. La pregunta forense: reconstruir qué hizo el agente
8. Ejemplo trabajado de servicios financieros: responder a una auditoría de cumplimiento con linaje
9. Resumen
10. Ejercicios
11. Notas

Capítulo 21. La cadena de suministro: plugins, habilidades, servidores MCP

1. Objetivos de aprendizaje
2. El problema de la confianza
3. Procedencia y firma
4. Fijación de versión
5. La auditoría antes de instalar.
6. Expansión de la dependencia
7. Construyendo un registro interno
8. El problema de los plugins de proveedores en industrias reguladas
9. Ejemplo de servicios financieros trabajados: el plugin de sanciones que llamaba a casa
10. Resumen
11. Ejercicios
12. Notas al pie

Capítulo 22. La mentalidad de evaluación

1. Objetivos de aprendizaje
2. Por qué las evaluaciones no son negociables
3. Los tres tipos de evaluación
4. Qué evaluar en un sistema de agentes versus un sistema de finalización
5. El ciclo de desarrollo eval-first
6. Construyendo evaluación en CI
7. Evaluaciones continuas y la conexión AgentOps
8. Cuando las evaluaciones fallan: interruptores de apagado, implementaciones canarias y respuestas automáticas
9. La trampa de la deuda de evaluación
10. Ejemplo FS: agentes de detección y deriva de resultados
11. Resumen
12. Ejercicios

Capítulo 23. Diseño de evaluaciones para cargas de trabajo agentes

1. Objetivos de aprendizaje
2. Trayectoria versus calificación de respuestas
3. Creación de conjuntos de datos valiosos para agentes
4. El problema de las fugas de etiquetas
5. Arquitectura de arnés de evaluación
6. Cómo encaja Claude Code en el flujo de trabajo de evaluación
7. Trazado de trayectorias de agentes y puntos de decisión
8. Trampas del determinismo
9. Validez estadística para conjuntos de evaluación pequeños
10. Ejemplo FS: Evaluación de screening de medios adversoss sin fugas en las etiquetas
11. Resumen
12. Ejercicios

Capítulo 24. LLM-como-juez, hecho en serio

1. Objetivos de aprendizaje
2. Qué es un modelo de juez
3. Escribir indicaciones del juez que realmente discriminan
4. Calibrando jueces contra calificaciones humanas
5. Juzgar la deriva y cómo detectarla
6. Paneles de jueces múltiples
7. La cuestión de la circularidad
8. El coste de juzgar
9. Jueces de Habilidades 2.0
10. Ejemplo de FS: Calibrar a un juez en una clasificación de investigación
11. Resumen
12. Ejercicios

Capítulo 25. Observabilidad: seguimientos, intervalos y línea de tiempo del agente.

1. Objetivos de aprendizaje
2. Qué instrumentar
3. El modelo de seguimiento para agentes: turnos, llamadas de herramientas, subagentes
4. La pila de observabilidad y dónde encaja Claude Code
5. Integración de OpenTelemetry
6. MLflow para seguimiento de experimentos
7. Opik para seguimientos específicos de agentes
8. Datadog para el seguimiento de la producción
9. Creación de paneles de control que importen
10. Tarjetas de agente y respuestas basadas en KPI
11. Diseño de alertas para agentes
12. Ejemplo de FS: Instrumentación para un agente KYC
13. Resumen
14. Ejercicios

Capítulo 26. Modos de falla e ingeniería de fiabilidad.

1. Objetivos de aprendizaje
2. La taxonomía del fracaso
3. Detección de modos de fallo
4. SLO para agentes
5. Presupuestos erróneos
6. Estrategias de reversión para agentes
7. Dónde falla el libro de jugadas SRE para los agentes
8. Disyuntores y patrones de respaldo
9. Respuesta a incidentes por fallas del agente
10. FS ejemplo: adulación en un agente de screening
11. Resumen
12. Ejercicios

Capítulo 27. Ingeniería de costes

1. Objetivos de aprendizaje
2. 27.1 Los cuatro tipos de costes
3. 27.2 Mecánica de costes de tokens y palancas de optimización
4. 27.3 Coste de tiempo: por qué el tiempo real importa más que las tokens
5. 27.4 Coste de revisión: el impuesto oculto sobre cada producción de agente
6. 27.5 Coste del cambio de contexto: lo que le cuesta al ser humano volver a interactuar
7. 27.6 Coste de infraestructura: la partida que todos olvidan
8. 27.7 Construyendo un modelo de costes
9. 27.8 Monitoreo de costes y alertas
10. 27.9 La curva de compensación coste-calidad
11. 27.10 Ejemplo resuelto: modelo de costes para una carga de trabajo de detección
12. Resumen
13. Ejercicios
14. Notas

Capítulo 28. Flujos de trabajo del equipo y la fábrica de agentes.

1. Objetivos de aprendizaje
2. 28.1 La pareja: un desarrollador, un agente
3. 28.2 El grupo: agentes compartidos, gobierno del equipo
4. 28.3 La plataforma: agentes como infraestructura
5. 28.4 Cuándo encaja cada patrón
6. 28.5 La fábrica de agentes: aprovisionamiento, monitoreo y ciclo de vida
7. 28.6 El camino dorado para las cargas de trabajo de nuevos agentes
8. 28.7 Responsabilidades: el equipo de la plataforma vs el desarrollador
9. 28.8 Ejemplo resuelto: escalar de par a plataforma
10. Resumen
11. Ejercicios
12. Notas

Capítulo 29. Antipatrones desde el campo y cómo migrar la automatización heredada sin arrepentimiento

1. Objetivos de aprendizaje
2. 29.1 Antipatrón 1: El ciclo de decisión
3. 29.2 Antipatrón 2: El bucle de inferencia
4. 29.3 Antipatrón 3: fragilidad inmediata
5. 29.4 Antipatrón 4: La trampa de herramientas
6. 29.5 Antipatrón 5: El culto al modelo
7. 29.6 Antipatrón 6: Sobrecarga de contexto
8. 29.7 Antipatrón 7: El cuello de botella en la aprobación
9. 29.8 Antipatrón 8: Coste desbocado
10. 29.9 La prueba del juicio: decidir qué debe ser un agente
11. 29.10 Migrar la automatización heredada sin arrepentimientos
12. 29.11 Ejemplo resuelto: el equipo de cumplimiento que se arrepintió de haber convertido todo su proceso
13. 29.12 Cosas que nunca deberían ser agentes
14. Resumen
15. Ejercicios
16. Notas

Capítulo 30. El camino por delante, con un mínimo de publicidad.

1. Objetivos de aprendizaje
2. 30.1 Lo que ha aterrizado y lo que viene
3. 30.2 Lo que es plausible pero no confirmado
4. 30.3 Lo que no sucederá en 2026
5. 30.4 Tres cosas para construir ahora que darán sus frutos independientemente
6. 30.5 Tres apuestas a evitar
7. 30.6 Lista de verificación de preparación de un arquitecto
8. 30.7 Las próximas conversaciones
9. Resumen
10. Lista de verificación de preparación de un arquitecto
11. Ejercicios
12. Notas

Apéndice A. Lista de verificación de preparación para la producción en noventa días

1. Fase 1: Cimentaciones (Días 1-30)
2. Fase 2: Gobernanza (Días 31-60)
3. Fase 3: Evaluaciones y operacionalización (días 61-90)
4. Métricas para rastrear

Apéndice B. El kit de inicio de evaluación

1. Evaluaciones canónicas (todos los agentes)
2. Evaluaciones de servicios financieros
3. Cómo ejecutar estas evaluaciones
4. Resultados de grabación

Apéndice C. managed-settings.json Referencia con anotaciones

1. Explicación campo por campo
2. Cómo utilizar esta configuración

Apéndice D. MCP Plantilla de auditoría del servidor

1. MCP Lista de verificación de auditoría del servidor
2. Puntuación
3. Después de la auditoría: seguimiento continuo

Apéndice E. Glosario

1. Patrones y antipatrones
2. Gobernanza y Cumplimiento
3. Abreviaturas comunes
4. Cuando este glosario no está sincronizado