메인 콘텐츠로 건너뛰기
failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화되어 있는지, 정책이 어떻게 동작하는지, 커스텀 정책을 어디서 로드할지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되었습니다. 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다.

​
설정 범위

설정 범위는 세 가지이며, 우선순위 순서대로 평가됩니다:
범위파일 경로용도
project.failproofai/policies-config.json저장소별 설정, 버전 관리에 커밋
local.failproofai/policies-config.local.json개인 저장소별 오버라이드, gitignore 처리
global~/.failproofai/policies-config.json모든 프로젝트에 적용되는 사용자 수준 기본값
failproofai가 훅 이벤트를 수신하면, 현재 작업 디렉터리에 존재하는 세 파일을 모두 로드하여 병합합니다.

​
병합 규칙

enabledPolicies - 세 범위의 합집합입니다. 어느 한 수준에서라도 활성화된 정책은 적용됩니다. 
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가 표시하는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 기본 제공 정책을 참조하세요. enabledPolicies에 포함되지 않은 정책은 policyParams에 항목이 있더라도 비활성 상태입니다.

​
policyParams

타입: Record<string, Record<string, unknown>> 정책별 파라미터 오버라이드입니다. 외부 키는 정책 이름이고, 내부 키는 정책별로 다릅니다. 각 정책의 사용 가능한 파라미터는 기본 제공 정책에 문서화되어 있습니다. 정책에 파라미터가 있지만 별도로 지정하지 않으면 정책의 기본값이 사용됩니다. 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가 거부할 때, Claude는 다음을 보게 됩니다: “Force-pushing is blocked. Try creating a fresh branch instead.” 문자열이 아닌 값과 빈 문자열은 조용히 무시됩니다. hint를 설정하지 않으면 동작이 변경되지 않습니다(하위 호환성 유지).

​
customPoliciesPath

타입: string (절대 경로) 커스텀 훅 정책이 담긴 JavaScript 파일 경로입니다. failproofai policies --install --custom <path> 명령으로 자동 설정되며, 저장 전에 절대 경로로 변환됩니다. 파일은 매 훅 이벤트마다 새로 로드됩니다. 캐싱은 없습니다. 작성 방법은 커스텀 정책을 참조하세요.

​
컨벤션 기반 정책

명시적인 customPoliciesPath 외에도, failproofai는 .failproofai/policies/ 디렉터리에서 정책 파일을 자동으로 검색하여 로드합니다:
수준디렉터리범위
프로젝트.failproofai/policies/버전 관리를 통해 팀과 공유
사용자~/.failproofai/policies/개인용, 모든 프로젝트에 적용
파일 매칭: *policies.{js,mjs,ts} 패턴과 일치하는 파일만 로드됩니다(예: security-policies.mjs, workflow-policies.js). 디렉터리 내 다른 파일은 무시됩니다. 설정 불필요: 컨벤션 정책은 policies-config.json에 별도 항목이 필요하지 않습니다. 해당 디렉터리에 파일을 넣기만 하면 다음 훅 이벤트에서 자동으로 인식됩니다. 합집합 로딩: 프로젝트와 사용자 컨벤션 디렉터리가 모두 검색됩니다. 두 수준의 일치하는 파일이 모두 로드됩니다(customPoliciesPath는 첫 번째 범위가 우선하는 것과 다릅니다). 자세한 내용과 예시는 커스텀 정책을 참조하세요.

​
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은 직접 관리하는 파일입니다. 두 파일은 별개입니다:
  • settings.json - 각 도구 사용 시 Claude Code가 failproofai --hook <event>를 호출하도록 지시
  • 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 처리)을 생성하여 팀원에게 영향을 주지 않고 개인 오버라이드를 적용할 수 있습니다.