Examples

title: أمثلة description: “كيفية إعداد hooks لـ Claude Code و Agents SDK” icon: book-open

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

إعداد hooks لـ Claude Code

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

تثبيت failproofai

npm install -g failproofai

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

failproofai policies --install

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

cat ~/.claude/settings.json | grep failproofai

يجب أن تشاهد مدخلات hook لأحداث PreToolUse، PostToolUse، Notification، و Stop.

تشغيل Claude Code

claude

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

إعداد hooks لـ Agents SDK

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

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

npm install failproofai

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

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

failproofai --hook PreToolUse   # يُستدعى قبل كل أداة
failproofai --hook PostToolUse  # يُستدعى بعد كل أداة

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

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();
  },
});

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

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 عند احتياج الوكلاء إلى الاهتمام

استخدم notification hook لإعادة توجيه تنبيهات عدم النشاط إلى Slack.

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 ?? "غير معروف";

    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();
  },
});

ثبّته:

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: "منع الوكيل من التحقق من فروع أخرى",
  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();
  },
});

اطلب الاختبارات قبل الالتزام

ذكّر الوكلاء بتشغيل الاختبارات قبل الالتزام.

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();
  },
});

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

التزم بتكوين على مستوى المشروع بحيث يحصل كل مطور في فريقك على نفس السياسات. أنشئ .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/ في مستودعك مع سياسات مخصصة لمشروعك. يحصل كل عضو في الفريق عليها تلقائياً — بدون أوامر تثبيت ولا تغييرات تكوين.

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

mkdir -p .failproofai/policies

// .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();
  },
});

التزم بـ git

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

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

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

أمثلة إضافية

يحتوي دليل examples/ في المستودع على:

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

البداية

المفاهيم الأساسية

CLI

الأدوات

متقدم

أمثلة

title: أمثلة description: “كيفية إعداد hooks لـ Claude Code و Agents SDK” icon: book-open

إعداد hooks لـ Claude Code

إعداد hooks لـ Agents SDK

حجب الأوامر التدميرية

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

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

إبقاء الوكلاء على فرع معين

اطلب الاختبارات قبل الالتزام

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

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

أمثلة إضافية

​title: أمثلة description: “كيفية إعداد hooks لـ Claude Code و Agents SDK” icon: book-open

​إعداد hooks لـ Claude Code

​إعداد hooks لـ Agents SDK

​حجب الأوامر التدميرية

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

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

​إبقاء الوكلاء على فرع معين

​اطلب الاختبارات قبل الالتزام

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

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

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

title: أمثلة description: “كيفية إعداد hooks لـ Claude Code و Agents SDK” icon: book-open

إعداد hooks لـ Claude Code

إعداد hooks لـ Agents SDK

حجب الأوامر التدميرية

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

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

إبقاء الوكلاء على فرع معين

اطلب الاختبارات قبل الالتزام

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

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

أمثلة إضافية