الانتقال إلى المحتوى الرئيسي
أمثلة جاهزة للاستخدام لسيناريوهات شائعة. يوضح كل منها كيفية التثبيت وما يمكن توقعه.

​
إعداد hooks لـ Claude Code

يتكامل Failproof AI مع Claude Code عبر نظام hooks الخاص به. عند تشغيل failproofai policies --install، يسجل أوامر hook في ملف settings.json الخاص بـ Claude Code التي تُشغّل عند كل استدعاء أداة.
1

تثبيت failproofai

npm install -g failproofai
2

تفعيل جميع السياسات المدمجة

failproofai policies --install
3

التحقق من تسجيل hooks

cat ~/.claude/settings.json | grep failproofai
يجب أن ترى إدخالات hook لأحداث PreToolUse و PostToolUse و Notification و Stop.
4

تشغيل Claude Code

claude
تعمل السياسات الآن تلقائياً عند كل استدعاء أداة. جرب طلب Claude بتشغيل sudo rm -rf / - سيتم حظره.

​
إعداد hooks لـ Agents SDK

إذا كنت تبني باستخدام Agents SDK، يمكنك استخدام نفس نظام hooks برمجياً.
1

تثبيت failproofai في مشروعك

npm install failproofai
2

تكوين hooks في وكيلك

مرر أوامر hook عند إنشاء عملية الوكيل. تُشغّل الـ hooks بنفس الطريقة كما في Claude Code - عبر JSON في stdin/stdout:
failproofai --hook PreToolUse   # يُستدعى قبل كل أداة
failproofai --hook PostToolUse  # يُستدعى بعد كل أداة
3

كتابة سياسة مخصصة لوكيلك

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "limit-to-project-dir",
  description: "Keep the agent inside the project directory",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    const path = String(ctx.toolInput?.file_path ?? "");
    if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
      return deny("Agent is restricted to the project directory");
    }
    return allow();
  },
});
4

تثبيت السياسة المخصصة

failproofai policies --install --custom ./my-agent-policies.js

​
حظر الأوامر المدمرة

الإعداد الأكثر شيوعاً - منع الوكلاء من إلحاق الضرر الذي لا يمكن إرجاعه. 
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 - يحظر توجيه النصوص البعيدة إلى shell

​
منع تسرب الأسرار

منع الوكلاء من رؤية أو تسرب بيانات اعتماد من مخرجات الأداة. 
failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
تُشغّل على PostToolUse - بعد تشغيل الأداة، تُنظّف المخرجات قبل أن يراها الوكيل.

​
الحصول على تنبيهات Slack عندما يحتاج الوكلاء إلى الاهتمام

استخدم hook الإشعار لإعادة توجيه تنبيهات عدم النشاط إلى Slack. 
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Alert Slack when the agent is waiting for input",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Agent is waiting");
    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 {
      // never block the agent if Slack is unreachable
    }

    return allow();
  },
});
ثبته: 
SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

​
الحفاظ على الوكلاء على فرع معين

منع الوكلاء من تبديل الفروع أو الدفع إلى الفروع المحمية. 
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Prevent the agent from checking out other branches",
  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("Stay on the current branch. Create a new branch with -b if needed.");
    }
    return allow();
  },
});

​
مطالبة الوكلاء بتشغيل الاختبارات قبل الالتزام

ذكّر الوكلاء بتشغيل الاختبارات قبل الالتزام. 
import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Remind the agent to run tests before committing",
  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("Run tests before committing. Use `npm test` or `bun test` first.");
    }
    return allow();
  },
});

​
قفل مستودع الإنتاج

ألزم إعداد على مستوى المشروع حتى يحصل كل مطور في فريقك على نفس السياسات. أنشئ .failproofai/policies-config.json في مستودعك: 
{
  "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"]
    }
  }
}
ثم ألزمه: 
git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"
كل عضو في الفريق لديه failproofai مثبت سيختار هذه القواعد تلقائياً.

​
بناء معيار جودة على مستوى المنظمة باستخدام سياسات الاتفاقية

الإعداد الأكثر تأثيراً: ألزم .failproofai/policies/ في مستودعك مع سياسات مصممة خصيصاً لمشروعك. يحصل كل عضو في الفريق عليها تلقائياً — بدون أوامر تثبيت، بدون تغييرات في الإعدادات.
1

أنشئ المجلد وأضف السياسات

mkdir -p .failproofai/policies

// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

// Enforce your team's preferred package manager
// (or enable the built-in prefer-package-manager policy instead)
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();
  },
});

// Remind the agent to run tests before committing
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();
  },
});
2

ألزم إلى git

git add .failproofai/policies/
git commit -m "Add team quality policies"
3

استمر في التحسين

عندما يواجه فريقك أنماط فشل جديدة، أضف سياسات واضغط. يحصل الجميع على التحديث عند git pull التالي. تصبح هذه السياسات معياراً للجودة يتطور مع فريقك.

​
أمثلة إضافية

يحتوي دليل examples/ في المستودع على:
الملفما يوضحه
policies-basic.jsسياسات البداية - حظر عمليات الكتابة في الإنتاج، الدفع القسري، النصوص المعاد توجيهها
policies-notification.jsتنبيهات Slack لإشعارات عدم النشاط ونهاية الجلسة
policies-advanced/index.jsالواردات الانتقالية، hooks غير المتزامنة، تنظيف مخرجات PostToolUse، معالجة حدث Stop