메인 콘텐츠로 건너뛰기
일반적인 시나리오에 바로 사용할 수 있는 예시 모음입니다. 각 예시에는 설치 방법과 예상 동작이 포함되어 있습니다.

Claude Code용 훅 설정

Failproof AI는 Claude Code의 훅 시스템을 통해 통합됩니다. failproofai policies --install을 실행하면 모든 도구 호출 시 실행되는 훅 명령이 Claude Code의 settings.json에 등록됩니다.
1

failproofai 설치

npm install -g failproofai
2

모든 내장 정책 활성화

failproofai policies --install
3

훅 등록 확인

cat ~/.claude/settings.json | grep failproofai
PreToolUse, PostToolUse, Notification, Stop 이벤트에 대한 훅 항목이 표시되어야 합니다.
4

Claude Code 실행

claude
이제 모든 도구 호출 시 정책이 자동으로 실행됩니다. Claude에게 sudo rm -rf /를 실행하도록 요청해 보세요 — 차단됩니다.

Agents SDK용 훅 설정

Agents SDK로 개발하는 경우, 동일한 훅 시스템을 프로그래밍 방식으로 사용할 수 있습니다.
1

프로젝트에 failproofai 설치

npm install failproofai
2

에이전트에 훅 설정

에이전트 프로세스를 생성할 때 훅 명령을 전달합니다. 훅은 Claude Code와 동일한 방식으로 — stdin/stdout JSON을 통해 — 실행됩니다:
failproofai --hook PreToolUse   # 각 도구 실행 전 호출
failproofai --hook PostToolUse  # 각 도구 실행 후 호출
3

에이전트용 커스텀 정책 작성

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "limit-to-project-dir",
  description: "Keep the agent inside the project directory",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    const path = String(ctx.toolInput?.file_path ?? "");
    if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
      return deny("Agent is restricted to the project directory");
    }
    return allow();
  },
});
4

커스텀 정책 설치

failproofai policies --install --custom ./my-agent-policies.js

파괴적 명령 차단

가장 일반적인 설정으로, 에이전트가 되돌릴 수 없는 피해를 입히는 것을 방지합니다.
failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
각 정책의 역할:
  • block-sudo — 모든 sudo 명령 차단
  • block-rm-rf — 재귀적 파일 삭제 차단
  • block-force-pushgit push --force 차단
  • block-curl-pipe-sh — 원격 스크립트를 셸로 파이핑하는 것 차단

시크릿 유출 방지

에이전트가 도구 출력에서 자격 증명을 보거나 유출하지 못하도록 차단합니다.
failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
이 정책들은 PostToolUse에서 실행됩니다 — 도구 실행 후, 에이전트가 출력을 확인하기 전에 민감한 정보를 제거합니다.

에이전트 대기 시 Slack 알림 받기

알림 훅을 사용하여 유휴 알림을 Slack으로 전달합니다.
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Alert Slack when the agent is waiting for input",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Agent is waiting");
    const project = ctx.session?.cwd ?? "unknown";

    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${message}*\nProject: \`${project}\``,
        }),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      // Slack에 연결할 수 없어도 에이전트를 절대 차단하지 않음
    }

    return allow();
  },
});
설치:
SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

에이전트를 특정 브랜치에 고정

에이전트가 브랜치를 전환하거나 보호된 브랜치에 푸시하는 것을 방지합니다.
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Prevent the agent from checking out other branches",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
      return deny("Stay on the current branch. Create a new branch with -b if needed.");
    }
    return allow();
  },
});

커밋 전 테스트 실행 요구

에이전트가 커밋하기 전에 테스트를 실행하도록 상기시킵니다.
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Remind the agent to run tests before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+commit/.test(cmd)) {
      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
    }
    return allow();
  },
});

프로덕션 저장소 잠금

팀의 모든 개발자가 동일한 정책을 적용받도록 프로젝트 수준의 설정을 저장소에 커밋합니다. 저장소에 .failproofai/policies-config.json을 생성합니다:
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-force-push",
    "block-push-master",
    "block-env-files",
    "sanitize-api-keys",
    "sanitize-jwt"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "production"]
    }
  }
}
커밋합니다:
git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"
failproofai가 설치된 모든 팀원은 이 규칙을 자동으로 적용받습니다.

더 많은 예시

저장소의 examples/ 디렉토리에는 다음 파일들이 포함되어 있습니다:
파일내용
policies-basic.js기본 정책 — 프로덕션 쓰기 차단, force-push 차단, 파이프된 스크립트 차단
policies-notification.js유휴 알림 및 세션 종료 시 Slack 알림
policies-advanced/index.js전이적 임포트, 비동기 훅, PostToolUse 출력 스크러빙, Stop 이벤트 처리