سير العمل الفاعل عملياً: Claude Code + MCP + خط أنابيب التحقق

سير عمل فاعل هو حلقة plan-act-observe موصولة بأداة حقيقية وفحص حقيقي وشرط توقف حقيقي وليس رسماً توضيحياً. يوصل هذا المختبر واحد مع Claude Code: خادم MCP يضيف أداة وخطاف PreToolUse يرفض الاستدعاءات الخطرة التي توفرها تلك الأداة وزوج PostToolUse/Stop الذي يشغل lint والاختبارات بعد كل تحرير وثلاث أماكن يجب على إنسان أن يتصرف. كل أمر أدناه يأتي من توثيق Claude Code الرسمي أو خوادم مرجع MCP أو مستودع MCP الخاص بـ GitHub.

الخطوة 1 — أعطِ الوكيل أداة مع MCP

Claude Code لا يستدعي الأدوات مباشرة؛ يقرأ قائمة أدوات عميل جمعها و MCP هو كيفية نمو تلك القائمة. مسجل MCP الرسمي يحافظ على خادمي مرجع يغطيان معظم حاجات مختبر DevOps: خادم نظام ملفات وخادم GitHub كليهما شحن بمجموعة التوجيه أو GitHub نفسه وليس حزمة عشوائية من طرف ثالث.

خادم النظام الملفات. منشور كـ @modelcontextprotocol/server-filesystem يقرأ ويكتب ويُنقل ويبحث الملفات تحت الأدلة المسماة على سطر أوامره. تُوثق تلك الحجة كالطريقة الوحيدة التي تعمل مع كل إصدار بروتوكول يدعمه الخادم؛ قائمة الأدلة المزودة من عميل (Roots) ملاءمة الإهمال للعملاء الأقدم وليس شيء تعتمد عليه. أضفه كخادم project-scoped بحيث الإدخال يعيش في .mcp.json الفريق يمكنه مراجعتها:

claude mcp add --scope project --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem "$CLAUDE_PROJECT_DIR"

يكتب:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${CLAUDE_PROJECT_DIR}"]
    }
  }
}

خادم GitHub. يحافظ GitHub على github/github-mcp-server موزع كصورة Docker في ghcr.io/github/github-mcp-server وينصح بإبقاء الرمز الشخصي خارج ملف التكوين بتمريره عبر البيئة:

export GITHUB_PAT=your_token_here
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

بديل مستضاف موجود في https://api.githubcopilot.com/mcp/ إذا فضّلت عدم تشغيل حاوية محلياً؛ في كلا الحالتين نطّق الرمز بضيق لأن الخادم يمكن أن يصل إلى معظم GitHub API يسمح به ذلك الرمز.

افتح جلسة وتأكد من تحميل الخادم بـ /mcp. المضيفون والعملاء والنقل مغطاة في MCP servers explained؛ يذهب هذا المختبر مباشرة إلى الضوابط حول الأداة.

الخطوة 2 — حجب الاستدعاءات الخطرة مع خطاف PreToolUse

أداة MCP تظهر في أحداث الخطاف تحت اسم نمط ثابت: mcp__<server>__<tool>. أدوات كتابة خادم النظام الملفات هي write_file و edit_file لذا الأسماء الكاملة هي mcp__filesystem__write_file و mcp__filesystem__edit_file. بحث مبني من أحرف وأرقام وشرطات سفلية و | فقط يُقارن كقائمة دقيقة من السلاسل لذا هذا البحث يضرب فقط تلك الأداتين وليس شيء بادئة مشابهة:

.claude/hooks/guard-fs-write.sh:

#!/bin/bash
# Deny filesystem MCP writes outside the project's scratch/ directory.
input=$(cat)
path=$(printf '%s' "$input" | jq -r '.tool_input.path // empty')
scratch="${CLAUDE_PROJECT_DIR:-.}/scratch"

case "$path" in
  "$scratch"/*) exit 0 ;;
  "") exit 0 ;;
  *)
    echo "Blocked: $path is outside scratch/. Widen the hook on purpose if this edit is intended." >&2
    exit 2
    ;;
esac

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__filesystem__write_file|mcp__filesystem__edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-fs-write.sh"
          }
        ]
      }
    ]
  }
}

الخروج 2 يلغي الاستدعاء ويعطي الوكيل سطر stderr كالسبب لذا حلقة تستمر في الوصول خارج scratch/ تُعاد بدلاً من أن تُرفض بصمت. نفس الصيغة تغطي خادم GitHub: mcp__github__.* هو تعبير عادي (يحتوي على نقطة) يطابق كل أداة ينفذها ذلك الخادم؛ ضيّقه أكثر على بوابة فقط الأدوات التي تكتب.

هذي نفس الآلية الأدوات المدمجة Edit و Write تستخدم مغطاة في hooks guide؛ أداة MCP فقط اسم أطول على نفس حقل tool_name.

الخطوة 3 — شغّل خط أنابيب التحقق تلقائياً

خطاف PostToolUse يشغل بعد استدعاء أداة بالفعل نجح وهي النقطة الصحيحة لمنسق أو اختبار ضيق لا للوقاية من الكتابة. سلسلها بعد الأدوات التحرير المدمجة وأداة نظام الملفات MCP بحيث لا مسار يتخطى الفحص:

.claude/hooks/validate-change.sh:

#!/bin/bash
# Lint, then test, the file Claude just touched. Block the result on failure.
input=$(cat)
path=$(printf '%s' "$input" | jq -r '.tool_input.path // .tool_input.file_path // empty')
[ -f "$path" ] || exit 0

case "$path" in
  *.py)
    ruff check "$path" >&2 || exit 2
    pytest "$path" >&2 || exit 2
    ;;
  *.ts|*.js)
    npx eslint "$path" >&2 || exit 2
    npm test -- "$path" >&2 || exit 2
    ;;
esac
exit 0

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|mcp__filesystem__write_file|mcp__filesystem__edit_file",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate-change.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

خطاف Stop يغلق الفجوة فحص لكل ملف يترك: لا شيء أعلاه يُعيد تشغيل المجموعة الكاملة. Stop يطلق على كل دور يتجاهل المطابقات تماماً ويمكن حجب نهاية الدور حتى يخرج 0:

.claude/hooks/require-green-suite.sh:

#!/bin/bash
# Block the end of the turn until the full test suite is green.
if ! npm test >&2; then
  echo "Full suite is red. Fix the failure before the turn ends." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-green-suite.sh",
            "timeout": 180
          }
        ]
      }
    ]
  }
}

Claude Code يتوقف عن احترام خطاف Stop محجوب بعد ثمانية عرقلة متتالية بدون استدعاء أداة بينها لذا هذا مسند ضد اختبار متقلب وليس إعادة محاولة لا نهاية لها. وكيل فرعي هو الشكل الآخر الموثق لهذه الوظيفة: وكيل code-reviewer بأدوات القراءة فقط يُستدعى بعد دفعة من التحريرات يُبلّغ الأمور محجوبة وغير محجوبة بدون لمس الملفات بنفسه. subagents guide لديه صيغة الملف؛ استخدم خطاف Stop لفحص pass/fail حتمي وكيل فرعي لحكم استدعاء نص لا يستطيع القيام به.

الخطوة 4 — ضع إنسان في ثلاثة أماكن محددة

الخطافات تبقي الحلقة داخل حارة. لا تستبدل شخص يقرر الحارة صحيحة. ثلاث نقاط تفتيش مدمجة في Claude Code ولا تحتاج سيناريو مخصص:

1. موجهات الإذن. في وضع default يطلب Claude Code قبل الاستخدام الأول لكل أداة في جلسة بما في ذلك أداة MCP المشروع للتو أضاف. هذا الموجه الواحد هو لا يزال اللحظة لاحظ خادم الذي لا ينبغي أن يُوافق عليه.
2. وضع الخطة. claude --permission-mode plan /plan أو Shift+Tab يضع الجلسة إلى ممر بحث القراءة فقط: يقرأ Claude الملفات ويستكشف لكن لا يحرر وتحريرات تبقى محجوبة حتى تُوافق على الخطة حتى لو خطاف PreToolUse سيسمح بواحد آخر. وصل لهذا قبل الموجه الأول على مستودع غير مألوف.
3. مراجعة طلب السحب. أشر خادم GitHub MCP على فتح فرع وطلب سحب draft بدلاً من الدفع إلى فرع default وتطلب الموافقة البشرية المعتادة قبل دمج. خط أنابيب التحقق هو البوابة قبل وجود PR؛ المراجعة هي البوابة قبل الهبوط.

لا شيء من هذا في حاوية بنفسه. احتفظ bypassPermissions لحاوية معزولة أو VM كما التوثيق permission-mode نفسه يحدده وليس جلسة تعمل ضد شجرة عملك.

نهاية الحلقة end to end

            ┌────────────────────────────────────────────────┐
            │                                                  │
            ▼                                                  │
      ┌───────────┐     ┌───────────┐     ┌────────────┐     ┌─────────────┐
      │   PLAN    │ --> │    ACT    │ --> │  VALIDATE  │ --> │ HUMAN GATE  │
      │ plan mode │     │ MCP tool  │     │ PostToolUse│     │ permission  │
      │ read-only │     │ call,     │     │ lint+test, │     │ prompt, PR  │
      │ research  │     │ guarded   │     │ Stop hook  │     │ review      │
      │           │     │ by        │     │ re-runs    │     │             │
      │           │     │ PreToolUse│     │ full suite │     │             │
      └───────────┘     └───────────┘     └─────┬──────┘     └──────┬──────┘
                                                  │ exit 2                 │ reject plan
                                                  └── keep acting ◄────────┘

وضع الخطة هو الإدخال؛ PreToolUse يجلس على كل استدعاء MCP داخل act؛ PostToolUse و Stop التحقق؛ موجه الإذن ومصادقة الخطة ومراجعة PR هي بوابات بشرية الثلاث. فشل خطاف Stop يرسل الحلقة مرة أخرى إلى act وليس حول البوابة البشرية.

عقدة n8n AI Agent تبني نفس الحلقة خارج وكيل ترميز مع عقد سير عمل تقف بدلاً من الخطافات؛ انظر first n8n workflow لهدف HTTP-shaped بدلاً من مستودع. فريق تشكيل التحقق كمواصفات مكتوبة بدلاً من الاختبارات المخصصة يمكن أن يحمل نفس البوابة إلى spec-driven development.

المزالق

حلقات جامحة. حد Stop hook الثماني عرقلة هو مسند وليس تصميم. التحكم الحقيقي يحد ما act يمكن أن يصل أولاً: مجموعة أدوات MCP ضيقة دليل scratch/ و bypassPermissions محفوظ لحاوية يمكنك رميها.

إذن أدوات واسع جداً. قائمة الدليل المسموح بها في خادم النظام الملفات تغطي فقط المسارات الممررة على سطر أوامره؛ لا تعتمد على دعم Roots من عميل بدلاً من ذلك لأن هي الطريقة الوحيدة المضمونة على كل إصدار بروتوكول. لـ GitHub نطّق الرمز إلى المستودعات والإجراءات المختبر يحتاجها وليس رمز بوصول حساب كامل.

الأسرار في بيئة MCP. مرّر GITHUB_PERSONAL_ACCESS_TOKEN عبر env الخادم نفسه كما أعلاه أبداً inline في .mcp.json مرسال. نطاق المشروع مشارك عبر git على القصد؛ رمز مخبوز في ملف ذاك يشحن إلى الجميع الذي ينسخ المستودع.

التكلفة. كل استدعاء أداة MCP استدعاء خطاف استدعاء وكيل فرعي هو وحدة عمل ضد الجلسة. خطاف Stop يُعيد تشغيل مجموعة بطيئة في كل دور أو حلقة تستمر في إعادة محاولة تحرير محجوب تجميع سريع؛ احتفظ بفحص المجموعة الكاملة في Stop وليس PostToolUse واحتفظ بفحص الملف الفردي ضيق.

تعامل مع خط الأنابيب الكامل كشيء لتكتبه مرة واحدة تعمل الطريقة ذاتها التي AI governance checklist يتوقع فريق لتسجيل الأدوات أي وكيل يمكنه الوصول إليها ومن يوافق على ما يغيره.

الأسئلة الشائعة

ما هو سير العمل الفاعل؟

حلقة حيث يخطط نموذج خطوة ويستدعي أداة ويقرأ النتيجة ويقرر الخطوة التالية بدلاً من إرجاع إجابة واحدة. يستمر حتى لا توجد استدعاء أداة أو فحص يفشل أو إنسان يوقفه. الأجزاء التي تجعله آمناً للتشغيل هي حد الأداة وخطوة التحقق ونقطة واحدة على الأقل حيث يجب على شخص أن يقول نعم.

كيف أعطي Claude Code أداة جديدة دون كتابة خادم؟

أضف خادم MCP مرجع رسمي. خادم النظام الملفات (@modelcontextprotocol/server-filesystem) وخادم GitHub (github/github-mcp-server) يُصانهما مجموعة التوجيه البروتوكول و GitHub. سجل كليهما مع claude mcp add أو اكتب الإدخال في .mcp.json بنفسك.

أي حدث خطاف يحجب إجراء خطير قبل التشغيل؟

PreToolUse. أعطه بحثاً عن الأداة الدقيقة بما في ذلك اسم mcp__server__tool الكامل لأداة MCP والخروج 2 من سيناريو الخطاف بسبب على stderr. قرار صالح من deny يفعل نفس الشيء بدون الاعتماد على رمز الخروج.

هل خطاف Stop يحتل مكان إنسان يراجع الفرق؟

لا. يمكن لخطاف Stop حجب نهاية دور حتى أمر يخرج صفر وهو مفيد لمجموعة اختبار لكن Claude Code يستسلم بعد ثمانية عرقلة متتالية بدون استدعاء أداة بينها. موجهات الإذن وضع خطة ومراجعة طلب السحب هي نقاط التحقق البشرية الفعلية؛ الخطاف فقط يبقي الحلقة تعمل طويلاً بما يكفي للوصول إلى واحد.

كيف أمنع الوكيل من الحلقة إلى الأبد؟

نطاق إذن الخادم MCP أولاً مثلاً حجة الدليل المسموح به لخادم النظام الملفات بحيث حلقة سيئة يمكن فقط أن تلمس شجرة صغيرة. احتفظ bypassPermissions لحاوية معزولة وليس جهازك المحمول. حد Stop hook الثماني عرقلة هو مسند وليس التحكم الرئيسي.