Saltar al contenido principal
failproofai utiliza archivos de configuración JSON para controlar qué políticas están activas, cómo se comportan y desde dónde se cargan las políticas personalizadas. La configuración está diseñada para compartirse fácilmente con tu equipo: confírmala en tu repositorio y todos los desarrolladores tendrán la misma red de seguridad para el agente.

​
Ámbitos de configuración

Existen tres ámbitos de configuración, evaluados en orden de prioridad:
ÁmbitoRuta del archivoPropósito
project.failproofai/policies-config.jsonConfiguración por repositorio, confirmada en control de versiones
local.failproofai/policies-config.local.jsonAnulaciones personales por repositorio, ignoradas por git
global~/.failproofai/policies-config.jsonValores predeterminados a nivel de usuario para todos los proyectos
Cuando failproofai recibe un evento de hook, carga y fusiona los tres archivos que existen en el directorio de trabajo actual.

​
Reglas de fusión

enabledPolicies — la unión de los tres ámbitos. Una política habilitada en cualquier nivel estará activa. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← unión sin duplicados
policyParams — el primer ámbito que defina parámetros para una política determinada gana por completo. No se realiza una fusión profunda de los valores dentro de los parámetros de una política. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← gana project, se ignora global

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

resolved: { allowPatterns: ["sudo systemctl status"] }  ← cae al nivel global
customPoliciesPath — gana el primer ámbito que lo defina. llm — gana el primer ámbito que lo defina.

​
Formato del archivo de configuración

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

​
Referencia de campos

​
enabledPolicies

Tipo: string[] Lista de nombres de políticas a habilitar. Los nombres deben coincidir exactamente con los identificadores de política que muestra failproofai policies. Consulta Políticas integradas para ver la lista completa. Las políticas que no estén en enabledPolicies estarán inactivas, incluso si tienen entradas en policyParams.

​
policyParams

Tipo: Record<string, Record<string, unknown>> Anulaciones de parámetros por política. La clave externa es el nombre de la política; las claves internas son específicas de cada política. Cada política documenta sus parámetros disponibles en Políticas integradas. Si una política tiene parámetros pero no los especificas, se usan los valores predeterminados integrados de la política. Los usuarios que no configuren policyParams en absoluto obtendrán un comportamiento idéntico al de las versiones anteriores. Las claves desconocidas dentro del bloque de parámetros de una política se ignoran silenciosamente en el momento de disparar el hook, pero se marcan como advertencias cuando ejecutas failproofai policies.

​
hint (transversal)

Tipo: string (opcional) Un mensaje que se añade al motivo cuando una política devuelve deny o instruct. Úsalo para dar a Claude orientación accionable sin modificar la política en sí. Funciona con cualquier tipo de política: integrada, personalizada (custom/), convención de proyecto (.failproofai-project/) o convención de usuario (.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."
    }
  }
}
Cuando block-force-push deniega, Claude ve: “Force-pushing is blocked. Try creating a fresh branch instead.” Los valores que no sean cadenas de texto y las cadenas vacías se ignoran silenciosamente. Si hint no está definido, el comportamiento no cambia (compatible con versiones anteriores).

​
customPoliciesPath

Tipo: string (ruta absoluta) Ruta a un archivo JavaScript que contiene políticas de hook personalizadas. Este valor lo establece automáticamente failproofai policies --install --custom <path> (la ruta se resuelve a absoluta antes de almacenarse). El archivo se carga desde cero en cada evento de hook; no hay caché. Consulta Políticas personalizadas para ver los detalles de creación.

​
Políticas basadas en convención

Además del customPoliciesPath explícito, failproofai descubre y carga automáticamente archivos de políticas desde directorios .failproofai/policies/:
NivelDirectorioÁmbito
Proyecto.failproofai/policies/Compartido con el equipo a través del control de versiones
Usuario~/.failproofai/policies/Personal, se aplica a todos los proyectos
Coincidencia de archivos: Solo se cargan los archivos que coincidan con *policies.{js,mjs,ts} (por ejemplo, security-policies.mjs, workflow-policies.js). Los demás archivos del directorio se ignoran. Sin configuración necesaria: Las políticas de convención no requieren entradas en policies-config.json. Simplemente coloca los archivos en el directorio y se detectarán en el siguiente evento de hook. Carga por unión: Se analizan tanto el directorio de convención del proyecto como el del usuario. Todos los archivos coincidentes de ambos niveles se cargan (a diferencia de customPoliciesPath, que usa el criterio de primer ámbito que gana). Consulta Políticas personalizadas para más detalles y ejemplos.

​
llm

Tipo: object (opcional) Configuración del cliente LLM para políticas que realizan llamadas a IA. No es necesario para la mayoría de las configuraciones. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
Gestión de la configuración desde la CLI

Los comandos policies --install y policies --uninstall escriben en el settings.json de Claude Code (los puntos de entrada del hook), mientras que policies-config.json es el archivo que gestionas directamente. Los dos son independientes:
  • settings.json — le indica a Claude Code que llame a failproofai --hook <event> en cada uso de herramienta
  • policies-config.json — le indica a failproofai qué políticas evaluar y con qué parámetros
Puedes editar policies-config.json directamente en cualquier momento; los cambios surten efecto de inmediato en el siguiente evento de hook sin necesidad de reiniciar.

​
Ejemplo: configuración a nivel de proyecto con valores predeterminados del equipo

Confirma .failproofai/policies-config.json en tu repositorio: 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
Cada desarrollador puede entonces crear .failproofai/policies-config.local.json (ignorado por git) para sus anulaciones personales sin afectar a sus compañeros de equipo.