시작하기

failproofai를 설치하고, 정책을 활성화하여 에이전트를 안정적으로 실행하세요

​

요구사항

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

---

​

설치

npm

npm install -g failproofai

bun add -g failproofai

---

​

빠른 시작

1. 정책 활성화

   정책은 에이전트의 모든 도구 호출 전후에 실행되는 규칙입니다. 파괴적인 명령, 비밀 정보 유출, 기타 장애 유형을 피해가 발생하기 전에 차단합니다.

   failproofai policies --install
   

   이 명령은 설치된 에이전트 CLI의 훅 항목을 작성합니다 (Claude Code의 ~/.claude/settings.json, OpenAI Codex의 ~/.codex/hooks.json, GitHub Copilot CLI의 ~/.copilot/hooks/failproofai.json, Cursor Agent의 ~/.cursor/hooks.json, OpenCode의 ~/.config/opencode/plugins/failproofai.mjs 플러그인 심 및 ~/.config/opencode/opencode.json의 plugin 배열 등록 항목, Pi의 ~/.pi/agent/settings.json, Gemini CLI의 ~/.gemini/settings.json). 하나 이상 설치되어 있는 경우 선택 메시지가 표시됩니다. --cli claude codex copilot cursor opencode pi gemini (임의의 조합)를 전달하면 메시지를 건너뜁니다.

   GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Gemini CLI 지원은 베타 단계입니다 — --cli copilot, --cli cursor, --cli opencode, --cli pi, --cli gemini로 설치하세요.

   failproofai policies --install --scope project
   failproofai policies --install --cli codex --scope project
   failproofai policies --install --cli copilot --scope project
   failproofai policies --install --cli cursor --scope project
   failproofai policies --install --cli opencode --scope project
   failproofai policies --install --cli pi --scope project
   failproofai policies --install --cli gemini --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/ 컨벤션을 활용하는 것입니다. 이 디렉토리에 정책 파일을 추가하면 자동으로 로드됩니다 — 플래그, 설정 변경, 설치 명령이 필요 없습니다.

1. 정책 디렉토리 생성

   mkdir -p .failproofai/policies
   
2. 정책 파일 추가

   예제 파일을 복사하거나 직접 작성하세요:

   cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
   

   또는 새로 만들기:

   // .failproofai/policies/team-policies.mjs
   import { customPolicies, allow, deny, instruct } from "failproofai";
   
   customPolicies.add({
     name: "test-before-commit",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       if (ctx.toolName !== "Bash") return allow();
       if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
         return instruct("Run tests before committing.");
       }
       return allow();
     },
   });
   
3. git에 커밋

   git add .failproofai/policies/
   git commit -m "Add team quality policies"
   

   failproofai가 설치된 모든 팀원은 이 정책을 자동으로 적용받습니다. 개발자별 별도 설정이 필요 없습니다.

팀 전체가 동일한 기준을 공유할 수 있도록 .failproofai/policies/를 저장소에 커밋하세요. 팀이 새로운 장애 유형을 발견할 때마다 정책을 추가하고 푸시하면 — 모든 팀원이 다음 git pull 시 업데이트를 받게 됩니다. 시간이 지남에 따라 이 정책들은 지속적으로 발전하는 살아있는 품질 기준이 됩니다.

---

​

데이터 저장

모든 설정과 로그는 로컬 머신에 저장됩니다:

경로	저장 내용
~/.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로 나만의 정책 작성하기

에이전트 모니터

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