--- title: "Cómo construir un agente con Claude Code" description: "Guía práctica para construir un agente con Claude Code: arquitectura, herramientas, bucles de ejecución y ejemplos reales. Sin rodeos, solo lo que funciona." slug: "como-construir-un-agente-con-claude-code" url: "https://catalizadora.ai/blog/como-construir-un-agente-con-claude-code" cluster: "aprender-construir-agentes" author: "Pablo Estrada" published_at: "2026-06-20T10:47:39.431+00:00" updated_at: "2026-06-20T10:47:39.497078+00:00" read_minutes: "7" lang: "es" --- # Cómo construir un agente con Claude Code > Guía práctica para construir un agente con Claude Code: arquitectura, herramientas, bucles de ejecución y ejemplos reales. Sin rodeos, solo lo que funciona. # Cómo construir un agente con Claude Code Claude Code es la CLI oficial de Anthropic que convierte a Claude en un agente autónomo capaz de leer archivos, ejecutar comandos, escribir código y razonar sobre los resultados — todo desde tu terminal. No es un chatbot con acceso a herramientas: es un entorno de ejecución agentic completo donde Claude actúa, observa y ajusta sin que tengas que guiarlo paso a paso. Esta guía explica **cómo construir un agente con Claude Code** desde cero: arquitectura, herramientas disponibles, patrones de diseño y errores comunes. Aplica tanto si estás prototipando en solitario como si estás construyendo un sistema de producción. --- ## Qué hace exactamente Claude Code Antes de escribir una sola línea, conviene entender qué distingue a Claude Code de llamar directamente a la API de Claude. | Capacidad | API estándar | Claude Code | |---|---|---| | Leer archivos del sistema | ✗ | ✓ | | Ejecutar comandos de shell | ✗ | ✓ | | Navegar directorios | ✗ | ✓ | | Loop agentic integrado | ✗ | ✓ | | Uso de herramientas sin configuración | ✗ | ✓ | Claude Code incluye un conjunto de **herramientas predefinidas** que el modelo puede invocar autónomamente: - `Read` / `Write` / `Edit` — lectura y escritura de archivos - `Bash` — ejecución de comandos de terminal - `Glob` / `Grep` — búsqueda en el sistema de archivos - `WebFetch` — obtención de contenido web - `TodoWrite` / `TodoRead` — gestión de tareas internas del agente El resultado: Claude puede recibir una instrucción como *"Refactoriza todos los endpoints de esta API para que usen async/await"* y ejecutarla completamente sin intervención humana. --- ## Instalación y configuración inicial ### Requisitos - Node.js 18 o superior - Una API key de Anthropic (variable de entorno `ANTHROPIC_API_KEY`) - Permisos de escritura en el directorio de trabajo ```bash npm install -g @anthropic-ai/claude-code export ANTHROPIC_API_KEY="sk-ant-..." claude ``` Con `claude` sin argumentos entras al modo interactivo. Con `claude -p "instrucción"` ejecutas una tarea no interactiva, ideal para pipelines de CI/CD. ### Archivos de configuración clave Claude Code lee dos archivos especiales al iniciar: - **`CLAUDE.md`** en la raíz del proyecto: instrucciones persistentes, convenciones de código, arquitectura del sistema. Todo lo que Claude debe saber antes de empezar a actuar. - **`~/.claude/CLAUDE.md`**: preferencias globales del usuario (estilo de código, idioma de respuesta, herramientas preferidas). Invertir 20 minutos en un buen `CLAUDE.md` ahorra horas de correcciones posteriores. --- ## Arquitectura de un agente con Claude Code Un agente construido sobre Claude Code sigue un bucle **Percepción → Razonamiento → Acción → Observación**: ``` Usuario / Sistema │ ▼ [Instrucción] │ ▼ Claude (LLM) ──── razona ────► elige herramienta │ │ │◄─────── observa resultado ───┘ │ ¿Tarea completa? ├── No → siguiente acción └── Sí → entrega resultado ``` Este loop se repite automáticamente hasta que Claude determina que la tarea está terminada o que necesita input del usuario. La clave está en que **el modelo decide cuándo preguntar** — no en cada paso. ### Patrones de diseño probados #### 1. Agente de tarea única con CLAUDE.md especializado El patrón más simple y más confiable. Defines un `CLAUDE.md` con contexto muy específico y lanzas Claude Code contra una tarea acotada. ```md # CLAUDE.md — Agente de migración de base de datos ## Rol Eres un agente especializado en migraciones de PostgreSQL. ## Reglas - Nunca ejecutes DROP sin confirmar con el usuario - Siempre genera el script de rollback antes del script principal - Usa transacciones explícitas en todas las migraciones ## Contexto del proyecto - ORM: Prisma 5.x - DB: PostgreSQL 15 - Convención de nombres: snake_case ``` #### 2. Agente multi-paso con subagentes Para tareas complejas, Claude Code puede orquestar múltiples instancias de sí mismo mediante el comando `claude` dentro de un script Bash o Python. Cada subagente tiene un `CLAUDE.md` especializado y scope limitado. ```python import subprocess def run_subagent(prompt: str, working_dir: str) -> str: result = subprocess.run( ["claude", "-p", prompt, "--output-format", "json"], cwd=working_dir, capture_output=True, text=True ) return result.stdout # Agente 1: análisis analysis = run_subagent("Analiza este codebase e identifica code smells", "./src") # Agente 2: refactoring basado en el análisis run_subagent(f"Refactoriza basándote en este análisis: {analysis}", "./src") ``` #### 3. Agente con herramientas personalizadas vía MCP Claude Code soporta el **Model Context Protocol (MCP)**, que permite conectar herramientas externas: bases de datos, APIs internas, sistemas de tickets, dashboards de métricas. ```bash # Agregar un servidor MCP al proyecto claude mcp add mi-api-interna -- python3 ./mcp_server.py # Ahora Claude puede usar las herramientas expuestas por ese servidor ``` Con MCP, el agente puede hacer queries a tu base de datos, abrir tickets en Jira, leer métricas de Datadog o ejecutar queries en BigQuery — todo dentro del mismo loop agentic. --- ## Control de permisos y seguridad Un agente autónomo con acceso a Bash es poderoso y potencialmente peligroso. Claude Code tiene un sistema de permisos granular: ### Modos de aprobación - **`default`**: Claude pide confirmación antes de ejecutar comandos que modifican el sistema - `--allowedTools "Bash(git *),Read,Write"`: permite solo herramientas específicas - `--dangerously-skip-permissions`: desactiva confirmaciones (solo para ambientes aislados/CI) ### Buenas prácticas de seguridad - Corre Claude Code dentro de contenedores Docker en producción - Usa `.claude/settings.json` para definir listas blancas de comandos Bash permitidos - Nunca expongas la API key en logs ni en el `CLAUDE.md` - Limita el acceso de red si el agente solo necesita trabajar con archivos locales ```json // .claude/settings.json { "permissions": { "allow": [ "Bash(npm run *)", "Bash(git *)", "Read", "Write" ], "deny": [ "Bash(rm -rf *)", "Bash(curl *)" ] } } ``` --- ## Casos de uso reales y métricas Estos son patrones que funcionan en proyectos reales, no teoría: ### Revisión de código automatizada Un agente configurado para revisar PRs puede analizar un diff de 500 líneas, ejecutar los tests, identificar regresiones potenciales y escribir comentarios estructurados en menos de 3 minutos. El mismo proceso manual toma entre 30 y 90 minutos. ### Generación de tests unitarios Con un `CLAUDE.md` que define el framework de testing y las convenciones del proyecto, Claude Code puede generar suites de tests con 80%+ de cobertura para módulos sin tests existentes. No perfectos, pero sí funcionales y con estructura correcta. ### Migración de dependencias Actualizar un proyecto de React 17 a React 18, incluyendo cambios en la API de renderizado, manejo de Suspense y actualizaciones de tipos TypeScript: Claude Code lo completa en una sola sesión en proyectos de hasta ~50,000 líneas de código. ### Auditorías de seguridad Conectado vía MCP a herramientas de análisis estático, un agente puede escanear el codebase, priorizar vulnerabilidades por severidad y generar los patches correspondientes en la misma sesión. --- ## Errores comunes al construir agentes con Claude Code ### 1. CLAUDE.md vacío o genérico Sin contexto de proyecto, Claude asume defaults que pueden no coincidir con tus convenciones. Un `CLAUDE.md` de 50 líneas bien escrito tiene más impacto que horas de prompting. ### 2. Tareas demasiado amplias "Refactoriza toda la aplicación" lleva a loops largos, inconsistencias y resultados difíciles de revisar. Mejor: "Refactoriza el módulo de autenticación para seguir el patrón Repository". ### 3. No verificar resultados intermedios Claude Code puede cometer errores que se propagan. En tareas largas, insertar checkpoints de verificación — ya sea humanos o automatizados con scripts de validación — reduce el costo de corrección. ### 4. Ignorar el uso de tokens Un loop agentic largo consume entre 50,000 y 500,000 tokens fácilmente. Usa `--output-format json` para monitorear el uso y establece presupuestos máximos en tareas no críticas. --- ## Del prototipo al sistema productivo Construir un agente que funciona en tu máquina es el paso 1. Llevarlo a producción requiere: - **Orquestación**: cómo se disparan los agentes (webhook, cron, evento en cola) - **Observabilidad**: logs estructurados de cada acción del agente, duración, tokens usados - **Manejo de errores**: qué pasa cuando el agente falla a mitad de una tarea - **Control de versiones del CLAUDE.md**: tratar las instrucciones del agente como código Estos son exactamente los problemas que resuelve un equipo con experiencia en arquitectura de sistemas de IA. Construir el agente es la parte fácil; integrarlo de forma robusta con tus sistemas existentes es donde está el trabajo real. --- ## Próximos pasos Construir un agente con Claude Code es accesible. Construir uno que sea confiable, auditable y que genere valor medible en producción es un problema de ingeniería que combina diseño de sistemas, conocimiento de LLMs y experiencia operativa. Si quieres profundizar en cómo Catalizadora diseña y despliega agentes de IA a medida — con ownership completo del código y sin licencias recurrentes — revisa nuestro enfoque en [/manifiesto](/manifiesto). ## Preguntas frecuentes ### ¿Claude Code es lo mismo que la API de Claude? No. La API de Claude es una interfaz de texto puro donde tú gestionas el contexto y las herramientas. Claude Code es una CLI agentic que incluye herramientas predefinidas (leer/escribir archivos, ejecutar Bash, buscar en el sistema) y un loop de ejecución autónomo. Claude Code usa la API de Claude internamente, pero agrega toda la capa de agente. ### ¿Cuánto cuesta usar Claude Code? Claude Code se factura por tokens consumidos a través de tu API key de Anthropic, usando el modelo Claude Sonnet o Opus según tu configuración. No hay costo fijo adicional por la CLI. Un loop agentic típico de mediana complejidad consume entre 20,000 y 100,000 tokens de entrada y salida, lo que a precios actuales equivale a centavos de dólar por tarea. ### ¿Es seguro darle acceso a Bash a un agente de IA? Con las configuraciones correctas, sí. Claude Code tiene un sistema de permisos granular que permite aprobar solo comandos específicos (por ejemplo, solo 'git *' y 'npm run *'). Para producción, se recomienda correr el agente en contenedores aislados y usar listas blancas de comandos en el archivo .claude/settings.json. ### ¿Puedo conectar Claude Code a mis propias APIs o bases de datos? Sí, mediante el Model Context Protocol (MCP). Puedes exponer herramientas personalizadas como servidores MCP y Claude Code las usará automáticamente dentro del loop agentic. Esto permite conectar el agente a PostgreSQL, APIs REST internas, sistemas de tickets, dashboards de métricas, o cualquier fuente de datos que puedas envolver en un servidor MCP. ### ¿Qué tamaño de codebase puede manejar Claude Code? Claude Code usa búsqueda selectiva (Glob, Grep) para trabajar con repositorios grandes sin cargar todo en contexto. En la práctica funciona bien con proyectos de hasta 500,000 líneas de código, aunque el rendimiento depende de qué tan acotada sea la tarea. Para proyectos muy grandes, la recomendación es dividir en subtareas con scope limitado. ### ¿Cómo se diferencia de GitHub Copilot o Cursor? Copilot y Cursor son herramientas de asistencia al desarrollador: sugieren código mientras escribes. Claude Code es un agente autónomo que ejecuta tareas completas sin que el desarrollador esté al teclado. Es una diferencia de paradigma: asistencia vs. ejecución autónoma. Ambos enfoques son complementarios. --- Source: https://catalizadora.ai/blog/como-construir-un-agente-con-claude-code Author: Pablo Estrada — AI Catalyst, LLC (catalizadora.ai)