> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/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에게 반환되기 전에 출력을 검사합니다. 시크릿 패턴이 감지되면 정책은 출력이 다시 전달되지 못하도록 거부 결정을 반환합니다.

### `sanitize-jwt`

**이벤트:** PostToolUse (모든 도구)\
**기본값:** JWT 토큰(`.`으로 구분된 세 개의 base64url 세그먼트)을 난독화합니다.

매개변수 없음.

***

### `sanitize-api-keys`

**이벤트:** PostToolUse (모든 도구)\
**기본값:** 일반적인 API 키 형식을 난독화합니다: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PATs (`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. 정책이 거부하면 체인의 이후 정책은 건너뜁니다 (거부 시 단락).

모든 워크플로 정책은 **fail-open** 방식입니다: 필요한 도구를 사용할 수 없는 경우(예: `gh` 미설치, git 리모트 없음) 정책은 확인이 건너뛰어진 이유를 알리는 정보 메시지와 함께 허용합니다.

### CLI별 Stop 시맨틱

Stop 적용은 지원되는 6개 CLI에서 각각 다른 "에이전트 완료" 훅 계약을 노출하기 때문에 약간씩 다르게 동작합니다. **결과**는 동일합니다 — 에이전트는 워크플로 게이트가 실패하는 동안 중단할 수 없습니다 — 하지만 **메커니즘**은 다릅니다. 아래 표에 요약되어 있습니다; `require-*-before-stop` 정책을 활성화하기 전에 이해할 가치가 있는 사용자에게 보이는 특이점은 Pi에만 있습니다.

| 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가 중단된 후, 거부 이유는 Pi 세션 id로 키된 인메모리에 캡처됩니다. 동일한 Pi 프로세스에서 다음에 제출하는 프롬프트가 이를 소비합니다: LLM은 시스템 프롬프트 상단에 `MANDATORY ACTION REQUIRED` 지시문을 보고, 커밋(또는 푸시 / PR 열기 / CI 대기)을 수행한 후 요청을 계속합니다. 캡처된 거부 이유는 일회성입니다 — 소비되면 게이트가 해제됩니다.
  * 게이트는 Pi의 프로세스 수명에 의해 제한됩니다. 턴 사이에 Pi를 `Ctrl+C`하거나 종료하면 인메모리 항목이 프로세스와 함께 삭제되고 게이트가 놓칩니다. Claude, Copilot, Cursor, OpenCode도 동일한 제한이 있습니다(에이전트를 종료하면 게이트가 놓침) — Pi는 에이전트가 게이트가 실행되기 전에 눈에 띄게 종료되므로 더 명확하게 보입니다.
  * 보류 중인 거부는 어떤 이유로든(`new` / `resume` / `fork` / `quit`) `session_shutdown` 시에도 지워지므로, 이전 세션의 오래된 게이트가 동일한 Pi 프로세스에서 시작된 새 세션으로 누출될 수 없습니다.

  동일 루프 재시도가 필요하다면 다른 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 theme={null}
{
  "policyParams": {
    "require-push-before-stop": {
      "remote": "upstream"
    }
  }
}
```

***

### `require-pr-before-stop`

**이벤트:** Stop\
**기본값:** 현재 브랜치에 대한 풀 리퀘스트가 없거나 기존 PR이 병합 없이 닫힌 경우 중단을 거부합니다. `gh pr create`로 PR을 생성하도록 Claude에게 안내합니다. 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이 없으면 강제할 병합 대상이 없으므로 전체 정책이 allow로 단락됩니다. `OPEN` PR이 확인되면 두 가지 독립적인 프로브가 실행됩니다:

1. **로컬** — `git merge-tree --write-tree --name-only origin/<baseBranch> HEAD`. 충돌 시 거부 메시지에 충돌된 파일 이름이 포함되어 Claude가 정확히 무엇을 해결해야 하는지 알 수 있습니다.
2. **GitHub** — 사전 확인에서 이미 가져온 `gh pr view --json mergeable,state` 결과를 재사용합니다. 오래된 로컬 `origin/<baseBranch>`가 놓칠 수 있는 충돌을 감지합니다 (예: 마지막 fetch 이후 누군가가 `main`에 충돌하는 PR을 병합한 경우). `CONFLICTING` 결과는 거부됩니다. `UNKNOWN` 결과도 거부되며 Claude에게 다시 중단을 시도하기 전에 약 10초 기다리고 재확인하도록 안내합니다 — 이는 GitHub가 재계산하는 동안의 false negative를 방지합니다.

다음 경우에 전체 건너뜁니다(허용): `gh`가 설치되지 않음, 브랜치에 대한 PR이 없음, PR의 상태가 `OPEN`이 아님 (예: `MERGED`, `CLOSED`), 또는 `gh pr view`가 파싱 불가능한 출력을 반환. `origin/<baseBranch>`가 로컬에 없거나 베이스보다 앞선 커밋이 없을 때도 fail-open 방식으로 동작합니다 — 이러한 Layer 1 폴스루는 허용하기 전에 캐시된 PR 병합 가능성을 계속 참조합니다.

**매개변수:**

| 매개변수         | 타입       | 기본값      | 설명               |
| ------------ | -------- | -------- | ---------------- |
| `baseBranch` | `string` | `"main"` | 충돌을 확인할 베이스 브랜치. |

<Note>
  이 정책에는 GitHub CLI (`gh`)가 필요합니다. 정책은 충돌 프로브를 실행하기 전에 `gh pr view`를 사용하여 `OPEN` PR이 존재하는지 확인합니다 — `gh` 없이는 정책이 allow로 단락됩니다. 풀 리퀘스트에 대한 읽기 액세스를 위해 `repo` 스코프가 있는 개인 액세스 토큰으로 `gh auth login`을 실행하세요.
</Note>

***

### `require-ci-green-before-stop`

**이벤트:** Stop\
**기본값:** 현재 브랜치에서 CI 확인이 실패하거나 아직 실행 중일 때 중단을 거부합니다. GitHub Actions 워크플로 실행과 서드파티 봇 확인(예: CodeRabbit, SonarCloud, Codecov)을 모두 확인합니다. `skipped`, `cancelled`, `neutral` 결론은 실패로 처리하지 않습니다 (후자는 예를 들어 앱이 의도적으로 성공/실패 대신 neutral을 보고하는 외부 기여자 PR의 Socket Security 알림을 포함). 모든 확인이 통과되면 정보 메시지를 반환합니다.

매개변수 없음.

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

***

***

## 개별 정책 비활성화

설정 파일의 `enabledPolicies`에서 특정 정책을 제거하거나, 대시보드의 정책 탭에서 해제하세요.

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

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