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

# Примеры

> Как настроить хуки для Claude Code и Agents SDK

Готовые к использованию примеры для типичных сценариев. Каждый показывает, как установить и чего ожидать.

***

## Настройка хуков для Claude Code

Failproof AI интегрируется с Claude Code через его [систему хуков](https://docs.anthropic.com/en/docs/claude-code/hooks). Когда вы запускаете `failproofai policies --install`, он регистрирует команды хуков в `settings.json` Claude Code, которые срабатывают при каждом вызове инструмента.

<Steps>
  <Step title="Установите failproofai">
    ```bash theme={null}
    npm install -g failproofai
    ```
  </Step>

  <Step title="Включите все встроенные политики">
    ```bash theme={null}
    failproofai policies --install
    ```
  </Step>

  <Step title="Проверьте регистрацию хуков">
    ```bash theme={null}
    cat ~/.claude/settings.json | grep failproofai
    ```

    Вы должны увидеть записи хуков для событий `PreToolUse`, `PostToolUse`, `Notification` и `Stop`.
  </Step>

  <Step title="Запустите Claude Code">
    ```bash theme={null}
    claude
    ```

    Политики теперь работают автоматически при каждом вызове инструмента. Попробуйте попросить Claude запустить `sudo rm -rf /` — это будет заблокировано.
  </Step>
</Steps>

***

## Настройка хуков для Agents SDK

Если вы разрабатываете с помощью [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), вы можете использовать ту же систему хуков программным способом.

<Steps>
  <Step title="Установите failproofai в ваш проект">
    ```bash theme={null}
    npm install failproofai
    ```
  </Step>

  <Step title="Настройте хуки в вашем агенте">
    Передайте команды хуков при создании процесса агента. Хуки срабатывают так же, как в Claude Code — через stdin/stdout JSON:

    ```bash theme={null}
    failproofai --hook PreToolUse   # вызывается перед каждым инструментом
    failproofai --hook PostToolUse  # вызывается после каждого инструмента
    ```
  </Step>

  <Step title="Напишите пользовательскую политику для вашего агента">
    ```javascript theme={null}
    import { customPolicies, allow, deny } from "failproofai";

    customPolicies.add({
      name: "limit-to-project-dir",
      description: "Держите агента внутри директории проекта",
      match: { events: ["PreToolUse"] },
      fn: async (ctx) => {
        const path = String(ctx.toolInput?.file_path ?? "");
        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
          return deny("Агент ограничен директорией проекта");
        }
        return allow();
      },
    });
    ```
  </Step>

  <Step title="Установите пользовательскую политику">
    ```bash theme={null}
    failproofai policies --install --custom ./my-agent-policies.js
    ```
  </Step>
</Steps>

***

## Блокируйте деструктивные команды

Самая распространённая настройка — предотвратить агентам наносить необратимый ущерб.

```bash theme={null}
failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
```

Что это делает:

* `block-sudo` — блокирует все команды `sudo`
* `block-rm-rf` — блокирует рекурсивное удаление файлов
* `block-force-push` — блокирует `git push --force`
* `block-curl-pipe-sh` — блокирует передачу удалённых скриптов в оболочку

***

## Предотвратите утечку секретов

Остановите агентов от просмотра или утечки учётных данных в выводе инструмента.

```bash theme={null}
failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
```

Они срабатывают на `PostToolUse` — после выполнения инструмента они очищают вывод до того, как агент его увидит.

***

## Получайте оповещения в Slack, когда агентам нужно внимание

Используйте хук уведомления для отправки оповещений о простое в Slack.

```javascript theme={null}
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Оповестить Slack, когда агент ждёт ввода",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Агент ожидает");
    const project = ctx.session?.cwd ?? "unknown";

    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${message}*\nProject: \`${project}\``,
        }),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      // никогда не блокируйте агента, если Slack недоступен
    }

    return allow();
  },
});
```

Установите это:

```bash theme={null}
SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
```

***

## Держите агентов на ветке

Предотвратите переключение ветвей агентами или отправку в защищённые ветви.

```javascript theme={null}
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Предотвратить переключение агента на другие ветви",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
      return deny("Оставайтесь на текущей ветви. Создайте новую ветвь с флагом -b при необходимости.");
    }
    return allow();
  },
});
```

***

## Требуйте тесты перед коммитом

Напомните агентам запустить тесты перед коммитом.

```javascript theme={null}
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Напомнить агенту запустить тесты перед коммитом",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+commit/.test(cmd)) {
      return instruct("Запустите тесты перед коммитом. Сначала используйте `npm test` или `bun test`.");
    }
    return allow();
  },
});
```

***

## Заблокируйте production репозиторий

Зафиксируйте конфиг на уровне проекта, чтобы все разработчики в вашей команде получили одинаковые политики.

Создайте `.failproofai/policies-config.json` в вашем репозитории:

```json theme={null}
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-force-push",
    "block-push-master",
    "block-env-files",
    "sanitize-api-keys",
    "sanitize-jwt"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "production"]
    }
  }
}
```

Затем зафиксируйте это:

```bash theme={null}
git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"
```

Каждый член команды, у которого установлен failproofai, автоматически получит эти правила.

***

## Создайте стандарт качества на уровне организации с политиками соглашений

Наиболее эффективная настройка: зафиксируйте `.failproofai/policies/` в вашем репозитории с политиками, адаптированными к вашему проекту. Каждый член команды получит их автоматически — без команд установки, без изменения конфига.

<Steps>
  <Step title="Создайте директорию и добавьте политики">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```

    ```js theme={null}
    // .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("Используйте bun вместо 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("Запустите тесты перед коммитом.");
        }
        return allow();
      },
    });
    ```
  </Step>

  <Step title="Зафиксируйте в git">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```
  </Step>

  <Step title="Продолжайте совершенствоваться">
    Когда ваша команда столкнётся с новыми режимами сбоя, добавляйте политики и отправляйте. Все получат обновление при следующем `git pull`. Эти политики становятся живым стандартом качества, который растёт вместе с вашей командой.
  </Step>
</Steps>

***

## Ещё примеры

Директория [`examples/`](https://github.com/failproofai/failproofai/tree/main/examples) в репозитории содержит:

| Файл                         | Что он показывает                                                                             |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| `policies-basic.js`          | Стартовые политики — блокируйте запись в production, force-push, передачу скриптов в оболочку |
| `policies-notification.js`   | Оповещения Slack для уведомлений о простое и завершении сессии                                |
| `policies-advanced/index.js` | Транзитивные импорты, асинхронные хуки, очистка вывода PostToolUse, обработка события Stop    |