Exemplos

Exemplos prontos para uso em cenários comuns. Cada um mostra como instalar e o que esperar.

Configurando hooks para Claude Code

Failproof AI se integra com Claude Code por meio do seu sistema de hooks. Quando você executa failproofai policies --install, ele registra comandos de hook no settings.json do Claude Code que disparam a cada chamada de ferramenta.

Instale o failproofai

npm install -g failproofai

Ative todas as políticas integradas

failproofai policies --install

Verifique se os hooks estão registrados

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

Você deve ver entradas de hook para os eventos PreToolUse, PostToolUse, Notification e Stop.

Execute o Claude Code

claude

As políticas agora são executadas automaticamente a cada chamada de ferramenta. Tente pedir ao Claude para executar sudo rm -rf / — o comando será bloqueado.

Configurando hooks para o Agents SDK

Se você está desenvolvendo com o Agents SDK, você pode usar o mesmo sistema de hooks de forma programática.

Instale o failproofai no seu projeto

npm install failproofai

Configure os hooks no seu agente

Passe comandos de hook ao criar o processo do seu agente. Os hooks disparam da mesma forma que no Claude Code — via JSON pelo stdin/stdout:

failproofai --hook PreToolUse   # chamado antes de cada ferramenta
failproofai --hook PostToolUse  # chamado após cada ferramenta

Escreva uma política personalizada para o seu agente

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

customPolicies.add({
  name: "limit-to-project-dir",
  description: "Mantém o agente dentro do diretório do projeto",
  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();
  },
});

Instale a política personalizada

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

Bloquear comandos destrutivos

A configuração mais comum — impede que agentes causem danos irreversíveis.

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

O que isso faz:

block-sudo — bloqueia todos os comandos sudo
block-rm-rf — bloqueia a exclusão recursiva de arquivos
block-force-push — bloqueia git push --force
block-curl-pipe-sh — bloqueia o redirecionamento de scripts remotos para o shell

Evitar vazamento de segredos

Impede que agentes vejam ou vazem credenciais na saída das ferramentas.

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

Esses hooks disparam no PostToolUse — após a execução de uma ferramenta, eles limpam a saída antes que o agente a veja.

Receber alertas no Slack quando agentes precisam de atenção

Use o hook de notificação para encaminhar alertas de ociosidade para o Slack.

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

customPolicies.add({
  name: "slack-on-idle",
  description: "Alerta o Slack quando o agente está aguardando 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 {
      // nunca bloqueie o agente se o Slack estiver inacessível
    }

    return allow();
  },
});

Instale:

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

Manter agentes em uma branch

Impede que agentes troquem de branch ou façam push para branches protegidas.

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

customPolicies.add({
  name: "stay-on-branch",
  description: "Impede o agente de fazer checkout em outras 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();
  },
});

Exigir testes antes de commits

Lembra os agentes de executar testes antes de fazer commit.

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

customPolicies.add({
  name: "test-before-commit",
  description: "Lembra o agente de executar testes antes de fazer commit",
  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();
  },
});

Bloquear um repositório de produção

Faça commit de uma configuração em nível de projeto para que todos os desenvolvedores da sua equipe utilizem as mesmas políticas. Crie .failproofai/policies-config.json no seu repositório:

{
  "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"]
    }
  }
}

Em seguida, faça o commit:

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

Todo membro da equipe que tiver o failproofai instalado receberá essas regras automaticamente.

Construir um padrão de qualidade para toda a organização com políticas de convenção

A configuração de maior impacto: faça commit de .failproofai/policies/ no seu repositório com políticas adaptadas ao seu projeto. Todos os membros da equipe as recebem automaticamente — sem comandos de instalação, sem alterações de configuração.

Crie o diretório e adicione as políticas

mkdir -p .failproofai/policies

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

// Aplica o gerenciador de pacotes preferido da equipe
// (ou ative a política integrada 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();
  },
});

// Lembra o agente de executar testes antes de fazer commit
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();
  },
});

Faça commit no git

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

Continue melhorando

À medida que a equipe encontrar novos modos de falha, adicione políticas e faça push. Todos recebem a atualização no próximo git pull. Essas políticas se tornam um padrão de qualidade vivo que cresce junto com a sua equipe.

Mais exemplos

O diretório examples/ no repositório contém:

Arquivo	O que demonstra
`policies-basic.js`	Políticas iniciais — bloqueia escritas em produção, force-push e scripts redirecionados
`policies-notification.js`	Alertas no Slack para notificações de ociosidade e encerramento de sessão
`policies-advanced/index.js`	Importações transitivas, hooks assíncronos, limpeza de saída no PostToolUse e tratamento do evento Stop

Começando

Conceitos principais

CLI

Ferramentas

Avançado

Exemplos

Configurando hooks para Claude Code

Configurando hooks para o Agents SDK

Bloquear comandos destrutivos

Evitar vazamento de segredos

Receber alertas no Slack quando agentes precisam de atenção

Manter agentes em uma branch

Exigir testes antes de commits

Bloquear um repositório de produção

Construir um padrão de qualidade para toda a organização com políticas de convenção

Mais exemplos

​Configurando hooks para Claude Code

​Configurando hooks para o Agents SDK

​Bloquear comandos destrutivos

​Evitar vazamento de segredos

​Receber alertas no Slack quando agentes precisam de atenção

​Manter agentes em uma branch

​Exigir testes antes de commits

​Bloquear um repositório de produção

​Construir um padrão de qualidade para toda a organização com políticas de convenção

​Mais exemplos

Configurando hooks para Claude Code

Configurando hooks para o Agents SDK

Bloquear comandos destrutivos

Evitar vazamento de segredos

Receber alertas no Slack quando agentes precisam de atenção

Manter agentes em uma branch

Exigir testes antes de commits

Bloquear um repositório de produção

Construir um padrão de qualidade para toda a organização com políticas de convenção

Mais exemplos