Exemples

Des exemples prêts à l’emploi pour les scénarios courants. Chacun montre comment installer et à quoi s’attendre.

Configurer des hooks pour Claude Code

Failproof AI s’intègre à Claude Code via son système de hooks. Lorsque vous exécutez failproofai policies --install, il enregistre des commandes de hook dans le fichier settings.json de Claude Code, qui se déclenchent à chaque appel d’outil.

Installer failproofai

npm install -g failproofai

Activer toutes les politiques intégrées

failproofai policies --install

Vérifier que les hooks sont enregistrés

cat ~/.claude/settings.json | grep failproofai

Vous devriez voir des entrées de hook pour les événements PreToolUse, PostToolUse, Notification et Stop.

Lancer Claude Code

claude

Les politiques s’exécutent désormais automatiquement à chaque appel d’outil. Essayez de demander à Claude d’exécuter sudo rm -rf / — la commande sera bloquée.

Configurer des hooks pour l’Agents SDK

Si vous développez avec l’Agents SDK, vous pouvez utiliser le même système de hooks de manière programmatique.

Installer failproofai dans votre projet

npm install failproofai

Configurer les hooks dans votre agent

Passez des commandes de hook lors de la création de votre processus d’agent. Les hooks se déclenchent de la même façon que dans Claude Code — via JSON en stdin/stdout :

failproofai --hook PreToolUse   # appelé avant chaque outil
failproofai --hook PostToolUse  # appelé après chaque outil

Écrire une politique personnalisée pour votre agent

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "limit-to-project-dir",
  description: "Keep the agent inside the project directory",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    const path = String(ctx.toolInput?.file_path ?? "");
    if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
      return deny("Agent is restricted to the project directory");
    }
    return allow();
  },
});

Installer la politique personnalisée

failproofai policies --install --custom ./my-agent-policies.js

Bloquer les commandes destructives

La configuration la plus courante — empêcher les agents de causer des dommages irréversibles.

failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh

Ce que cela fait :

block-sudo — bloque toutes les commandes sudo
block-rm-rf — bloque la suppression récursive de fichiers
block-force-push — bloque git push --force
block-curl-pipe-sh — bloque l’exécution directe de scripts distants via un pipe vers le shell

Empêcher la fuite de secrets

Évitez que les agents voient ou divulguent des identifiants dans la sortie des outils.

failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens

Ces politiques se déclenchent sur PostToolUse — après l’exécution d’un outil, elles nettoient la sortie avant que l’agent ne la voie.

Recevoir des alertes Slack quand les agents ont besoin d’attention

Utilisez le hook de notification pour transmettre les alertes d’inactivité à Slack.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Alert Slack when the agent is waiting for input",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Agent is waiting");
    const project = ctx.session?.cwd ?? "unknown";

    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${message}*\nProject: \`${project}\``,
        }),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      // ne jamais bloquer l'agent si Slack est inaccessible
    }

    return allow();
  },
});

Installez-la :

SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

Maintenir les agents sur une branche

Empêchez les agents de changer de branche ou de pousser sur des branches protégées.

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Prevent the agent from checking out other branches",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
      return deny("Stay on the current branch. Create a new branch with -b if needed.");
    }
    return allow();
  },
});

Exiger des tests avant les commits

Rappelez aux agents d’exécuter les tests avant de committer.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Remind the agent to run tests before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+commit/.test(cmd)) {
      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
    }
    return allow();
  },
});

Verrouiller un dépôt de production

Commitez une configuration au niveau du projet afin que chaque développeur de votre équipe bénéficie des mêmes politiques. Créez .failproofai/policies-config.json dans votre dépôt :

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-force-push",
    "block-push-master",
    "block-env-files",
    "sanitize-api-keys",
    "sanitize-jwt"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "production"]
    }
  }
}

Puis commitez-le :

git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"

Chaque membre de l’équipe ayant failproofai installé récupérera automatiquement ces règles.

Établir un standard qualité à l’échelle de l’organisation avec des politiques de convention

La configuration la plus efficace : commitez .failproofai/policies/ dans votre dépôt avec des politiques adaptées à votre projet. Chaque membre de l’équipe les obtient automatiquement — sans commandes d’installation, sans modifications de configuration.

Créer le répertoire et ajouter des politiques

mkdir -p .failproofai/policies

// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

// Impose le gestionnaire de paquets préféré de votre équipe
// (ou activez plutôt la politique intégrée prefer-package-manager)
customPolicies.add({
  name: "enforce-bun",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
    return allow();
  },
});

// Rappelle à l'agent d'exécuter les tests avant de committer
customPolicies.add({
  name: "test-before-commit",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
      return instruct("Run tests before committing.");
    }
    return allow();
  },
});

Commiter dans git

git add .failproofai/policies/
git commit -m "Add team quality policies"

Continuer à améliorer

Au fur et à mesure que votre équipe rencontre de nouveaux types d’erreurs, ajoutez des politiques et poussez-les. Tout le monde reçoit la mise à jour au prochain git pull. Ces politiques deviennent un standard qualité vivant qui évolue avec votre équipe.

Plus d’exemples

Le répertoire examples/ du dépôt contient :

Fichier	Ce qu’il illustre
`policies-basic.js`	Politiques de démarrage — bloquer les écritures en production, les force-push, les scripts pipés
`policies-notification.js`	Alertes Slack pour les notifications d’inactivité et la fin de session
`policies-advanced/index.js`	Imports transitifs, hooks asynchrones, nettoyage de la sortie PostToolUse, gestion de l’événement Stop

Démarrage

Concepts clés

CLI

Outils

Avancé

Exemples

Configurer des hooks pour Claude Code

Configurer des hooks pour l’Agents SDK

Bloquer les commandes destructives

Empêcher la fuite de secrets

Recevoir des alertes Slack quand les agents ont besoin d’attention

Maintenir les agents sur une branche

Exiger des tests avant les commits

Verrouiller un dépôt de production

Établir un standard qualité à l’échelle de l’organisation avec des politiques de convention

Plus d’exemples

​Configurer des hooks pour Claude Code

​Configurer des hooks pour l’Agents SDK

​Bloquer les commandes destructives

​Empêcher la fuite de secrets

​Recevoir des alertes Slack quand les agents ont besoin d’attention

​Maintenir les agents sur une branche

​Exiger des tests avant les commits

​Verrouiller un dépôt de production

​Établir un standard qualité à l’échelle de l’organisation avec des politiques de convention

​Plus d’exemples

Configurer des hooks pour Claude Code

Configurer des hooks pour l’Agents SDK

Bloquer les commandes destructives

Empêcher la fuite de secrets

Recevoir des alertes Slack quand les agents ont besoin d’attention

Maintenir les agents sur une branche

Exiger des tests avant les commits

Verrouiller un dépôt de production

Établir un standard qualité à l’échelle de l’organisation avec des politiques de convention

Plus d’exemples