DEV Community

Cover image for Comment créer des workflows Claude automatisés
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment créer des workflows Claude automatisés

Il y a une phrase qui résume bien le codage agentique : l’objectif n’est pas une meilleure invite, c’est un flux de travail qui s’exécute sans que vous ayez à le surveiller. Si vous utilisez Claude comme une simple fenêtre de chat, votre débit reste limité par votre attention. Pour gagner en production, construisez plutôt des workflows déclenchés automatiquement, capables d’exécuter une tâche, de vérifier leurs résultats et de demander une intervention humaine uniquement lorsqu’une décision est nécessaire.

Essayez Apidog aujourd’hui

TL;DR

Un workflow Claude autonome doit contenir cinq éléments :

  1. une spécification écrite et précise ;
  2. une exécution headless, par exemple avec claude -p ;
  3. une porte de vérification déterministe : tests, typage, validation de schéma, tests de contrat ;
  4. des garde-fous : permissions limitées, nombre d’itérations borné, plafond de coûts, logs, arrêt d’urgence ;
  5. un transfert clair vers un humain : notification, PR de brouillon ou alerte d’échec.

Le mode headless de Claude Code, le SDK Claude Agent, les hooks et un ordonnanceur comme cron ou launchd permettent de mettre ces pièces en place. Le risque n’est pas l’agent lui-même, mais l’exécution non supervisée sans porte de validation ni limites.

Pourquoi « s’exécuter sans vous » est le vrai objectif

Le chat supervisé a un plafond simple : vous.

À chaque itération, Claude attend que vous lisiez la sortie, décidiez de la suite, reformuliez une instruction, puis relanciez. Le modèle peut générer rapidement, mais le workflow reste bloqué par vos changements de contexte.

Un workflow non supervisé retire ce goulot d’étranglement :

  • l’agent exécute une tâche ;
  • un script vérifie le résultat ;
  • les échecs sont renvoyés automatiquement à l’agent ;
  • un humain intervient seulement à la fin ou en cas de blocage.

Le gain principal n’est pas seulement la vitesse, mais le parallélisme. Une fois qu’un workflow peut tourner sans supervision, vous augmentez votre capacité en ajoutant d’autres workflows, pas en tapant plus vite. C’est le même principe que dans les flux de travail dynamiques de Claude Code, où une session peut se déployer en plusieurs agents parallèles.

Mais l’autonomie augmente aussi le risque. Un agent supervisé qui fait une mauvaise modification peut être arrêté lorsque vous lisez le diff. Un agent non supervisé peut valider, passer à l’étape suivante et continuer. Il faut donc passer de l’art de l’invite à la conception d’un système borné, observable et vérifiable. L’article d’Anthropic sur la construction d’agents efficaces va dans le même sens : l’effet de levier vient surtout de l’environnement autour du modèle.

Les cinq éléments d’un workflow Claude autonome

1. Une spécification précise

L’agent doit lire une définition claire de ce qui est attendu au début de chaque exécution.

Mauvais exemple :

Corrige l’API.
Enter fullscreen mode Exit fullscreen mode

Meilleur exemple :

Implémente POST /orders.

Critères d’acceptation :
- retourne 201 lorsque la commande est valide ;
- valide le corps de requête contre le schéma OpenAPI ;
- retourne 422 si customer_id ou items est manquant ;
- retourne une réponse JSON conforme au schéma OrderResponse ;
- tous les tests API doivent passer.
Enter fullscreen mode Exit fullscreen mode

Une bonne spécification sert à la fois d’instruction pour l’agent et de référence pour la porte de vérification.

2. Une exécution headless

Claude doit pouvoir s’exécuter sans interface de chat ni approbation manuelle à chaque action.

Avec Claude Code, la base est le mode non interactif :

claude -p "Implement the orders endpoint per spec.md, then run the test suite" \
  --allowedTools "Edit,Write,Bash" \
  --output-format json \
  >> run.log 2>&1
Enter fullscreen mode Exit fullscreen mode

Le flag --allowedTools est critique. En mode interactif, vous approuvez les actions. En mode headless, personne ne le fait. La liste blanche devient donc votre contrôle principal.

Commencez avec le minimum :

--allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

Évitez de donner un accès shell large à un agent non supervisé sans sandbox. La liste complète des options se trouve dans la documentation de Claude Code.

3. Une porte de vérification déterministe

L’agent ne doit pas décider seul qu’il a terminé. Une vérification externe doit produire un résultat clair : succès ou échec.

Exemples de portes utiles :

npm test
Enter fullscreen mode Exit fullscreen mode 
npm run typecheck
Enter fullscreen mode Exit fullscreen mode 
npm run test:contract
Enter fullscreen mode Exit fullscreen mode 
pytest tests/api
Enter fullscreen mode Exit fullscreen mode

Pour un workflow API, la porte peut vérifier :

  • les codes de statut ;
  • les schémas JSON ;
  • les champs obligatoires ;
  • les contrats OpenAPI ;
  • les erreurs attendues ;
  • les cas limites.

Le résultat doit être exploitable par l’agent :

Échec :
POST /orders sans customer_id
Attendu : 422
Reçu : 500
Enter fullscreen mode Exit fullscreen mode

Cette sortie devient l’entrée de l’itération suivante.

4. Des garde-fous stricts

Un workflow autonome doit être limité par construction :

  • permissions minimales ;
  • nombre maximal d’itérations ;
  • plafond de coûts ;
  • logs par exécution ;
  • espace de travail isolé ;
  • arrêt d’urgence ;
  • tests et spécifications non modifiables par l’agent.

La règle pratique : l’agent doit pouvoir faire son travail, et rien d’autre.

5. Un transfert explicite

À la fin, le workflow doit prévenir quelqu’un.

Exemples :

  • créer une PR de brouillon ;
  • envoyer une notification Slack ;
  • ouvrir une issue ;
  • envoyer un rapport d’échec ;
  • attacher les logs de l’exécution.

Le silence n’est pas un succès.

Utiliser le SDK Claude Agent pour contrôler la boucle

Une commande shell suffit pour des tâches simples. Pour un workflow plus robuste, utilisez le SDK Claude Agent afin d’implémenter la boucle dans votre code.

Exemple TypeScript simplifié :

import { query } from "@anthropic-ai/claude-agent-sdk";

const MAX_ITERATIONS = 8;

let feedback = "";

for (let attempt = 0; attempt < MAX_ITERATIONS; attempt++) {
  for await (const msg of query({
    prompt: `
${task}

Échecs précédents :
${feedback}
    `,
    options: {
      allowedTools: ["Edit", "Write", "Bash"],
    },
  })) {
    // Écrire les messages dans les logs
    console.log(msg);
  }

  const gate = runVerification();

  if (gate.passed) {
    await createDraftPullRequest();
    break;
  }

  feedback = gate.failures;

  if (attempt === MAX_ITERATIONS - 1) {
    await notifyHuman({
      status: "failed",
      reason: gate.failures,
    });
  }
}
Enter fullscreen mode Exit fullscreen mode

La structure importante est celle-ci :

  1. envoyer la tâche ;
  2. laisser Claude modifier le code ;
  3. exécuter une vérification déterministe ;
  4. renvoyer les erreurs structurées à Claude ;
  5. arrêter après une limite ;
  6. transférer à un humain.

Si vous hésitez entre une boucle personnalisée et une solution hébergée, cette comparaison entre les agents gérés et le SDK Agent détaille les cas d’usage.

Ajouter des hooks pour appliquer les règles

Les hooks exécutent vos commandes à des moments fixes du cycle de vie de Claude. Contrairement à une instruction donnée au modèle, un hook est déterministe : l’agent ne choisit pas de l’exécuter ou non.

Exemple : lancer les tests après chaque modification de fichier.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm test --silent"
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Ce type de hook est utile pour :

  • exécuter les tests après une modification ;
  • vérifier le formatage ;
  • refuser certaines commandes ;
  • empêcher la modification de fichiers sensibles ;
  • déclencher une analyse statique.

Exemple de règle simple côté script :

#!/usr/bin/env bash
set -euo pipefail

if git diff --name-only | grep -E "openapi.yaml|tests/contract"; then
  echo "Erreur : l’agent ne doit pas modifier la spécification ou les tests de contrat."
  exit 1
fi
Enter fullscreen mode Exit fullscreen mode

Déclencher le workflow avec cron ou launchd

Un workflow autonome doit être lancé par un ordonnanceur.

Sur un serveur Linux, utilisez cron :

# Tous les jours de semaine à 7h : exécuter la maintenance API
0 7 * * 1-5 cd /srv/api && claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Bash" \
  >> logs/run-$(date +\%F).log 2>&1
Enter fullscreen mode Exit fullscreen mode

Structure recommandée :

/srv/api
├── tasks/
│   └── nightly-maintenance.md
├── logs/
├── scripts/
│   └── verify.sh
├── openapi.yaml
└── tests/
Enter fullscreen mode Exit fullscreen mode

Votre tâche peut être écrite ainsi :

# Maintenance API quotidienne

Objectif :
Synchroniser l’implémentation avec openapi.yaml.

Contraintes :
- ne pas modifier openapi.yaml ;
- ne pas modifier tests/contract ;
- corriger uniquement les endpoints listés dans cette tâche ;
- exécuter ./scripts/verify.sh avant de terminer.

Définition de terminé :
- ./scripts/verify.sh retourne 0 ;
- aucun test de contrat ne casse ;
- les modifications sont prêtes pour une PR de brouillon.
Enter fullscreen mode Exit fullscreen mode

Concevez la boucle, pas seulement l’invite

La question utile n’est pas :

Que dois-je dire à Claude ?
Enter fullscreen mode Exit fullscreen mode

La question utile est :

Quelle boucle permet à Claude de recevoir automatiquement le bon feedback ?
Enter fullscreen mode Exit fullscreen mode

L’agent génère rapidement, mais il ne possède pas un sens fiable de sa propre justesse. La boucle lui fournit ce signal via la porte de vérification.

C’est le cœur de l’approche décrite dans arrêtez de solliciter votre agent de codage, construisez la boucle à la place. Quand la porte décide, la confiance déclarée du modèle n’a plus d’importance.

Une spécification claire est donc plus importante qu’une invite astucieuse. Un fichier design.md ou AGENTS.md peut contenir :

# AGENTS.md

## Objectif
Maintenir les endpoints Orders conformes à openapi.yaml.

## Contraintes
- Ne jamais modifier openapi.yaml.
- Ne jamais modifier les tests de contrat.
- Ne jamais pousser directement sur main.
- Toujours exécuter ./scripts/verify.sh.

## Définition de terminé
- Tous les tests passent.
- Les réponses respectent les schémas OpenAPI.
- Une PR de brouillon est créée.
Enter fullscreen mode Exit fullscreen mode

Exemple concret : maintenance d’API non supervisée

Supposons que vous vouliez maintenir des endpoints API synchronisés avec leur spécification OpenAPI, chaque matin, sans envoyer de code cassé.

Architecture du workflow

  1. Spécification

    Le contrat est dans openapi.yaml. Les comportements attendus sont dans les tests.

  2. Déclencheur

    Une tâche cron lance Claude en mode headless à 7h.

  3. Génération

    Claude corrige les écarts entre l’implémentation et la spécification.

  4. Porte

    Le workflow exécute les tests API et les validations de schéma.

  5. Boucle

    Si la porte échoue, l’erreur structurée est renvoyée à Claude.

  6. Escalade

    Après N tentatives, le workflow s’arrête et alerte un humain.

  7. Transfert

    Si tout passe, une PR de brouillon est créée.

Exemple de script de vérification :

#!/usr/bin/env bash
set -euo pipefail

npm run typecheck
npm test
npm run test:contract
Enter fullscreen mode Exit fullscreen mode

Exemple de feedback renvoyé à l’agent :

La porte de vérification a échoué.

Échec 1 :
Endpoint : POST /orders
Cas : customer_id manquant
Attendu : 422
Reçu : 500

Échec 2 :
Endpoint : GET /orders/{id}
Champ : total
Attendu par le schéma : number
Reçu : string

Corrige uniquement ces écarts. Ne modifie pas openapi.yaml ni les tests.
Enter fullscreen mode Exit fullscreen mode

La porte de l’étape 4 est ce qui rend le workflow sûr. Sans elle, l’agent peut modifier le code et déclarer un succès sur la base de sa propre lecture.

C’est là qu’Apidog s’intègre dans un workflow autonome : la conception de l’API, le schéma, le serveur de mock et les tests automatisés vivent dans un seul espace de travail. La spécification et la porte de vérification restent donc alignées. Vous pouvez diriger l’exécution vers un scénario de test Apidog et donner à l’agent un résultat succès/échec validé par schéma à chaque itération. Le serveur de mock permet aussi de remplacer des dépendances indisponibles, afin qu’une exécution nocturne ne soit pas bloquée par un service tiers instable.

Les équipes qui câblent l’accès aux endpoints via le débogueur d’agent AI Apidog permettent à l’agent d’inspecter les endpoints comme un testeur humain. Téléchargez Apidog si vous préférez construire cette porte visuellement plutôt que coder tout l’exécuteur à la main.

Interface Apidog

Garde-fous pour les exécutions non supervisées

Voici les règles à appliquer avant de laisser un workflow tourner sans vous.

Limitez les permissions

N’accordez que les outils nécessaires :

--allowedTools "Edit,Write,Bash"
Enter fullscreen mode Exit fullscreen mode

Évitez les accès destructeurs non sandboxés. Une exécution non supervisée ne doit jamais avoir carte blanche sur votre environnement.

Bornez les itérations

Une boucle doit s’arrêter.

const MAX_ITERATIONS = 5;
Enter fullscreen mode Exit fullscreen mode

Si la porte ne passe pas après cinq tentatives, l’agent doit escalader, pas continuer indéfiniment.

Ajoutez un plafond de coûts

Les boucles non supervisées peuvent consommer des tokens sans signal immédiat. Définissez un budget par exécution et loggez la consommation. Les recommandations sur la réduction des coûts des tokens d’agent s’appliquent directement ici.

Protégez les tests et la spécification

Ne laissez pas l’agent modifier la porte qui le vérifie.

À protéger :

openapi.yaml
tests/contract/
scripts/verify.sh
Enter fullscreen mode Exit fullscreen mode

Sinon, vous construisez un système capable de simuler le progrès en réécrivant ses propres critères de réussite.

Utilisez une sandbox

Exécutez le workflow dans :

  • un conteneur ;
  • une branche jetable ;
  • un git worktree ;
  • un environnement CI isolé.

Exemple :

git worktree add ../api-agent-run -b agent/nightly-$(date +%F)
cd ../api-agent-run
Enter fullscreen mode Exit fullscreen mode

Loggez tout

Chaque exécution doit produire un journal exploitable :

mkdir -p logs

claude -p "$(cat tasks/nightly-maintenance.md)" \
  --allowedTools "Edit,Bash" \
  --output-format json \
  >> logs/run-$(date +%F-%H%M).log 2>&1
Enter fullscreen mode Exit fullscreen mode

Vous ne pouvez pas déboguer ce que vous n’avez pas enregistré.

Gardez une approbation humaine aux marges

« Sans vous » ne veut pas dire « sans contrôle humain ». Placez l’humain :

  • au début, pour approuver la tâche ;
  • ou à la fin, pour valider la PR.

Ne le mettez pas dans la boucle interne. Les schémas de câblage et les modes de défaillance sont détaillés dans cet article sur le câblage des outils de flux de travail agentique.

Erreurs courantes

Pas de porte de vérification

Si la seule vérification est :

Claude, as-tu terminé ?
Enter fullscreen mode Exit fullscreen mode

vous n’avez pas un workflow autonome. Vous avez un chatbot non supervisé.

La porte doit être externe au modèle.

Une tâche trop large

Une tâche comme celle-ci converge rarement :

Maintiens tout le service backend.
Enter fullscreen mode Exit fullscreen mode

Préférez :

Corrige uniquement POST /orders selon openapi.yaml et tests/orders.contract.ts.
Enter fullscreen mode Exit fullscreen mode

Les petites tâches terminent. Les grosses tâches dérivent.

Permissions trop larges

Accorder tous les outils est pratique, mais dangereux. En mode non supervisé, un petit bug peut devenir un incident si l’agent dispose d’un accès trop large.

Succès ou échec silencieux

Un workflow qui réussit sans notification ou échoue sans alerte est difficile à exploiter. Chaque exécution doit produire un transfert explicite.

Faire confiance à l’auto-déclaration du modèle

Claude peut dire que c’est terminé. La porte décide si c’est vrai.

Construisez pour l’écart entre :

semble terminé
Enter fullscreen mode Exit fullscreen mode

et :

est vérifié
Enter fullscreen mode Exit fullscreen mode

Si vous souhaitez une architecture plus complète, cette analyse de la conception du harnais d’agent explique comment assembler ces pièces à plus grande échelle.

Le point à retenir

Construire des workflows Claude qui s’exécutent sans vous dépend moins de Claude que du système autour de lui.

Les cinq pièces indispensables sont :

  1. une spécification précise ;
  2. une exécution headless ;
  3. une porte de vérification déterministe ;
  4. des garde-fous stricts ;
  5. un transfert propre vers un humain.

Commencez petit : un endpoint, une spécification, une porte rapide, une boucle bornée, des permissions limitées et une notification finale.

Pour les workflows API, la suite de tests est la porte qui rend l’exécution non supervisée sûre. Apidog fournit la conception, la simulation et les tests automatisés dans un seul espace de travail pour construire cette porte. Téléchargez-le, câblez la vérification, puis laissez le workflow tourner pendant que vous faites autre chose.

Top comments (0)