Ejemplos

Ejemplos listos para usar en escenarios comunes. Cada uno muestra cómo instalarlo y qué esperar.

Configurar hooks para Claude Code

Failproof AI se integra con Claude Code a través de su sistema de hooks. Cuando ejecutas failproofai policies --install, registra comandos de hook en el archivo settings.json de Claude Code que se disparan en cada llamada a una herramienta.

Instalar failproofai

npm install -g failproofai

Activar todas las políticas integradas

failproofai policies --install

Verificar que los hooks están registrados

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

Deberías ver entradas de hook para los eventos PreToolUse, PostToolUse, Notification y Stop.

Ejecutar Claude Code

claude

Las políticas ahora se ejecutan automáticamente en cada llamada a una herramienta. Prueba pedirle a Claude que ejecute sudo rm -rf / — será bloqueado.

Configurar hooks para el Agents SDK

Si estás desarrollando con el Agents SDK, puedes usar el mismo sistema de hooks de forma programática.

Instalar failproofai en tu proyecto

npm install failproofai

Configurar hooks en tu agente

Pasa comandos de hook al crear el proceso de tu agente. Los hooks se disparan de la misma manera que en Claude Code — mediante JSON por stdin/stdout:

failproofai --hook PreToolUse   # se llama antes de cada herramienta
failproofai --hook PostToolUse  # se llama después de cada herramienta

Escribir una política personalizada para tu 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();
  },
});

Instalar la política personalizada

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

Bloquear comandos destructivos

La configuración más habitual: evita que los agentes causen daños irreversibles.

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

Qué hace esto:

block-sudo — bloquea todos los comandos sudo
block-rm-rf — bloquea la eliminación recursiva de archivos
block-force-push — bloquea git push --force
block-curl-pipe-sh — bloquea la canalización de scripts remotos al shell

Prevenir la filtración de secretos

Evita que los agentes vean o filtren credenciales en la salida de las herramientas.

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

Estas se disparan en PostToolUse — después de que una herramienta se ejecuta, limpian la salida antes de que el agente la vea.

Recibir alertas en Slack cuando los agentes necesitan atención

Usa el hook de notificación para reenviar alertas de inactividad 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 {
      // nunca bloquear al agente si Slack no está disponible
    }

    return allow();
  },
});

Instálalo:

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

Mantener a los agentes en una rama

Evita que los agentes cambien de rama o hagan push a ramas protegidas.

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

Exigir pruebas antes de hacer commits

Recuerda a los agentes que ejecuten las pruebas antes de confirmar cambios.

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

Proteger un repositorio de producción

Confirma una configuración a nivel de proyecto para que todos los desarrolladores de tu equipo apliquen las mismas políticas. Crea .failproofai/policies-config.json en tu repositorio:

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

Luego confírmalo:

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

Todos los miembros del equipo que tengan failproofai instalado aplicarán estas reglas automáticamente.

Establecer un estándar de calidad organizacional con políticas de convención

La configuración con mayor impacto: confirma .failproofai/policies/ en tu repositorio con políticas adaptadas a tu proyecto. Todos los miembros del equipo las recibirán automáticamente — sin comandos de instalación ni cambios de configuración.

Crear el directorio y agregar políticas

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

Confirmar en git

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

Seguir mejorando

A medida que tu equipo encuentre nuevos casos de fallo, agrega políticas y súbelas. Todos recibirán la actualización en su próximo git pull. Estas políticas se convierten en un estándar de calidad vivo que crece junto con tu equipo.

Más ejemplos

El directorio examples/ en el repositorio contiene:

Archivo	Qué muestra
`policies-basic.js`	Políticas de inicio — bloquear escrituras en producción, force-push y scripts canalizados
`policies-notification.js`	Alertas de Slack para notificaciones de inactividad y fin de sesión
`policies-advanced/index.js`	Importaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y gestión del evento Stop

Primeros pasos

Conceptos principales

CLI

Herramientas

Avanzado

Ejemplos

Configurar hooks para Claude Code

Configurar hooks para el Agents SDK

Bloquear comandos destructivos

Prevenir la filtración de secretos

Recibir alertas en Slack cuando los agentes necesitan atención

Mantener a los agentes en una rama

Exigir pruebas antes de hacer commits

Proteger un repositorio de producción

Establecer un estándar de calidad organizacional con políticas de convención

Más ejemplos

​Configurar hooks para Claude Code

​Configurar hooks para el Agents SDK

​Bloquear comandos destructivos

​Prevenir la filtración de secretos

​Recibir alertas en Slack cuando los agentes necesitan atención

​Mantener a los agentes en una rama

​Exigir pruebas antes de hacer commits

​Proteger un repositorio de producción

​Establecer un estándar de calidad organizacional con políticas de convención

​Más ejemplos

Configurar hooks para Claude Code

Configurar hooks para el Agents SDK

Bloquear comandos destructivos

Prevenir la filtración de secretos

Recibir alertas en Slack cuando los agentes necesitan atención

Mantener a los agentes en una rama

Exigir pruebas antes de hacer commits

Proteger un repositorio de producción

Establecer un estándar de calidad organizacional con políticas de convención

Más ejemplos