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.

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

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.

# 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.

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.

# 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

// .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.