> ## 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.

# はじめに

> failproofai をインストールし、ポリシーを有効化して、エージェントを安定稼働させましょう

## 動作要件

* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0（任意 — ソースからビルドする場合のみ必要）

***

## インストール

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## クイックスタート

<Steps>
  <Step title="ポリシーを有効化する">
    ポリシーは、エージェントのツール呼び出しの前後に実行されるルールです。破壊的なコマンド、シークレットの漏洩、その他の障害モードを、実害が出る前に検出します。

    ```bash theme={null}
    failproofai policies --install
    ```

    このコマンドは、インストール済みのエージェント CLI にフックエントリを書き込みます（Claude Code の `~/.claude/settings.json`、OpenAI Codex の `~/.codex/hooks.json`、GitHub Copilot CLI の `~/.copilot/hooks/failproofai.json`、Cursor Agent の `~/.cursor/hooks.json`、OpenCode の `~/.config/opencode/plugins/failproofai.mjs` と `~/.config/opencode/opencode.json` の `plugin` 配列へのエントリ、Pi の `~/.pi/agent/settings.json`、または Hermes の `~/.hermes/config.yaml`）。複数が存在する場合はプロンプトで選択を求められます。`--cli claude codex copilot cursor opencode pi hermes`（任意のサブセット）を渡すとプロンプトをスキップできます。

    GitHub Copilot CLI、Cursor Agent、OpenCode、Pi のサポートは**ベータ版**です — それぞれ `--cli copilot`、`--cli cursor`、`--cli opencode`、`--cli pi` でインストールしてください。Hermes（hermes-agent、Slack/Telegram ゲートウェイ）は `--cli hermes` でユーザースコープにインストールでき、オフライン監査ソースとしても機能します。

    ```bash theme={null}
    failproofai policies --install --scope project
    failproofai policies --install --cli codex --scope project
    failproofai policies --install --cli copilot --scope project
    failproofai policies --install --cli cursor --scope project
    failproofai policies --install --cli opencode --scope project
    failproofai policies --install --cli pi --scope project
    failproofai policies --install --cli hermes --scope user
    failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
    ```
  </Step>

  <Step title="確認する">
    ```bash theme={null}
    failproofai policies
    ```

    すべてのポリシー、その有効・無効の状態、および設定済みパラメータが表示されます。
  </Step>

  <Step title="ダッシュボードを起動する">
    ```bash theme={null}
    failproofai
    ```

    `http://localhost:8020` にローカルダッシュボードが開きます。セッションの閲覧、ツール呼び出しの確認、ポリシーの管理が行えます。
  </Step>

  <Step title="エージェントを実行する">
    Claude Code を通常通り起動してください。エージェントがリスクのある操作を試みた場合、failproofai が自動的にインターセプトします。放置したまま実行し、あとでダッシュボードで何が起きたかを確認できます。
  </Step>
</Steps>

***

## ポリシーの仕組み

エージェントがツールを実行するたびに、Claude Code はサブプロセスとして failproofai を呼び出します。

```text theme={null}
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
```

各ポリシーは次の 3 つの判定のいずれかを返します。

* **allow** — エージェントは通常通り処理を続行する
* **deny** — アクションがブロックされ、エージェントにその理由が通知される
* **instruct** — エージェントのプロンプトに追加コンテキストが付加される

<Note>
  ポリシーはローカルプロセス内で実行されます。リモートサービスへのデータ送信は一切行われません。
</Note>

***

## 規約ベースのポリシーでチームポリシーを設定する

チーム全体に品質基準を確立する最も手軽な方法は、`.failproofai/policies/` の規約です。このディレクトリにポリシーファイルを置くだけで自動的に読み込まれます — フラグも、設定変更も、インストールコマンドも不要です。

<Steps>
  <Step title="ポリシーディレクトリを作成する">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="ポリシーファイルを追加する">
    サンプルをコピーするか、独自のポリシーを作成してください。

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

    または新しいファイルを作成します。

    ```js theme={null}
    // .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 theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

    failproofai をインストールしているすべてのチームメンバーが、これらのポリシーを自動的に取得します。開発者ごとの個別設定は不要です。
  </Step>
</Steps>

<Tip>
  `.failproofai/policies/` をリポジトリにコミットすることで、チーム全員が同じ基準を共有できます。新たな障害モードが見つかったらポリシーを追加してプッシュするだけで、次の `git pull` 時に全員へ反映されます。こうして蓄積されたポリシーは、継続的に改善される生きた品質基準となります。
</Tip>

***

## データの保存場所

すべての設定とログはお使いのマシン上に保存されます。

| パス                                        | 保存内容                     |
| ----------------------------------------- | ------------------------ |
| `~/.failproofai/policies-config.json`     | グローバルポリシー設定              |
| `~/.failproofai/hook-activity.jsonl`      | フック実行履歴                  |
| `~/.failproofai/hook.log`                 | カスタムフックエラーのデバッグログ        |
| `.failproofai/policies-config.json`       | プロジェクト別設定（コミット対象）        |
| `.failproofai/policies-config.local.json` | 個人用オーバーライド（gitignore 対象） |

***

## アンインストール

```bash theme={null}
failproofai policies --uninstall
```

`~/.claude/settings.json` からフックエントリを削除します。`~/.failproofai/` 内の設定ファイルはそのまま保持されます。

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="設定" icon="gear" href="/ja/configuration">
    スコープと設定ファイルのフォーマット
  </Card>

  <Card title="組み込みポリシー" icon="shield" href="/ja/built-in-policies">
    パラメータを含む全 26 ポリシー
  </Card>

  <Card title="カスタムポリシー" icon="code" href="/ja/custom-policies">
    JavaScript で独自のポリシーを作成する
  </Card>

  <Card title="エージェントモニター" icon="chart-line" href="/ja/dashboard">
    セッションの監視とポリシーアクティビティの確認
  </Card>
</CardGroup>