使用例

よくあるシナリオに対応したすぐに使える使用例です。インストール方法と期待される動作を紹介します。

Claude Code へのフック設定

Failproof AI は Claude Code のフックシステムを通じて統合されます。failproofai policies --install を実行すると、すべてのツール呼び出し時に起動するフックコマンドが Claude Code の settings.json に登録されます。

failproofai をインストールする

npm install -g failproofai

組み込みポリシーをすべて有効にする

failproofai policies --install

フックが登録されているか確認する

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

PreToolUse、PostToolUse、Notification、Stop イベントのフックエントリが表示されるはずです。

Claude Code を起動する

claude

すべてのツール呼び出しでポリシーが自動的に実行されます。Claude に sudo rm -rf / を実行するよう指示してみてください — ブロックされます。

Agents SDK へのフック設定

Agents SDK を使って開発している場合、同じフックシステムをプログラムから利用できます。

プロジェクトに failproofai をインストールする

npm install failproofai

エージェントにフックを設定する

エージェントプロセスの作成時にフックコマンドを渡します。フックは Claude Code と同じように stdin/stdout の JSON を介して起動します。

failproofai --hook PreToolUse   # 各ツールの呼び出し前に実行
failproofai --hook PostToolUse  # 各ツールの呼び出し後に実行

エージェント用のカスタムポリシーを作成する

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

破壊的なコマンドをブロックする

最も一般的なセットアップ — エージェントが取り返しのつかない操作を行うのを防ぎます。

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 — リモートスクリプトをシェルにパイプする操作をブロック

シークレットの漏洩を防ぐ

エージェントがツールの出力からクレデンシャルを参照・漏洩するのを防ぎます。

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

これらは PostToolUse で起動します — ツール実行後、エージェントが出力を受け取る前にクレデンシャル情報を除去します。

エージェントが注意を要するときに Slack へ通知する

通知フックを使って、アイドル状態のアラートを 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 {
      // Slack に接続できない場合でもエージェントをブロックしない
    }

    return allow();
  },
});

インストールする：

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

エージェントをブランチに固定する

エージェントが別のブランチに切り替えたり、保護されたブランチにプッシュしたりするのを防ぎます。

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

コミット前にテストを要求する

コミット前にテストを実行するようエージェントに促します。

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 をインストールしているすべてのチームメンバーがこれらのルールを自動的に取得します。

コンベンションポリシーでorg全体の品質標準を構築する

最も効果的なセットアップ：プロジェクトに合わせたポリシーを含む .failproofai/policies/ をリポジトリにコミットします。インストールコマンドや設定変更なしに、すべてのチームメンバーが自動的にポリシーを取得できます。

ディレクトリを作成してポリシーを追加する

mkdir -p .failproofai/policies

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

// チームが使うパッケージマネージャーを強制する
// （代わりに組み込みの 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();
  },
});

// コミット前にテストを実行するようエージェントに促す
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 で全員がアップデートを取得できます。これらのポリシーはチームとともに成長する、生きた品質標準になります。

その他の使用例

リポジトリの examples/ ディレクトリには以下が含まれています：

ファイル	内容
`policies-basic.js`	基本的なポリシー — 本番環境への書き込み、force-push、パイプスクリプトのブロック
`policies-notification.js`	アイドル通知とセッション終了時の Slack アラート
`policies-advanced/index.js`	推移的インポート、非同期フック、PostToolUse の出力スクラビング、Stop イベントの処理

はじめに

基本概念

CLI

ツール

上級

例

Claude Code へのフック設定

Agents SDK へのフック設定

破壊的なコマンドをブロックする

シークレットの漏洩を防ぐ

エージェントが注意を要するときに Slack へ通知する

エージェントをブランチに固定する

コミット前にテストを要求する

本番リポジトリをロックダウンする

コンベンションポリシーでorg全体の品質標準を構築する

その他の使用例

​Claude Code へのフック設定

​Agents SDK へのフック設定

​破壊的なコマンドをブロックする

​シークレットの漏洩を防ぐ

​エージェントが注意を要するときに Slack へ通知する

​エージェントをブランチに固定する

​コミット前にテストを要求する

​本番リポジトリをロックダウンする

​コンベンションポリシーでorg全体の品質標準を構築する

​その他の使用例

Claude Code へのフック設定

Agents SDK へのフック設定

破壊的なコマンドをブロックする

シークレットの漏洩を防ぐ

エージェントが注意を要するときに Slack へ通知する

エージェントをブランチに固定する

コミット前にテストを要求する

本番リポジトリをロックダウンする

コンベンションポリシーでorg全体の品質標準を構築する

その他の使用例