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

package/.next/standalone/docs/ja/custom-policies.mdx

@@ -1,10 +1,10 @@
 ---
 title: カスタムポリシー
-description: "JavaScriptで独自のポリシーを記述する — 規約の適用、ドリフトの防止、障害の検出、外部システムとの連携"
+description: "JavaScriptで独自のポリシーを記述する — 規約の強制、ドリフトの防止、障害の検出、外部システムとの連携"
 icon: code
 ---
 
-カスタムポリシーを使用すると、あらゆるエージェントの動作に対してルールを記述できます。プロジェクトの規約を適用する、ドリフトを防止する、破壊的な操作をゲートする、スタックしたエージェントを検出する、あるいはSlackや承認ワークフローと連携するといったことが可能です。組み込みポリシーと同じフックイベントシステムおよび`allow`、`deny`、`instruct`の判定を使用します。
+カスタムポリシーを使用すると、エージェントのあらゆる動作に対してルールを記述できます。プロジェクト規約の強制、ドリフトの防止、破壊的な操作のゲート処理、スタックしたエージェントの検出、Slackや承認ワークフローとの統合などが可能です。組み込みポリシーと同じフックイベントシステムおよび `allow`、`deny`、`instruct` の決定を使用します。
 
 ---
 
@@ -37,30 +37,30 @@ failproofai policies --install --custom ./my-policies.js
 
 ---
 
-## カスタムポリシーの読み込み方法
+## カスタムポリシーの2つのロード方法
 
 ### オプション1: 規約ベース（推奨）
 
-`*policies.{js,mjs,ts}` ファイルを `.failproofai/policies/` に配置するだけで、フラグや設定変更なしに自動的に読み込まれます。Gitフックと同じ仕組みです。ファイルを置けば、そのまま動作します。
+`.failproofai/policies/` に `*policies.{js,mjs,ts}` ファイルを配置するだけで自動的にロードされます — フラグや設定変更は不要です。git フックと同じ仕組みです: ファイルを置くだけで動作します。
 
 ```
-# プロジェクトレベル — gitにコミットされ、チームで共有
+# プロジェクトレベル — gitにコミット、チームで共有
 .failproofai/policies/security-policies.mjs
 .failproofai/policies/workflow-policies.mjs
 
-# ユーザーレベル — 個人用、全プロジェクトに適用
+# ユーザーレベル — 個人用、すべてのプロジェクトに適用
 ~/.failproofai/policies/my-policies.mjs
 ```
 
-**仕組み:**
-- プロジェクトディレクトリとユーザーディレクトリの両方がスキャンされます（ユニオン — 先着スコープ優先ではありません）
-- ファイルは各ディレクトリ内でアルファベット順に読み込まれます。順序を制御するには `01-`、`02-` などのプレフィックスを付けてください
-- `*policies.{js,mjs,ts}` にマッチするファイルのみ読み込まれ、それ以外は無視されます
-- 各ファイルは独立して読み込まれます（ファイル単位でフェイルオープン）
-- 明示的な `--custom` および組み込みポリシーと共存できます
+**動作の仕組み:**
+- プロジェクトとユーザーの両方のディレクトリがスキャンされます（最初のスコープ優先ではなく、両方の和集合）
+- 各ディレクトリ内でファイルはアルファベット順にロードされます。順序を制御するには `01-`、`02-` などのプレフィックスを付けてください
+- `*policies.{js,mjs,ts}` に一致するファイルのみロードされ、その他のファイルは無視されます
+- 各ファイルは独立してロードされます（ファイルごとにフェイルオープン）
+- 明示的な `--custom` および組み込みポリシーと併用できます
 
 <Tip>
-規約ポリシーは、チーム全体でポリシーを共有する最も簡単な方法です。`.failproofai/policies/` をgitにコミットすれば、チームメンバー全員が自動的に取得できます。
+規約ポリシーは、組織の品質基準を構築する最も簡単な方法です。`.failproofai/policies/` を git にコミットすれば、すべてのチームメンバーが自動的に同じルールを取得できます — 開発者ごとのセットアップは不要です。チームが新しい障害パターンを発見するたびにポリシーを追加してプッシュしてください。時間とともに、これらは貢献のたびに改善され続ける生きた品質基準となります。
 </Tip>
 
 ### オプション2: 明示的なファイルパス
@@ -69,22 +69,22 @@ failproofai policies --install --custom ./my-policies.js
 # カスタムポリシーファイルを指定してインストール
 failproofai policies --install --custom ./my-policies.js
 
-# ポリシーファイルパスを置き換える
+# ポリシーファイルパスを置き換え
 failproofai policies --install --custom ./new-policies.js
 
-# カスタムポリシーのパスを設定から削除
+# 設定からカスタムポリシーパスを削除
 failproofai policies --uninstall --custom
 ```
 
-解決された絶対パスは `policies-config.json` の `customPoliciesPath` に保存されます。ファイルはフックイベントのたびに新たに読み込まれます — イベント間でキャッシュは行われません。
+解決された絶対パスは `policies-config.json` に `customPoliciesPath` として保存されます。ファイルはフックイベントのたびに新たにロードされます — イベント間のキャッシュはありません。
 
 ### 両方を併用する
 
-規約ポリシーと明示的な `--custom` ファイルは共存できます。読み込み順序:
+規約ポリシーと明示的な `--custom` ファイルは共存できます。ロード順序:
 
 1. 明示的な `customPoliciesPath` ファイル（設定されている場合）
-2. プロジェクトの規約ファイル（`{cwd}/.failproofai/policies/`、アルファベット順）
-3. ユーザーの規約ファイル（`~/.failproofai/policies/`、アルファベット順）
+2. プロジェクト規約ファイル（`{cwd}/.failproofai/policies/`、アルファベット順）
+3. ユーザー規約ファイル（`~/.failproofai/policies/`、アルファベット順）
 
 ---
 
@@ -98,45 +98,45 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-ポリシーを登録します。同じファイル内に複数のポリシーを定義する場合は、必要な回数だけ呼び出してください。
+ポリシーを登録します。同じファイル内で複数のポリシーを登録するために何度でも呼び出せます。
 
 ```ts
 customPolicies.add({
   name: string;                         // 必須 - 一意の識別子
   description?: string;                 // `failproofai policies` の出力に表示される
-  match?: { events?: HookEventType[] }; // イベントタイプでフィルタリング。省略すると全てにマッチ
+  match?: { events?: HookEventType[] }; // イベントタイプでフィルタリング。省略するとすべてにマッチ
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
 ```
 
-### 判定ヘルパー
+### 決定ヘルパー
 
-| 関数 | 効果 | 使用場面 |
+| 関数 | 効果 | 使用タイミング |
 |----------|--------|----------|
-| `allow()` | 操作を静かに許可する | アクションが安全で、メッセージが不要な場合 |
-| `deny(message)` | 操作をブロックする | エージェントがこのアクションを取るべきでない場合 |
-| `instruct(message)` | ブロックせずにコンテキストを追加する | エージェントが正しい方向を維持するための追加コンテキストを提供する場合 |
+| `allow()` | 操作を暗黙的に許可 | アクションが安全で、メッセージが不要な場合 |
+| `deny(message)` | 操作をブロック | エージェントがこのアクションを実行すべきでない場合 |
+| `instruct(message)` | ブロックせずにコンテキストを追加 | エージェントに追加のコンテキストを与えて軌道を保つ場合 |
 
-`deny(message)` — メッセージは `"Blocked by failproofai:"` というプレフィックスを付けてClaudeに表示されます。単一の `deny` が発生すると、以降の全ての評価がショートサーキットされます。
+`deny(message)` — メッセージは `"Blocked by failproofai:"` というプレフィックス付きで Claude に表示されます。1つの `deny` で以降のすべての評価がショートサーキットされます。
 
-`instruct(message)` — メッセージは現在のツールコールのClaudeのコンテキストに追加されます。全ての `instruct` メッセージは蓄積され、まとめて配信されます。
+`instruct(message)` — メッセージは現在のツール呼び出しに対する Claude のコンテキストに追加されます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
 
 <Tip>
-`deny` または `instruct` メッセージに追加のガイダンスを付け加えるには、`policyParams` の `hint` フィールドを使用します — コードの変更は不要です。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳細は[設定 → hint](/ja/configuration#hint-cross-cutting)を参照してください。
+`policyParams` の `hint` フィールドを追加することで、コード変更なしに `deny` または `instruct` メッセージに追加のガイダンスを付加できます。これはカスタム（`custom/`）、プロジェクト規約（`.failproofai-project/`）、ユーザー規約（`.failproofai-user/`）ポリシーでも機能します。詳しくは[設定 → hint](/ja/configuration#hint-cross-cutting)をご覧ください。
 </Tip>
 
 ### 情報提供用のallowメッセージ
 
-`allow(message)` は操作を許可し**つつ**、情報提供メッセージをClaudeに返します。メッセージはフックハンドラーのstdoutレスポンスの `additionalContext` として配信されます — `instruct` と同じ仕組みですが、意味的には異なります: これは警告ではなく、状態の更新です。
+`allow(message)` は操作を許可し**かつ**情報メッセージを Claude に送信します。メッセージはフックハンドラーの stdout レスポンスの `additionalContext` として配信されます — `instruct` と同じ仕組みですが、意味的に異なります: 警告ではなくステータス更新です。
 
-| 関数 | 効果 | 使用場面 |
+| 関数 | 効果 | 使用タイミング |
 |----------|--------|----------|
-| `allow(message)` | 許可してClaudeにコンテキストを送信する | チェックが通過したことを確認する、またはチェックがスキップされた理由を説明する |
+| `allow(message)` | 許可してコンテキストを Claude に送信 | チェックが通過したことの確認、またはチェックがスキップされた理由の説明 |
 
 ユースケース:
-- **状態確認:** `allow("All CI checks passed.")` — Claudeに全てが正常であることを伝える
-- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — チェックがスキップされた理由をClaudeに伝え、完全なコンテキストを提供する
-- **複数のメッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返した場合、全てのメッセージが改行で結合されてまとめて配信される
+- **ステータス確認:** `allow("All CI checks passed.")` — Claudeにすべてが正常であることを伝える
+- **フェイルオープンの説明:** `allow("GitHub CLI not installed, skipping CI check.")` — Claudeにチェックがスキップされた理由を伝え、完全なコンテキストを提供する
+- **複数メッセージの蓄積:** 複数のポリシーがそれぞれ `allow(message)` を返す場合、すべてのメッセージが改行で結合されてまとめて配信されます
 
 ```js
 customPolicies.add({
@@ -146,7 +146,7 @@ customPolicies.add({
     const cwd = ctx.session?.cwd;
     if (!cwd) return allow("No working directory, skipping branch check.");
 
-    // ... ブランチの状態を確認 ...
+    // ... check branch status ...
     if (allPushed) {
       return allow("Branch is up to date with remote.");
     }
@@ -162,39 +162,39 @@ customPolicies.add({
 | `eventType` | `string` | `"PreToolUse"`、`"PostToolUse"`、`"Notification"`、`"Stop"` |
 | `toolName` | `string \| undefined` | 呼び出されるツール（例: `"Bash"`、`"Write"`、`"Read"`） |
 | `toolInput` | `Record<string, unknown> \| undefined` | ツールの入力パラメータ |
-| `payload` | `Record<string, unknown>` | Claude Codeからの完全な生イベントペイロード |
+| `payload` | `Record<string, unknown>` | Claude Code からの完全な生イベントペイロード |
 | `session` | `SessionMetadata \| undefined` | セッションコンテキスト（下記参照） |
 
 ### `SessionMetadata` フィールド
 
 | フィールド | 型 | 説明 |
 |-------|------|-------------|
-| `sessionId` | `string` | Claude Codeセッションの識別子 |
-| `cwd` | `string` | Claude Codeセッションの作業ディレクトリ |
-| `transcriptPath` | `string` | セッションのJSONLトランスクリプトファイルへのパス |
+| `sessionId` | `string` | Claude Code セッション識別子 |
+| `cwd` | `string` | Claude Code セッションの作業ディレクトリ |
+| `transcriptPath` | `string` | セッションの JSONL トランスクリプトファイルへのパス |
 
 ### イベントタイプ
 
 | イベント | 発火タイミング | `toolInput` の内容 |
 |-------|--------------|----------------------|
-| `PreToolUse` | Claudeがツールを実行する前 | ツールの入力（例: Bashの場合 `{ command: "..." }`） |
+| `PreToolUse` | Claude がツールを実行する前 | ツールの入力（例: Bash の場合 `{ command: "..." }`） |
 | `PostToolUse` | ツールが完了した後 | ツールの入力 + `tool_result`（出力） |
-| `Notification` | Claudeが通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - フックは常に `allow()` を返す必要があり、通知をブロックすることはできません |
-| `Stop` | Claudeセッションが終了するとき | 空 |
+| `Notification` | Claude が通知を送信するとき | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - フックは常に `allow()` を返す必要があり、通知をブロックすることはできません |
+| `Stop` | Claude セッションが終了するとき | 空 |
 
 ---
 
 ## 評価順序
 
-ポリシーは以下の順序で評価されます:
+ポリシーは次の順序で評価されます:
 
 1. 組み込みポリシー（定義順）
-2. `customPoliciesPath` からの明示的なカスタムポリシー（`.add()` の順序）
-3. プロジェクトの `.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序）
-4. ユーザーの `~/.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、ファイル内は `.add()` の順序）
+2. `customPoliciesPath` からの明示的なカスタムポリシー（`.add()` 順）
+3. プロジェクト `.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、内部では `.add()` 順）
+4. ユーザー `~/.failproofai/policies/` からの規約ポリシー（ファイルはアルファベット順、内部では `.add()` 順）
 
 <Note>
-最初の `deny` が全ての後続ポリシーをショートサーキットします。全ての `instruct` メッセージは蓄積され、まとめて配信されます。
+最初の `deny` で以降のすべてのポリシーがショートサーキットされます。すべての `instruct` メッセージは蓄積されてまとめて配信されます。
 </Note>
 
 ---
@@ -218,11 +218,11 @@ customPolicies.add({
 });
 ```
 
-エントリファイルから到達可能な全ての相対インポートが解決されます。これは `from "failproofai"` インポートを実際のdistパスに書き換え、ESMの互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。
+エントリーファイルから到達可能なすべての相対インポートが解決されます。これは `from "failproofai"` インポートを実際の dist パスに書き換え、ESM 互換性を確保するために一時的な `.mjs` ファイルを作成することで実装されています。
 
 ---
 
-## イベントタイプのフィルタリング
+## イベントタイプフィルタリング
 
 `match.events` を使用して、ポリシーが発火するタイミングを制限します:
 
@@ -231,30 +231,30 @@ customPolicies.add({
   name: "require-summary-on-stop",
   match: { events: ["Stop"] },
   fn: async (ctx) => {
-    // セッション終了時のみ発火
-    // ctx.session.transcriptPath にセッションの完全なログが含まれる
+    // セッション終了時にのみ発火
+    // ctx.session.transcriptPath には完全なセッションログが含まれる
     return allow();
   },
 });
 ```
 
-`match` を完全に省略すると、全てのイベントタイプで発火します。
+`match` を完全に省略すると、すべてのイベントタイプで発火します。
 
 ---
 
-## エラー処理と障害モード
+## エラーハンドリングと障害モード
 
 カスタムポリシーは**フェイルオープン**です: エラーが発生しても組み込みポリシーをブロックしたり、フックハンドラーをクラッシュさせたりすることはありません。
 
 | 障害 | 動作 |
 |---------|----------|
-| `customPoliciesPath` が未設定 | 明示的なカスタムポリシーは実行されない。規約ポリシーと組み込みポリシーは正常に継続 |
-| ファイルが見つからない | `~/.failproofai/hook.log` に警告をログ記録。組み込みポリシーは継続 |
-| 構文/インポートエラー（明示的） | `~/.failproofai/hook.log` にエラーをログ記録。明示的なカスタムポリシーはスキップ |
-| 構文/インポートエラー（規約） | エラーをログ記録。該当ファイルはスキップ。他の規約ファイルは引き続き読み込まれる |
-| `fn` が実行時に例外をスロー | エラーをログ記録。該当フックは `allow` として扱われる。他のフックは継続 |
-| `fn` が10秒以上かかる | タイムアウトをログ記録。`allow` として扱われる |
-| 規約ディレクトリが存在しない | 規約ポリシーは実行されない。エラーなし |
+| `customPoliciesPath` が未設定 | 明示的なカスタムポリシーは実行されない。規約ポリシーと組み込みは通常通り継続 |
+| ファイルが見つからない | `~/.failproofai/hook.log` に警告が記録される。組み込みは継続 |
+| 構文/インポートエラー（明示的） | `~/.failproofai/hook.log` にエラーが記録される。明示的なカスタムポリシーはスキップ |
+| 構文/インポートエラー（規約） | エラーが記録される。そのファイルはスキップされ、他の規約ファイルは引き続きロード |
+| 実行時に `fn` が例外をスロー | エラーが記録される。そのフックは `allow` として扱われ、他のフックは継続 |
+| `fn` が10秒以上かかる | タイムアウトが記録される。`allow` として扱われる |
+| 規約ディレクトリが存在しない | 規約ポリシーは実行されない。エラーは発生しない |
 
 <Tip>
 カスタムポリシーのエラーをデバッグするには、ログファイルを監視してください:
@@ -272,7 +272,7 @@ tail -f ~/.failproofai/hook.log
 // my-policies.js
 import { customPolicies, allow, deny, instruct } from "failproofai";
 
-// エージェントがsecretsディレクトリに書き込むことを防止
+// エージェントが secrets/ ディレクトリに書き込むのを防ぐ
 customPolicies.add({
   name: "block-secrets-dir",
   description: "Prevent agent from writing to secrets/ directory",
@@ -285,7 +285,7 @@ customPolicies.add({
   },
 });
 
-// エージェントを正しい方向に維持: コミット前にテストを確認
+// エージェントを軌道に乗せる: コミット前にテストを確認
 customPolicies.add({
   name: "remind-test-before-commit",
   description: "Keep the agent on track: verify tests pass before committing",
@@ -300,7 +300,7 @@ customPolicies.add({
   },
 });
 
-// フリーズ期間中の予定外の依存関係変更を防止
+// フリーズ期間中の予定外の依存関係変更を防ぐ
 customPolicies.add({
   name: "dependency-freeze",
   description: "Prevent unplanned dependency changes during freeze period",
@@ -323,22 +323,22 @@ export { customPolicies };
 
 ## サンプル
 
-`examples/` ディレクトリには、すぐに実行できるポリシーファイルが含まれています:
+`examples/` ディレクトリにはすぐに実行できるポリシーファイルが含まれています:
 
 | ファイル | 内容 |
 |------|----------|
-| `examples/policies-basic.js` | 一般的なエージェントの障害モードをカバーする5つのスターターポリシー |
+| `examples/policies-basic.js` | よくあるエージェント障害モードをカバーする5つのスタータポリシー |
 | `examples/policies-advanced/index.js` | 高度なパターン: 推移的インポート、非同期呼び出し、出力のスクラビング、セッション終了フック |
-| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.envファイルへの書き込みのブロック、gitの履歴書き換えの防止） |
-| `examples/convention-policies/workflow-policies.mjs` | 規約ベースのワークフローポリシー（テストのリマインダー、ファイル書き込みの監査） |
+| `examples/convention-policies/security-policies.mjs` | 規約ベースのセキュリティポリシー（.env ファイルへの書き込みのブロック、git履歴の書き換え防止） |
+| `examples/convention-policies/workflow-policies.mjs` | 規約ベースのワークフローポリシー（テストリマインダー、監査ファイル書き込み） |
 
-### 明示的なファイルサンプルの使用
+### 明示的なファイルの例を使用する
 
 ```bash
 failproofai policies --install --custom ./examples/policies-basic.js
 ```
 
-### 規約ベースのサンプルの使用
+### 規約ベースの例を使用する
 
 ```bash
 # プロジェクトレベルにコピー
@@ -350,4 +350,4 @@ mkdir -p ~/.failproofai/policies
 cp examples/convention-policies/*.mjs ~/.failproofai/policies/
 ```
 
-インストールコマンドは不要です — 次のフックイベント時に自動的にファイルが読み込まれます。
+インストールコマンドは不要です — 次のフックイベント時にファイルが自動的に検出されます。

package/.next/standalone/docs/ja/examples.mdx

@@ -1,16 +1,16 @@
 ---
 title: 使用例
-description: "Claude Code と Agents SDK 向けフックの設定方法"
+description: "Claude Code と Agents SDK にフックを設定する方法"
 icon: book-open
 ---
 
-よくあるシナリオですぐに使える例を紹介します。各例では、インストール方法と期待される動作を説明します。
+よく使われるシナリオのすぐに使えるサンプル集です。インストール方法と期待される動作をそれぞれ示します。
 
 ---
 
 ## Claude Code 向けフックの設定
 
-Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.com/en/docs/claude-code/hooks)を通じて統合されます。`failproofai policies --install` を実行すると、Claude Code の `settings.json` にフックコマンドが登録され、すべてのツール呼び出し時に実行されます。
+Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.com/en/docs/claude-code/hooks)を通じて連携します。`failproofai policies --install` を実行すると、Claude Code の `settings.json` にフックコマンドが登録され、すべてのツール呼び出し時に発火します。
 
 <Steps>
   <Step title="failproofai をインストールする">
@@ -18,7 +18,7 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c
     npm install -g failproofai
     ```
   </Step>
-  <Step title="組み込みポリシーをすべて有効にする">
+  <Step title="すべての組み込みポリシーを有効にする">
     ```bash
     failproofai policies --install
     ```
@@ -28,14 +28,14 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c
     cat ~/.claude/settings.json | grep failproofai
     ```
 
-    `PreToolUse`、`PostToolUse`、`Notification`、`Stop` イベントのフックエントリが表示されるはずです。
+    `PreToolUse`、`PostToolUse`、`Notification`、`Stop` イベントのフックエントリーが表示されるはずです。
   </Step>
   <Step title="Claude Code を起動する">
     ```bash
     claude
     ```
 
-    これで、すべてのツール呼び出しに対してポリシーが自動的に実行されます。試しに Claude に `sudo rm -rf /` を実行するよう指示してみてください — ブロックされます。
+    ポリシーがすべてのツール呼び出しで自動的に実行されるようになります。Claude に `sudo rm -rf /` を実行するよう依頼してみてください — ブロックされます。
   </Step>
 </Steps>
 
@@ -52,11 +52,11 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c
     ```
   </Step>
   <Step title="エージェントにフックを設定する">
-    エージェントプロセスの作成時にフックコマンドを渡します。フックは Claude Code と同じように、stdin/stdout の JSON を介して起動されます。
+    エージェントプロセスの作成時にフックコマンドを渡します。フックは Claude Code と同様に stdin/stdout の JSON 形式で発火します。
 
     ```bash
-    failproofai --hook PreToolUse   # 各ツールの実行前に呼び出される
-    failproofai --hook PostToolUse  # 各ツールの実行後に呼び出される
+    failproofai --hook PreToolUse   # 各ツールの前に呼び出される
+    failproofai --hook PostToolUse  # 各ツールの後に呼び出される
     ```
   </Step>
   <Step title="エージェント用のカスタムポリシーを作成する">
@@ -88,7 +88,7 @@ Failproof AI は Claude Code の[フックシステム](https://docs.anthropic.c
 
 ## 破壊的なコマンドをブロックする
 
-最もよく使われる設定 — エージェントが取り消し不可能な操作を行うのを防ぎます。
+最も一般的なセットアップ — エージェントが取り返しのつかない操作を行わないようにします。
 
 ```bash
 failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
@@ -98,23 +98,23 @@ failproofai policies --install block-sudo block-rm-rf block-force-push block-cur
 - `block-sudo` — すべての `sudo` コマンドをブロック
 - `block-rm-rf` — 再帰的なファイル削除をブロック
 - `block-force-push` — `git push --force` をブロック
-- `block-curl-pipe-sh` — リモートスクリプトのシェルへのパイプをブロック
+- `block-curl-pipe-sh` — リモートスクリプトをシェルにパイプする操作をブロック
 
 ---
 
 ## シークレットの漏洩を防ぐ
 
-ツールの出力に含まれる認証情報をエージェントが参照・漏洩するのを防ぎます。
+ツールの出力に含まれる認証情報をエージェントが参照・漏洩しないようにします。
 
 ```bash
 failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
 ```
 
-これらは `PostToolUse` で実行されます。ツールの実行後、エージェントが出力を受け取る前にスクラブ処理が行われます。
+これらは `PostToolUse` で発火します — ツールの実行後、エージェントが出力を受け取る前にスクラブ処理が行われます。
 
 ---
 
-## エージェントの待機時に Slack へアラートを送信する
+## エージェントの待機時に Slack へアラートを送る
 
 通知フックを使って、アイドル状態のアラートを Slack に転送します。
 
@@ -158,9 +158,9 @@ SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --c
 
 ---
 
-## エージェントをブランチに固定する
+## エージェントを特定のブランチに留める
 
-エージェントが他のブランチに切り替えたり、保護されたブランチにプッシュしたりするのを防ぎます。
+エージェントが他のブランチに切り替えたり、保護されたブランチにプッシュしたりできないようにします。
 
 ```javascript
 import { customPolicies, allow, deny } from "failproofai";
@@ -182,9 +182,9 @@ customPolicies.add({
 
 ---
 
-## コミット前にテストを要求する
+## コミット前にテストを必須にする
 
-コミット前にテストを実行するようエージェントに促します。
+コミットの前にテストを実行するようエージェントに促します。
 
 ```javascript
 import { customPolicies, allow, instruct } from "failproofai";
@@ -238,16 +238,70 @@ git add .failproofai/policies-config.json
 git commit -m "Add failproofai team policies"
 ```
 
-failproofai をインストール済みのすべてのチームメンバーに、これらのルールが自動的に適用されます。
+failproofai をインストールしているすべてのチームメンバーが、これらのルールを自動的に取得します。
 
 ---
 
-## その他の使用例
+## コンベンションポリシーでチーム全体の品質基準を構築する
+
+最も効果的なセットアップ: プロジェクトに合わせたポリシーを `.failproofai/policies/` にコミットします。チーム全員がインストールコマンドや設定変更なしに自動で適用されます。
+
+<Steps>
+  <Step title="ディレクトリを作成してポリシーを追加する">
+    ```bash
+    mkdir -p .failproofai/policies
+    ```
+
+    ```js
+    // .failproofai/policies/team-policies.mjs
+    import { customPolicies, allow, deny, instruct } from "failproofai";
+
+    // チームが使用するパッケージマネージャーを強制する
+    // (組み込みの prefer-package-manager ポリシーを有効にしても構いません)
+    customPolicies.add({
+      name: "enforce-bun",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        if (ctx.toolName !== "Bash") return allow();
+        const cmd = String(ctx.toolInput?.command ?? "");
+        if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
+        return allow();
+      },
+    });
+
+    // コミット前にテストを実行するようエージェントに促す
+    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"
+    ```
+  </Step>
+  <Step title="継続的に改善する">
+    チームが新たな問題に直面するたびにポリシーを追加してプッシュしてください。全員が次の `git pull` 時にアップデートを受け取ります。これらのポリシーはチームとともに成長する、生きた品質基準になります。
+  </Step>
+</Steps>
+
+---
+
+## その他のサンプル
 
 リポジトリの [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) ディレクトリには以下が含まれています:
 
 | ファイル | 内容 |
 |------|---------------|
-| `policies-basic.js` | 基本ポリシー — 本番環境への書き込み、force-push、パイプスクリプトのブロック |
+| `policies-basic.js` | スターターポリシー — 本番環境への書き込み、force-push、パイプスクリプトのブロック |
 | `policies-notification.js` | アイドル通知とセッション終了時の Slack アラート |
-| `policies-advanced/index.js` | トランジティブインポート、非同期フック、PostToolUse の出力スクラブ、Stop イベントの処理 |
+| `policies-advanced/index.js` | トランジティブインポート、非同期フック、PostToolUse 出力のスクラブ、Stop イベント処理 |