Como Configurar 5 Agentes de IA para Criar uma API Completa (Da Especificação ao Teste)

Pare de usar um assistente de IA genérico para tudo. Configure 5 agentes especializados para construir uma API completa: Arquiteto de Backend projeta o sistema, Otimizador de Banco de Dados revisa o esquema, Desenvolvedor Frontend constrói o cliente, Revisor de Código verifica a segurança e Verificador de Realidade valida antes do lançamento.

Experimente o Apidog hoje

Você precisa construir uma API rapidamente. A tentação: pedir a uma única IA para fazer tudo. Ela projetará o banco de dados, escreverá os endpoints, construirá o frontend, revisará o código e testará o resultado.

Eis o que acontece: o banco de dados carece de índices, os endpoints têm falhas de segurança, o frontend ignora estados de erro e os testes consistem em "parece bom para mim".

Agentes especializados corrigem isso. Cada agente conhece seu domínio. Cada agente possui listas de verificação. Cada agente produz entregáveis específicos. O Arquiteto de Backend pensa em escala. O Otimizador de Banco de Dados identifica índices ausentes. O Revisor de Código encontra vulnerabilidades. O Verificador de Realidade exige provas.

Neste tutorial, você configurará 5 agentes da coleção Agency e executará um fluxo de trabalho completo de construção de API. Você integrará com o Apidog para teste e documentação de API, garantindo que seus endpoints sejam validados em relação às especificações OpenAPI antes da implantação.

Os 5 Agentes Que Você Usará

Agente	Divisão	Responsabilidade
Arquiteto de Backend	Engenharia	Design de API, esquema de banco de dados, autenticação
Otimizador de Banco de Dados	Engenharia	Recomendações de índice, otimização de consulta
Desenvolvedor Frontend	Engenharia	Componentes React, cliente API, gerenciamento de estado
Revisor de Código	Engenharia	Auditoria de segurança, segurança de tipo, tratamento de erros
Verificador de Realidade	Testes	Validação baseada em evidências, prova por captura de tela

Instale os agentes:

# Clone o repositório Agency
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# Copie os agentes para 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/

Passo 1: O Arquiteto de Backend Projeta o Sistema

Inicie uma nova sessão do 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

Entregáveis esperados:

Especificação 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 do Banco de Dados:

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()
);

Estrutura de Pastas:

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

Salve a saída. Você a passará para o próximo agente.

Passo 2: O Otimizador de Banco de Dados Revisa o Esquema

Abra uma nova sessão:

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.

Entregáveis esperados:

Recomendações de Índice:

-- 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);

Tabelas Ausentes:

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)
);

Restrições a Adicionar:

-- 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;

Aplique essas recomendações ao seu esquema.

Passo 3: O Desenvolvedor Frontend Constrói o Cliente

Abra uma nova sessão:

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

Entregáveis 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 Produtos:

// 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>
  );
}

Limite de Erro (Error Boundary):

// 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;
  }
}

Passo 4: O Revisor de Código Verifica Tudo

Abra uma nova sessão:

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.

Entregáveis esperados:

Relatório de Segurança:

## Problemas Críticos

### 1. Injeção de SQL na Pesquisa de Produtos
**Localização:** `src/controllers/products.controller.ts:24`
**Problema:** Entrada do usuário concatenada diretamente na consulta SQL

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

**Correção:** Use consultas parametrizadas

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

## Problemas de Alta Gravidade

### 2. Proteção CSRF Ausente
**Localização:** `src/index.ts`
**Problema:** Nenhum middleware CSRF para operações que alteram o estado  
**Correção:** Adicione o middleware csurf

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

## Problemas de Média Gravidade

### 3. 'any' Implícito na Resposta da API
**Localização:** `src/lib/api-client.ts:8`  
**Problema:** Tipo genérico `any` para a função fetcher  
**Correção:** Adicione restrições de tipo apropriadas

typescript
async function fetcher>(
endpoint: string,
options?: RequestInit
): Promise { ... }

**Relatório de Segurança de Tipo:**

markdown

Violações do TypeScript

1. products.controller.ts:45 - Anotação de tipo de retorno ausente
2. auth.middleware.ts:12 - 'any' implícito no bloco catch
3. orders.service.ts:78 - Objeto possivelmente indefinido

Execute tsc --noEmit para ver a lista completa. Corrija antes da implantação.

Aplique as correções antes de prosseguir.

## Passo 5: O Verificador de Realidade Valida Antes do Lançamento

Abra uma nova sessão:

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

**Entregáveis esperados:**

**Comandos de Verificação de Realidade:**

bash

1. Verificar se os arquivos existem

ls -la src/controllers/ src/services/ src/routes/
ls -la src/components/ src/lib/

2. Fazer referência cruzada dos recursos declarados

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. Executar captura de tela do Playwright

npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

4. Revisar resultados dos testes

cat public/qa-screenshots/test-results.json

**Relatório de Validação:**

markdown

Resultados da Verificação de Realidade

Verificação de Arquivos: APROVADO

• Todos os arquivos de controlador presentes
• Todos os arquivos de componente presentes

Verificação de Recursos: NECESSITA DE TRABALHO

• Autenticação JWT: ENCONTRADA
• Hashing de senha: ENCONTRADO
• Limitação de taxa (Rate limiting): NÃO ENCONTRADA (bloqueante)

Evidência de Captura de Tela: NECESSITA DE TRABALHO

• Layout de desktop: APROVADO
• Layout de tablet: APROVADO
• Layout móvel: FALHA (grade de produtos quebrada em 375px)

Métricas de Desempenho: NECESSITA DE TRABALHO

• Tempo médio de carregamento: 2.3s (meta: <1s)
• Erros de console: 3 (meta: 0)
• Requisições de rede falhas: 1 (meta: 0)

Status Final: NECESSITA DE TRABALHO

Problemas Bloqueantes:

1. Limitação de taxa não implementada
2. Layout móvel quebrado na lista de produtos
3. 3 erros de console para corrigir
4. Tempo de carregamento excede a meta de 1s

Não Bloqueantes:

• Adicionar esqueletos de carregamento ao histórico de pedidos
• Melhorar mensagens de erro

Corrija os problemas bloqueantes e execute o Verificador de Realidade novamente.

## Resumo do Fluxo de Trabalho

plaintext
┌─────────────────────────────────────────────────────────────────┐
│ Arquiteto de Backend │
│ → Especificação OpenAPI, esquema de banco de dados, estrutura de pastas │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Otimizador de Banco de Dados │
│ → Recomendações de índice, tabelas ausentes, restrições │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Desenvolvedor Frontend │
│ → Componentes React, cliente API, tratamento de erros │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Revisor de Código │
│ → Auditoria de segurança, segurança de tipo, lacunas no tratamento de erros│
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Verificador de Realidade │
│ → Validação baseada em evidências, prova por captura de tela, APROVADO/REPROVADO│
└─────────────────────────────────────────────────────────────────┘

## Execução Paralela de Agentes (Avançado)

Execute agentes em paralelo para reduzir o tempo total:

bash

Terminal 1: Arquiteto de Backend

claude "Ativar modo Arquiteto de Backend. Projetar API de e-commerce..."

Terminal 2: Otimizador de Banco de Dados (aguardar saída do esquema)

claude "Ativar modo Otimizador de Banco de Dados. Revisar este esquema..."

Terminal 3: Desenvolvedor Frontend (aguardar especificação da API)

claude "Ativar modo Desenvolvedor Frontend. Construir painel React..."

Terminal 4: Revisor de Código (aguardar código)

claude "Ativar modo Revisor de Código. Revisar esta base de código..."

Todos os terminais: Verificador de Realidade (validação final)

claude "Ativar modo Verificador de Realidade. Executar verificações obrigatórias..."

Com a execução paralela, você pode completar o fluxo de trabalho em 2-4 horas, em vez de 6-8 horas.

## O Que Você Construiu

<table>
<thead>
<tr>
<th>Entregável</th>
<th>Agente</th>
<th>Saída</th>
</tr>
</thead>
<tbody>
<tr>
<td>Design da API</td>
<td>Arquiteto de Backend</td>
<td>Especificação OpenAPI, esquema de banco de dados, estrutura de pastas</td>
</tr>
<tr>
<td>Otimização do Esquema</td>
<td>Otimizador de Banco de Dados</td>
<td>Recomendações de índice, tabelas adicionais, restrições</td>
</tr>
<tr>
<td>Frontend</td>
<td>Desenvolvedor Frontend</td>
<td>Componentes React, cliente API, limites de erro (error boundaries)</td>
</tr>
<tr>
<td>Auditoria de Segurança</td>
<td>Revisor de Código</td>
<td>Relatório de vulnerabilidades, correções de segurança de tipo</td>
</tr>
<tr>
<td>Validação Final</td>
<td>Verificador de Realidade</td>
<td>Evidência de captura de tela, certificação APROVADO/REPROVADO</td>
</tr>
</tbody>
</table>

---

## Próximos Passos

- Configure o PostgreSQL de produção com pooling de conexão
- Configure variáveis de ambiente para segredos
- Adicione endpoints de verificação de saúde (health check)
- Configure o monitoramento (Prometheus, Grafana)

**Estenda o fluxo de trabalho:**

- Adicione o agente Avaliador de Desempenho para testes de carga
- Adicione o agente Redator Técnico para documentação
- Adicione o agente Automatizador DevOps para pipeline de CI/CD

**Reutilize o padrão:**

- Salve os prompts como modelos
- Crie um script de fluxo de trabalho que encadeie sessões de agentes
- Compartilhe com sua equipe

**Cinco agentes especializados. Uma API completa. Sem conselhos genéricos.**

Esse é o poder da especialização. Cada agente conhece seu domínio. Cada agente possui listas de verificação. Cada agente produz entregáveis específicos.

Sua vez: escolha um projeto, ative os agentes e lance mais rápido.

## Principais Conclusões

- **Agentes especializados superam assistentes genéricos** — Cada agente possui expertise de domínio, listas de verificação e entregáveis específicos
- **Fluxo de trabalho sequencial garante qualidade** — Arquiteto de Backend projeta, Otimizador de Banco de Dados revisa, Desenvolvedor Frontend constrói, Revisor de Código audita, Verificador de Realidade valida
- **Aprovação baseada em evidências previne bugs** — O Verificador de Realidade exige prova por captura de tela, resultados de grep e métricas de desempenho antes da certificação APROVADO
- **Execução paralela reduz o tempo total** — Execute 4 terminais simultaneamente para concluir em 2-4 horas em vez de 6-8 horas
- **Salve prompts como modelos** — Reutilize as mesmas ativações de agente para resultados consistentes em todos os projetos

---

## FAQ

**O que são agentes de IA para desenvolvedores?**  
Agentes de IA são assistentes de IA especializados com expertise de domínio. Diferente de chatbots genéricos, agentes como Arquiteto de Backend ou Revisor de Código possuem listas de verificação específicas e produzem entregáveis consistentes.

**Como instalo agentes do The Agency?**  
Clone o repositório em `github.com/msitarzewski/agency-agents`, então copie os arquivos `.md` para `~/.claude/agents/` para Claude Code ou use o script de instalação para outras ferramentas.

**O que é o agente Verificador de Realidade?**  
O Verificador de Realidade é um agente de QA baseado em evidências que se recusa a aprovar o trabalho sem prova. Ele exige capturas de tela, resultados de grep e métricas de desempenho antes de conceder a certificação APROVADO.

**Posso executar múltiplos agentes em paralelo?**  
Sim. Abra múltiplos terminais e ative diferentes agentes em cada um. Passe os entregáveis copiando a saída ou usando a memória MCP para transferências automáticas.

**Como passo contexto entre agentes?**  
Copie a saída de um agente e cole-a como entrada para o próximo. Para transferências automáticas, use a memória MCP para armazenar entregáveis que o próximo agente pode recuperar.

**E se um agente disser "NECESSITA DE TRABALHO"?**  
Corrija os problemas bloqueantes que o agente identificou e, em seguida, execute o agente novamente. O Verificador de Realidade lista especificamente o que precisa ser corrigido antes da certificação APROVADO.

**Preciso de todos os 5 agentes para cada projeto?**  
Não. Comece com o Arquiteto de Backend e o Revisor de Código para projetos de API. Adicione o Otimizador de Banco de Dados para esquemas complexos, o Desenvolvedor Frontend para trabalho de UI e o Verificador de Realidade antes do lançamento.