必要な環境
- Node.js >= 20.9.0
- Bun >= 1.3.0（任意 — ソースからビルドする場合のみ必要）
インストール
npm install -g failproofai
クイックスタート
ポリシーを有効にする
ポリシーとは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンド、シークレットの漏洩、その他の障害モードを、実際に被害が出る前に検出します。failproofai policies --install
~/.claude/settings.json、OpenAI Codex の ~/.codex/hooks.json、GitHub Copilot CLI の ~/.copilot/hooks/failproofai.json、Cursor Agent の ~/.cursor/hooks.json、OpenCode の ~/.config/opencode/plugins/failproofai.mjs に生成されるプラグインシムおよび ~/.config/opencode/opencode.json の plugin 配列への登録エントリ、Pi の ~/.pi/agent/settings.json、Gemini CLI の ~/.gemini/settings.json）。複数が存在する場合はプロンプトが表示されます。--cli claude codex copilot cursor opencode pi gemini（任意のサブセット）を渡すとプロンプトをスキップできます。GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Gemini CLI のサポートはベータ版です — それぞれ --cli copilot、--cli cursor、--cli opencode、--cli pi、または --cli gemini でインストールしてください。failproofai policies --install --scope project
failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli gemini --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
確認する
すべてのポリシー、有効かどうか、設定済みのパラメータが表示されます。 ダッシュボードを起動する
http://localhost:8020 にローカルダッシュボードが開き、セッションの閲覧、ツール呼び出しの確認、ポリシーの管理ができます。エージェントを実行する
Claude Code をいつも通り起動します。エージェントが危険な操作を試みると、failproofai が自動的に介入します。そのまま無人で実行し、後からダッシュボードで何が起きたかを確認できます。
ポリシーの仕組み
エージェントがツールを実行するたびに、Claude Code はサブプロセスとして failproofai を呼び出します。
Claude Code → failproofai --hook PreToolUse → reads stdin JSON
evaluates policies
writes decision to stdout
- allow — エージェントは通常どおり処理を続行する
- deny — アクションがブロックされ、エージェントにその理由が通知される
- instruct — エージェントのプロンプトに追加のコンテキストが付加される
ポリシーはローカルプロセス内で実行されます。リモートサービスには何も送信されません。
規約ベースのポリシーでチームポリシーを設定する
チーム全体で品質基準を素早く確立するには、.failproofai/policies/ 規約を使う方法が最も手軽です。このディレクトリにポリシーファイルを置くだけで自動的に読み込まれます — フラグも設定変更もインストールコマンドも不要です。
ポリシーディレクトリを作成する
mkdir -p .failproofai/policies
ポリシーファイルを追加する
サンプルをコピーするか、独自のものを作成します。cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";
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"
.failproofai/policies/ をリポジトリにコミットして、チーム全体で同じ基準を共有しましょう。新たな障害モードを発見したらポリシーを追加してプッシュするだけで、全員が次回の git pull 時にアップデートを受け取ります。時間をかけてこれらのポリシーを育てることで、継続的に改善される生きた品質基準になります。
データの保存場所
すべての設定とログはマシン上にのみ保存されます。
| パス | 保存される内容 |
|---|
~/.failproofai/policies-config.json | グローバルポリシー設定 |
~/.failproofai/hook-activity.jsonl | フック実行履歴 |
~/.failproofai/hook.log | カスタムフックエラーのデバッグログ |
.failproofai/policies-config.json | プロジェクト単位の設定（コミット対象） |
.failproofai/policies-config.local.json | 個人用オーバーライド（gitignore 対象） |
アンインストール
failproofai policies --uninstall
~/.claude/settings.json からフックエントリを削除します。~/.failproofai/ 内の設定ファイルは保持されます。
次のステップ
組み込みポリシー
パラメータ付きの全 26 ポリシー
カスタムポリシー
JavaScript で独自のポリシーを作成する
エージェントモニター
セッションの監視とポリシーアクティビティの確認
