メインコンテンツへスキップ
failproofai は JSON 設定ファイルを使用して、どのポリシーが有効か、その動作方法、カスタムポリシーの読み込み元を管理します。設定はチームで共有しやすい設計になっています。リポジトリにコミットすれば、すべての開発者が同じエージェントセーフティネットを利用できます。

​
設定スコープ

設定スコープは優先順位の高い順に 3 つあります。
スコープファイルパス用途
project.failproofai/policies-config.jsonリポジトリ単位の設定、バージョン管理にコミット
local.failproofai/policies-config.local.json個人用のリポジトリ単位オーバーライド、gitignore 対象
global~/.failproofai/policies-config.json全プロジェクト共通のユーザーレベルデフォルト
failproofai がフックイベントを受け取ると、現在の作業ディレクトリに存在する 3 つのファイルをすべて読み込んでマージします。

​
マージルール

enabledPolicies - 3 つのスコープすべての和集合。いずれかのレベルで有効化されたポリシーはアクティブになります。 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← 重複排除済みの和集合
policyParams - 特定のポリシーのパラメーターを最初に定義したスコープが全体として優先されます。ポリシーのパラメーター内での深いマージは行われません。 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project が優先、global は無視

project:  (block-sudo エントリなし)
local:    (block-sudo エントリなし)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← global にフォールスルー
customPoliciesPath - 最初に定義したスコープが優先されます。 llm - 最初に定義したスコープが優先されます。

​
設定ファイルのフォーマット

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "sanitize-jwt",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "block-rm-rf": {
      "allowPaths": ["/tmp"]
    },
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  },
  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
}

​
フィールドリファレンス

​
enabledPolicies

型: string[] 有効化するポリシー名の一覧。名前は failproofai policies で表示されるポリシー識別子と完全に一致する必要があります。全一覧は Built-in Policies を参照してください。 enabledPolicies に含まれていないポリシーは、policyParams にエントリがあっても非アクティブになります。

​
policyParams

型: Record<string, Record<string, unknown>> ポリシーごとのパラメーターオーバーライド。外側のキーがポリシー名、内側のキーはポリシー固有の設定です。各ポリシーで利用可能なパラメーターは Built-in Policies に記載されています。 ポリシーにパラメーターがあっても指定しない場合は、ポリシーの組み込みデフォルト値が使用されます。policyParams をまったく設定していないユーザーは、以前のバージョンと同じ動作になります。 ポリシーのパラメーターブロック内の未知のキーは、フック発火時には無視されますが、failproofai policies 実行時に警告として表示されます。

​
hint（共通設定）

型: string（省略可能） ポリシーが deny または instruct を返した際に、理由メッセージに追加されるテキスト。ポリシー自体を変更せずに Claude への具体的なガイダンスを提供するために使用します。 組み込みポリシー、カスタムポリシー（custom/）、プロジェクト規約（.failproofai-project/）、ユーザー規約（.failproofai-user/）など、すべてのポリシータイプで利用できます。 
{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}
block-force-push が deny した場合、Claude には次のように表示されます: “Force-pushing is blocked. Try creating a fresh branch instead.” 文字列以外の値および空文字列は無視されます。hint が設定されていない場合は動作に変化はありません（後方互換性あり）。

​
customPoliciesPath

型: string（絶対パス） カスタムフックポリシーを含む JavaScript ファイルへのパス。failproofai policies --install --custom <path> によって自動的に設定されます（パスは保存前に絶対パスに解決されます）。 このファイルはフックイベントのたびに新たに読み込まれます。キャッシュは使用されません。作成方法の詳細は Custom Policies を参照してください。

​
規約ベースのポリシー

明示的な customPoliciesPath に加えて、failproofai は .failproofai/policies/ ディレクトリからポリシーファイルを自動的に検出して読み込みます。
レベルディレクトリスコープ
プロジェクト.failproofai/policies/バージョン管理でチームと共有
ユーザー~/.failproofai/policies/個人用、全プロジェクトに適用
ファイルのマッチング: *policies.{js,mjs,ts} にマッチするファイルのみ読み込まれます（例: security-policies.mjs、workflow-policies.js）。ディレクトリ内のその他のファイルは無視されます。 設定不要: 規約ポリシーは policies-config.json へのエントリが不要です。ディレクトリにファイルを配置するだけで、次のフックイベント時に自動的に読み込まれます。 全量読み込み: プロジェクトとユーザーの両方の規約ディレクトリがスキャンされます。両レベルのマッチするファイルがすべて読み込まれます（最初のスコープ優先となる customPoliciesPath とは異なります）。 詳細と例については Custom Policies を参照してください。

​
llm

型: object（省略可能） AI 呼び出しを行うポリシー向けの LLM クライアント設定。ほとんどの環境では不要です。 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
CLI からの設定管理

policies --install および policies --uninstall コマンドは Claude Code の settings.json（フックエントリポイント）に書き込みます。一方、policies-config.json は直接管理するファイルです。この 2 つは別物です。
  • settings.json - ツール使用のたびに failproofai --hook <event> を呼び出すよう Claude Code に指示する
  • policies-config.json - どのポリシーをどのパラメーターで評価するかを failproofai に指示する
policies-config.json はいつでも直接編集できます。変更は再起動不要で、次のフックイベント時に即座に反映されます。

​
例: チームデフォルトを含むプロジェクトレベル設定

.failproofai/policies-config.json をリポジトリにコミットします。 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
各開発者はチームメンバーに影響を与えることなく、個人用のオーバーライドとして .failproofai/policies-config.local.json（gitignore 対象）を作成できます。