failproofai 0.0.6-beta.1 → 0.0.6-beta.3

package/.next/standalone/docs/ja/getting-started.mdx

@@ -1,10 +1,10 @@
 ---
 title: はじめに
-description: "failproofai をインストールし、ポリシーを有効化して、エージェントを安定稼働させましょう"
+description: "failproofaiをインストールし、ポリシーを有効化して、エージェントを安定して動かしましょう"
 icon: rocket
 ---
 
-## 必要環境
+## 必要要件
 
 - **Node.js** >= 20.9.0
 - **Bun** >= 1.3.0（オプション — ソースからビルドする場合のみ必要）
@@ -31,13 +31,13 @@ bun add -g failproofai
 
 <Steps>
   <Step title="ポリシーを有効化する">
-    ポリシーとは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンドの実行、シークレットの漏洩、その他の障害パターンを、実害が生じる前に検出します。
+    ポリシーは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンドやシークレットの漏洩、その他の障害パターンを被害が発生する前に検出します。
 
     ```bash
     failproofai policies --install
     ```
 
-    このコマンドは Claude Code の `settings.json` にフックエントリを書き込みます。単一プロジェクト向けにインストールしたり、特定のポリシーだけを選択することも可能です。
+    これにより、Claude Code の `settings.json` にフックエントリが書き込まれます。単一プロジェクト向けにインストールしたり、特定のポリシーを選択したりすることもできます。
 
     ```bash
     failproofai policies --install --scope project
@@ -49,17 +49,17 @@ bun add -g failproofai
     failproofai policies
     ```
 
-    すべてのポリシー、その有効・無効の状態、および設定済みのパラメータを表示します。
+    すべてのポリシー、その有効・無効の状態、設定済みのパラメータを表示します。
   </Step>
   <Step title="ダッシュボードを起動する">
     ```bash
     failproofai
     ```
 
-    `http://localhost:8020` にローカルダッシュボードを開きます。セッションの閲覧、ツール呼び出しの検査、ポリシーの管理が行えます。
+    `http://localhost:8020` にローカルダッシュボードを開きます。セッションの閲覧、ツール呼び出しの確認、ポリシーの管理が行えます。
   </Step>
   <Step title="エージェントを実行する">
-    通常通り Claude Code を起動してください。エージェントが危険な操作を試みた場合、failproofai が自動的に介入します。エージェントを無人で稼働させておき、何が起きたかをダッシュボードで後から確認できます。
+    通常通り Claude Code を起動してください。エージェントが危険な操作を試みた場合、failproofai が自動的に介入します。無人で実行したまま放置し、ダッシュボードで何が起きたかを後から確認できます。
   </Step>
 </Steps>
 
@@ -75,18 +75,70 @@ Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                  writes decision to stdout
 ```
 
-各ポリシーは次の3つのいずれかの判定を返します。
+各ポリシーは以下の3つの決定のいずれかを返します。
 
 - **allow** — エージェントは通常通り処理を続行する
 - **deny** — アクションがブロックされ、エージェントにその理由が通知される
-- **instruct** — エージェントのプロンプトに追加のコンテキストが付加される
+- **instruct** — エージェントのプロンプトに追加のコンテキストが付与される
 
 <Note>
-ポリシーはローカルプロセス上で実行されます。リモートサービスへのデータ送信は一切行われません。
+ポリシーはローカルプロセス内で実行されます。リモートサービスには何も送信されません。
 </Note>
 
 ---
 
+## 規約ベースのポリシーでチームポリシーを設定する
+
+チーム全体で品質基準を素早く確立するには、`.failproofai/policies/` の規約を活用するのが最速です。このディレクトリにポリシーファイルを配置するだけで自動的に読み込まれます — フラグも設定変更もインストールコマンドも不要です。
+
+<Steps>
+  <Step title="ポリシーディレクトリを作成する">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+  </Step>
+  <Step title="ポリシーファイルを追加する">
+    サンプルのスターターファイルをコピーするか、独自に作成してください。
+
+    ```bash
+    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
+    ```
+
+    または新しいファイルを作成する場合：
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    customPolicies.add({
+      name: "test-before-commit",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
+          return instruct("Run tests before committing.");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="gitにコミットする">
+    ```bash
+    git add .failproofai/policies/
+    git commit -m "Add team quality policies"
+    ```
+
+    failproofai をインストールしているすべてのチームメンバーが、これらのポリシーを自動的に受け取ります。開発者ごとのセットアップは不要です。
+  </Step>
+</Steps>
+
+<Tip>
+`.failproofai/policies/` をリポジトリにコミットすることで、チーム全体が同じ基準を共有できます。チームが新たな障害パターンを発見したらポリシーを追加してプッシュするだけで、全員が次の `git pull` 時に更新を受け取れます。時間をかけてこれらのポリシーを積み重ねることで、継続的に改善される生きた品質基準が生まれます。
+</Tip>
+
+---
+
 ## データの保存場所
 
 すべての設定とログはお使いのマシン上に保存されます。
@@ -97,7 +149,7 @@ Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
 | `~/.failproofai/hook-activity.jsonl` | フック実行履歴 |
 | `~/.failproofai/hook.log` | カスタムフックエラーのデバッグログ |
 | `.failproofai/policies-config.json` | プロジェクト別設定（コミット対象） |
-| `.failproofai/policies-config.local.json` | 個人用オーバーライド（gitignore 対象） |
+| `.failproofai/policies-config.local.json` | 個人用上書き設定（gitignore対象） |
 
 ---
 
@@ -120,11 +172,11 @@ failproofai policies --uninstall
 </Card>
 
 <Card title="組み込みポリシー" icon="shield" href="/ja/built-in-policies">
-  パラメータ付き全 26 ポリシーの一覧
+  パラメータ付きの全26ポリシー
 </Card>
 
 <Card title="カスタムポリシー" icon="code" href="/ja/custom-policies">
-  JavaScript で独自のポリシーを作成する
+  JavaScriptで独自のポリシーを作成する
 </Card>
 
 <Card title="エージェントモニター" icon="chart-line" href="/ja/dashboard">

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

@@ -1,16 +1,16 @@
 ---
 title: 내장 정책
-description: "일반적인 에이전트 실패 유형을 감지하는 30개의 내장 정책 전체 목록"
+description: "일반적인 에이전트 오류 패턴을 감지하는 30가지 내장 정책"
 icon: shield
 ---
 
-failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의 내장 정책을 제공합니다. 각 정책은 특정 훅 이벤트 유형과 툴 이름에 따라 실행됩니다. 9개의 정책은 코드를 작성하지 않고도 동작을 조정할 수 있는 파라미터를 허용합니다. 4개의 워크플로우 정책은 Claude가 종료되기 전에 커밋 → 푸시 → PR → CI 파이프라인을 강제합니다.
+failproofai에는 일반적인 에이전트 오류 패턴을 감지하는 30가지 내장 정책이 포함되어 있습니다. 각 정책은 특정 훅 이벤트 유형 및 도구 이름에 따라 실행됩니다. 9가지 정책은 코드를 작성하지 않고도 동작을 조정할 수 있는 파라미터를 제공합니다. 4가지 워크플로우 정책은 Claude가 중단하기 전에 커밋 → 푸시 → PR → CI 파이프라인을 완료하도록 강제합니다.
 
 ---
 
 ## 개요
 
-정책은 카테고리별로 분류됩니다:
+정책은 다음과 같은 카테고리로 분류됩니다:
 
 | 카테고리 | 정책 | 훅 유형 |
 |----------|----------|-----------|
@@ -21,37 +21,38 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 | [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-ci-green-before-stop | Stop |
 
-- **`block-`** — 에이전트 진행을 차단합니다.
-- **`warn-`** — 에이전트가 스스로 수정할 수 있도록 추가 컨텍스트를 제공합니다.
-- **`sanitize-`** — 에이전트에게 전달되기 전에 툴 출력에서 민감한 데이터를 제거합니다.
+- **`block-`** — 에이전트가 계속 진행하지 못하도록 차단합니다.
+- **`warn-`** — 에이전트가 스스로 수정할 수 있도록 추가 맥락 정보를 제공합니다.
+- **`sanitize-`** — 에이전트가 도구 출력을 받기 전에 민감한 데이터를 제거합니다.
 - **`require-`** — 조건이 충족될 때까지 Stop 이벤트를 차단합니다.
 
 ---
 
 <Tip>
-모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 보는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 내장, 커스텀, 컨벤션 정책 모두에서 동작합니다. 자세한 내용은 [구성 → hint](/ko/configuration#hint-cross-cutting)를 참조하세요.
+모든 정책은 `policyParams`에서 선택적 `hint` 필드를 지원합니다. hint는 Claude가 보는 deny 또는 instruct 메시지에 추가되어, 정책 코드를 수정하지 않고도 실행 가능한 안내를 제공합니다. 내장 정책, 커스텀 정책, 컨벤션 정책 모두에서 사용할 수 있습니다. 자세한 내용은 [설정 → hint](/ko/configuration#hint-cross-cutting)를 참고하세요.
 </Tip>
 
 ---
 
 ## 위험한 명령어
 
-에이전트가 되돌리기 어렵거나 호스트 시스템에 손상을 줄 수 있는 작업을 실행하는 것을 방지합니다.
+에이전트가 실행하기 어렵거나 호스트 시스템에 손상을 줄 수 있는 작업을 실행하지 못하도록 방지합니다.
 
 ### `block-sudo`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `sudo` 키워드가 포함된 모든 명령어를 차단합니다.
+**기본값:** `sudo` 명령어가 포함된 모든 명령을 차단합니다.
 
-`sudo` 키워드가 포함된 호출을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령어 토큰을 기준으로 수행되어, 셸 연산자 인젝션을 통한 우회를 방지합니다.
+`sudo` 키워드가 포함된 명령 실행을 차단합니다. 패턴 매칭은 원시 문자열이 아닌 파싱된 명령 토큰을 기준으로 수행되므로, 셸 연산자 삽입을 통한 우회를 방지합니다.
 
 **파라미터:**
 
 | 파라미터 | 타입 | 기본값 | 설명 |
 |-------|------|---------|-------------|
-| `allowPatterns` | `string[]` | `[]` | 허용되는 정확한 명령어 프리픽스. 각 항목은 파싱된 argv 토큰과 대조하여 매칭됩니다. |
+| `allowPatterns` | `string[]` | `[]` | 허용되는 정확한 명령 접두사. 각 항목은 파싱된 argv 토큰과 대조됩니다. |
 
 **예시:**
 
@@ -65,10 +66,10 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 }
 ```
 
-이 설정을 사용하면 `sudo systemctl status nginx`는 허용되지만, `sudo rm /etc/hosts`는 차단됩니다.
+이 설정에서 `sudo systemctl status nginx`는 허용되지만, `sudo rm /etc/hosts`는 차단됩니다.
 
 <Note>
-패턴은 원시 명령어 문자열이 아닌 파싱된 토큰과 대조하여 매칭됩니다. 이를 통해 셸 연산자 추가를 통한 우회를 방지합니다 (예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않습니다).
+패턴은 원시 명령 문자열이 아닌 파싱된 토큰과 대조됩니다. 이를 통해 셸 연산자 추가를 통한 우회를 방지합니다 (예: `sudo systemctl status x; rm -rf /`는 `sudo systemctl status *`와 매칭되지 않습니다).
 </Note>
 
 ---
@@ -76,13 +77,13 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `block-rm-rf`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `rm -rf`, `rm -fr` 및 유사한 재귀 삭제 형태를 차단합니다.
+**기본값:** `rm -rf`, `rm -fr` 및 유사한 재귀적 삭제 형식을 차단합니다.
 
 **파라미터:**
 
 | 파라미터 | 타입 | 기본값 | 설명 |
 |-------|------|---------|-------------|
-| `allowPaths` | `string[]` | `[]` | 재귀 삭제가 허용되는 경로 (예: `/tmp`). |
+| `allowPaths` | `string[]` | `[]` | 재귀적 삭제가 허용되는 경로 (예: `/tmp`). |
 
 **예시:**
 
@@ -101,7 +102,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `block-curl-pipe-sh`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` 및 유사한 패턴을 차단합니다.
+**기본값:** `curl <url> | bash`, `curl <url> | sh`, `wget <url> | bash` 및 유사한 패턴을 차단합니다.
 
 파라미터 없음.
 
@@ -110,7 +111,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `block-failproofai-commands`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** failproofai 자체를 제거하거나 비활성화하려는 명령어를 차단합니다 (예: `npm uninstall failproofai`, `failproofai policies --uninstall`).
+**기본값:** failproofai 자체를 제거하거나 비활성화하는 명령(예: `npm uninstall failproofai`, `failproofai policies --uninstall`)을 차단합니다.
 
 파라미터 없음.
 
@@ -118,12 +119,12 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ## 시크릿 (새니타이저)
 
-에이전트가 자격 증명을 컨텍스트나 출력에 노출시키는 것을 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 실행됩니다. Claude가 Bash 명령어를 실행하거나, 파일을 읽거나, 어떤 툴을 호출할 때, 이 정책들은 출력이 Claude에게 반환되기 전에 검사합니다. 시크릿 패턴이 감지되면, 정책은 출력이 다시 전달되는 것을 막는 deny 결정을 반환합니다.
+에이전트가 자격 증명을 컨텍스트나 출력에 노출하지 못하도록 방지합니다. 새니타이저 정책은 **PostToolUse** 이벤트에서 실행됩니다. Claude가 Bash 명령을 실행하거나, 파일을 읽거나, 도구를 호출하면 이 정책들이 출력값을 Claude에 반환하기 전에 검사합니다. 시크릿 패턴이 감지되면 해당 정책은 출력이 다시 전달되지 않도록 deny 결정을 반환합니다.
 
 ### `sanitize-jwt`
 
-**이벤트:** PostToolUse (모든 툴)  
-**기본 동작:** JWT 토큰 (`.`으로 구분된 세 개의 base64url 세그먼트)을 마스킹합니다.
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** JWT 토큰(`.`으로 구분된 세 개의 base64url 세그먼트)을 마스킹합니다.
 
 파라미터 없음.
 
@@ -131,8 +132,8 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ### `sanitize-api-keys`
 
-**이벤트:** PostToolUse (모든 툴)  
-**기본 동작:** 일반적인 API 키 형식을 마스킹합니다: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), AWS 액세스 키 (`AKIA`), Stripe 키 (`sk_live_`, `sk_test_`), Google API 키 (`AIza`).
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** 일반적인 API 키 형식을 마스킹합니다: Anthropic (`sk-ant-`), OpenAI (`sk-`), GitHub PAT (`ghp_`), AWS 액세스 키 (`AKIA`), Stripe 키 (`sk_live_`, `sk_test_`), Google API 키 (`AIza`).
 
 **파라미터:**
 
@@ -159,8 +160,8 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ### `sanitize-connection-strings`
 
-**이벤트:** PostToolUse (모든 툴)  
-**기본 동작:** 자격 증명이 포함된 데이터베이스 연결 문자열을 마스킹합니다 (예: `postgresql://user:password@host/db`).
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** 자격 증명이 포함된 데이터베이스 연결 문자열(예: `postgresql://user:password@host/db`)을 마스킹합니다.
 
 파라미터 없음.
 
@@ -168,8 +169,8 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ### `sanitize-private-key-content`
 
-**이벤트:** PostToolUse (모든 툴)  
-**기본 동작:** PEM 블록(`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` 등)을 마스킹합니다.
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** PEM 블록(`-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` 등)을 마스킹합니다.
 
 파라미터 없음.
 
@@ -177,8 +178,8 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ### `sanitize-bearer-tokens`
 
-**이벤트:** PostToolUse (모든 툴)  
-**기본 동작:** 토큰이 20자 이상인 `Authorization: Bearer <token>` 헤더를 마스킹합니다.
+**이벤트:** PostToolUse (모든 도구)  
+**기본값:** 토큰이 20자 이상인 `Authorization: Bearer <token>` 헤더를 마스킹합니다.
 
 파라미터 없음.
 
@@ -186,14 +187,14 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ## 환경
 
-에이전트가 민감한 환경 구성을 읽거나 노출시키는 것을 보호합니다.
+에이전트가 민감한 환경 설정을 읽거나 노출하지 못하도록 보호합니다.
 
 ### `block-env-files`
 
 **이벤트:** PreToolUse (Bash, Read)  
-**기본 동작:** `cat .env`, `.env`를 파일 경로로 사용하는 `Read` 툴 호출 등을 통한 `.env` 파일 읽기를 차단합니다.
+**기본값:** `cat .env`, 파일 경로가 `.env`인 `Read` 도구 호출 등 `.env` 파일을 읽는 것을 차단합니다.
 
-`.envrc`나 다른 환경 관련 파일은 차단하지 않으며, 정확히 `.env`라는 이름의 파일만 차단합니다.
+`.envrc`나 다른 환경 관련 파일은 차단하지 않으며, 정확히 `.env`로 명명된 파일만 차단합니다.
 
 파라미터 없음.
 
@@ -202,7 +203,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `protect-env-vars`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** 환경 변수를 출력하는 명령어를 차단합니다: `printenv`, `env`, `echo $VAR`.
+**기본값:** 환경 변수를 출력하는 명령(`printenv`, `env`, `echo $VAR`)을 차단합니다.
 
 파라미터 없음.
 
@@ -210,18 +211,18 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ## 파일 접근
 
-에이전트가 프로젝트 경계 내에서만 작업하고 민감한 파일에 접근하지 못하도록 합니다.
+에이전트가 프로젝트 경계 내에서만 작업하고 민감한 파일에 접근하지 못하도록 유지합니다.
 
 ### `block-read-outside-cwd`
 
 **이벤트:** PreToolUse (Read, Bash)  
-**기본 동작:** 현재 작업 디렉토리(프로젝트 루트) 외부의 파일 읽기를 차단합니다.
+**기본값:** 현재 작업 디렉터리(프로젝트 루트) 외부의 파일을 읽는 것을 차단합니다.
 
 **파라미터:**
 
 | 파라미터 | 타입 | 기본값 | 설명 |
 |-------|------|---------|-------------|
-| `allowPaths` | `string[]` | `[]` | cwd 외부에 있더라도 허용되는 절대 경로 프리픽스. |
+| `allowPaths` | `string[]` | `[]` | cwd 외부에 있더라도 허용되는 절대 경로 접두사. |
 
 **예시:**
 
@@ -240,13 +241,13 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `block-secrets-write`
 
 **이벤트:** PreToolUse (Write, Edit)  
-**기본 동작:** 개인 키 및 인증서에 일반적으로 사용되는 파일에 대한 쓰기를 차단합니다: `id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`.
+**기본값:** 개인 키 및 인증서에 일반적으로 사용되는 파일(`id_rsa`, `id_ed25519`, `*.key`, `*.pem`, `*.p12`, `*.pfx`)에 대한 쓰기를 차단합니다.
 
 **파라미터:**
 
 | 파라미터 | 타입 | 기본값 | 설명 |
 |-------|------|---------|-------------|
-| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일명 패턴 (글로브 스타일). |
+| `additionalPatterns` | `string[]` | `[]` | 차단할 추가 파일명 패턴 (글로브 방식). |
 
 **예시:**
 
@@ -269,7 +270,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `block-push-master`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `git push origin main`과 `git push origin master`를 차단합니다.
+**기본값:** `git push origin main` 및 `git push origin master`를 차단합니다.
 
 **파라미터:**
 
@@ -290,7 +291,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ```
 
 <Tip>
-`enabledPolicies`에서 정책을 제거하지 않고 모든 브랜치로의 푸시를 허용하려면 (사실상 정책 비활성화), `protectedBranches: []`로 설정하세요.
+`enabledPolicies`에서 제거하지 않고 이 정책을 사실상 비활성화하려면(모든 브랜치에 푸시 허용), `protectedBranches: []`로 설정하세요.
 </Tip>
 
 ---
@@ -298,7 +299,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `block-work-on-main`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `main` 또는 `master` 브랜치를 직접 체크아웃하는 것을 차단합니다.
+**기본값:** `main` 또는 `master` 브랜치를 직접 체크아웃하는 것을 차단합니다.
 
 **파라미터:**
 
@@ -311,9 +312,9 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `block-force-push`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `git push --force`와 `git push -f`를 차단합니다.
+**기본값:** `git push --force` 및 `git push -f`를 차단합니다.
 
-정책별 파라미터 없음. 크로스커팅 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하여 대안을 제안할 수 있습니다:
+정책별 파라미터는 없습니다. 공통 [`hint`](/ko/configuration#hint-cross-cutting)를 사용하여 대안을 제안할 수 있습니다:
 
 ```json
 {
@@ -330,7 +331,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-git-amend`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `git commit --amend` 실행 시 Claude에게 신중하게 진행하도록 안내합니다. 명령어 자체를 차단하지는 않습니다.
+**기본값:** `git commit --amend` 실행 시 Claude에게 주의하여 진행하도록 안내합니다. 명령을 차단하지는 않습니다.
 
 파라미터 없음.
 
@@ -339,7 +340,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-git-stash-drop`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `git stash drop` 실행 전에 Claude에게 확인하도록 안내합니다. 명령어 자체를 차단하지는 않습니다.
+**기본값:** `git stash drop` 실행 전 Claude에게 확인하도록 안내합니다. 명령을 차단하지는 않습니다.
 
 파라미터 없음.
 
@@ -348,7 +349,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-all-files-staged`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `git add -A` 또는 `git add .` 실행 시 Claude에게 스테이징할 내용을 검토하도록 안내합니다. 명령어 자체를 차단하지는 않습니다.
+**기본값:** `git add -A` 또는 `git add .` 실행 시 Claude에게 스테이징할 내용을 검토하도록 안내합니다. 명령을 차단하지는 않습니다.
 
 파라미터 없음.
 
@@ -361,7 +362,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-destructive-sql`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `DROP TABLE`, `DROP DATABASE`, 또는 `WHERE` 절 없는 `DELETE`가 포함된 SQL 실행 전에 Claude에게 확인하도록 안내합니다.
+**기본값:** `DROP TABLE`, `DROP DATABASE`, 또는 `WHERE` 절이 없는 `DELETE`가 포함된 SQL 실행 전 Claude에게 확인하도록 안내합니다.
 
 파라미터 없음.
 
@@ -370,7 +371,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-schema-alteration`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `ALTER TABLE` 구문 실행 전에 Claude에게 확인하도록 안내합니다.
+**기본값:** `ALTER TABLE` 구문 실행 전 Claude에게 확인하도록 안내합니다.
 
 파라미터 없음.
 
@@ -378,12 +379,12 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ## 경고
 
-파괴적이지는 않지만 잠재적으로 위험한 작업 전에 에이전트에게 추가 컨텍스트를 제공합니다.
+잠재적으로 위험하지만 파괴적이지 않은 작업 전에 에이전트에게 추가 맥락을 제공합니다.
 
 ### `warn-large-file-write`
 
 **이벤트:** PreToolUse (Write)  
-**기본 동작:** 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 안내합니다.
+**기본값:** 1024 KB보다 큰 파일을 쓰기 전에 Claude에게 확인하도록 안내합니다.
 
 **파라미터:**
 
@@ -412,7 +413,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-package-publish`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `npm publish` 실행 전에 Claude에게 확인하도록 안내합니다.
+**기본값:** `npm publish` 실행 전 Claude에게 확인하도록 안내합니다.
 
 파라미터 없음.
 
@@ -421,7 +422,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-background-process`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `nohup`, `&`, `disown`, 또는 `screen`을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의하도록 안내합니다.
+**기본값:** `nohup`, `&`, `disown`, `screen`을 통해 백그라운드 프로세스를 시작할 때 Claude에게 주의하도록 안내합니다.
 
 파라미터 없음.
 
@@ -430,20 +431,56 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `warn-global-package-install`
 
 **이벤트:** PreToolUse (Bash)  
-**기본 동작:** `npm install -g`, `yarn global add`, 또는 가상 환경 없이 `pip install` 실행 전에 Claude에게 확인하도록 안내합니다.
+**기본값:** `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`는 모두 차단되며, `uv` 또는 `bun`을 사용하도록 안내하는 메시지가 표시됩니다. `uv pip install flask`와 같은 명령은 `uv`가 허용 목록에 있고 우선적으로 확인되므로 허용됩니다.
+
+---
+
 ## AI 동작
 
-에이전트가 멈추거나 예기치 않게 동작하는 경우를 감지합니다.
+에이전트가 루프에 빠지거나 예상치 못한 동작을 보일 때 감지합니다.
 
 ### `warn-repeated-tool-calls`
 
-**이벤트:** PreToolUse (모든 툴)  
-**기본 동작:** 동일한 툴이 동일한 파라미터로 3회 이상 호출될 때 Claude에게 재고하도록 안내합니다 — 이는 에이전트가 루프에 빠진 일반적인 신호입니다.
+**이벤트:** PreToolUse (모든 도구)  
+**기본값:** 동일한 도구가 동일한 파라미터로 3회 이상 호출될 때 Claude에게 재고하도록 안내합니다. 이는 에이전트가 루프에 빠졌다는 일반적인 신호입니다.
 
 파라미터 없음.
 
@@ -451,14 +488,14 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 
 ## 워크플로우
 
-세션 종료 시 체계적인 워크플로우를 강제합니다. 이 정책들은 **Stop** 이벤트에서 실행되며, 각 조건이 충족될 때까지 Claude의 종료를 차단합니다. 커밋 → 푸시 → PR → CI의 자연스러운 의존성 체인을 따릅니다. 정책이 deny를 반환하면, 체인의 이후 정책은 건너뜁니다 (deny 단락 평가).
+세션 종료 시 규율 있는 워크플로우를 강제합니다. 이 정책들은 **Stop** 이벤트에서 실행되며, 각 조건이 충족될 때까지 Claude의 중단을 차단합니다. 커밋 → 푸시 → PR → CI의 자연스러운 의존성 체인을 따릅니다. 정책이 deny를 반환하면 이후 정책들은 건너뜁니다 (deny 단락 평가).
 
-모든 워크플로우 정책은 **fail-open** 방식입니다: 필요한 툴을 사용할 수 없는 경우 (예: `gh`가 설치되지 않음, git 원격 없음), 정책은 검사를 건너뛴 이유를 설명하는 안내 메시지와 함께 허용합니다.
+모든 워크플로우 정책은 **fail-open** 방식입니다: 필요한 도구를 사용할 수 없는 경우(예: `gh` 미설치, git 원격 없음), 정책은 검사가 건너뛰어진 이유를 설명하는 안내 메시지와 함께 허용합니다.
 
 ### `require-commit-before-stop`
 
 **이벤트:** Stop  
-**기본 동작:** 커밋되지 않은 변경 사항(수정됨, 스테이징됨, 추적되지 않는 파일)이 있을 때 종료를 차단합니다. 작업 디렉토리가 깨끗할 때는 안내 메시지를 반환합니다.
+**기본값:** 커밋되지 않은 변경사항(수정됨, 스테이징됨, 추적되지 않은 파일)이 있을 때 중단을 차단합니다. 작업 디렉터리가 깨끗한 경우 안내 메시지를 반환합니다.
 
 파라미터 없음.
 
@@ -467,7 +504,7 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `require-push-before-stop`
 
 **이벤트:** Stop  
-**기본 동작:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 종료를 차단합니다. 필요한 경우 추적 브랜치 생성을 위해 `git push -u`를 제안합니다. 원격이 구성되지 않은 경우 fail-open 처리됩니다.
+**기본값:** 푸시되지 않은 커밋이 있거나 현재 브랜치에 원격 추적 브랜치가 없을 때 중단을 차단합니다. 필요한 경우 추적 브랜치를 생성하도록 `git push -u`를 제안합니다. 원격이 설정되지 않은 경우 fail-open 방식으로 동작합니다.
 
 **파라미터:**
 
@@ -492,13 +529,13 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `require-pr-before-stop`
 
 **이벤트:** Stop  
-**기본 동작:** 현재 브랜치에 대한 풀 리퀘스트가 없거나, 기존 PR이 닫혔거나 머지된 경우 종료를 차단합니다. `gh pr create`로 PR을 생성하도록 Claude에게 안내합니다.
+**기본값:** 현재 브랜치에 풀 리퀘스트가 없거나 기존 PR이 closed/merged 상태일 때 중단을 차단합니다. `gh pr create`로 PR을 생성하도록 Claude에게 안내합니다.
 
 파라미터 없음.
 
 <Note>
-이 정책은 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다.
-풀 리퀘스트에 대한 읽기 접근을 위해 `repo` 스코프를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않거나 인증되지 않은 경우, 정책은 fail-open 처리되고 Claude에게 이유를 보고합니다.
+이 정책을 사용하려면 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되어 있고 인증되어 있어야 합니다.
+풀 리퀘스트 읽기 권한을 위해 `repo` 스코프를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되어 있지 않거나 인증되지 않은 경우, 정책은 fail-open 방식으로 동작하며 그 이유를 Claude에게 보고합니다.
 </Note>
 
 ---
@@ -506,13 +543,13 @@ failproofai는 일반적인 에이전트 실패 유형을 감지하는 30개의
 ### `require-ci-green-before-stop`
 
 **이벤트:** Stop  
-**기본 동작:** 현재 브랜치에서 CI 검사가 실패 중이거나 아직 실행 중일 때 종료를 차단합니다. GitHub Actions 워크플로우 실행과 서드파티 봇 검사(예: CodeRabbit, SonarCloud, Codecov)를 모두 확인합니다. `skipped` 결론은 성공으로 처리합니다. 모든 검사가 통과하면 안내 메시지를 반환합니다.
+**기본값:** 현재 브랜치의 CI 검사가 실패하거나 아직 실행 중일 때 중단을 차단합니다. GitHub Actions 워크플로우 실행과 서드파티 봇 검사(예: CodeRabbit, SonarCloud, Codecov) 모두를 확인합니다. `skipped` 및 `cancelled` 결과는 성공으로 처리합니다. 모든 검사가 통과되면 안내 메시지를 반환합니다.
 
 파라미터 없음.
 
 <Note>
-이 정책은 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되고 인증되어 있어야 합니다.
-Actions 워크플로우 실행 및 Checks API에 대한 읽기 접근을 위해 `repo` 스코프를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되지 않거나 인증되지 않은 경우, 정책은 fail-open 처리되고 Claude에게 이유를 보고합니다.
+이 정책을 사용하려면 [GitHub CLI](https://cli.github.com/) (`gh`)가 설치되어 있고 인증되어 있어야 합니다.
+Actions 워크플로우 실행 및 Checks API에 대한 읽기 권한을 위해 `repo` 스코프를 가진 개인 액세스 토큰으로 `gh auth login`을 실행하세요. `gh`가 설치되어 있지 않거나 인증되지 않은 경우, 정책은 fail-open 방식으로 동작하며 그 이유를 Claude에게 보고합니다.
 </Note>
 
 ---
@@ -521,7 +558,7 @@ Actions 워크플로우 실행 및 Checks API에 대한 읽기 접근을 위해
 
 ## 개별 정책 비활성화
 
-설정 파일의 `enabledPolicies`에서 특정 정책을 제거하거나, 대시보드의 Policies 탭에서 토글로 끄세요.
+설정 파일의 `enabledPolicies`에서 특정 정책을 제거하거나, 대시보드의 Policies 탭에서 해제합니다.
 
 ```json
 {