> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260624-1149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 기본 제공 정책

> 에이전트의 일반적인 실패 패턴을 감지하는 39가지 기본 제공 정책

failproofai에는 에이전트의 일반적인 실패 패턴을 감지하는 39가지 기본 제공 정책이 포함되어 있습니다. 각 정책은 특정 훅 이벤트 유형과 도구 이름에 따라 실행됩니다. 19개의 정책은 코드 작성 없이 동작을 조정할 수 있는 파라미터를 허용합니다. 5개의 워크플로 정책은 Claude가 중단하기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다.

***

## 개요

정책은 다음과 같은 카테고리로 분류됩니다:

| 카테고리                              | 정책                                                                                                                                           | 훅 유형        |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| [위험한 명령어](#dangerous-commands)    | block-sudo, block-rm-rf, block-curl-pipe-sh, block-failproofai-commands                                                                      | 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 theme={null}
{
  "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` 명령어가 포함된 모든 명령을 차단합니다.

`sudo` 키워드가 포함된 호출을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령 토큰에 대해 수행되어 셸 연산자 주입을 통한 우회를 방지합니다.

**파라미터:**

| 파라미터            | 타입         | 기본값  | 설명                                        |
| --------------- | ---------- | ---- | ----------------------------------------- |
| `allowPatterns` | `string[]` | `[]` | 허용된 정확한 명령 접두사. 각 항목은 파싱된 argv 토큰과 매칭됩니다. |

**예시:**

```json theme={null}
{
  "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 theme={null}
{
  "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`)을 차단합니다.

파라미터 없음.

***

## 인프라 명령어

코딩 에이전트가 인프라 CLI를 실행하거나 CI/CD 파이프라인을 트리거하지 못하도록 차단합니다. 이 카테고리의 모든 정책은 **옵트인**(`defaultEnabled: false`)입니다. `kubectl`, `terraform` 등을 합법적으로 호출해야 하는 에이전트는 정책을 활성화하지 않는 한 영향을 받지 않습니다. 활성화된 경우, 명령이 `allowPatterns`의 항목과 일치하지 않는 한 해당 CLI의 모든 호출이 차단됩니다.

패턴 문법은 [`block-sudo`](#block-sudo)와 동일합니다. 토큰은 파싱된 argv와 매칭되고, `*`는 하나의 토큰에 대한 와일드카드이며, 독립적인 셸 연산자(`&&`, `||`, `|`, `;`) 또는 셸 메타문자가 내장된 토큰을 포함하는 명령은 주입 우회를 방지하기 위해 허용 목록 매칭 전에 거부됩니다.

### `block-kubectl`

**이벤트:** PreToolUse (Bash)\
**기본값:** 모든 `kubectl` 호출을 차단합니다.

**파라미터:**

| 파라미터            | 타입         | 기본값  | 설명                  |
| --------------- | ---------- | ---- | ------------------- |
| `allowPatterns` | `string[]` | `[]` | 허용된 kubectl 명령 접두사. |

**예시:**

```json theme={null}
{
  "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 theme={null}
{
  "policyParams": {
    "block-terraform": {
      "allowPatterns": ["terraform plan", "terraform validate", "terraform show *"]
    }
  }
}
```

***

### `block-aws-cli`

**이벤트:** PreToolUse (Bash)\
**기본값:** 모든 `aws` CLI 호출을 차단합니다.

**파라미터:**

| 파라미터            | 타입         | 기본값  | 설명                  |
| --------------- | ---------- | ---- | ------------------- |
| `allowPatterns` | `string[]` | `[]` | 허용된 aws CLI 명령 접두사. |

**예시:**

```json theme={null}
{
  "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 theme={null}
{
  "policyParams": {
    "block-gcloud": {
      "allowPatterns": ["gcloud auth list", "gcloud config list"]
    }
  }
}
```

***

### `block-az-cli`

**이벤트:** PreToolUse (Bash)\
**기본값:** 모든 `az`(Azure) CLI 호출을 차단합니다.

**파라미터:**

| 파라미터            | 타입         | 기본값  | 설명                 |
| --------------- | ---------- | ---- | ------------------ |
| `allowPatterns` | `string[]` | `[]` | 허용된 az CLI 명령 접두사. |

**예시:**

```json theme={null}
{
  "policyParams": {
    "block-az-cli": {
      "allowPatterns": ["az account show", "az group list"]
    }
  }
}
```

***

### `block-helm`

**이벤트:** PreToolUse (Bash)\
**기본값:** 모든 `helm` 호출을 차단합니다.

**파라미터:**

| 파라미터            | 타입         | 기본값  | 설명               |
| --------------- | ---------- | ---- | ---------------- |
| `allowPatterns` | `string[]` | `[]` | 허용된 helm 명령 접두사. |

**예시:**

```json theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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 theme={null}
{
  "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"]` | commit/merge/rebase/cherry-pick이 차단되는 브랜치 이름. |

***

### `block-force-push`

**이벤트:** PreToolUse (Bash)\
**기본값:** `git push --force` 및 `git push -f`를 차단합니다.

정책별 파라미터 없음. 대안을 제안하려면 공통 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하세요:

```json theme={null}
{
  "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)\
**기본값:** `DROP TABLE`, `DROP DATABASE`, 또는 `WHERE` 절 없는 `DELETE`가 포함된 SQL 실행 전 Claude에게 확인하도록 지시합니다.

파라미터 없음.

***

### `warn-schema-alteration`

**이벤트:** PreToolUse (Bash)\
**기본값:** `ALTER TABLE` 구문 실행 전 Claude에게 확인하도록 지시합니다.

파라미터 없음.

***

## 경고

잠재적으로 위험하지만 파괴적이지 않은 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다.

### `warn-large-file-write`

**이벤트:** PreToolUse (Write)\
**기본값:** 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 지시합니다.

**파라미터:**

| 파라미터          | 타입       | 기본값    | 설명                         |
| ------------- | -------- | ------ | -------------------------- |
| `thresholdKb` | `number` | `1024` | 경고가 발생하는 파일 크기 임계값(킬로바이트). |

**예시:**

```json theme={null}
{
  "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 theme={null}
{
  "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 적용은 일곱 가지 지원 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회 재시도).                                                                                                                                       |
| Gemini CLI               | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다(`AfterAgent`의 Gemini `{decision:"block", reason}` 채널 사용).                                                                                                                                                   |
| OpenCode                 | 동일한 에이전트 루프, 즉시 | Claude와 동일합니다(`hookSpecificOutput.additionalContext`를 통해 라우팅된 OpenCode의 `client.session.prompt(...)` SDK 호출 사용).                                                                                                          |
| **Pi (pi-coding-agent)** | **다음 사용자 턴**    | **Pi는 게이트가 실행될 때 눈에 띄게 중단됩니다** — 에이전트 루프가 종료되고 프롬프트로 반환됩니다. 그런 다음 다음에 프롬프트를 제출할 때 게이트가 실행됩니다: failproofai는 해당 턴의 시스템 프롬프트에 `MANDATORY ACTION REQUIRED` 지시문을 앞에 추가하여 LLM에게 요청한 작업을 수행하기 전에 워크플로 단계(커밋, 푸시 등)를 완료하도록 지시합니다. |

<Note>
  **Pi의 제한 사항.** Pi의 `AgentEndEvent`(Claude의 `Stop` 훅에 해당하는 업스트림 이벤트)에는 Result 타입이 없습니다 — 실행될 때 Pi의 에이전트 루프가 이미 종료된 상태입니다. Pi는 Claude / Copilot / Cursor / Gemini / 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, Gemini, OpenCode도 동일한 제한이 있습니다(에이전트를 종료하면 게이트를 놓침) — Pi는 에이전트가 게이트 실행 전에 눈에 띄게 종료되기 때문에 이를 더 분명하게 만들 뿐입니다.
  * 보류 중인 deny는 어떤 이유로든 `session_shutdown`(`new` / `resume` / `fork` / `quit`) 시 지워지므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출될 수 없습니다.

  Claude 스타일의 동일 루프 재시도가 필요하다면, 다른 여섯 가지 지원 CLI 중 하나에서 `Stop` 정책을 실행하세요. Pi 업스트림에서 이 격차를 해소할 수 있는 `AgentEndEvent`의 향후 Result 타입을 추적하고 있습니다.
</Note>

### `require-commit-before-stop`

**이벤트:** Stop\
**기본값:** 커밋되지 않은 변경 사항(수정, 스테이징, 추적되지 않은 파일)이 있을 때 중단을 차단합니다. 작업 디렉토리가 깨끗할 때 안내 메시지를 반환합니다.

파라미터 없음.

***

### `require-push-before-stop`

**이벤트:** Stop\
**기본값:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 중단을 차단합니다. 필요한 경우 `git push -u`를 통해 추적 브랜치를 생성하도록 제안합니다. 원격이 구성되지 않은 경우 fail-open됩니다.

**파라미터:**

| 파라미터     | 타입       | 기본값        | 설명         |
| -------- | -------- | ---------- | ---------- |
| `remote` | `string` | `"origin"` | 푸시할 원격 이름. |

**예시:**

```json theme={null}
{
  "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` 결과를 재사용합니다. 오래된 로컬 `origin/<baseBranch>`가 놓칠 수 있는 충돌을 감지합니다(예: 마지막 fetch 이후 누군가가 충돌하는 PR을 `main`에 병합한 경우). `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에서의 Socket Security 알림을 포함합니다. 여기서 앱은 의도적으로 성공/실패 대신 neutral을 보고합니다). 모든 검사가 통과되면 안내 메시지를 반환합니다.

파라미터 없음.

<Note>
  이 정책은 [GitHub CLI](https://cli.github.com/)(`gh`)가 설치되고 인증된 상태를 요구합니다.
  Actions 워크플로 실행 및 Checks API에 대한 읽기 접근을 위해 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않았거나 인증되지 않은 경우, 정책은 fail-open되고 Claude에게 이유를 보고합니다.
</Note>

***

***

## 개별 정책 비활성화

설정의 `enabledPolicies`에서 특정 정책을 제거하거나 대시보드의 Policies 탭에서 비활성화하세요.

```json theme={null}
{
  "enabledPolicies": [
    "block-rm-rf",
    "sanitize-api-keys"
  ]
}
```

`enabledPolicies`에 나열되지 않은 정책은 `policyParams` 항목이 있더라도 실행되지 않습니다.