Zum Hauptinhalt springen
failproofai verwendet JSON-Konfigurationsdateien, um festzulegen, welche Richtlinien aktiv sind, wie sie sich verhalten und woher benutzerdefinierte Richtlinien geladen werden. Die Konfiguration ist so gestaltet, dass sie einfach mit dem Team geteilt werden kann – committen Sie sie in Ihr Repository und jeder Entwickler erhält dasselbe Sicherheitsnetz für Agenten.

​
Konfigurationsscopes

Es gibt drei Konfigurationsscopes, die in Prioritätsreihenfolge ausgewertet werden:
ScopeDateipfadZweck
project.failproofai/policies-config.jsonRepository-spezifische Einstellungen, in die Versionsverwaltung eingecheckt
local.failproofai/policies-config.local.jsonPersönliche repository-spezifische Überschreibungen, per .gitignore ausgeschlossen
global~/.failproofai/policies-config.jsonBenutzerweite Standardeinstellungen für alle Projekte
Wenn failproofai ein Hook-Ereignis empfängt, lädt und zusammenführt es alle drei Dateien, die für das aktuelle Arbeitsverzeichnis vorhanden sind.

​
Zusammenführungsregeln

enabledPolicies – die Vereinigung aller drei Scopes. Eine Richtlinie, die auf irgendeiner Ebene aktiviert ist, ist aktiv. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplizierte Vereinigung
policyParams – der erste Scope, der Parameter für eine bestimmte Richtlinie definiert, gewinnt vollständig. Es findet kein tiefes Zusammenführen von Werten innerhalb der Parameter einer Richtlinie statt. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project gewinnt, global ignoriert

project:  (kein block-sudo-Eintrag)
local:    (kein block-sudo-Eintrag)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← fällt auf global zurück
customPoliciesPath – der erste Scope, der diesen Wert definiert, gewinnt. llm – der erste Scope, der diesen Wert definiert, gewinnt.

​
Konfigurationsdateiformat

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

​
Feldreferenz

​
enabledPolicies

Typ: string[] Liste der zu aktivierenden Richtliniennamen. Die Namen müssen exakt mit den Richtlinienbezeichnern übereinstimmen, die von failproofai policies angezeigt werden. Die vollständige Liste finden Sie unter Integrierte Richtlinien. Richtlinien, die nicht in enabledPolicies aufgeführt sind, sind inaktiv, auch wenn sie Einträge in policyParams haben.

​
policyParams

Typ: Record<string, Record<string, unknown>> Richtlinienspezifische Parameterüberschreibungen. Der äußere Schlüssel ist der Richtlinienname; die inneren Schlüssel sind richtlinienspezifisch. Jede Richtlinie dokumentiert ihre verfügbaren Parameter unter Integrierte Richtlinien. Wenn eine Richtlinie Parameter hat, Sie diese aber nicht angeben, werden die integrierten Standardwerte der Richtlinie verwendet. Benutzer, die policyParams gar nicht konfigurieren, erhalten dasselbe Verhalten wie in früheren Versionen. Unbekannte Schlüssel innerhalb des Parameterblocks einer Richtlinie werden zum Zeitpunkt der Hook-Auslösung stillschweigend ignoriert, aber als Warnungen markiert, wenn Sie failproofai policies ausführen.

​
hint (übergreifend)

Typ: string (optional) Eine Nachricht, die an die Begründung angehängt wird, wenn eine Richtlinie deny oder instruct zurückgibt. Verwenden Sie diesen Wert, um Claude handlungsrelevante Hinweise zu geben, ohne die Richtlinie selbst zu ändern. Funktioniert mit jedem Richtlinientyp – integriert, benutzerdefiniert (custom/), Projektkonvention (.failproofai-project/) oder Benutzerkonvention (.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."
    }
  }
}
Wenn block-force-push verweigert, sieht Claude: „Force-Pushing ist blockiert. Versuche stattdessen, einen neuen Branch zu erstellen.” Nicht-String-Werte und leere Zeichenketten werden stillschweigend ignoriert. Wenn hint nicht gesetzt ist, bleibt das Verhalten unverändert (abwärtskompatibel).

​
customPoliciesPath

Typ: string (absoluter Pfad) Pfad zu einer JavaScript-Datei mit benutzerdefinierten Hook-Richtlinien. Dieser Wert wird automatisch durch failproofai policies --install --custom <path> gesetzt (der Pfad wird vor der Speicherung in einen absoluten Pfad aufgelöst). Die Datei wird bei jedem Hook-Ereignis neu geladen – es gibt kein Caching. Informationen zur Erstellung finden Sie unter Benutzerdefinierte Richtlinien.

​
Konventionsbasierte Richtlinien

Zusätzlich zum expliziten customPoliciesPath erkennt und lädt failproofai automatisch Richtliniendateien aus .failproofai/policies/-Verzeichnissen:
EbeneVerzeichnisScope
Projekt.failproofai/policies/Wird mit dem Team über die Versionsverwaltung geteilt
Benutzer~/.failproofai/policies/Persönlich, gilt für alle Projekte
Dateiabgleich: Es werden nur Dateien geladen, die dem Muster *policies.{js,mjs,ts} entsprechen (z. B. security-policies.mjs, workflow-policies.js). Andere Dateien im Verzeichnis werden ignoriert. Keine Konfiguration erforderlich: Konventionsrichtlinien benötigen keine Einträge in policies-config.json. Legen Sie die Dateien einfach im Verzeichnis ab und sie werden beim nächsten Hook-Ereignis aufgenommen. Vereinigtes Laden: Sowohl das Projekt- als auch das Benutzerkonventionsverzeichnis werden durchsucht. Alle passenden Dateien aus beiden Ebenen werden geladen (im Gegensatz zu customPoliciesPath, das das Prinzip „erster Scope gewinnt” verwendet). Weitere Details und Beispiele finden Sie unter Benutzerdefinierte Richtlinien.

​
llm

Typ: object (optional) LLM-Client-Konfiguration für Richtlinien, die KI-Aufrufe durchführen. Für die meisten Setups nicht erforderlich. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
Konfiguration über die CLI verwalten

Die Befehle policies --install und policies --uninstall schreiben in Claude Codes settings.json (die Hook-Einstiegspunkte), während policies-config.json die Datei ist, die Sie direkt verwalten. Beide sind voneinander getrennt:
  • settings.json – weist Claude Code an, bei jeder Toolnutzung failproofai --hook <event> aufzurufen
  • policies-config.json – teilt failproofai mit, welche Richtlinien mit welchen Parametern ausgewertet werden sollen
Sie können policies-config.json jederzeit direkt bearbeiten; Änderungen treten sofort beim nächsten Hook-Ereignis in Kraft, ohne dass ein Neustart erforderlich ist.

​
Beispiel: Konfiguration auf Projektebene mit Team-Standardwerten

Committen Sie .failproofai/policies-config.json in Ihr Repository: 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
Jeder Entwickler kann dann .failproofai/policies-config.local.json (per .gitignore ausgeschlossen) für persönliche Überschreibungen erstellen, ohne die Teamkollegen zu beeinflussen.