커스텀 정책

커스텀 정책은 트레이스나 감사 기록에서 발견된 장애 패턴을 에이전트가 작동하는 동안 실시간으로 처리하는 결정 규칙으로 전환합니다. 정책은 특정 작업을 허용하거나, 에이전트에게 지침을 제공하거나, 문제가 발생하기 전에 해당 작업을 차단할 수 있습니다. 도구, 경로, 명령어, 환경, 또는 운영 규칙에 따라 동작이 달라지는 경우 커스텀 정책을 사용하세요. 기존 컨트롤을 중복으로 만들지 않도록 먼저 기본 제공 정책 카탈로그를 확인하세요.

커스텀 정책 작성

대시보드
CLI

Admin → policy editor로 이동하여 New policy를 선택하고, 방지하려는 장애를 설명합니다.
정책 소스를 추가한 후 에디터에서 예상 일치 케이스와 안전한 비일치 케이스를 테스트합니다. 모든 유효성 검사 오류를 해결하세요.
초안을 저장하고 Publish version을 선택하여 변경 불가능한 버전을 생성합니다.
Admin → enforcement로 이동하여 observe 모드의 테스트 머신에 버전을 배포하고, 적용하기 전에 Observe → policy에서 결정 사항을 확인합니다.

.failproofai/policies/checkout-policies.ts를 생성합니다. 파일명은 반드시 policies.js, policies.mjs, 또는 policies.ts로 끝나야 합니다.
customPolicies.add()로 하나 이상의 정책을 등록합니다.
failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project 명령어로 파일을 유효성 검사하고 설치합니다.
일치하는 작업 하나와 안전한 작업 하나를 트리거합니다. failproofai policies를 실행한 후 Observe → policy에서 해당 정책에 귀속된 결정 사항을 확인합니다.

좁은 범위의 규칙으로 시작하기

아래 정책은 명령어가 프로덕션을 대상으로 할 때만 파괴적인 Kubernetes 명령을 차단합니다. 해당 장애 패턴에 정확히 해당하지 않는 경우에는 allow()를 반환합니다.

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

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

좋은 정책은 한 문장으로 설명할 수 있을 만큼 좁은 범위여야 합니다. 에이전트의 의도가 아닌 관찰 가능한 실제 행동에 매칭하고, 규칙이 적용되지 않는 즉시 allow()를 반환하세요.

결정 방식 선택

헬퍼	결과	사용 시기
`allow(reason?)`	작업이 계속됩니다.	정책이 적용되지 않거나 작업이 안전한 경우.
`instruct(reason)`	작업이 계속되며, 해당 하네스가 지원하는 경우 지침이 제공됩니다.	불변 규칙을 강제하지 않고 에이전트가 더 나은 방법을 사용하도록 유도하려는 경우.
`deny(reason)`	이벤트와 하네스가 차단을 지원하는 경우 작업이 차단됩니다.	작업이 진행되어서는 안 되는 경우.

복구해야 하는 에이전트를 위해 이유(reason)를 작성하세요. 무엇이 감지되었고 대신 무엇을 해야 하는지 설명하세요.

instruct()를 안전 경계로 사용하지 마세요. 지침 전달 방식은 에이전트 하네스에 따라 다릅니다. 작업을 반드시 막아야 할 경우에는 deny()를 사용하세요.

정책 객체

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

필드	필수 여부	설명
`name`	예	정책의 안정적인 식별자입니다. 파일 전체에서 고유한 이름을 유지하세요.
`description`	아니오	정책 목록 및 결정 사항에 표시되는 사람이 읽을 수 있는 설명입니다.
`match.events`	아니오	정책을 호출하는 이벤트 유형입니다. `match`를 생략하면 사용 가능한 모든 이벤트에 대해 호출됩니다.
`fn`	예	`allow`, `instruct`, 또는 `deny` 결과를 반환하는 동기 또는 비동기 함수입니다.

fn 내부에서 도구를 필터링하세요. match.toolNames은 공개 커스텀 정책 타입에 포함되지 않습니다.

정책 컨텍스트

모든 정책은 PolicyContext를 받습니다.

필드	타입	포함 내용
`eventType`	`HookEventType`	현재 평가 중인 정규화된 이벤트.
`toolName`	`string \| undefined`	`Bash`, `Read`, `Write`, `Edit` 등의 표준 도구 이름.
`toolInput`	`Record<string, unknown> \| undefined`	현재 도구 호출의 표준 입력.
`payload`	`Record<string, unknown>`	완전히 정규화된 이벤트 페이로드.
`session`	`SessionMetadata \| undefined`	세션 ID, 작업 디렉토리, 트랜스크립트 경로, 권한 모드, 사용 가능한 경우 하네스 메타데이터.
`cli`	`string \| undefined`	`claude`, `codex`, `cursor` 등의 소스 에이전트 하네스.
`params`	`Record<string, unknown>`	기본 제공 정책 파라미터. 커스텀 정책은 현재 빈 객체를 받습니다.

모든 선택적 값을 실제로 선택 사항으로 취급하세요. 에이전트 버전과 이벤트 타입에 따라 제공되는 필드가 다를 수 있습니다.

일반적인 도구 입력

Failproof AI는 지원되는 하네스 전반에서 공통 도구를 정규화하므로, 정책은 일반적으로 하나의 입력 형태를 사용할 수 있습니다.

도구	공통 필드
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

도구 입력 값은 unknown으로 타입이 지정되므로 방어적 변환을 사용하세요:

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

이벤트 선택

이벤트	실행 시점	일반적인 용도
`PreToolUse`	도구 실행 전.	명령어, 쓰기, 읽기, 외부 작업 차단 또는 안내.
`PostToolUse`	도구 반환 후.	에이전트에 도달하기 전 결과 검사. deny는 전체 결과를 차단하며, 선택적 필드를 삭제하지는 않습니다.
`PermissionRequest`	에이전트가 권한을 요청할 때.	조직별 권한 규칙 적용.
`UserPromptSubmit`	제출된 프롬프트가 계속되기 전.	금지된 지시 거부 또는 워크플로우 지침 추가.
`Stop`	에이전트가 완료를 시도할 때.	로컬 검증 단계 등 충족 가능한 완료 조건 요구.
`SubagentStop`	서브에이전트가 완료를 시도할 때.	부모에게 반환되기 전 위임된 작업 게이팅.
`SessionStart` / `SessionEnd`	세션 경계에서.	세션 수준 상태 기록 또는 확인.

이벤트 가용성 및 차단 동작은 에이전트 하네스에 따라 다릅니다. 혼합 환경에서 이벤트에 의존하기 전에 에이전트 하네스를 확인하세요.

모든 정책 이벤트 이름

SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, UserPromptExpansion, PostToolBatch, Setup.

일반적인 정책 패턴 작성

보호된 경로에 대한 쓰기 차단

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

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

비차단 지침 제공

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

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

세션 완료 게이팅

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

Stop 이벤트가 거부되면 에이전트가 재시도할 수 있습니다. 현재 환경에서 에이전트가 충족할 수 있는 조건에만 게이팅하고, 모든 서브프로세스나 네트워크 호출에 제한을 두세요.

정책 파일 로드

컨벤션 파일

컨벤션 파일은 자동으로 로드됩니다:

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

프로젝트 및 사용자 정책 디렉토리가 모두 로드됩니다.
각 디렉토리 내에서 파일은 알파벳 순서로 로드됩니다.
파일은 반드시 policies.js, policies.mjs, 또는 policies.ts로 끝나야 합니다.
하나의 파일에서 customPolicies.add()를 여러 번 호출할 수 있습니다.
로컬 모듈에서의 상대 임포트를 지원합니다.
프로젝트 정책은 커밋할 수 있어 동일한 규칙이 레포지토리를 따라갑니다.

명시적 파일

유효성 검사나 설정에서 엔트리 파일을 직접 지정해야 할 때는 명시적 경로를 사용하세요:

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

명시적 파일이 먼저 로드되고, 이후 프로젝트 컨벤션 파일, 사용자 컨벤션 파일 순으로 로드됩니다. 두 경로 모두에서 발견된 파일은 한 번만 로드됩니다.

유효성 검사 및 테스트

유효성 검사는 프로덕션 로더를 통해 모듈을 실행하고 최소 하나의 정책이 등록되었는지 확인합니다.

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

유효성 검사는 누락된 파일, 구문 오류, 해결되지 않은 임포트, 최상위 예외, 모듈 로드 타임아웃을 감지합니다. 단, 매칭 로직의 정확성을 보장하지는 않습니다. 최소한 다음 케이스를 테스트하세요:

반드시 일치해야 하며 의도한 정책 이유를 생성하는 작업 하나.
유사하지만 안전한 작업으로 allow()를 반환해야 하는 케이스 하나.
누락되거나 잘못된 형식의 도구 필드.
대체 명령어 구문, 경로, 인용 방식, 대소문자, 공백.
사용 불가능한 서브프로세스 또는 네트워크 의존성.

Observe → policy에서 결과가 커스텀 정책에 귀속되는지 확인하세요. 다른 기본 제공 정책이 결정을 내린 경우, 차단된 테스트만으로는 충분하지 않습니다.

런타임 동작

기본 제공 정책이 커스텀 정책보다 먼저 평가됩니다.
첫 번째 deny가 발생하면 이후 정책 평가가 중단됩니다.
어떤 정책도 이벤트를 거부하지 않을 경우, 여러 instruct 결과가 결합될 수 있습니다.
정책 함수의 실행 제한 시간은 10초입니다.
예외가 발생하거나 타임아웃이 발생하면 로그에 기록되고 allow()로 처리됩니다.
로드에 실패한 컨벤션 파일은 건너뜁니다. 다른 커스텀 파일과 기본 제공 정책은 계속 실행됩니다.
최상위 모듈 로드에도 10초 제한 시간이 적용됩니다.
Cloud observe 모드에서는 정책을 실행하지만, allow가 아닌 결정은 기록만 하고 적용하지 않습니다.

정책 모듈은 결정론적이고 빠르게 유지하세요. 최상위 네트워크 호출이나 서버 시작을 피하세요. fn 내부의 작업을 제한하고, 의존성 실패를 캐치하며, 해당 실패가 작업을 허용할지 거부할지 신중하게 결정하세요.

API 익스포트

익스포트	용도
`customPolicies.add(policy)`	모듈이 로드될 때 커스텀 정책을 등록합니다.
`allow(reason?)`	작업을 허용합니다.
`instruct(reason)`	작업을 허용하고 지원되는 경우 지침을 제공합니다.
`deny(reason)`	지원되는 경우 작업을 차단합니다.
`getCustomHooks()`	모듈 레지스트리에 현재 등록된 정책을 반환합니다.
`clearCustomHooks()`	해당 레지스트리를 초기화합니다. 주로 테스트 및 로더에서 사용됩니다.

TypeScript는 PolicyContext, PolicyResult, CustomHook, PolicyDecision, PolicyFunction을 익스포트합니다.