Vai al contenuto principale
Esempi pronti all’uso per scenari comuni. Ognuno mostra come installare e cosa aspettarsi.

​
Configurare i hook per Claude Code

Failproof AI si integra con Claude Code tramite il suo sistema di hook. Quando esegui failproofai policies --install, registra i comandi hook nel file settings.json di Claude Code che si attivano ad ogni chiamata di strumento.
1

Installa failproofai

npm install -g failproofai
2

Abilita tutte le policy integrate

failproofai policies --install
3

Verifica che gli hook siano registrati

cat ~/.claude/settings.json | grep failproofai
Dovresti vedere i record degli hook per gli eventi PreToolUse, PostToolUse, Notification e Stop.
4

Esegui Claude Code

claude
Le policy si eseguono automaticamente ad ogni chiamata di strumento. Prova a chiedere a Claude di eseguire sudo rm -rf / - sarà bloccato.

​
Configurare i hook per Agents SDK

Se stai sviluppando con Agents SDK, puoi utilizzare lo stesso sistema di hook programmaticamente.
1

Installa failproofai nel tuo progetto

npm install failproofai
2

Configura gli hook nel tuo agente

Passa i comandi hook quando crei il tuo processo agente. Gli hook si attivano allo stesso modo che in Claude Code - tramite JSON su stdin/stdout:
failproofai --hook PreToolUse   # chiamato prima di ogni strumento
failproofai --hook PostToolUse  # chiamato dopo ogni strumento
3

Scrivi una policy personalizzata per il tuo agente

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

Installa la policy personalizzata

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

​
Blocca i comandi distruttivi

La configurazione più comune - evita che gli agenti causino danni irreversibili. 
failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
Cosa fa:
  • block-sudo - blocca tutti i comandi sudo
  • block-rm-rf - blocca l’eliminazione ricorsiva di file
  • block-force-push - blocca git push --force
  • block-curl-pipe-sh - blocca il reindirizzamento di script remoti verso la shell

​
Previeni la fuga di segreti

Impedisci agli agenti di vedere o divulgare credenziali nell’output degli strumenti. 
failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
Questi si attivano su PostToolUse - dopo che uno strumento viene eseguito, ripuliscono l’output prima che l’agente lo veda.

​
Ricevi avvisi su Slack quando gli agenti richiedono attenzione

Utilizza l’hook di notifica per inoltrare gli avvisi di inattività a 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 {
      // never block the agent if Slack is unreachable
    }

    return allow();
  },
});
Installala: 
SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

​
Mantieni gli agenti su un branch

Previeni che gli agenti cambino branch o facciano push su quelli protetti. 
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();
  },
});

​
Richiedi test prima dei commit

Ricorda agli agenti di eseguire i test prima di fare commit. 
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();
  },
});

​
Proteggi un repository di produzione

Effettua il commit di una config a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse policy. Crea .failproofai/policies-config.json nel tuo repository: 
{
  "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"]
    }
  }
}
Quindi fai il commit: 
git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"
Ogni membro del team che ha failproofai installato raccoglierà automaticamente queste regole.

​
Costruisci uno standard di qualità a livello organizzativo con policy di convenzione

La configurazione più efficace: effettua il commit di .failproofai/policies/ nel tuo repository con policy personalizzate per il tuo progetto. Ogni membro del team le ottiene automaticamente — nessun comando di installazione, nessun cambio di configurazione.
1

Crea la directory e aggiungi le policy

mkdir -p .failproofai/policies

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

// Enforce your team's preferred package manager
// (or enable the built-in prefer-package-manager policy instead)
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();
  },
});

// Remind the agent to run tests before committing
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();
  },
});
2

Fai il commit su git

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

Continua a migliorare

Man mano che il tuo team incontra nuovi problemi, aggiungi policy e fai push. Tutti ricevono l’aggiornamento al prossimo git pull. Queste policy diventano uno standard di qualità vivo che cresce con il tuo team.

​
Altri esempi

La directory examples/ nel repository contiene:
FileCosa mostra
policies-basic.jsPolicy per iniziare - blocca scritture di produzione, force-push, script reindirizzati
policies-notification.jsAvvisi Slack per notifiche di inattività e fine sessione
policies-advanced/index.jsImport transitivi, hook asincroni, ripulitura dell’output PostToolUse, gestione dell’evento Stop