failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/ko/built-in-policies.mdx

@@ -0,0 +1,854 @@
+---
+title: 기본 제공 정책
+description: "일반적인 에이전트 오류 패턴을 감지하는 39개의 기본 제공 정책"
+icon: shield
+---
+
+failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 39개의 기본 제공 정책이 포함되어 있습니다. 각 정책은 특정 훅 이벤트 유형 및 도구 이름에 따라 작동합니다. 19개의 정책은 코드를 작성하지 않고도 동작을 조정할 수 있는 매개변수를 지원합니다. 5개의 워크플로 정책은 Claude가 중지되기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다.
+
+---
+
+## 개요
+
+정책은 다음 카테고리로 분류됩니다:
+
+| 카테고리 | 정책 | 훅 유형 |
+|----------|----------|-----------|
+| [위험한 명령어](#dangerous-commands) | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands, block-self-pause | PreToolUse |
+| [인프라 명령어](#infra-commands) | block-kubectl, block-terraform, block-aws-cli, block-gcloud, block-az-cli, block-helm, block-gh-pipeline | PreToolUse |
+| [시크릿 (새니타이저)](#secrets-sanitizers) | sanitize-jwt, sanitize-api-keys, sanitize-connection-strings, sanitize-private-key-content, sanitize-bearer-tokens | PostToolUse |
+| [환경](#environment) | block-env-files, protect-env-vars | PreToolUse |
+| [파일 접근](#file-access) | block-read-outside-cwd, block-secrets-write | PreToolUse |
+| [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
+| [데이터베이스](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
+| [경고](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [패키지 매니저](#package-managers) | prefer-package-manager | PreToolUse |
+| [워크플로](#workflow) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-no-conflicts-before-stop, require-ci-green-before-stop | Stop |
+
+- **`block-`** — 에이전트의 진행을 차단합니다.
+- **`warn-`** — 에이전트가 스스로 수정할 수 있도록 추가 컨텍스트를 제공합니다.
+- **`sanitize-`** — 에이전트가 보기 전에 도구 출력에서 민감한 데이터를 제거합니다.
+
+### 네임스페이스
+
+모든 정책은 `<namespace>/<name>` 슬롯에 위치합니다. 기본 제공 정책은
+**`failproofai/`** 네임스페이스에 속합니다 — 예를 들어 `failproofai/sanitize-jwt`. 이
+네임스페이스는 유사한 짧은 이름을 가진 커스텀 또는 서드파티 정책을 함께 로드할 때
+충돌을 방지합니다.
+
+설정에서 기본 제공 정책은 짧은 이름 또는 전체 한정 이름으로 참조할 수 있으며,
+두 형식 모두 동일한 정책으로 해석됩니다:
+
+```json
+{
+  "enabledPolicies": [
+    "sanitize-jwt",
+    "failproofai/block-rm-rf"
+  ]
+}
+```
+
+이름에 `/`가 없으면 failproofai는 기본 네임스페이스인 `failproofai`에 속하는
+것으로 처리합니다. 이미 `/`를 포함하는 이름(예: `myorg/foo`,
+`custom/my-hook`)은 그대로 유지됩니다.
+- **`require-`** — 조건이 충족될 때까지 Stop 이벤트를 차단합니다.
+
+---
+
+<Tip>
+모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 받는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 기본 제공, 커스텀, 컨벤션 정책 모두에서 동작합니다. 자세한 내용은 [구성 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요.
+</Tip>
+
+---
+
+## 위험한 명령어
+
+에이전트가 되돌리기 어렵거나 호스트 시스템을 손상시킬 수 있는 작업을 실행하지 못하도록 방지합니다.
+
+### `block-sudo`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `sudo` 또는 `doas` 명령어를 거부합니다.
+
+**명령 위치**에서 권한 상승 바이너리를 실행하는 명령어를 차단합니다. 매칭은 텍스트 기반이 아닌 구조적 방식으로 이루어집니다: 명령어는 쉘이 처리하는 방식으로 세그먼트로 분리되고, 접두사 할당(`FOO=bar`), 리다이렉션, 플래그가 포함된 실행기(`env`, `nohup`, `timeout`, `xargs`, `sh -c` 등)가 제거된 후 결과 바이너리를 **basename** 기준으로 비교합니다. 따라서 `/usr/bin/sudo`, `env sudo`, `timeout 5 sudo`, `"sudo"`, `\sudo`, `bash -c "sudo …"` 모두 거부되며, `doas`도 다른 이름의 동일한 권한으로 처리됩니다.
+
+명령어 위치를 기준으로 하므로, 단순히 해당 단어가 포함된 명령어에는 **작동하지 않습니다** — `grep -r sudo /etc`, `cat /etc/sudoers`, `git commit -m "fix sudo handling"`, 또는 해당 단어를 포함한 `grep` 교차 표현은 정상적으로 실행됩니다.
+
+<Warning>
+이 정책은 명백한 시도를 차단하지만 모든 경우를 막지는 않습니다. 임의의 쉘 명령을 실행할 수 있는 에이전트는 변수(`S=sudo; $S …`), base64 디코딩 파이프, 또는 디스크의 래퍼 스크립트를 통해 간접적으로 권한 상승에 도달할 수 있습니다 — 단일 명령 문자열 검사로는 이러한 경로를 추적할 수 없기 때문입니다. 이 정책은 실수와 우발적인 권한 상승에 대한 가드레일로 취급하세요. 결정적인 에이전트에 대한 보안 경계로는 적합하지 않습니다. 실제 경계는 쉘 아래 레벨에서 강제되어야 합니다.
+</Warning>
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 정확한 명령어 접두사. 각 항목은 파싱된 argv 토큰과 대조됩니다. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+    }
+  }
+}
+```
+
+이 설정에서 `sudo systemctl status nginx`는 허용되지만 `sudo rm /etc/hosts`는 거부됩니다.
+
+<Note>
+패턴은 원시 명령 문자열이 아닌 파싱된 토큰과 대조됩니다. 이를 통해 추가된 쉘 연산자를 통한 우회를 방지합니다 (예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않습니다).
+</Note>
+
+---
+
+### `block-rm-rf`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `rm -rf`, `rm -fr` 및 유사한 재귀 삭제 형식을 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | 재귀 삭제가 허용되는 경로 (예: `/tmp`). |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-rm-rf": {
+      "allowPaths": ["/tmp", "/var/cache"]
+    }
+  }
+}
+```
+
+---
+
+### `block-curl-pipe-sh`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` 및 유사한 패턴을 거부합니다.
+
+매개변수 없음.
+
+---
+
+### `block-failproofai-commands`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** failproofai 자체를 제거하거나 비활성화하는 명령어를 거부합니다 (예: `npm uninstall failproofai`, `failproofai policies --uninstall`).
+
+매개변수 없음.
+
+---
+
+### `block-self-pause`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 세션의 적용을 일시 중단하는 `failproofai config --pause`를 거부합니다. 일시 중지는 사람이 결정해야 할 사항으로, 에이전트가 이를 실행할 수 있다면 단 하나의 명령으로 다른 모든 정책을 비활성화할 수 있습니다.
+
+[`block-failproofai-commands`](#block-failproofai-commands)보다 의도적으로 범위가 좁으며, 해당 정책에 포함되지 않습니다: 그 정책은 명령 경계를 기준으로 하므로 `npx -y failproofai config --pause`와 매칭되지 않고, 범위가 넓어 에이전트가 `failproofai audit`을 실행할 수 있도록 종종 비활성화됩니다. `--resume`과 `--status`는 허용됩니다 — 둘 다 적용을 제거하지 않습니다.
+
+이 정책은 직접적인 시도를 차단하지만 전체 경우를 막지는 않습니다: 에이전트는 여전히 별칭이나 래퍼 스크립트를 통해 동일한 상태에 도달할 수 있습니다. 완전히 차단하려면 도구 호출에서 일시 중지 기능 자체에 접근할 수 없어야 합니다.
+
+매개변수 없음.
+
+---
+
+## 인프라 명령어
+
+코딩 에이전트가 인프라 CLI를 실행하거나 CI/CD 파이프라인을 트리거하지 못하도록 방지합니다. 이 카테고리의 모든 정책은 **옵트인** (`defaultEnabled: false`) 방식입니다 — `kubectl`, `terraform` 등을 합법적으로 호출해야 하는 에이전트는 정책을 활성화하지 않는 한 영향을 받지 않습니다. 활성화되면 명령이 `allowPatterns`의 항목과 일치하지 않는 한 매칭된 CLI의 모든 호출이 거부됩니다.
+
+패턴 문법은 [`block-sudo`](#block-sudo)와 동일합니다: 토큰은 파싱된 argv와 대조되고, `*`는 단일 토큰에 대한 와일드카드이며, 독립적인 쉘 연산자(`&&`, `||`, `|`, `;`)를 포함하거나 내장된 쉘 메타문자를 포함하는 토큰이 있는 명령어는 인젝션 우회를 방지하기 위해 허용 목록 매칭 전에 거부됩니다.
+
+### `block-kubectl`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 모든 `kubectl` 호출을 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 kubectl 명령어 접두사. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-kubectl": {
+      "allowPatterns": ["kubectl get *", "kubectl describe *", "kubectl logs *"]
+    }
+  }
+}
+```
+
+이 설정에서 `kubectl get pods`는 허용되지만 `kubectl apply -f deploy.yaml`은 거부됩니다.
+
+---
+
+### `block-terraform`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 모든 `terraform` 또는 `tofu` (OpenTofu) 호출을 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 terraform/tofu 명령어 접두사. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-terraform": {
+      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-aws-cli`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 모든 `aws` CLI 호출을 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 aws CLI 명령어 접두사. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-aws-cli": {
+      "allowPatterns": ["aws s3 ls *", "aws sts get-caller-identity"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gcloud`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 모든 `gcloud` (Google Cloud) CLI 호출을 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 gcloud 명령어 접두사. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-gcloud": {
+      "allowPatterns": ["gcloud auth list", "gcloud config list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-az-cli`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 모든 `az` (Azure) CLI 호출을 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 az CLI 명령어 접두사. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-az-cli": {
+      "allowPatterns": ["az account show", "az group list"]
+    }
+  }
+}
+```
+
+---
+
+### `block-helm`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 모든 `helm` 호출을 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 허용되는 helm 명령어 접두사. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-helm": {
+      "allowPatterns": ["helm list", "helm status *"]
+    }
+  }
+}
+```
+
+---
+
+### `block-gh-pipeline`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 상태를 변경하거나 파이프라인을 트리거하는 다음 `gh` CLI 서브커맨드를 거부합니다:
+
+- `gh workflow run`, `gh workflow enable`, `gh workflow disable`
+- `gh run rerun`, `gh run cancel`
+- `gh pr merge`
+- `gh release create`, `gh release delete`
+- `gh cache delete`
+- `gh secret set`, `gh secret delete`
+
+`gh pr view`, `gh pr list`, `gh run list`, `gh release view`, `gh api repos/.../...`와 같은 읽기 전용 `gh` 서브커맨드는 이 정책에서 **매칭되지 않습니다** — 이러한 명령은 워크플로 확인(failproofai의 `require-ci-green-before-stop` 포함)에 일상적으로 필요합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPatterns` | `string[]` | `[]` | 일반적으로 거부되더라도 허용할 특정 스크립트 호출. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-gh-pipeline": {
+      "allowPatterns": ["gh run rerun *"]
+    }
+  }
+}
+```
+
+---
+
+## 시크릿 (새니타이저)
+
+에이전트가 자격 증명을 컨텍스트나 출력에 노출하지 못하도록 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 작동합니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출하면 이 정책들이 출력이 Claude에게 반환되기 전에 검사합니다. 시크릿 패턴이 감지되면 출력이 전달되는 것을 방지하는 deny 결정을 반환합니다.
+
+### `sanitize-jwt`
+
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** JWT 토큰(`.`으로 구분된 세 개의 base64url 세그먼트)을 삭제합니다.
+
+매개변수 없음.
+
+---
+
+### `sanitize-api-keys`
+
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** 일반적인 API 키 형식을 삭제합니다: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), AWS 액세스 키 (`AKIA`), Stripe 키 (`sk_live_`, `sk_test_`), Google API 키 (`AIza`).
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `{ regex: string; label: string }[]` | `[]` | 시크릿으로 처리할 추가 정규식 패턴. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "sanitize-api-keys": {
+      "additionalPatterns": [
+        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo internal API key" },
+        { "regex": "pat_[0-9a-f]{40}", "label": "Internal PAT" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `sanitize-connection-strings`
+
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** 자격 증명이 내장된 데이터베이스 연결 문자열을 삭제합니다 (예: `postgresql://user:password@host/db`).
+
+매개변수 없음.
+
+---
+
+### `sanitize-private-key-content`
+
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** PEM 블록(`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` 등)을 삭제합니다.
+
+매개변수 없음.
+
+---
+
+### `sanitize-bearer-tokens`
+
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** 토큰이 20자 이상인 `Authorization: Bearer <token>` 헤더를 삭제합니다.
+
+매개변수 없음.
+
+---
+
+## 환경
+
+에이전트가 민감한 환경 설정을 읽거나 노출하지 못하도록 보호합니다.
+
+### `block-env-files`
+
+**이벤트:** PreToolUse (Bash, Read)  
+**기본값:** `cat .env`, `.env`를 파일 경로로 하는 `Read` 도구 호출 등을 통해 `.env` 파일을 읽는 것을 거부합니다.
+
+`.envrc` 또는 다른 환경 관련 파일은 차단하지 않습니다 - 정확히 `.env`라는 이름의 파일만 차단합니다.
+
+매개변수 없음.
+
+---
+
+### `protect-env-vars`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 환경 변수를 출력하는 명령어를 거부합니다: `printenv`, `env`, `echo $VAR`.
+
+매개변수 없음.
+
+---
+
+## 파일 접근
+
+에이전트가 프로젝트 경계 내에서 작업하고 민감한 파일에 접근하지 못하도록 합니다.
+
+### `block-read-outside-cwd`
+
+**이벤트:** PreToolUse (Read, Bash)  
+**기본값:** 프로젝트 루트 외부의 파일 읽기를 거부합니다. 경계는 `CLAUDE_PROJECT_DIR` (Claude Code에 의해 세션당 한 번 설정됨)이며, 해당 변수가 설정되지 않은 경우 세션의 현재 작업 디렉토리로 대체됩니다. 현재 `cwd` 대신 프로젝트 루트를 사용하므로 Claude가 하위 디렉토리로 `cd`하더라도 경계가 안정적으로 유지됩니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `allowPaths` | `string[]` | `[]` | 프로젝트 루트 외부에 있더라도 허용되는 절대 경로 접두사. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-read-outside-cwd": {
+      "allowPaths": ["/shared/data", "/opt/company/config"]
+    }
+  }
+}
+```
+
+---
+
+### `block-secrets-write`
+
+**이벤트:** PreToolUse (Write, Edit)  
+**기본값:** 개인 키 및 인증서에 일반적으로 사용되는 파일에 대한 쓰기를 거부합니다: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일명 패턴 (글로브 스타일). |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-secrets-write": {
+      "additionalPatterns": [".token", ".secret"]
+    }
+  }
+}
+```
+
+---
+
+## Git
+
+되돌리기 어려운 실수적인 푸시, 강제 푸시, 브랜치 오류를 방지합니다.
+
+### `block-push-master`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `git push origin main` 및 `git push origin master`를 거부합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | 직접 푸시할 수 없는 브랜치 이름. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release", "prod"]
+    }
+  }
+}
+```
+
+<Tip>
+모든 브랜치로의 푸시를 허용하려면 (실질적으로 `enabledPolicies`에서 제거하지 않고 이 정책을 비활성화), `protectedBranches: []`로 설정하세요.
+</Tip>
+
+---
+
+### `block-work-on-main`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 작업 트리가 `main` 또는 `master`에 있는 동안 `git commit`, `git merge`, `git rebase`, `git cherry-pick`을 거부합니다. 브랜치 생성 및 전환(`git checkout`, `git checkout -b`, `git switch`, `git switch -c`)은 영향을 받지 않습니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `protectedBranches` | `string[]` | `["main", "master"]` | 커밋/머지/리베이스/체리픽이 거부되는 브랜치 이름. |
+
+---
+
+### `block-force-push`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `git push --force` 및 `git push -f`를 거부합니다.
+
+정책 전용 매개변수 없음. 대안을 제안하려면 범용 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하세요:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
+    }
+  }
+}
+```
+
+---
+
+### `warn-git-amend`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `git commit --amend` 실행 시 Claude에게 신중하게 진행하도록 안내합니다. 명령을 차단하지는 않습니다.
+
+매개변수 없음.
+
+---
+
+### `warn-git-stash-drop`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `git stash drop` 실행 전 Claude에게 확인하도록 안내합니다. 명령을 차단하지는 않습니다.
+
+매개변수 없음.
+
+---
+
+### `warn-all-files-staged`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `git add -A` 또는 `git add .` 실행 시 스테이징할 내용을 검토하도록 Claude에게 안내합니다. 명령을 차단하지는 않습니다.
+
+매개변수 없음.
+
+---
+
+## 데이터베이스
+
+데이터베이스에 실행되기 전에 파괴적인 SQL 작업을 감지합니다.
+
+### `warn-destructive-sql`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `WHERE` 절 없이 `DROP TABLE`, `DROP DATABASE`, 또는 `DELETE`가 포함된 SQL 실행 전 Claude에게 확인하도록 안내합니다.
+
+매개변수 없음.
+
+---
+
+### `warn-schema-alteration`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `ALTER TABLE` 구문 실행 전 Claude에게 확인하도록 안내합니다.
+
+매개변수 없음.
+
+---
+
+## 경고
+
+잠재적으로 위험하지만 파괴적이지 않은 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다.
+
+### `warn-large-file-write`
+
+**이벤트:** PreToolUse (Write)  
+**기본값:** 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 안내합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `thresholdKb` | `number` | `1024` | 경고가 발생하는 파일 크기 임계값(킬로바이트). |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "warn-large-file-write": {
+      "thresholdKb": 256
+    }
+  }
+}
+```
+
+<Note>
+훅 핸들러는 페이로드에 1 MB stdin 제한을 적용합니다. 작은 내용으로 이 정책을 테스트하려면 `thresholdKb`를 1024보다 훨씬 작은 값으로 설정하세요.
+</Note>
+
+---
+
+### `warn-package-publish`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `npm publish` 실행 전 Claude에게 확인하도록 안내합니다.
+
+매개변수 없음.
+
+---
+
+### `warn-background-process`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** `nohup`, `&`, `disown`, 또는 `screen`을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의하도록 안내합니다.
+
+매개변수 없음.
+
+---
+
+### `warn-global-package-install`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 가상 환경 없이 `npm install -g`, `yarn global add`, 또는 `pip install` 실행 전 Claude에게 확인하도록 안내합니다.
+
+매개변수 없음.
+
+---
+
+## 패키지 매니저
+
+에이전트가 사용할 수 있는 패키지 매니저를 강제합니다.
+
+### `prefer-package-manager`
+
+**이벤트:** PreToolUse (Bash)  
+**기본값:** 비활성화됨. 활성화되면 `allowed` 목록에 없는 패키지 매니저 명령어를 차단하고 Claude에게 허용된 매니저를 사용하도록 명령어를 재작성하도록 안내합니다.
+
+감지 대상: pip, pip3, python -m pip, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo.
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-----------|------|---------|-------------|
+| `allowed` | string[] | `[]` | 허용되는 패키지 매니저 이름. 이 목록에 없는 감지된 매니저는 차단됩니다. 비어 있으면 정책이 아무 동작도 하지 않습니다. |
+| `blocked` | string[] | `[]` | 기본 목록 외에 추가로 차단할 매니저 이름 (예: `['pdm', 'pipx']`). |
+
+기본 차단 목록은 다음을 포함합니다: pip, pip3, npm, npx, yarn, pnpm, pnpx, bun, bunx, uv, poetry, pipenv, conda, cargo. 이 목록에 없는 매니저를 추가하려면 `blocked`를 사용하세요.
+
+**설정 예시:**
+
+```json
+{
+  "enabledPolicies": ["prefer-package-manager"],
+  "policyParams": {
+    "prefer-package-manager": {
+      "allowed": ["uv", "bun"],
+      "blocked": ["pdm", "pipx"]
+    }
+  }
+}
+```
+
+이 설정에서 `pip install flask`와 `pdm install flask`는 모두 거부되며 Claude에게 `uv` 또는 bun을 사용하라는 메시지가 표시됩니다. `uv pip install flask`와 같은 명령은 `uv`가 허용 목록에 있고 먼저 확인되므로 허용됩니다.
+
+---
+
+## AI 동작
+
+에이전트가 막히거나 예상치 못한 동작을 보이는 경우를 감지합니다.
+
+### `warn-repeated-tool-calls`
+
+**이벤트:** PreToolUse (모든 도구)  
+**기본값:** 동일한 도구가 동일한 매개변수로 3회 이상 호출될 때 Claude에게 재고하도록 안내합니다 — 에이전트가 루프에 갇혔다는 일반적인 신호입니다.
+
+매개변수 없음.
+
+---
+
+## 워크플로
+
+세션 종료 시 규율 있는 워크플로를 강제합니다. 이 정책들은 **Stop** 이벤트에서 작동하며 각 조건이 충족될 때까지 에이전트가 중지하지 못하도록 거부합니다. 자연적인 의존성 체인을 따릅니다: 커밋 → 푸시 → PR → CI. 정책이 거부하면 체인의 이후 정책은 건너뜁니다 (deny 단락).
+
+모든 워크플로 정책은 **fail-open** 방식입니다: 필요한 도구를 사용할 수 없는 경우 (예: `gh` 미설치, git 리모트 없음), 정책은 확인이 건너뛰어진 이유를 설명하는 정보 메시지와 함께 허용합니다.
+
+### CLI별 Stop 동작
+
+Stop 적용은 6개 지원 CLI에서 각각 다른 "에이전트 완료" 훅 계약을 노출하기 때문에 약간 다르게 보입니다. **결과**는 동일합니다 — 에이전트는 워크플로 게이트가 실패하는 동안 중지할 수 없습니다 — 하지만 **메커니즘**은 다릅니다. 아래 표는 요약을 제공합니다. Pi만 `require-*-before-stop` 정책을 활성화하기 전에 이해해야 할 사용자에게 보이는 동작 특이사항이 있습니다.
+
+| CLI | 게이트 작동 시점 | 표시 내용 |
+|---|---|---|
+| Claude Code | 동일한 에이전트 루프, 즉시 | Claude가 계속 작업합니다 — 문제를 해결한 후 다시 완료를 시도합니다. 사용자에게 중단이 표시되지 않습니다. |
+| Codex | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다. |
+| GitHub Copilot CLI | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다 (Copilot의 `{decision:"block", reason}` 재시도 채널 사용 — Copilot CLI 1.0.41에서 실험적으로 검증됨). |
+| Cursor Agent | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다 (Cursor의 `{followup_message}` 채널 사용 — `loop_limit`에 제한, 기본 5회 재시도). |
+| OpenCode | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다 (OpenCode의 `client.session.prompt(...)` SDK 호출이 `hookSpecificOutput.additionalContext`를 통해 라우팅됨). |
+| **Pi (pi-coding-agent)** | **다음 사용자 턴** | **Pi는 게이트가 작동할 때 눈에 띄게 중지됩니다** — 에이전트 루프가 종료되고 프롬프트로 돌아갑니다. 그런 다음 다음 프롬프트를 제출할 때 게이트가 작동합니다: failproofai가 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여 LLM이 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 지시합니다. |
+
+<Note>
+**Pi 제한사항.** Pi의 `AgentEndEvent` (Claude의 `Stop` 훅에 해당하는 업스트림 이벤트)는 Result 타입이 없습니다 — 작동 시점에 Pi의 에이전트 루프가 이미 종료되어 있습니다. Pi는 Claude / Copilot / Cursor / OpenCode처럼 동일한 루프를 강제로 재시도할 수 없습니다. failproofai는 게이트를 Pi의 `before_agent_start` 이벤트(다음 사용자 프롬프트 후 작동)로 이동하여 워크플로 확인이 현재 턴이 아닌 다음 턴에서 강제되도록 합니다.
+
+**실제적 의미:**
+
+- Pi가 중지된 후, deny 이유는 Pi 세션 id로 키가 지정된 메모리에 캡처됩니다. 동일한 Pi 프로세스에서 제출하는 바로 다음 프롬프트가 이를 처리합니다: LLM은 시스템 프롬프트 상단에 `MANDATORY ACTION REQUIRED` 지시문을 보고, 커밋(또는 푸시 / PR 열기 / CI 대기)을 수행한 후 요청을 계속합니다. 캡처된 deny 이유는 한 번만 처리됩니다 — 처리되면 게이트가 해제됩니다.
+- 게이트는 Pi의 프로세스 수명에 의해 경계가 정해집니다. 턴 사이에 Pi를 `Ctrl+C`하거나 종료하면 메모리 항목이 프로세스와 함께 삭제되어 게이트가 누락됩니다. Claude, Copilot, Cursor, OpenCode도 동일한 경계를 가집니다 (에이전트를 종료하면 게이트가 누락됨) — Pi는 에이전트가 게이트가 작동하기 전에 눈에 띄게 종료되므로 더 명확하게 보입니다.
+- 보류 중인 deny는 어떤 이유로든 (`new` / `resume` / `fork` / `quit`) `session_shutdown` 시에도 지워지므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출될 수 없습니다.
+
+Claude 스타일의 동일 루프 재시도가 필요하면 다른 5개 지원 CLI 중 하나에서 `Stop` 정책을 실행하세요. 이 격차를 해소할 수 있는 `AgentEndEvent`의 향후 Result 타입에 대해 Pi 업스트림을 추적 중입니다.
+</Note>
+
+### `require-commit-before-stop`
+
+**이벤트:** Stop  
+**기본값:** 커밋되지 않은 변경사항(수정됨, 스테이징됨, 추적되지 않은 파일)이 있을 때 중지를 거부합니다. 작업 디렉토리가 깨끗할 때는 정보 메시지를 반환합니다.
+
+매개변수 없음.
+
+---
+
+### `require-push-before-stop`
+
+**이벤트:** Stop  
+**기본값:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 중지를 거부합니다. 필요한 경우 추적 브랜치를 생성하기 위해 `git push -u`를 제안합니다. 리모트가 설정되지 않은 경우 fail-open 방식으로 처리합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | 푸시할 리모트 이름. |
+
+**예시:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**이벤트:** Stop  
+**기본값:** 현재 브랜치에 대한 풀 리퀘스트가 없거나 기존 PR이 머지 없이 닫혀 있을 때 중지를 거부합니다. Claude에게 `gh pr create`로 PR을 생성하도록 안내합니다. PR이 **머지**되면 정책이 허용합니다 (작업이 배포됨) 하고 브랜치를 전환하도록 힌트를 제공합니다 (`git checkout main && git pull`).
+
+매개변수 없음.
+
+<Note>
+이 정책을 사용하려면 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다.
+풀 리퀘스트에 대한 읽기 접근을 위한 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우 정책은 fail-open으로 처리되고 이유를 Claude에게 보고합니다.
+</Note>
+
+---
+
+### `require-no-conflicts-before-stop`
+
+**이벤트:** Stop  
+**기본값:** 현재 브랜치가 베이스 브랜치에 깔끔하게 머지될 수 없을 때 중지를 거부합니다. 정책은 먼저 브랜치에 대한 GitHub의 `OPEN` PR이 있는지 확인합니다 — PR이 없으면 머지 대상이 없으므로 전체 정책이 단락되어 허용합니다. `OPEN` PR이 확인되면 두 가지 독립적인 프로브가 실행됩니다:
+
+1. **로컬** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. 충돌 시 deny 메시지에 충돌 파일이 명시되어 Claude가 정확히 무엇을 해결해야 하는지 알 수 있습니다.
+2. **GitHub** — 사전 확인에서 이미 가져온 `gh pr view --json mergeable,state` 결과를 재사용합니다. 마지막 fetch 이후 누군가가 `main`에 충돌하는 PR을 병합한 경우처럼 오래된 로컬 `origin/<baseBranch>`가 놓칠 수 있는 충돌을 감지합니다. `CONFLICTING` 결과는 거부됩니다. `UNKNOWN` 결과도 거부되며 Claude에게 다시 중지를 시도하기 전에 약 10초 기다리고 재확인하도록 안내합니다 — GitHub가 재계산하는 동안 거짓 음성을 방지합니다.
+
+다음의 경우 완전히 건너뜁니다 (허용): `gh`가 설치되지 않음, 브랜치에 PR이 없음, PR 상태가 `OPEN`이 아님 (예: `MERGED`, `CLOSED`), 또는 `gh pr view`가 파싱할 수 없는 출력을 반환함. 로컬에 `origin/<baseBranch>`가 없거나 베이스보다 앞서는 커밋이 없는 경우에도 fail-open으로 처리됩니다 — 이러한 레이어 1 폴스루는 허용하기 전에 캐시된 PR 병합 가능성을 여전히 참조합니다.
+
+**매개변수:**
+
+| 매개변수 | 유형 | 기본값 | 설명 |
+|-------|------|---------|-------------|
+| `baseBranch` | `string` | `"main"` | 충돌을 확인할 베이스 브랜치. |
+
+<Note>
+이 정책에는 GitHub CLI (`gh`)가 필요합니다. 정책은 충돌 프로브를 실행하기 전에 `gh pr view`를 사용하여 `OPEN` PR이 있는지 확인합니다 — `gh` 없이는 정책이 단락되어 허용합니다. 풀 리퀘스트에 대한 읽기 접근을 위한 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**이벤트:** Stop  
+**기본값:** 현재 브랜치에서 CI 확인이 실패하거나 아직 실행 중일 때 중지를 거부합니다. GitHub Actions 워크플로 실행과 서드파티 봇 확인(예: CodeRabbit, SonarCloud, Codecov)을 모두 확인합니다. `skipped`, `cancelled`, `neutral` 결론은 실패하지 않는 것으로 처리합니다 (후자는 예를 들어 외부 기여자 PR에서 앱이 의도적으로 성공/실패 대신 neutral을 보고하는 Socket Security 알림을 포함합니다). 모든 확인이 통과되면 정보 메시지를 반환합니다.
+
+매개변수 없음.
+
+<Note>
+이 정책을 사용하려면 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다.
+Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위한 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우 정책은 fail-open으로 처리되고 이유를 Claude에게 보고합니다.
+</Note>
+
+---
+
+---
+
+## 개별 정책 비활성화
+
+설정의 `enabledPolicies`에서 특정 정책을 제거하거나 대시보드의 Policies 탭에서 비활성화하세요.
+
+```json
+{
+  "enabledPolicies": [
+    "block-rm-rf",
+    "sanitize-api-keys"
+  ]
+}
+```
+
+`enabledPolicies`에 나열되지 않은 정책은 `policyParams` 항목이 있더라도 실행되지 않습니다.