failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/ko/configuration.mdx

@@ -0,0 +1,267 @@
+---
+title: 설정
+description: "설정 파일 형식, 세 가지 스코프 시스템, 그리고 병합 규칙"
+icon: gear
+---
+
+failproofai는 JSON 설정 파일을 사용하여 어떤 정책이 활성화될지, 정책이 어떻게 동작할지, 커스텀 정책을 어디서 불러올지를 제어합니다. 설정은 팀과 쉽게 공유할 수 있도록 설계되어 있습니다 — 저장소에 커밋하면 모든 개발자가 동일한 에이전트 안전망을 갖게 됩니다.
+
+---
+
+## 설정 스코프
+
+설정 스코프는 세 가지이며, 우선순위 순서대로 평가됩니다:
+
+| 스코프 | 파일 경로 | 목적 |
+|-------|-----------|---------|
+| **project** | `.failproofai/policies-config.json` | 저장소별 설정, 버전 관리에 커밋 |
+| **local** | `.failproofai/policies-config.local.json` | 개인 저장소별 재정의, gitignore 처리 |
+| **global** | `~/.failproofai/policies-config.json` | 모든 프로젝트에 걸친 사용자 수준 기본값 |
+
+failproofai가 훅 이벤트를 수신하면, 현재 작업 디렉터리에 존재하는 세 파일을 모두 불러와 병합합니다.
+
+### 병합 규칙
+
+**`enabledPolicies`** — 세 스코프의 합집합입니다. 어느 한 레벨에서라도 활성화된 정책은 모두 적용됩니다.
+
+```text
+project:  ["block-sudo"]
+local:    ["block-rm-rf"]
+global:   ["block-sudo", "sanitize-api-keys"]
+
+resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← 중복 제거된 합집합
+```
+
+**`policyParams`** — 특정 정책에 대한 파라미터를 먼저 정의한 스코프가 전적으로 우선합니다. 정책의 파라미터 내부 값은 깊은 병합(deep merge)이 이루어지지 않습니다.
+
+```text
+project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo apt-get update"] }   ← project가 우선, global은 무시됨
+```
+
+```text
+project:  (block-sudo 항목 없음)
+local:    (block-sudo 항목 없음)
+global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
+
+resolved: { allowPatterns: ["sudo systemctl status"] }  ← global까지 내려감
+```
+
+**`customPoliciesPaths` / `customPoliciesPath`** — 두 형태 중 어느 하나를 먼저 정의한 스코프가 우선합니다.
+
+**`disabledCustomPolicies`** — 모든 스코프의 합집합입니다. 명시적 또는 컨벤션 정책 파일에서 개별 정책을 비활성화하면 대시보드가 소스가 포함된 ID를 여기에 기록합니다. 목록에 없는 정책은 기본적으로 활성화 상태를 유지합니다. ID에는 소스 파일이 포함되어 있어, 여러 파일에 동일한 이름의 정책이 있더라도 독립적으로 제어할 수 있습니다.
+
+**`llm`** — 먼저 정의한 스코프가 우선합니다.
+
+---
+
+## 설정 파일 형식
+
+```json
+{
+  "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`에 표시되는 정책 식별자와 정확히 일치해야 합니다. 전체 목록은 [기본 제공 정책](/ko/built-in-policies)을 참조하세요.
+
+`enabledPolicies`에 없는 정책은 `policyParams`에 항목이 있더라도 비활성 상태입니다.
+
+### `policyParams`
+
+타입: `Record<string, Record<string, unknown>>`
+
+정책별 파라미터 재정의입니다. 외부 키는 정책 이름이고, 내부 키는 각 정책에 고유합니다. 각 정책의 사용 가능한 파라미터는 [기본 제공 정책](/ko/built-in-policies)에서 확인할 수 있습니다.
+
+파라미터가 있는 정책이라도 직접 지정하지 않으면 해당 정책의 기본값이 사용됩니다. `policyParams`를 전혀 설정하지 않은 사용자는 이전 버전과 동일하게 동작합니다.
+
+정책 파라미터 블록의 알 수 없는 키는 훅 실행 시에는 자동으로 무시되지만, `failproofai policies`를 실행할 때는 경고로 표시됩니다.
+
+#### `hint` (공통 옵션)
+
+타입: `string` (선택 사항)
+
+정책이 `deny` 또는 `instruct`를 반환할 때 사유에 추가되는 메시지입니다. 정책 자체를 수정하지 않고도 Claude에게 실행 가능한 안내를 제공할 수 있습니다.
+
+기본 제공 정책, 커스텀 정책(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 등 모든 정책 유형에서 동작합니다.
+
+```json
+{
+  "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>` 명령으로 자동 설정되며, 경로는 저장 전 절대 경로로 변환됩니다.
+
+이 파일은 훅 이벤트마다 새로 불러옵니다 — 캐싱이 없습니다. 작성 방법은 [커스텀 정책](/ko/custom-policies)을 참조하세요.
+
+### 컨벤션 기반 정책
+
+명시적인 `customPoliciesPath` 외에도, failproofai는 `.failproofai/policies/` 디렉터리에서 정책 파일을 자동으로 탐색하고 불러옵니다:
+
+| 레벨 | 디렉터리 | 스코프 |
+|-------|-----------|-------|
+| 프로젝트 | `.failproofai/policies/` | 버전 관리로 팀과 공유 |
+| 사용자 | `~/.failproofai/policies/custom-policies/` | 개인용, 모든 프로젝트에 적용 |
+
+<Note>
+  사용자 수준 디렉터리가 홈 디렉터리 재구성으로 한 단계 아래로 이동했습니다.
+  이전 경로인 `~/.failproofai/policies/`에 남아 있는 파일은 업그레이드 후
+  처음 `failproofai` 명령을 실행할 때 `custom-policies/`로 자동으로 이동되며,
+  어떤 파일이 이동됐는지 안내 메시지가 표시됩니다.
+</Note>
+
+**파일 매칭:** `*policies.{js,mjs,ts}` 패턴과 일치하는 파일만 불러옵니다(예: `security-policies.mjs`, `workflow-policies.js`). 디렉터리의 다른 파일은 무시됩니다.
+
+**설정 불필요:** 컨벤션 정책은 `policies-config.json`에 항목을 추가할 필요가 없습니다. 디렉터리에 파일을 넣기만 하면 다음 훅 이벤트 시 자동으로 인식됩니다.
+
+**합집합 로딩:** 프로젝트와 사용자 컨벤션 디렉터리가 모두 스캔됩니다. 두 레벨의 일치하는 파일이 모두 불러와집니다(`customPoliciesPath`는 첫 번째 스코프 우선이지만, 컨벤션 정책은 그렇지 않습니다).
+
+자세한 내용과 예시는 [커스텀 정책](/ko/custom-policies)을 참조하세요.
+
+### `llm`
+
+타입: `object` (선택 사항)
+
+AI 호출을 수행하는 정책을 위한 LLM 클라이언트 설정입니다. 대부분의 설정에서는 필요하지 않습니다.
+
+```json
+{
+  "llm": {
+    "model": "claude-sonnet-4-6",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+---
+
+## CLI에서 설정 관리
+
+`policies --install`과 `policies --uninstall` 명령은 에이전트 CLI의 훅 설정 파일(훅 진입점)에 쓰는 반면, `policies-config.json`은 직접 관리하는 파일입니다. 두 가지는 별개입니다:
+
+- **에이전트 CLI 설정** — 에이전트가 각 도구 사용 시 `failproofai --hook <event>`를 호출하도록 지시합니다:
+  - **Claude Code**: `~/.claude/settings.json` (user), `<cwd>/.claude/settings.json` (project), `<cwd>/.claude/settings.local.json` (local)
+  - **OpenAI Codex**: `~/.codex/hooks.json` (user), `<cwd>/.codex/hooks.json` (project) — Codex에는 `local` 스코프가 없음
+  - **GitHub Copilot CLI _(beta)_**: `~/.copilot/hooks/failproofai.json` (user), `<cwd>/.github/hooks/failproofai.json` (project) — Copilot에는 `local` 스코프가 없습니다. 훅 항목은 `timeoutSec`와 함께 Copilot의 OS별 `bash`/`powershell` 커맨드 필드를 사용하며, 파일에는 최상위 `version: 1` 마커가 있습니다. Copilot CLI 지원은 **beta** 단계로, 공개 문서에 명시되지 않은 `events.jsonl` 레코드 스키마를 더 많은 실제 세션을 통해 검증 중입니다. **VS Code Copilot Chat 에이전트 모드 (Preview)**는 `chat.hookFilesLocations` 설정에 따라 `.github/hooks/*.json`, `~/.copilot/hooks/*.json`, `~/.claude/settings.json`에서 훅 설정을 읽으며, Claude 형식의 `{hookSpecificOutput:{permissionDecision:"deny",…}}` 계약을 사용합니다 — 이는 `copilot` 통합과 `claude` 통합(`~/.claude/settings.json`)이 이미 쓰는 경로이므로, `failproofai policies --install --cli copilot` (또는 `--cli claude`)으로 별도의 `vscode` 통합 없이 **VS Code 에이전트 모드에서 이미 적용됩니다**(VS Code 검색 로그에서 확인됨).
+  - **Cursor Agent _(beta)_**: `~/.cursor/hooks.json` (user), `<cwd>/.cursor/hooks.json` (project) — Cursor에는 `local` 스코프가 없습니다. 훅 항목은 Claude 형식의 `{type, command, timeout}` 구조를 사용하지만(`bash`/`powershell` 분리 없음), Cursor의 [훅 스키마](https://cursor.com/docs/hooks)에 따라 camelCase 이벤트 키(`preToolUse`, `beforeSubmitPrompt`, …) 아래 평면 배열로 저장됩니다. 파일에는 최상위 `version: 1` 마커가 있습니다. 핸들러는 `CURSOR_EVENT_MAP`을 통해 camelCase를 PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 실행됩니다. Cursor Agent 지원은 **beta** 단계로, 공개 문서에 명시되지 않은 Cursor의 트랜스크립트 온디스크 형식을 더 많은 실제 설치를 통해 검증 중입니다.
+  - **OpenCode _(beta)_**: `~/.config/opencode/opencode.json` + `~/.config/opencode/plugins/failproofai.mjs` (user), `<cwd>/.opencode/opencode.json` + `<cwd>/.opencode/plugins/failproofai.mjs` (project) — OpenCode에는 `local` 스코프가 없습니다. 다른 다섯 CLI와 달리 OpenCode에는 **외부 명령 훅 시스템이 없습니다**: `opencode.json`의 `plugin: []` 배열을 통해 명시적으로 등록된 인프로세스 JS/TS 플러그인을 불러옵니다(`.opencode/plugins/`에서의 자동 검색은 opencode v1.14.33에서 플러그인 로드 방식이 **아닙니다**). 설치 시 failproofai 바이너리를 서브프로세스로 호출하고 바이너리의 Claude 형식 JSON 응답을 플러그인 시맨틱으로 변환하는 소형 생성 플러그인 심(shim)이 배포됩니다: 도구 이벤트 거부에는 `throw new Error()`(도구 호출 취소), instruct와 `Stop` / `SubagentStop` 거부에는 `client.session.prompt(...)`(거부 사유를 다음 사용자 메시지로 제출 — `session.idle`은 알림 전용이고 여기서 throw는 no-op이라 유일한 강제 재시도 채널), allow에는 no-op입니다. 심은 도구 이름(`OPENCODE_TOOL_MAP`을 통해 소문자 → PascalCase)과 도구 입력 인수 키(`OPENCODE_TOOL_INPUT_MAP`을 통해 `Read` / `Write` / `Edit`에 대해 camelCase → snake_case, 예: `filePath` → `file_path`, `oldString` → `old_string`)를 정규화한 후 바이너리에 전달하므로, `block-read-outside-cwd`, `block-env-files`, `block-secrets-write` 같은 경로 검사 기본 정책이 OpenCode 도구 호출에서 변경 없이 실행됩니다. 세션은 `~/.local/share/opencode/opencode.db`의 OpenCode SQLite DB에 저장되며, 대시보드의 세션 뷰어는 `opencode db --format json`과 `opencode export <id>`를 통해 이를 읽습니다. OpenCode 지원은 **beta** 단계로, 버전별 동작 및 더 많은 실제 세션을 통해 검증 중입니다. [OpenCode 플러그인 문서](https://opencode.ai/docs/plugins/)를 참조하세요.
+  - **Pi _(beta)_**: `~/.pi/agent/settings.json` (user), `<cwd>/.pi/settings.json` (project) — Pi에는 `local` 스코프가 없습니다. Pi는 시작 시 TypeScript 확장 패키지를 로드하며, 설정 파일은 `{"packages": ["./relative/path", …]}` 형태의 평면 문자열 배열입니다. failproofai는 번들된 `pi-extension/` 디렉터리를 가리키는 단일 packages-array 항목을 씁니다. 확장은 내부적으로 Pi의 `tool_call` / `user_bash` / `input` / `session_start` 이벤트를 구독하고 `failproofai --hook <Event> --cli pi`를 셸아웃합니다. 핸들러는 `PI_EVENT_MAP`을 통해 underscore_lower_snake_case를 PascalCase로 정규화하므로 기존 기본 제공 정책이 변경 없이 실행됩니다. 도구 입력 인수도 `PI_TOOL_INPUT_MAP`을 통해 정규화됩니다(Pi의 Read / Write / Edit는 `file_path` 대신 `path`를 사용하며, 최상위 키를 매핑하면 `block-env-files`와 `block-secrets-write`가 실행됩니다 — `block-read-outside-cwd`는 이미 `path` 폴백이 있었습니다). Pi 지원은 **beta** 단계로, Pi의 확장 API와 세션 로그 레이아웃이 안정화되는 동안 검증 중입니다.
+  - **Hermes (hermes-agent)**: `~/.hermes/config.yaml` (**user 스코프만** — Hermes에는 project/local 설정이 없음). Hermes는 Slack/Telegram **게이트웨이**이므로, 설치 한 번으로 모든 플랫폼(Slack/Telegram/cli/cron)의 도구 호출과 내부 서브에이전트를 가로챕니다. 훅 항목은 Hermes의 snake_case 이벤트(`pre_tool_call` / `post_tool_call` / `on_session_start` / `on_session_end` / `subagent_stop`)를 키로 하는 `hooks:` 맵 아래의 `{command, timeout}` 쌍이며, timeout은 **초** 단위입니다. 핸들러는 `HERMES_EVENT_MAP`을 통해 이벤트를, `HERMES_TOOL_MAP`을 통해 도구 이름을 정규화하므로 기본 제공 정책이 변경 없이 실행됩니다. 설정은 주석을 보존하는 YAML `Document` 라운드트립으로 편집되므로 운영자의 다른 설정이 유지되며, 설치 시 `hooks_auto_accept: true`를 설정하여 헤드리스 게이트웨이(TTY 없음)가 동의 프롬프트 없이 훅을 실행합니다. 평가자는 Hermes의 `{"decision":"block","reason"}` stdout 계약을 출력합니다(Hermes는 종료 코드를 무시합니다). **제한 사항:** Hermes에는 턴 종료 `Stop` 이벤트가 없으므로 `require-*-before-stop` 기본 정책이 실행되지 않습니다(적용 불가이지, 버그가 아님). `instruct`는 allow-with-logged-note로 성능이 저하됩니다(추가 컨텍스트 채널 없음). 출력 시크릿 편집(`sanitize-*`)은 셸 훅 계약을 통해 도구 출력을 재작성할 수 없습니다. Hermes는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.hermes/state.db`에서 게이트웨이 세션을 직접 읽습니다.
+  - **OpenClaw (openclaw gateway)**: `~/.openclaw/openclaw.json` (**user 스코프만** — OpenClaw에는 project/local 설정이 없음). Hermes처럼 OpenClaw도 자체 호스팅 멀티채널 **게이트웨이**이므로, 설치 한 번으로 모든 채널과 내부 서브에이전트의 도구 호출을 가로챕니다. 적용은 OpenClaw의 **인프로세스 플러그인 훅**을 통해 실행됩니다(파일 기반 내부 훅은 관찰 전용으로 차단 불가). 따라서 OpenCode/Pi와 마찬가지로 failproofai는 failproofai 바이너리를 비동기로 스폰하고 판정 결과를 변환하는 정적 `openclaw-plugin/` 패키지를 제공합니다. 설치 시 `openclaw.json`의 `plugins.load.paths[]`에 제공된 플러그인 디렉터리를 등록하고 `plugins.entries.failproofai` 아래에서 활성화합니다(`hooks.allowConversationAccess: true` 포함, 원시 대화 훅에 필요). 평가자는 평면 `{permission, reason}` 판정을 출력하고 심이 이를 각 훅의 네이티브 반환 형태로 매핑합니다: `before_tool_call → {block:true, blockReason}` (**PreToolUse**), `before_agent_run → {outcome:"block", reason}` (**UserPromptSubmit**), `before_agent_finalize → {action:"revise", reason}` (**Stop** — 실제 턴 종료 게이트이므로 `require-*-before-stop` 기본 정책이 Hermes와 달리 OpenClaw에서 **적용됩니다**). 이벤트와 도구 이름은 `OPENCLAW_EVENT_MAP` / `OPENCLAW_TOOL_MAP`(`exec→Bash`, `read→Read`, …)을 통해 바이너리 측에서 정규화되므로 기본 제공 정책이 변경 없이 실행됩니다. 심은 스폰/파싱/타임아웃 오류 시 열린 상태로 실패합니다. OpenClaw는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.openclaw/agents/<agentId>/sessions/<uuid>.jsonl`의 JSONL 세션을 읽습니다.
+  - **Factory Droid (`droid`)**: `~/.factory/hooks.json` (user), `<cwd>/.factory/hooks.json` (project) — Factory에는 `local` 스코프가 없습니다. droid는 Claude 형식의 외부 명령 훅 시스템을 제공하지만, droid v0.171.0에서 실제로 검증된 두 가지 특이점이 있습니다: (1) 이벤트 이름은 `hooks.json`의 **최상위 레벨**에 위치합니다 — **`"hooks"` 래퍼가 없습니다**(droid가 거부함). 도구 이벤트(`PreToolUse`/`PostToolUse`)는 `"matcher": "*"`를 포함하고, 비도구 이벤트는 생략합니다. (2) 거부는 JSON 결정이 아니라 훅 **종료 코드 2 + stderr**로 처리됩니다 — 평가자의 `factory` 브랜치는 도구/프롬프트 이벤트에 대해 종료 코드 2를 반환하고, 턴 종료 `Stop` 이벤트(droid의 유일한 강제 재시도 채널)에서만 `{decision:"block", reason}`을 반환합니다. 이벤트는 이미 PascalCase이며(이벤트 맵 불필요), 페이로드는 Claude snake_case입니다. 도구 이름만 `FACTORY_TOOL_MAP`(`Execute→Bash`, `Create→Write`, `FetchUrl→WebFetch`, …)을 통해 정규화됩니다. Factory는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.factory/sessions/<encoded-cwd>/<sessionId>.jsonl`의 온디스크 JSONL 세션을 읽습니다.
+  - **Devin CLI (`devin`, Cognition)**: `~/.config/devin/config.json` (user), `<cwd>/.devin/config.json` (project) — Devin에는 `local` 스코프가 없습니다. Devin은 devin v3000.1.27에서 실제로 검증된 **순수 Claude 클론**입니다: 표준 Claude `"hooks"` 래퍼 스키마를 사용하고(쓰기는 병합 보존 방식이라 설정 파일의 다른 키 — `org_id`, `theme_mode`, … — 가 유지됨), 이미 PascalCase 이벤트 이름(이벤트 맵 없음, 핸들러 브랜치 없음), Claude snake_case stdin 페이로드(정규화 불필요)를 사용합니다. 평가자의 `devin` 브랜치는 **모든** 이벤트에 대해 종료 코드 0에서 `{"decision":"block","reason"}` JSON을 stdout으로 출력하여 거부합니다(검증됨 — 블록이 `--permission-mode dangerous`를 재정의함). 턴 종료 `Stop` 이벤트에서는 `require-*-before-stop` 기본 정책이 적용되도록 사유에 MANDATORY-ACTION 강제 재시도 문구가 포함됩니다. 도구 이름만 `DEVIN_TOOL_MAP`(`exec→Bash`; `tool_input.command`는 이미 정규화됨)을 통해 정규화됩니다. Devin은 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/devin/cli/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에 실제 `working_directory`가 있어, Claude처럼 프로젝트 cwd별로 세션이 그룹화됨).
+  - **Antigravity CLI (`agy`)**: `~/.gemini/config/hooks.json` (user), `<cwd>/.agents/hooks.json` (project) — Antigravity에는 `local` 스코프가 없습니다. Factory/Devin과 달리 Antigravity는 agy v1.1.2에서 실제로 검증된 **자체 계약**(Claude 클론이 아님)을 사용합니다. `hooks.json`은 **이름 있는 훅** 스키마를 사용합니다: 최상위 키는 훅 *이름*(`"failproofai"`)이며, 그 값은 이벤트 → 핸들러 맵입니다 — 도구 이벤트(`PreToolUse`/`PostToolUse`)는 핸들러를 `{matcher:"*", hooks:[…]}`로 감싸고, `PreInvocation`/`Stop`은 **평면** 핸들러 배열입니다(다른 이름 있는 훅은 보존됩니다). stdin 페이로드는 **camelCase protojson** 형식(`toolCall:{name,args}`, `conversationId`, `workspacePaths`, `transcriptPath`)으로, failproofai는 정책 실행 전 이를 snake_case로 정규화하고 `run_command`의 PascalCase 인수(`CommandLine`/`Cwd`)를 `ANTIGRAVITY_TOOL_INPUT_MAP`으로 매핑합니다. 평가자의 `antigravity` 브랜치는 Antigravity의 **자체** 응답 형태를 사용합니다: `{decision:"deny", reason}`은 도구/프롬프트를 차단하고(종료 0), 턴 종료 `Stop`에서 `{decision:"continue", reason}`은 루프를 재진입하므로(`require-*-before-stop` 기본 정책이 적용됨), `{injectSteps:[{ephemeralMessage}]}`는 `PreInvocation`(→ `UserPromptSubmit`)에서 지시를 주입합니다. 도구 이름은 `ANTIGRAVITY_TOOL_MAP`(`run_command→Bash`, `view_file→Read`, …)을 통해 정규화됩니다. Antigravity는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript_full.jsonl`의 일반 JSONL 트랜스크립트를 읽습니다(대화 인덱스는 `conversation_summaries.db`에 있음).
+  - **Goose (codename goose, Block)**: `~/.agents/plugins/failproofai/hooks/hooks.json` (user), `<cwd>/.agents/plugins/failproofai/hooks/hooks.json` (project) — Goose에는 `local` 스코프가 없습니다. 적용은 Goose의 **훅** 시스템인 크로스에이전트 **Open Plugins** 스펙을 통해 이루어집니다: 설치 시 `failproofai` 플러그인 디렉터리만 배포하면 Goose가 시작 시 자동으로 검색합니다(이를 `~/.config/goose/config.yaml`에 자동 등록). `hooks.json`은 최상위 `"hooks"` 래퍼가 **있는** Open Plugins 스키마를 사용하며, **모든** 이벤트에서 matcher가 **생략됩니다** — 단순 `"*"`는 아무것도 일치하지 않는 잘못된 정규식입니다(goose v1.43.0에서 실제로 검증됨). 이벤트 이름은 이미 PascalCase이며(이벤트 맵 불필요), stdin 페이로드는 `event`/`working_dir`를 사용하고 핸들러가 이를 `hook_event_name`/`cwd`로 정규화합니다. 평가자의 `goose` 브랜치는 종료 코드 0에서 `{"decision":"block","reason"}` JSON을 stdout으로 출력하며, **`PreToolUse`** 이벤트에서만 적용됩니다(goose ≥ v1.37.0에 제공됨) — 이는 셸 도구와 **위임된 서브에이전트 내부** 모두에서 실행되므로 유일하게 충분한 거부 지점입니다. 다른 훅 오류는 **열린 상태로** 실패합니다. Goose에는 **`Stop` 이벤트가 없으므로** `require-*-before-stop` 기본 정책이 적용되지 않습니다(Hermes와 동일). 도구 이름은 `GOOSE_TOOL_MAP`(`shell→Bash`, `write→Write`, `todo__todo_write→TodoWrite`, …)을 통해, 경로 키는 `GOOSE_TOOL_INPUT_MAP`(`path`/`source` → `file_path`)을 통해 정규화됩니다. Goose는 **오프라인 감사** 소스이기도 합니다 — 대시보드는 `~/.local/share/goose/sessions/sessions.db`의 SQLite 세션을 읽습니다(각 `sessions` 행에 실제 `working_dir`가 있어 Devin처럼 프로젝트 cwd별로 세션이 그룹화됨. `--no-session` 임시 실행은 필터링됨).
+- **`policies-config.json`** — failproofai가 어떤 정책을 어떤 파라미터로 평가할지 지시합니다(모든 에이전트 CLI에서 공유)
+
+특정 에이전트를 지정하려면 `--cli claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`를 전달하세요(공백으로 구분하거나 반복 사용하여 부분 집합 지정 가능):
+
+```bash
+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 hermes --scope user
+failproofai policies --install --cli openclaw --scope user
+failproofai policies --install --cli factory --scope project
+failproofai policies --install --cli devin --scope project
+failproofai policies --install --cli antigravity --scope project
+failproofai policies --install --cli goose --scope project
+failproofai policies --install --cli claude codex copilot cursor opencode pi hermes openclaw factory devin antigravity goose
+```
+
+`--cli`를 생략하면 `failproofai`가 설치된 에이전트 CLI를 자동으로 감지합니다(`which claude` / `which codex` / `which copilot` / `which cursor-agent` / `which opencode` / `which pi` / `which hermes` / `which openclaw` / `which droid` / `which devin` / `which agy` / `which goose`):
+
+- **CLI 하나 감지** — 프롬프트 없이 해당 CLI를 자동으로 선택합니다.
+- **여러 CLI 감지** (인터랙티브 터미널) — `Detected (N)` 섹션(`Install for all N detected` 통합 행 + 감지된 각 CLI)과 `Not installed (M) · install hooks ahead of time` 섹션(감지되지 않은 모든 지원 CLI를 사전 설치 옵션으로 표시)으로 구성된 화살표 키 단일 선택 프롬프트를 표시합니다(↑↓로 이동, Enter로 선택, ^C로 종료). 제거 흐름에서는 Detected 섹션만 표시합니다.
+- **여러 CLI 감지** (비인터랙티브 실행, TTY 없음 — CI 등) — 프롬프트 없이 감지된 모든 CLI에 설치합니다.
+- **감지 없음** — `claude`로 폴백하며, PATH에서 에이전트 바이너리를 찾을 수 없다는 경고를 표시합니다. 훅 명령은 그래도 기록되어, 설치 후 즉시 활성화됩니다.
+
+`policies-config.json`은 언제든지 직접 편집할 수 있으며, 재시작 없이 다음 훅 이벤트부터 즉시 변경 사항이 적용됩니다.
+
+---
+
+## 예시: 팀 기본값이 포함된 프로젝트 수준 설정
+
+`.failproofai/policies-config.json`을 저장소에 커밋하세요:
+
+```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 처리됨)을 별도로 만들 수 있습니다.

package/.next/standalone/docs-old/ko/custom-policies.mdx

@@ -0,0 +1,358 @@
+---
+title: 커스텀 정책
+description: "JavaScript로 직접 정책 작성 - 컨벤션 강제, 드리프트 방지, 실패 감지, 외부 시스템 연동"
+icon: code
+---
+
+커스텀 정책을 사용하면 에이전트 동작에 관한 규칙을 직접 작성할 수 있습니다. 프로젝트 컨벤션 강제, 드리프트 방지, 위험한 작업 차단, 멈춘 에이전트 감지, Slack 연동, 승인 워크플로우 등 다양한 용도로 활용할 수 있습니다. 내장 정책과 동일한 훅 이벤트 시스템과 `allow`, `deny`, `instruct` 결정 방식을 사용합니다.
+
+---
+
+## 빠른 예시
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+설치:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## 커스텀 정책을 로드하는 두 가지 방법
+
+### 옵션 1: 컨벤션 기반 (권장)
+
+`.failproofai/policies/` 디렉터리에 `*policies.{js,mjs,ts}` 파일을 추가하면 자동으로 로드됩니다 — 별도 플래그나 설정 변경이 필요 없습니다. git hooks처럼 파일을 추가하기만 하면 바로 동작합니다.
+
+```
+# 프로젝트 레벨 — git에 커밋되어 팀과 공유
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# 사용자 레벨 — 개인용, 모든 프로젝트에 적용
+~/.failproofai/policies/my-policies.mjs
+```
+
+**동작 방식:**
+- 프로젝트 및 사용자 디렉터리 모두 스캔됨 (합집합 방식 — 첫 번째 스코프 우선이 아님)
+- 각 디렉터리 내에서 파일은 알파벳 순으로 로드됨. 순서 조정이 필요하면 `01-`, `02-` 등의 접두사 사용
+- `*policies.{js,mjs,ts}` 패턴에 매칭되는 파일만 로드되며, 그 외 파일은 무시됨
+- 각 파일은 독립적으로 로드됨 (파일 단위 fail-open)
+- 명시적 `--custom` 및 내장 정책과 함께 동작
+
+<Tip>
+컨벤션 정책은 조직의 품질 기준을 세우는 가장 쉬운 방법입니다. `.failproofai/policies/`를 git에 커밋하면 모든 팀원이 별도 설정 없이 동일한 규칙을 자동으로 적용받습니다. 새로운 실패 패턴을 발견할 때마다 정책을 추가하고 푸시하세요. 시간이 지날수록 팀의 기여로 점점 개선되는 살아있는 품질 기준이 됩니다.
+</Tip>
+
+### 옵션 2: 명시적 파일 경로
+
+```bash
+# 커스텀 정책 파일로 설치
+failproofai policies --install --custom ./my-policies.js
+
+# 커스텀 정책 경로 교체
+failproofai policies --install --custom ./new-policies.js
+
+# 여러 파일 설정 (플래그 순서대로 로드)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# 설정에서 모든 명시적 커스텀 정책 경로 제거
+failproofai policies --uninstall --custom
+```
+
+해석된 절대 경로는 `policies-config.json`에 `customPoliciesPaths`로 저장됩니다. 여러 파일을 설정하려면 `--custom`을 반복해서 사용하세요. 레거시 `customPoliciesPath` 필드를 사용하는 기존 설정도 계속 동작합니다. 파일은 훅 이벤트마다 새로 로드되며 — 이벤트 간 캐싱은 없습니다.
+
+등록된 각 정책은 대시보드에서 개별 토글로 표시됩니다. 정책을 비활성화하면 소스 한정 ID가 `disabledCustomPolicies`에 기록되고, 해당 파일과 다른 정책들은 계속 로드되지만 비활성화된 정책은 이벤트 매칭 전에 제외됩니다. 파일이 달라도 같은 이름의 정책은 각각 독립적인 토글을 갖습니다.
+
+### 두 방법 함께 사용하기
+
+컨벤션 정책과 명시적 `--custom` 파일은 함께 사용할 수 있습니다. 로드 순서:
+
+1. 명시적 `customPoliciesPaths` 파일 (설정된 순서)
+2. 프로젝트 컨벤션 파일 (`{cwd}/.failproofai/policies/`, 알파벳 순)
+3. 사용자 컨벤션 파일 (`~/.failproofai/policies/`, 알파벳 순)
+
+---
+
+## API
+
+### 가져오기
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+정책을 등록합니다. 같은 파일에 여러 정책을 등록하려면 원하는 만큼 호출하세요.
+
+```ts
+customPolicies.add({
+  name: string;                         // 필수 - 고유 식별자
+  description?: string;                 // `failproofai policies` 출력에 표시됨
+  match?: { events?: HookEventType[] }; // 이벤트 타입으로 필터링; 생략하면 모든 이벤트에 매칭
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### 결정 헬퍼
+
+| 함수 | 효과 | 사용 시점 |
+|----------|--------|----------|
+| `allow()` | 작업을 조용히 허용 | 작업이 안전하며 메시지가 필요 없을 때 |
+| `deny(message)` | 작업 차단 | 에이전트가 이 작업을 수행하지 않아야 할 때 |
+| `instruct(message)` | 차단 없이 컨텍스트 추가 | 에이전트가 올바른 방향을 유지하도록 추가 컨텍스트를 제공할 때 |
+
+`deny(message)` — 메시지는 `"Blocked by failproofai:"` 접두사와 함께 Claude에 표시됩니다. 하나의 `deny`가 발생하면 이후 모든 평가가 단락됩니다.
+
+`instruct(message)` — 메시지는 현재 툴 호출에 대한 Claude의 컨텍스트에 추가됩니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
+
+<Tip>
+`policyParams`의 `hint` 필드를 추가하면 코드 변경 없이 `deny` 또는 `instruct` 메시지에 추가 안내를 덧붙일 수 있습니다. 커스텀(`custom/`), 프로젝트 컨벤션(`.failproofai-project/`), 사용자 컨벤션(`.failproofai-user/`) 정책 모두에서 동작합니다. 자세한 내용은 [Configuration → hint](/ko/configuration#hint-cross-cutting)를 참고하세요.
+</Tip>
+
+### 정보성 allow 메시지
+
+`allow(message)`는 작업을 허용하면서 **동시에** Claude에 정보성 메시지를 전송합니다. 메시지는 훅 핸들러의 stdout 응답에서 `additionalContext`로 전달됩니다 — `instruct`와 동일한 메커니즘이지만 의미상 차이가 있습니다. 경고가 아닌 상태 업데이트입니다.
+
+| 함수 | 효과 | 사용 시점 |
+|----------|--------|----------|
+| `allow(message)` | 허용하면서 Claude에 컨텍스트 전송 | 검사 통과를 확인하거나 검사를 건너뛴 이유를 설명할 때 |
+
+사용 사례:
+- **상태 확인:** `allow("All CI checks passed.")` — Claude에 모든 것이 정상임을 알림
+- **Fail-open 설명:** `allow("GitHub CLI not installed, skipping CI check.")` — 검사를 건너뛴 이유를 Claude에 알려 완전한 컨텍스트 제공
+- **메시지 누적:** 여러 정책이 각각 `allow(message)`를 반환하면 모든 메시지가 줄바꿈으로 합쳐져 함께 전달됨
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
+
+### `PolicyContext` 필드
+
+| 필드 | 타입 | 설명 |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | 호출되는 툴 (예: `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | 툴의 입력 파라미터 |
+| `payload` | `Record<string, unknown>` | Claude Code에서 전달된 전체 원시 이벤트 페이로드 |
+| `session` | `SessionMetadata \| undefined` | 세션 컨텍스트 (아래 참고) |
+
+### `SessionMetadata` 필드
+
+| 필드 | 타입 | 설명 |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code 세션 식별자 |
+| `cwd` | `string` | Claude Code 세션의 작업 디렉터리 |
+| `transcriptPath` | `string` | 세션의 JSONL 트랜스크립트 파일 경로 |
+
+### 이벤트 타입
+
+| 이벤트 | 발생 시점 | `toolInput` 내용 |
+|-------|--------------|----------------------|
+| `PreToolUse` | Claude가 툴을 실행하기 전 | 툴의 입력 (예: Bash의 경우 `{ command: "..." }`) |
+| `PostToolUse` | 툴 실행 완료 후 | 툴의 입력 + `tool_result` (출력) |
+| `Notification` | Claude가 알림을 보낼 때 | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - 훅은 반드시 `allow()`를 반환해야 하며, 알림을 차단할 수 없음 |
+| `Stop` | Claude 세션이 종료될 때 | 비어있음 |
+
+---
+
+## 평가 순서
+
+정책은 다음 순서로 평가됩니다:
+
+1. 내장 정책 (정의 순서)
+2. `customPoliciesPath`의 명시적 커스텀 정책 (`.add()` 순서)
+3. 프로젝트 `.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서)
+4. 사용자 `~/.failproofai/policies/`의 컨벤션 정책 (파일 알파벳 순, 파일 내 `.add()` 순서)
+
+<Note>
+첫 번째 `deny`가 이후 모든 정책을 단락시킵니다. 모든 `instruct` 메시지는 누적되어 함께 전달됩니다.
+</Note>
+
+---
+
+## 전이적 가져오기
+
+커스텀 정책 파일은 상대 경로를 사용하여 로컬 모듈을 가져올 수 있습니다:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+엔트리 파일에서 접근 가능한 모든 상대 가져오기가 해석됩니다. 이는 `from "failproofai"` 가져오기를 실제 dist 경로로 재작성하고 ESM 호환성을 위해 임시 `.mjs` 파일을 생성하는 방식으로 구현됩니다.
+
+---
+
+## 이벤트 타입 필터링
+
+`match.events`를 사용하여 정책이 발동되는 시점을 제한할 수 있습니다:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // 세션이 종료될 때만 발동됨
+    // ctx.session.transcriptPath에 전체 세션 로그가 포함됨
+    return allow();
+  },
+});
+```
+
+모든 이벤트 타입에서 발동시키려면 `match`를 완전히 생략하세요.
+
+---
+
+## 오류 처리 및 실패 모드
+
+커스텀 정책은 **fail-open** 방식입니다. 오류가 발생해도 내장 정책이 차단되거나 훅 핸들러가 크래시되지 않습니다.
+
+| 실패 원인 | 동작 |
+|---------|----------|
+| `customPoliciesPath` 미설정 | 명시적 커스텀 정책 미실행; 컨벤션 정책 및 내장 정책은 정상 계속 |
+| 파일을 찾을 수 없음 | `~/.failproofai/hook.log`에 경고 기록; 내장 정책 계속 |
+| 구문/가져오기 오류 (명시적) | `~/.failproofai/hook.log`에 오류 기록; 명시적 커스텀 정책 건너뜀 |
+| 구문/가져오기 오류 (컨벤션) | 오류 기록; 해당 파일 건너뜀, 다른 컨벤션 파일은 계속 로드 |
+| `fn` 런타임 오류 | 오류 기록; 해당 훅은 `allow`로 처리; 다른 훅 계속 |
+| `fn` 10초 초과 | 타임아웃 기록; `allow`로 처리 |
+| 컨벤션 디렉터리 없음 | 컨벤션 정책 미실행; 오류 없음 |
+
+<Tip>
+커스텀 정책 오류를 디버그하려면 로그 파일을 실시간으로 확인하세요:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## 전체 예시: 여러 정책
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// 에이전트가 secrets/ 디렉터리에 쓰는 것을 방지
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// 에이전트 방향 유지: 커밋 전 테스트 확인
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// 동결 기간 중 계획되지 않은 의존성 변경 방지
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## 예시 파일
+
+`examples/` 디렉터리에 바로 사용할 수 있는 정책 파일이 포함되어 있습니다:
+
+| 파일 | 내용 |
+|------|----------|
+| `examples/policies-basic.js` | 일반적인 에이전트 실패 패턴을 다루는 5가지 기본 정책 |
+| `examples/policies-advanced/index.js` | 고급 패턴: 전이적 가져오기, 비동기 호출, 출력 스크러빙, 세션 종료 훅 |
+| `examples/convention-policies/security-policies.mjs` | 컨벤션 기반 보안 정책 (.env 파일 쓰기 차단, git 히스토리 재작성 방지) |
+| `examples/convention-policies/workflow-policies.mjs` | 컨벤션 기반 워크플로우 정책 (테스트 리마인더, 감사 파일 쓰기) |
+
+### 명시적 파일 예시 사용
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### 컨벤션 기반 예시 사용
+
+```bash
+# 프로젝트 레벨로 복사
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# 또는 사용자 레벨로 복사
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+별도 설치 명령이 필요 없습니다 — 다음 훅 이벤트 시 파일이 자동으로 감지됩니다.