메인 콘텐츠로 건너뛰기

​
요구 사항

  • Node.js >= 20.9.0
  • Bun >= 1.3.0 (선택 사항 - 소스에서 빌드할 때만 필요)

​
설치

npm install -g failproofai

​
빠른 시작

1

정책 활성화

정책은 에이전트의 모든 도구 호출 전후에 실행되는 규칙입니다. 파괴적인 명령, 시크릿 유출, 그 밖의 장애 상황이 실제 피해를 일으키기 전에 미리 차단합니다.
failproofai policies --install
이 명령은 Claude Code의 settings.json에 훅 항목을 작성합니다. 단일 프로젝트에만 설치하거나 특정 정책을 선택할 수도 있습니다:
failproofai policies --install --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
2

확인

failproofai policies
모든 정책의 활성화 여부와 설정된 파라미터를 표시합니다.
3

대시보드 실행

failproofai
http://localhost:8020에 로컬 대시보드를 열어 세션 조회, 도구 호출 검사, 정책 관리를 할 수 있습니다.
4

에이전트 실행

평소처럼 Claude Code를 시작하세요. 에이전트가 위험한 작업을 시도하면 failproofai가 자동으로 이를 차단합니다. 에이전트를 무인 상태로 실행하고, 대시보드에서 이후에 발생한 내용을 검토하세요.

​
정책 동작 방식

에이전트가 도구를 실행할 때마다 Claude Code는 failproofai를 서브프로세스로 호출합니다: 
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
각 정책은 다음 세 가지 결정 중 하나를 반환합니다:
  • allow - 에이전트가 정상적으로 진행됩니다
  • deny - 작업이 차단되고, 에이전트에게 차단 이유가 전달됩니다
  • instruct - 에이전트의 프롬프트에 추가 컨텍스트가 삽입됩니다
정책은 로컬 프로세스에서 실행됩니다. 원격 서비스로 전송되는 데이터는 없습니다.

​
데이터 저장

모든 설정 및 로그는 로컬 머신에 저장됩니다:
경로저장 내용
~/.failproofai/policies-config.json전역 정책 설정
~/.failproofai/hook-activity.jsonl훅 실행 기록
~/.failproofai/hook.log커스텀 훅 오류 디버그 로그
.failproofai/policies-config.json프로젝트별 설정 (커밋됨)
.failproofai/policies-config.local.json개인 재정의 설정 (gitignore 처리됨)

​
제거

failproofai policies --uninstall
~/.claude/settings.json에서 훅 항목을 제거합니다. ~/.failproofai/의 설정 파일은 유지됩니다.

​
다음 단계

설정

스코프 및 설정 파일 형식

기본 제공 정책

파라미터를 포함한 26가지 정책 전체 목록

커스텀 정책

JavaScript로 나만의 정책 작성하기

에이전트 모니터

세션 모니터링 및 정책 활동 검토