Comment Configurer 5 Agents IA pour Créer une API Complète (Des Spécifications aux Tests)

Arrêtez d'utiliser un assistant IA générique pour tout. Mettez en place 5 agents spécialisés pour construire une API complète : l'Architecte Backend conçoit le système, l'Optimiseur de Base de Données examine le schéma, le Développeur Frontend construit le client, le Relecteur de Code vérifie la sécurité, et le Vérificateur de Réalité valide avant l'expédition.

Essayez Apidog dès aujourd'hui

Vous devez construire une API rapidement. La tentation : demander à une seule IA de tout faire. Elle concevra la base de données, écrira les points d'accès, construira le frontend, révisera le code et testera le résultat.

Voici ce qui se passe : la base de données manque d'index, les points d'accès ont des failles de sécurité, le frontend ignore les états d'erreur, et les tests se résument à « ça me semble bon ».

Les agents spécialisés corrigent cela. Chaque agent connaît son domaine. Chaque agent a des listes de contrôle. Chaque agent produit des livrables spécifiques. L'Architecte Backend pense à l'échelle. L'Optimiseur de Base de Données repère les index manquants. Le Relecteur de Code trouve les vulnérabilités. Le Vérificateur de Réalité exige des preuves.

Dans ce tutoriel, vous allez configurer 5 agents de la collection Agency et exécuter un workflow complet de construction d'API. Vous intégrerez Apidog pour les tests et la documentation d'API, garantissant que vos points d'accès sont validés par rapport aux spécifications OpenAPI avant le déploiement.

Les 5 agents que vous utiliserez

Agent	Division	Responsabilité
Architecte Backend	Ingénierie	Conception d'API, schéma de base de données, authentification
Optimiseur de Base de Données	Ingénierie	Recommandations d'index, optimisation des requêtes
Développeur Frontend	Ingénierie	Composants React, client API, gestion d'état
Relecteur de Code	Ingénierie	Audit de sécurité, sûreté des types, gestion des erreurs
Vérificateur de Réalité	Tests	Validation basée sur des preuves, preuve par capture d'écran

Installez les agents :

# Clone The Agency repo
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# Copiez les agents dans 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/

Étape 1 : L'Architecte Backend conçoit le système

Démarrez une nouvelle session Claude Code :

Activez le mode Architecte Backend.

Concevez une API REST pour une plateforme e-commerce avec :
- Authentification utilisateur (JWT avec jetons de rafraîchissement)
- Catalogue de produits avec catégories et filtrage
- Gestion du panier d'achat
- Traitement des commandes avec suivi de statut
- Intégration de webhook de paiement

Sortie :
1. Spécification OpenAPI 3.0
2. Schéma de base de données PostgreSQL avec relations
3. Structure des dossiers du projet (Express.js + TypeScript)
4. Diagramme de flux d'authentification

Livrables attendus :

Spécification OpenAPI (partielle) :

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 }

Schéma de base de données :

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

Structure des dossiers :

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

Enregistrez la sortie. Vous la transmettrez à l'agent suivant.

Étape 2 : L'Optimiseur de Base de Données examine le schéma

Ouvrez une nouvelle session :

Activez le mode Optimiseur de Base de Données.

Examinez ce schéma PostgreSQL pour une API e-commerce :

[Collez le schéma de l'Étape 1]

Vérifiez les points suivants :
1. Index manquants sur les clés étrangères et les colonnes fréquemment interrogées
2. Performances des requêtes sur la recherche de produits (nom, catégorie, fourchette de prix)
3. Contraintes appropriées pour l'intégrité des données
4. Tables manquantes pour les fonctionnalités e-commerce courantes (avis, listes de souhaits)
5. Modèles de suppression logique pour les pistes d'audit

Produisez des instructions ALTER TABLE spécifiques et de nouvelles définitions de table.

Livrables attendus :

Recommandations d'index :

-- Ajoutez des index sur les clés étrangères
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);

-- Ajoutez un index pour la recherche de produits
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;

-- Ajoutez un index composite pour le filtrage par catégorie
CREATE INDEX idx_products_category_price ON products(category_id, price);

Tables manquantes :

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

Contraintes à ajouter :

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

-- Colonne de suppression logique
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;

Appliquez ces recommandations à votre schéma.

Étape 3 : Le Développeur Frontend construit le client

Ouvrez une nouvelle session :

Activez le mode Développeur Frontend.

Construisez un tableau de bord React pour cette API e-commerce :

[Collez la spécification OpenAPI de l'Étape 1]

Exigences :
- TypeScript en mode strict
- React Query pour la gestion d'état côté serveur
- Liste de produits avec filtres (catégorie, fourchette de prix, recherche)
- Panier d'achat avec mises à jour en temps réel
- Historique des commandes avec suivi de statut
- Gestion appropriée des erreurs et des états de chargement
- Conception réactive (mobile, tablette, ordinateur de bureau)

Sortie :
1. Configuration du projet (Vite + React + TypeScript)
2. Client API avec hooks React Query
3. Composants principaux (ProductList, ProductCard, Cart, OrderHistory)
4. Limite d'erreur (Error Boundary) et squelettes de chargement

Livrables attendus :

Client 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),
      }),
  });
}

Composant Liste de Produits :

// 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 d'erreur (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;
  }
}

Étape 4 : Le Relecteur de Code vérifie tout

Ouvrez une nouvelle session :

Activez le mode Relecteur de Code.

Examinez cette base de code pour :

1. Vulnérabilités de sécurité :
   - Risques d'injection SQL
   - Vulnérabilités XSS
   - Protection CSRF
   - Possibilités de contournement de l'authentification

2. Conformité au mode strict de TypeScript :
   - Pas de "any" implicite
   - Définitions de type appropriées
   - Gestion des valeurs null/undefined

3. Lacunes dans la gestion des erreurs :
   - Rejets de promesses non interceptés
   - Blocs try/catch manquants
   - Échecs silencieux

[Collez le code des Étapes 1-3]

Produisez un rapport avec des niveaux de gravité (Critique, Élevé, Moyen, Faible) et des corrections spécifiques.

Livrables attendus :

Rapport de sécurité :

## Problèmes critiques

### 1. Injection SQL dans la recherche de produits
**Emplacement :** `src/controllers/products.controller.ts:24`
**Problème :** Entrée utilisateur concaténée directement dans la requête SQL

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

Correction : Utilisez des requêtes paramétrées

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

Problèmes élevés

2. Protection CSRF manquante

Emplacement : src/index.ts
Problème : Aucun middleware CSRF pour les opérations modifiant l'état

Correction : Ajoutez le middleware csurf

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

Problèmes moyens

3. Type "any" implicite dans la réponse API

Emplacement : src/lib/api-client.ts:8
Problème : Type générique any pour la fonction fetcher

Correction : Ajoutez des contraintes de type appropriées

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

Rapport de sûreté des types :

## Violations TypeScript

1. `products.controller.ts:45` - Annotation de type de retour manquante
2. `auth.middleware.ts:12` - Type "any" implicite dans le bloc catch
3. `orders.service.ts:78` - Objet potentiellement indéfini

Exécutez `tsc --noEmit` pour voir la liste complète. Corrigez avant le déploiement.

Appliquez les correctifs avant de continuer.

Étape 5 : Le Vérificateur de Réalité valide avant l'expédition

Ouvrez une nouvelle session :

Activez le mode Vérificateur de Réalité.

Cette API e-commerce est prête pour la validation en production.

Exécutez votre processus de vérification de la réalité obligatoire :

1. Vérifiez l'existence des fichiers
2. Faites le recoupement entre les fonctionnalités annoncées et le code réel
3. Exigez des preuves par capture d'écran des tests Playwright
4. Examinez le fichier test-results.json pour les métriques de performance

URL du projet : http://localhost:3000
Résultats des tests : ./public/qa-screenshots/test-results.json

Sortie : PASS ou NEEDS WORK avec les problèmes bloquants spécifiques.

Livrables attendus :

Commandes de vérification de la réalité :

# 1. Vérifiez l'existence des fichiers
ls -la src/controllers/ src/services/ src/routes/
ls -la src/components/ src/lib/

# 2. Recoupez les fonctionnalités annoncées
grep -r "jwt\|jsonwebtoken" . --include="*.ts" || echo "AUCUN JWT TROUVÉ"
grep -r "bcrypt\|argon2" . --include="*.ts" || echo "AUCUN HACHAGE DE MOT DE PASSE TROUVÉ"
grep -r "rateLimit\|express-rate-limit" . --include="*.ts" || echo "AUCUNE LIMITATION DE DÉBIT TROUVÉE"

# 3. Exécutez la capture d'écran Playwright
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

# 4. Examinez les résultats des tests
cat public/qa-screenshots/test-results.json

Rapport de validation :

## Résultats de la vérification de la réalité

### Vérification des fichiers : RÉUSSI
- Tous les fichiers contrôleur présents
- Tous les fichiers composants présents

### Vérification des fonctionnalités : NÉCESSITE DU TRAVAIL
- Authentification JWT : TROUVÉE
- Hachage de mot de passe : TROUVÉ
- Limitation de débit : NON TROUVÉE (bloquant)

### Preuves par capture d'écran : NÉCESSITE DU TRAVAIL
- Disposition sur ordinateur de bureau : RÉUSSI
- Disposition sur tablette : RÉUSSI
- Disposition sur mobile : ÉCHEC (grille de produits cassée à 375px)

### Métriques de performance : NÉCESSITE DU TRAVAIL
- Temps de chargement moyen : 2.3s (cible : <1s)
- Erreurs de console : 3 (cible : 0)
- Requêtes réseau échouées : 1 (cible : 0)

## Statut final : NÉCESSITE DU TRAVAIL

### Problèmes bloquants :
1. Limitation de débit non implémentée
2. Disposition mobile cassée sur la liste de produits
3. 3 erreurs de console à corriger
4. Le temps de chargement dépasse la cible de 1s

### Non-bloquant :
- Ajoutez des squelettes de chargement à l'historique des commandes
- Améliorez les messages d'erreur

Corrigez les problèmes bloquants et exécutez à nouveau le Vérificateur de Réalité.

Résumé du flux de travail

┌─────────────────────────────────────────────────────────────────┐
│  Architecte Backend                                             │
│  → Spécification OpenAPI, schéma de base de données, structure des dossiers              │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Optimiseur de Base de Données                                            │
│  → Recommandations d'index, tables manquantes, contraintes           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Développeur Frontend                                             │
│  → Composants React, client API, gestion des erreurs                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Relecteur de Code                                                  │
│  → Audit de sécurité, sûreté des types, lacunes de gestion des erreurs             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  Vérificateur de Réalité                                                │
│  → Validation basée sur des preuves, preuve par capture d'écran, RÉUSSI/ÉCHEC       │
└─────────────────────────────────────────────────────────────────┘

Exécution parallèle des agents (Avancé)

Exécutez les agents en parallèle pour accélérer la livraison :

# Terminal 1 : Architecte Backend
claude "Activez l'Architecte Backend. Concevez une API e-commerce..."

# Terminal 2 : Optimiseur de Base de Données (attendre la sortie du schéma)
claude "Activez l'Optimiseur de Base de Données. Examinez ce schéma..."

# Terminal 3 : Développeur Frontend (attendre la spécification API)
claude "Activez le Développeur Frontend. Construisez un tableau de bord React..."

# Terminal 4 : Relecteur de Code (attendre le code)
claude "Activez le Relecteur de Code. Examinez cette base de code..."

# Tous les terminaux : Vérificateur de Réalité (validation finale)
claude "Activez le Vérificateur de Réalité. Exécutez les vérifications obligatoires..."

Avec l'exécution parallèle, vous pouvez compléter ce workflow en 2-4 heures au lieu de 6-8 heures.

Ce que vous avez construit

Livrable	Agent	Sortie
Conception API	Architecte Backend	Spécification OpenAPI, schéma de base de données, structure des dossiers
Optimisation du schéma	Optimiseur de Base de Données	Recommandations d'index, tables supplémentaires, contraintes
Frontend	Développeur Frontend	Composants React, client API, limites d'erreur
Audit de sécurité	Relecteur de Code	Rapport de vulnérabilité, corrections de sûreté des types
Validation finale	Vérificateur de Réalité	Preuve par capture d'écran, certification RÉUSSI/ÉCHEC

---

Prochaines étapes

• Déployer l'API :
  • Configurez PostgreSQL en production avec un pool de connexions
  • Configurez les variables d'environnement pour les secrets
  • Ajoutez des points d'accès de vérification de l'état de santé (health check)
  • Mettez en place la surveillance (Prometheus, Grafana)

Étendre le flux de travail :

• Ajoutez un agent Benchmarker de Performance pour les tests de charge
• Ajoutez un agent Rédacteur Technique pour la documentation
• Ajoutez un agent Automatisateur DevOps pour le pipeline CI/CD

Réutiliser le modèle :

• Enregistrez les invites comme modèles
• Créez un script de flux de travail qui enchaîne les sessions d'agents
• Partagez avec votre équipe

Cinq agents spécialisés. Une API complète. Pas de conseils génériques.

C'est la puissance de la spécialisation. Chaque agent connaît son domaine. Chaque agent a des listes de contrôle. Chaque agent produit des livrables spécifiques.

À votre tour : choisissez un projet, activez les agents et expédiez plus rapidement.

Points clés à retenir

• Les agents spécialisés surpassent les assistants génériques — Chaque agent possède une expertise de domaine, des listes de contrôle et des livrables spécifiques
• Un flux de travail séquentiel garantit la qualité — L'Architecte Backend conçoit, l'Optimiseur de Base de Données examine, le Développeur Frontend construit, le Relecteur de Code audite, le Vérificateur de Réalité valide
• L'approbation basée sur des preuves prévient les bugs — Le Vérificateur de Réalité exige des preuves par capture d'écran, des résultats grep et des métriques de performance avant la certification RÉUSSI
• L'exécution parallèle réduit le temps total — Exécutez 4 terminaux simultanément pour terminer en 2-4 heures au lieu de 6-8 heures
• Enregistrez les invites comme modèles — Réutilisez les mêmes activations d'agents pour des résultats cohérents entre les projets

---

FAQ

Que sont les agents IA pour les développeurs ?

Les agents IA sont des assistants IA spécialisés dotés d'une expertise de domaine. Contrairement aux chatbots génériques, des agents comme l'Architecte Backend ou le Relecteur de Code ont des listes de contrôle spécifiques et produisent des livrables cohérents.

Comment installer les agents de The Agency ?

Clonez le dépôt sur github.com/msitarzewski/agency-agents, puis copiez les fichiers .md dans ~/.claude/agents/ pour Claude Code ou utilisez le script d'installation pour d'autres outils.

Qu'est-ce que l'agent Vérificateur de Réalité ?

Le Vérificateur de Réalité est un agent d'assurance qualité basé sur des preuves qui refuse d'approuver un travail sans preuve. Il exige des captures d'écran, des résultats grep et des métriques de performance avant de délivrer la certification RÉUSSI.

Puis-je exécuter plusieurs agents en parallèle ?

Oui. Ouvrez plusieurs terminaux et activez différents agents dans chacun. Transmettez les livrables en copiant la sortie ou en utilisant la mémoire MCP pour des transferts automatiques.

Comment passer le contexte entre les agents ?

Copiez la sortie d'un agent et collez-la comme entrée pour le suivant. Pour des transferts automatiques, utilisez la mémoire MCP pour stocker les livrables que l'agent suivant pourra rappeler.

Que faire si un agent indique NÉCESSITE DU TRAVAIL ?

Corrigez les problèmes bloquants identifiés par l'agent, puis réexécutez l'agent. Le Vérificateur de Réalité liste spécifiquement ce qui doit être corrigé avant la certification RÉUSSI.

Ai-je besoin des 5 agents pour chaque projet ?

Non. Commencez avec l'Architecte Backend et le Relecteur de Code pour les projets API. Ajoutez l'Optimiseur de Base de Données pour les schémas complexes, le Développeur Frontend pour le travail d'interface utilisateur, et le Vérificateur de Réalité avant l'expédition.