示例 - FailproofAI

开箱即用的常见场景示例，每个示例均说明如何安装及预期效果。

为 Claude Code 配置 hooks

Failproof AI 通过 hooks 系统与 Claude Code 集成。运行 failproofai policies --install 后，它会在 Claude Code 的 settings.json 中注册 hook 命令，并在每次工具调用时触发。

安装 failproofai

npm install -g failproofai

启用所有内置策略

failproofai policies --install

验证 hooks 是否已注册

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

你应该能看到 PreToolUse、PostToolUse、Notification 和 Stop 事件对应的 hook 条目。

运行 Claude Code

claude

策略现在会在每次工具调用时自动执行。尝试让 Claude 运行 sudo rm -rf /，该命令将被拦截。

为 Agents SDK 配置 hooks

如果你正在使用 Agents SDK 进行开发，可以通过编程方式使用相同的 hook 系统。

在项目中安装 failproofai

npm install failproofai

在 agent 中配置 hooks

在创建 agent 进程时传入 hook 命令。hooks 的触发方式与 Claude Code 中相同——通过 stdin/stdout JSON 传递：

failproofai --hook PreToolUse   # called before each tool
failproofai --hook PostToolUse  # called after each tool

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

安装自定义策略

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

拦截破坏性命令

最常见的配置——防止 agent 执行不可逆的破坏性操作。

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

各策略说明：

block-sudo — 拦截所有 sudo 命令
block-rm-rf — 拦截递归文件删除
block-force-push — 拦截 git push --force
block-curl-pipe-sh — 拦截将远程脚本通过管道传递给 shell 的操作

防止密钥泄露

阻止 agent 在工具输出中看到或泄露凭据。

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

这些策略在 PostToolUse 阶段触发——工具执行完成后，在 agent 看到输出之前对其进行脱敏处理。

在 agent 需要关注时发送 Slack 提醒

使用 notification hook 将空闲告警转发至 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();
  },
});

安装方式：

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

将 agent 限制在指定分支

防止 agent 切换分支或向受保护分支推送代码。

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

提交前要求运行测试

提醒 agent 在提交代码前先运行测试。

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

锁定生产仓库

在项目中提交一份团队级配置，使所有开发者自动应用相同的策略。在仓库中创建 .failproofai/policies-config.json：

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

然后提交：

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

所有已安装 failproofai 的团队成员将自动获取这些规则。

通过约定策略构建组织级质量标准

最具价值的配置方式：将 .failproofai/policies/ 提交到仓库，其中包含针对项目定制的策略。所有团队成员将自动获取这些策略，无需执行任何安装命令，也无需修改配置。

创建目录并添加策略

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

提交到 git

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

持续完善

每当团队遇到新的问题模式时，添加相应策略并推送。每位成员在下次 git pull 后即可获取更新。这些策略将成为随团队成长而不断演进的质量标准。

文件	内容说明
`policies-basic.js`	入门策略——拦截生产环境写入、force push 及管道脚本
`policies-notification.js`	针对空闲通知和会话结束的 Slack 告警
`policies-advanced/index.js`	传递导入、异步 hooks、PostToolUse 输出脱敏及 Stop 事件处理

快速开始

核心概念

CLI

工具

进阶

示例

示例

为 Claude Code 配置 hooks

为 Agents SDK 配置 hooks

拦截破坏性命令

防止密钥泄露

在 agent 需要关注时发送 Slack 提醒

将 agent 限制在指定分支

提交前要求运行测试

锁定生产仓库

通过约定策略构建组织级质量标准

更多示例

​为 Claude Code 配置 hooks

​为 Agents SDK 配置 hooks

​拦截破坏性命令

​防止密钥泄露

​在 agent 需要关注时发送 Slack 提醒

​将 agent 限制在指定分支

​提交前要求运行测试

​锁定生产仓库

​通过约定策略构建组织级质量标准

​更多示例

为 Claude Code 配置 hooks

为 Agents SDK 配置 hooks

拦截破坏性命令

防止密钥泄露

在 agent 需要关注时发送 Slack 提醒

将 agent 限制在指定分支

提交前要求运行测试

锁定生产仓库

通过约定策略构建组织级质量标准

更多示例