Pular para o conteúdo principal
failproofai usa arquivos de configuração JSON para controlar quais políticas estão ativas, como elas se comportam e de onde as políticas personalizadas são carregadas. A configuração foi pensada para ser fácil de compartilhar com o time — faça commit dela no seu repositório e todos os desenvolvedores terão a mesma rede de segurança para agentes.

​
Escopos de configuração

Existem três escopos de configuração, avaliados em ordem de prioridade:
EscopoCaminho do arquivoFinalidade
project.failproofai/policies-config.jsonConfigurações por repositório, commitadas no controle de versão
local.failproofai/policies-config.local.jsonSubstituições pessoais por repositório, ignoradas pelo git
global~/.failproofai/policies-config.jsonPadrões do usuário para todos os projetos
Quando failproofai recebe um evento de hook, ele carrega e mescla os três arquivos que existirem para o diretório de trabalho atual.

​
Regras de mesclagem

enabledPolicies — a união dos três escopos. Uma política habilitada em qualquer nível fica ativa. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← união sem duplicatas
policyParams — o primeiro escopo que define os parâmetros de uma determinada política vence por completo. Não há mesclagem profunda dos valores dentro dos parâmetros de uma política. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project vence, global é ignorado

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

resolved: { allowPatterns: ["sudo systemctl status"] }  ← recai para o global
customPoliciesPath — o primeiro escopo que o define vence. llm — o primeiro escopo que o define vence.

​
Formato do arquivo de configuração

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

​
Referência de campos

​
enabledPolicies

Tipo: string[] Lista de nomes de políticas a habilitar. Os nomes devem corresponder exatamente aos identificadores de política exibidos por failproofai policies. Consulte Políticas integradas para a lista completa. Políticas ausentes de enabledPolicies ficam inativas, mesmo que possuam entradas em policyParams.

​
policyParams

Tipo: Record<string, Record<string, unknown>> Substituições de parâmetros por política. A chave externa é o nome da política; as chaves internas são específicas de cada política. Cada política documenta seus parâmetros disponíveis em Políticas integradas. Se uma política possui parâmetros mas você não os especifica, os valores padrão da política são utilizados. Usuários que não configuram policyParams têm comportamento idêntico ao das versões anteriores. Chaves desconhecidas dentro do bloco de parâmetros de uma política são silenciosamente ignoradas no momento de disparo do hook, mas sinalizadas como avisos ao executar failproofai policies.

​
hint (transversal)

Tipo: string (opcional) Uma mensagem anexada ao motivo quando uma política retorna deny ou instruct. Use-o para fornecer orientações acionáveis ao Claude sem modificar a própria política. Funciona com qualquer tipo de política — integrada, personalizada (custom/), convenção de projeto (.failproofai-project/) ou convenção de usuário (.failproofai-user/). 
{
  "policyParams": {
    "block-force-push": {
      "hint": "Tente criar um branch novo em vez disso."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get diretamente sem sudo."
    },
    "custom/my-policy": {
      "hint": "Peça aprovação ao usuário primeiro."
    }
  }
}
Quando block-force-push nega, Claude recebe: “Force-pushing está bloqueado. Tente criar um branch novo em vez disso.” Valores não textuais e strings vazias são silenciosamente ignorados. Se hint não estiver definido, o comportamento permanece inalterado (compatível com versões anteriores).

​
customPoliciesPath

Tipo: string (caminho absoluto) Caminho para um arquivo JavaScript contendo políticas de hook personalizadas. Esse campo é definido automaticamente por failproofai policies --install --custom <path> (o caminho é resolvido para absoluto antes de ser armazenado). O arquivo é carregado novamente a cada evento de hook — não há cache. Consulte Políticas personalizadas para detalhes de autoria.

​
Políticas baseadas em convenção

Além do customPoliciesPath explícito, failproofai descobre e carrega automaticamente arquivos de políticas dos diretórios .failproofai/policies/:
NívelDiretórioEscopo
Projeto.failproofai/policies/Compartilhado com o time via controle de versão
Usuário~/.failproofai/policies/Pessoal, aplica-se a todos os projetos
Correspondência de arquivos: Apenas arquivos que correspondam a *policies.{js,mjs,ts} são carregados (por exemplo, security-policies.mjs, workflow-policies.js). Outros arquivos no diretório são ignorados. Sem necessidade de configuração: Políticas de convenção não exigem entradas em policies-config.json. Basta adicionar os arquivos ao diretório e eles serão detectados no próximo evento de hook. Carregamento por união: Os diretórios de convenção do projeto e do usuário são varridos. Todos os arquivos correspondentes de ambos os níveis são carregados (ao contrário de customPoliciesPath, que usa o primeiro escopo vencedor). Consulte Políticas personalizadas para mais detalhes e exemplos.

​
llm

Tipo: object (opcional) Configuração do cliente LLM para políticas que fazem chamadas de IA. Não é necessário para a maioria dos casos. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
Gerenciando a configuração pela CLI

Os comandos policies --install e policies --uninstall escrevem no settings.json do Claude Code (os pontos de entrada do hook), enquanto policies-config.json é o arquivo que você gerencia diretamente. Os dois são separados:
  • settings.json — instrui o Claude Code a chamar failproofai --hook <event> a cada uso de ferramenta
  • policies-config.json — instrui o failproofai sobre quais políticas avaliar e com quais parâmetros
Você pode editar policies-config.json diretamente a qualquer momento; as alterações entram em vigor imediatamente no próximo evento de hook, sem necessidade de reinicialização.

​
Exemplo: configuração no nível do projeto com padrões do time

Faça commit de .failproofai/policies-config.json no seu repositório: 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
Cada desenvolvedor pode então criar .failproofai/policies-config.local.json (ignorado pelo git) para substituições pessoais sem afetar os colegas de time.