Cómo Configurar 5 Agentes de IA para Crear una API Completa (Desde la Especificación hasta las Pruebas)

Deja de usar un asistente de IA genérico para todo. Configura 5 agentes especializados para construir una API completa: el Arquitecto de Backend diseña el sistema, el Optimizador de Base de Datos revisa el esquema, el Desarrollador Frontend construye el cliente, el Revisor de Código verifica la seguridad y el Verificador de Realidad valida antes del envío.

Prueba Apidog hoy

Necesitas construir una API rápidamente. La tentación: pedirle a una sola IA que lo haga todo. Diseñará la base de datos, escribirá los endpoints, construirá el frontend, revisará el código y probará el resultado.

Esto es lo que sucede: la base de datos carece de índices, los endpoints tienen brechas de seguridad, el frontend ignora los estados de error y las pruebas consisten en "me parece bien".

Los agentes especializados solucionan esto. Cada agente conoce su dominio. Cada agente tiene listas de verificación. Cada agente produce entregables específicos. El Arquitecto de Backend piensa en la escalabilidad. El Optimizador de Base de Datos detecta índices faltantes. El Revisor de Código encuentra vulnerabilidades. El Verificador de Realidad exige pruebas.

En este tutorial, configurarás 5 agentes de la colección Agency y ejecutarás un flujo de trabajo completo de construcción de API. Te integrarás con Apidog para la prueba y documentación de API, asegurando que tus endpoints sean validados contra las especificaciones OpenAPI antes de la implementación.

Los 5 Agentes que Utilizarás

Agente	División	Responsabilidad
Arquitecto de Backend	Ingeniería	Diseño de API, esquema de base de datos, autenticación
Optimizador de Base de Datos	Ingeniería	Recomendaciones de índices, optimización de consultas
Desarrollador Frontend	Ingeniería	Componentes React, cliente API, gestión de estado
Revisor de Código	Ingeniería	Auditoría de seguridad, seguridad de tipos, manejo de errores
Verificador de Realidad	Pruebas	Validación basada en evidencia, prueba con capturas de pantalla

Instala los agentes:

# Clona el repositorio de Agency
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# Copia los agentes a Claude Code
cp engineering/engineering-backend-architect.md ~/.claude/agents/
cp engineering/engineering-database-optimizer.md ~/.claude/agents/
cp engineering/engineering-frontend-developer.md ~/.claude/agents/
cp engineering/engineering-code-reviewer.md ~/.claude/agents/
cp testing/testing-reality-checker.md ~/.claude/agents/

Paso 1: El Arquitecto de Backend Diseña el Sistema

Inicia una nueva sesión de Claude Code:

Activate Backend Architect mode.

Design a REST API for an e-commerce platform with:
- User authentication (JWT with refresh tokens)
- Product catalog with categories and filtering
- Shopping cart management
- Order processing with status tracking
- Payment webhook integration

Output:
1. OpenAPI 3.0 specification
2. PostgreSQL database schema with relationships
3. Project folder structure (Express.js + TypeScript)
4. Authentication flow diagram

Entregables esperados:

El Arquitecto de Backend generará:

Especificación OpenAPI (parcial):

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
paths:
  /auth/login:
    post:
      summary: User login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
      responses:
        '200':
          description: JWT tokens
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken: { type: string }
                  refreshToken: { type: string }

Esquema de Base de Datos:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL CHECK (price >= 0),
    category_id UUID REFERENCES categories(id),
    inventory_count INTEGER DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    total_amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(50) DEFAULT 'pending',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Estructura de Carpetas:

src/
├── controllers/
│   ├── auth.controller.ts
│   ├── products.controller.ts
│   └── orders.controller.ts
├── middleware/
│   ├── auth.middleware.ts
│   └── validation.middleware.ts
├── routes/
│   ├── auth.routes.ts
│   ├── products.routes.ts
│   └── orders.routes.ts
├── services/
│   ├── auth.service.ts
│   ├── products.service.ts
│   └── orders.service.ts
├── models/
│   ├── User.ts
│   ├── Product.ts
│   └── Order.ts
└── index.ts

Guarda el resultado. Lo pasarás al siguiente agente.

Paso 2: El Optimizador de Base de Datos Revisa el Esquema

Abre una nueva sesión:

Activate Database Optimizer mode.

Review this PostgreSQL schema for an e-commerce API:

[Paste the schema from Step 1]

Check for:
1. Missing indexes on foreign keys and frequently queried columns
2. Query performance on product search (name, category, price range)
3. Proper constraints for data integrity
4. Missing tables for common e-commerce features (reviews, wishlists)
5. Soft delete patterns for audit trails

Output specific ALTER TABLE statements and new table definitions.

Entregables esperados:

Recomendaciones de Índices:

-- Add indexes on foreign keys
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);

-- Add index for product search
CREATE INDEX idx_products_name_search ON products USING gin(to_tsvector('english', name));
CREATE INDEX idx_products_price ON products(price) WHERE inventory_count > 0;

-- Add composite index for category filtering
CREATE INDEX idx_products_category_price ON products(category_id, price);

Tablas Faltantes:

CREATE TABLE reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    product_id UUID REFERENCES products(id),
    user_id UUID REFERENCES users(id),
    rating INTEGER CHECK (rating >= 1 AND rating <= 5),
    comment TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(product_id, user_id)
);

CREATE TABLE cart_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    product_id UUID REFERENCES products(id),
    quantity INTEGER DEFAULT 1 CHECK (quantity > 0),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, product_id)
);

Restricciones a Añadir:

-- Email format validation
ALTER TABLE users ADD CONSTRAINT chk_email_format
    CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$');

-- Soft delete column
ALTER TABLE products ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE NULL;
CREATE INDEX idx_products_deleted_at ON products(deleted_at) WHERE deleted_at IS NULL;

Aplica estas recomendaciones a tu esquema.

Paso 3: El Desarrollador Frontend Construye el Cliente

Abre una nueva sesión:

Activate Frontend Developer mode.

Build a React dashboard for this e-commerce API:

[Paste OpenAPI spec from Step 1]

Requirements:
- TypeScript with strict mode
- React Query for server state management
- Product list with filters (category, price range, search)
- Shopping cart with real-time updates
- Order history with status tracking
- Proper error handling and loading states
- Responsive design (mobile, tablet, desktop)

Output:
1. Project setup (Vite + React + TypeScript)
2. API client with React Query hooks
3. Core components (ProductList, ProductCard, Cart, OrderHistory)
4. Error boundary and loading skeletons

Entregables esperados:

Cliente API:

// src/lib/api-client.ts
import { QueryClient, useQuery, useMutation } from '@tanstack/react-query';

const API_BASE = 'http://localhost:3000/api';

async function fetcher<T>(endpoint: string, options?: RequestInit): Promise<T> {
  const response = await fetch(`${API_BASE}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Request failed');
  }

  return response.json();
}

export function useProducts(filters?: ProductFilters) {
  const params = new URLSearchParams(filters as Record<string, string>);
  return useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetcher<Product[]>(`/products?${params}`),
  });
}

export function useAddToCart() {
  return useMutation({
    mutationFn: (item: CartItem) =>
      fetcher<CartItem>('/cart', {
        method: 'POST',
        body: JSON.stringify(item),
      }),
  });
}

Componente de Lista de Productos:

// src/components/ProductList.tsx
import { useProducts } from '@/lib/api-client';
import { ProductCard } from './ProductCard';
import { FilterSidebar } from './FilterSidebar';
import { Skeleton } from './ui/skeleton';

export function ProductList() {
  const [filters, setFilters] = useState<ProductFilters>({});
  const { data: products, isLoading, error } = useProducts(filters);

  if (error) {
    return <Alert variant="destructive">{error.message}</Alert>;
  }

  return (
    <div className="flex gap-4">
      <FilterSidebar filters={filters} onFilterChange={setFilters} />
      <div className="flex-1 grid grid-cols-1 md:grid-cols-3 gap-4">
        {isLoading ? (
          Array.from({ length: 6 }).map((_, i) => (
            <Skeleton key={i} className="h-64" />
          ))
        ) : products?.length === 0 ? (
          <EmptyState message="No products found" />
        ) : (
          products?.map(product => (
            <ProductCard key={product.id} product={product} />
          ))
        )}
      </div>
    </div>
  );
}

Límite de Errores:

// src/components/ErrorBoundary.tsx
export class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error: Error | null }
> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="p-4 bg-red-50 border border-red-200 rounded">
          <h2 className="text-lg font-semibold text-red-800">Something went wrong</h2>
          <p className="text-red-600">{this.state.error?.message}</p>
          <Button onClick={() => window.location.reload()} className="mt-2">
            Reload
          </Button>
        </div>
      );
    }

    return this.props.children;
  }
}

Paso 4: El Revisor de Código lo Revisa Todo

Abre una nueva sesión:

Activate Code Reviewer mode.

Review this codebase for:

1. Security vulnerabilities:
   - SQL injection risks
   - XSS vulnerabilities
   - CSRF protection
   - Authentication bypass possibilities

2. TypeScript strict mode compliance:
   - No implicit any
   - Proper type definitions
   - Null/undefined handling

3. Error handling gaps:
   - Uncaught promise rejections
   - Missing try/catch blocks
   - Silent failures

[Paste the code from Steps 1-3]

Output a report with severity ratings (Critical, High, Medium, Low) and specific fixes.

Entregables esperados:

Informe de Seguridad:

## Problemas Críticos

### 1. Inyección SQL en Búsqueda de Productos
**Ubicación:** `src/controllers/products.controller.ts:24`
**Problema:** Entrada de usuario concatenada directamente en la consulta SQL

typescript
// VULNERABLE
const query = SELECT * FROM products WHERE name LIKE '%${search}%';

typescript

Solución: Usar consultas parametrizadas

const query = 'SELECT * FROM products WHERE name LIKE $1';
await db.query(query, [`%${search}%`]);

Problemas de Alta Gravedad

2. Protección CSRF Faltante

Ubicación: src/index.ts
Problema: No hay middleware CSRF para operaciones que cambian el estado
Solución: Añadir middleware csurf

import csrf from 'csurf';
app.use(csrf({ cookie: true }));

Problemas de Media Gravedad

3. 'Any' Implícito en la Respuesta de la API

Ubicación: src/lib/api-client.ts:8
Problema: Tipo genérico any para la función fetcher
Solución: Añadir restricciones de tipo adecuadas

async function fetcher<T extends Record<string, unknown>>(
  endpoint: string,
  options?: RequestInit
): Promise<T> { ... }

Informe de Seguridad de Tipos:

## Violaciones de TypeScript

1. `products.controller.ts:45` - Anotación de tipo de retorno faltante
2. `auth.middleware.ts:12` - 'Any' implícito en bloque catch
3. `orders.service.ts:78` - Objeto posiblemente indefinido

Ejecuta `tsc --noEmit` para ver la lista completa. Corrige antes de la implementación.

Aplica las correcciones antes de continuar.

Paso 5: El Verificador de Realidad Valida Antes del Envío

Abre una nueva sesión:

Activate Reality Checker mode.

This e-commerce API is ready for production validation.

Run your mandatory reality check process:

1. Verify files exist
2. Cross-reference claimed features with actual code
3. Require screenshot evidence from Playwright tests
4. Review test-results.json for performance metrics

Project URL: http://localhost:3000
Test results: ./public/qa-screenshots/test-results.json

Output: PASS or NEEDS WORK with specific blocking issues.

Entregables esperados:

Comandos de Verificación de Realidad:

# 1. Verifica que los archivos existan
ls -la src/controllers/ src/services/ src/routes/
ls -la src/components/ src/lib/

# 2. Revisa características implementadas
grep -r "jwt\|jsonwebtoken" . --include="*.ts" || echo "NO JWT FOUND"
grep -r "bcrypt\|argon2" . --include="*.ts" || echo "NO PASSWORD HASHING FOUND"
grep -r "rateLimit\|express-rate-limit" . --include="*.ts" || echo "NO RATE LIMITING FOUND"

# 3. Ejecuta capturas de pantalla con Playwright
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

# 4. Revisa resultados de pruebas
cat public/qa-screenshots/test-results.json

Informe de Validación:

## Resultados de la Verificación de Realidad

### Verificación de Archivos: PASÓ
- Todos los archivos de controlador presentes
- Todos los archivos de componentes presentes

### Verificación de Características: NECESITA TRABAJO
- Autenticación JWT: ENCONTRADO
- Hash de contraseña: ENCONTRADO
- Limitación de velocidad: NO ENCONTRADO (bloqueante)

### Evidencia de Capturas de Pantalla: NECESITA TRABAJO
- Diseño de escritorio: PASÓ
- Diseño de tablet: PASÓ
- Diseño móvil: FALLÓ (cuadrícula de productos rota a 375px)

### Métricas de Rendimiento: NECESITA TRABAJO
- Tiempo de carga promedio: 2.3s (objetivo: <1s)
- Errores de consola: 3 (objetivo: 0)
- Solicitudes de red fallidas: 1 (objetivo: 0)

## Estado Final: NECESITA TRABAJO

### Problemas Bloqueantes:
1. Limitación de velocidad no implementada
2. Diseño móvil roto en la lista de productos
3. 3 errores de consola por corregir
4. El tiempo de carga supera el objetivo de 1s

### No Bloqueantes:
- Añadir esqueletos de carga al historial de pedidos
- Mejorar los mensajes de error

Corrige los problemas bloqueantes y vuelve a ejecutar el Verificador de Realidad.

Resumen del Flujo de Trabajo

┌─────────────────────────────────────────────────────────────────┐
│  Arquitecto de Backend                                          │
│  → Especificación OpenAPI, esquema de base de datos, estructura │
│    de carpetas                                                  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Optimizador de Base de Datos                                   │
│  → Recomendaciones de índices, tablas faltantes, restricciones  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Desarrollador Frontend                                         │
│  → Componentes React, cliente API, manejo de errores            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Revisor de Código                                              │
│  → Auditoría de seguridad, seguridad de tipos, brechas de manejo│
│    de errores                                                   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Verificador de Realidad                                        │
│  → Validación basada en evidencia, prueba con capturas de       │
│    pantalla, APROBADO/FALLÓ                                    │
└─────────────────────────────────────────────────────────────────┘

Ejecución Paralela de Agentes (Avanzado)

Ejecuta agentes en paralelo para reducir el tiempo total:

# Terminal 1: Arquitecto de Backend
claude "Activate Backend Architect. Design e-commerce API..."

# Terminal 2: Optimizador de Base de Datos (espera la salida del esquema)
claude "Activate Database Optimizer. Review this schema..."

# Terminal 3: Desarrollador Frontend (espera la especificación de la API)
claude "Activate Frontend Developer. Build React dashboard..."

# Terminal 4: Revisor de Código (espera el código)
claude "Activate Code Reviewer. Review this codebase..."

# Todas las terminales: Verificador de Realidad (validación final)
claude "Activate Reality Checker. Run mandatory checks..."

Con la ejecución paralela, puedes completar el flujo de trabajo en 2-4 horas en lugar de 6-8 horas.

Lo que Construiste

Entregable	Agente	Resultado
Diseño de API	Arquitecto de Backend	Especificación OpenAPI, esquema de base de datos, estructura de carpetas
Optimización de Esquema	Optimizador de Base de Datos	Recomendaciones de índices, tablas adicionales, restricciones
Frontend	Desarrollador Frontend	Componentes React, cliente API, límites de errores
Auditoría de Seguridad	Revisor de Código	Informe de vulnerabilidades, correcciones de seguridad de tipos
Validación Final	Verificador de Realidad	Evidencia de capturas de pantalla, certificación APROBADO/FALLÓ

---

Próximos Pasos

Desplegar la API:

• Configurar PostgreSQL de producción con pool de conexiones
• Configurar variables de entorno para secretos
• Añadir endpoints de verificación de salud
• Configurar monitoreo (Prometheus, Grafana)

Extender el flujo de trabajo:

• Añadir agente de Benchmarking de Rendimiento para pruebas de carga
• Añadir agente de Escritor Técnico para documentación
• Añadir agente de Automatización DevOps para pipeline CI/CD

Reutilizar el patrón:

• Guardar las instrucciones como plantillas
• Crear un script de flujo de trabajo que encadene sesiones de agentes
• Compartir con tu equipo

Cinco agentes especializados. Una API completa. Sin consejos genéricos.

Ese es el poder de la especialización. Cada agente conoce su dominio. Cada agente tiene listas de verificación. Cada agente produce entregables específicos.

Tu turno: elige un proyecto, activa los agentes y entrega más rápido.

Conclusiones Clave

• Los agentes especializados superan a los asistentes genéricos — Cada agente tiene experiencia en un dominio, listas de verificación y entregables específicos
• El flujo de trabajo secuencial garantiza la calidad — El Arquitecto de Backend diseña, el Optimizador de Base de Datos revisa, el Desarrollador Frontend construye, el Revisor de Código audita, el Verificador de Realidad valida
• La aprobación basada en evidencia previene errores — El Verificador de Realidad exige pruebas con capturas de pantalla, resultados de grep y métricas de rendimiento antes de la certificación de APROBADO
• La ejecución paralela reduce el tiempo total — Ejecuta 4 terminales simultáneamente para completar en 2-4 horas en lugar de 6-8 horas
• Guarda las instrucciones como plantillas — Reutiliza las mismas activaciones de agentes para resultados consistentes en todos los proyectos

---

Preguntas Frecuentes

¿Qué son los agentes de IA para desarrolladores?

Los agentes de IA son asistentes de IA especializados con experiencia en un dominio. A diferencia de los chatbots genéricos, agentes como el Arquitecto de Backend o el Revisor de Código tienen listas de verificación específicas y producen entregables consistentes.

¿Cómo instalo agentes de The Agency?

Clona el repositorio en github.com/msitarzewski/agency-agents, luego copia los archivos .md a ~/.claude/agents/ para Claude Code o usa el script de instalación para otras herramientas.

¿Qué es el agente Verificador de Realidad?

El Verificador de Realidad es un agente de QA basado en evidencia que se niega a aprobar el trabajo sin pruebas. Requiere capturas de pantalla, resultados de grep y métricas de rendimiento antes de otorgar la certificación de APROBADO.

¿Puedo ejecutar varios agentes en paralelo?

Sí. Abre varias terminales y activa diferentes agentes en cada una. Pasa los entregables copiando la salida o usando la memoria de MCP para transferencias automáticas.

¿Cómo paso el contexto entre agentes?

Copia la salida de un agente y pégala como entrada para el siguiente. Para transferencias automáticas, usa la memoria de MCP para almacenar los entregables que el siguiente agente puede recordar.

¿Qué pasa si un agente dice "NECESITA TRABAJO"?

Corrige los problemas bloqueantes que el agente identificó, luego vuelve a ejecutar el agente. El Verificador de Realidad lista específicamente lo que necesita ser corregido antes de la certificación de APROBADO.

¿Necesito los 5 agentes para cada proyecto?

No. Comienza con el Arquitecto de Backend y el Revisor de Código para proyectos de API. Añade el Optimizador de Base de Datos para esquemas complejos, el Desarrollador Frontend para trabajo de UI y el Verificador de Realidad antes de la implementación.