Better WorkflowsV6
العربية
V6 Corepre-alpha

لا دليل إلا الحديث.
المجهول يعني التوقف.

إضافة لـ Claude Code تمنع وكيل الذكاء الاصطناعي من إنهاء العمل اعتمادًا على اختبار أخضر قديم، ومن تكرار أو مراكمة آثار جانبية لم يرَ نتيجتها قط. ما يُسمح له بفعله يحدده ملف policy تكتبه أنت، وليس الـ prompt أبدًا.

  • دليل حديث
  • مرة واحدة على الأكثر
  • الـ policy لا الـ prompt
  • المنع عند الشك
التثبيت في Claude Code شاهده يتوقف GitHub

stale-green · أخضر قديم، ثم push أُعيدت محاولته

demo
  1. claude أصلح الخطأ في sum.mjs، ولا داعي لإعادة تشغيل الاختبارات
  2. testينجح node --test على الملفات a1f3
  3. editيعدّل الوكيل sum.mjs، فتصبح الملفات 9c07
  4. stop«تم. الاختبارات ناجحة.»
  5. bwأُعيد: نجح test آخر مرة على a1f3، وقد تغيّرت الملفات منذ ذلك الحين.
  6. testيعيد الوكيل تشغيل node --test: إخفاق واحد، يصلحه، فينجح على b2e8
  7. pushتنتهي مهلة git push بعد أن يكون الـ push قد وصل فعلًا
  8. pushيعيد الوكيل محاولة git push
  9. bwمرفوض: نجح git-push بالفعل عند هذا الـ commit.

SENT BACKأوقف Core الوكيل مرتين: مرة عن الإنهاء اعتمادًا على نجاح قديم، ومرة عن تنفيذ push مرة أخرى. وفي المرتين أُعيد مع ذكر السبب.

ما الذي فحصه Core

توقفان · 0 إعلان «تم» كاذب
  1. Policyمن .better-workflows/policy.jsonPASS
  2. الدليلاختبار على الملفات كما هي الآنBLOCKED
  3. إعادة التشغيلينجح الاختبار على b2e8PASS
  4. الإجراءgit-push، للمرة الأولىPASS
  5. مرة واحدة على الأكثرالـ push نفسه، الـ commit نفسهBLOCKED

مختصر من عرض stale-green في المستودع، ومعرّفات الـ tree للتوضيح فقط. شغّل العرض الكامل بنفسك في ثوانٍ قليلة، دون Claude.

01المبادئPRINCIPLES

ثلاث قواعد تزداد فائدتها كلما ازدادت النماذج قوة.

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

WITHOUT vs WITHالجلسة نفسها

الموقفالوكيل وحدهمع Core
نجحت الاختبارات، ثم تغيّر ملف«الاختبارات ناجحة.»يُعاد ليشغّلها من جديد على الملفات الحالية.
npm test | tailيُحتسب أخضر، ورمز الخروج يعود إلى tail.لا يُحتسب أبدًا، ويوضح Stop السبب.
ملف spec واحد بدل المجموعة كاملةيُحتسب على أنه «الاختبارات ناجحة».مع exact، لا يُحتسب إلا الأمر الكامل.
انتهت مهلة الـ push بعد وصولهيعيد الـ push.يُرفض الـ push نفسه عند الـ commit نفسه.
الـ prompt يقول «يمكنك النشر»ينشر.الـ policy هي التي تقرر: allow أو ask أو deny.

AUTHORITYمن أين تأتي الصلاحية

  1. L1
    policy.json

    يكتبه شخص ويعدّله. يرفض Core تعديلات الوكيل المباشرة عليه.

    المصدر
  2. L2
    صلاحيات Claude Code

    تبقى سارية. allow في الـ policy لا يمنح أبدًا أكثر مما يمنحه Claude Code.

  3. L3
    hooks الخاصة بـ Core

    تفرض الـ policy على كل أمر وكل تعديل وكل محاولة إنهاء.

  4. L4
    الـ prompt

    يصف الهدف. ولا يحمل أي صلاحية.

    لا شيء

02كيف يعملHOW IT WORKS

ستة hooks وسجل واحد في .git.

يعمل Core داخل hooks الخاصة بـ Claude Code نفسه. لا شيء لتشغيله، ولا خادم، ولا حساب؛ وتُحفظ الحالة في .git/better-workflows/ داخل كل مستودع.

HOOKSالـ hooks

  1. SessionStart: يخبر الوكيل بالفحوص التي يجب أن تنجح وبالآثار الجانبية التي لم تُحسم بعد، وينبّه إذا كانت الـ policy غير صالحة أو كان gh مطلوبًا لكنه غير قابل للاستخدام.
  2. PreToolUse: يسمح بكل أثر جانبي أو يسأل عنه أو يرفضه، ويرفض أي تعديل على الـ policy والسجل.
  3. PostToolUse: يسجّل كل فحص مع شجرة Git التي شُغّل عليها، وكل أثر جانبي مع رمز خروجه.
  4. Stop: إذا تغيّرت ملفات وكان فحص مطلوب مفقودًا أو فاشلًا أو قديمًا، يعيد الوكيل مرة واحدة مع ذكر السبب؛ وفي المرة التالية يكتفي بالتنبيه.
  5. bw status (أمر، وليس hook): يعرض لك الحالة نفسها.
STOP

الإنهاء

دليل مربوط بالملفات

لا يُحتسب الاختبار أو الـ lint أو الـ typecheck أو الـ build إلا إذا نجح، وكان رمز خروجه هو الذي حسم نتيجة السطر، ولم يتغيّر أي ملف أثناء تشغيله، وبقيت الملفات هي نفسها تمامًا التي شُغّل عليها.

اختياري

  • exact: لا يُحتسب إلا الأمر الكامل، ويحدد cwd أين يجب أن يعمل.
  • scope (مع exact): التغيير خارج المجلدات المحددة يُبقي النتيجة حديثة.
  • ignore (للـ policy كلها): ما يكتبه الفحص من مخرجات، مثل تقارير التغطية، لا يُحتسب تغييرًا.
PRETOOLUSE

الآثار الجانبية

مرة واحدة على الأكثر، والمجهول يوقف

عمليات الـ push، وإنشاء الـ PR ودمجها، والإصدارات، ونشر الحزم، وأنواعك المخصصة، يحتاج كل منها إلى allow من الـ policy. رمز الخروج 0 وحده نتيجة معروفة.

فحوص للقراءة فقط تُستخدم لحسم نتيجة مجهولة

  • git ls-remote
  • gh pr list / view
  • gh release view
  • npm view

RULESقواعد ثابتة

  • R1

    الـ policy غير الصالحة ترفض كل أثر جانبي بدل الرجوع إلى القيم الافتراضية.

  • R2

    الصلاحية المنتهية ترجع إلى ask. ولا يمددها إلا شخص، بتعديل الـ policy.

  • R3

    الأوامر التي لا يستطيع Core قراءتها، مثل eval أو sh -c، تُعامل على أنها مبهمة ويُسأل عنها.

  • R4

    السجل لا يقبل إلا الإضافة ومتسلسل بالـ hash؛ ويكشف bw verify الإدخالات المعدّلة أو المحذوفة وسطرًا أخيرًا كُتب نصفه، لكنه لا يكشف إدخالات كاملة مقتطعة من النهاية.

03المضيفاتHOSTS

Claude Code أولًا.

Core محايد تجاه المضيف، وكل مضيف يحتاج إلى محوّل صغير. Claude Code هو الأول والوحيد المدعوم حاليًا.

دعم المضيفات وأنظمة التشغيل
المضيفmacOSLinuxWindows
Claude Codeالمضيف الأولمدعوم ومختبر في CIمدعوم ومختبر في CIغير مختبر
CodexV5 فقط، مجمّدمخطط لهمخطط لهمخطط له
Gemini CLIV5 فقط، مجمّدمخطط لهمخطط لهمخطط له
Qwen CodeV5 فقط، مجمّدمخطط لهمخطط لهمخطط له

يشغّل CI أداة Core على كل pull request.macOS 15 وUbuntu 24.04، وNode 22.23.3 و24.21.0.

04البدءGET STARTED

ثلاثة أوامر، ثم اطلب تعديلًا.

يتطلب Node.js 22.14 أو أحدث، وGit، وClaude Code مع دعم الإضافات.

  1. 1

    استنسخ Core

    مرة واحدة لكل جهاز. إن كنت قد شغّلت V5 هنا، فانقل أولًا ~/.better-workflows إلى ~/.better-workflows-V5 واجعل SBW_STATE_ROOT يشير إليه.

  2. 2

    أضف الإضافة

    ثبّتها لكل مستودع على حدة باستخدام --scope local، حتى لا يُكتب شيء في ملفات تضيفها إلى commit.

  3. 3

    اكتب policy

    يكتب bw init الملف .better-workflows/policy.json. أضفه إلى commit ليحصل الجميع على القواعد نفسها.

  4. يغطي الشرح الكامل فحوصك الخاصة والآثار الجانبية والنتائج المجهولة. دليل البدء

Claude Code

git clone https://github.com/stephen-taipei/better-workflows ~/.better-workflows
claude plugin marketplace add ~/.better-workflows/packages/bw-core
claude plugin install better-workflows-core@better-workflows --scope local
node ~/.better-workflows/packages/bw-core/bin/bw.mjs init

اختياري: شغّل السيناريوهين دون Claude، في ثوانٍ قليلة.

node ~/.better-workflows/packages/bw-core/examples/stale-green/demo.mjs

ثم جرّبه

غيّر سطرًا واحدًا في هذا المستودع، ولا تشغّل الاختبارات.

عندما يحاول Claude Code الإنهاء، يُعاد ويُخبَر بالفحص المفقود.

05الحدودLIMITS

ما الذي يوقفه، وما الذي لا يراه.

البوابة لا تكون مفيدة إلا إذا عرفت حدودها.

يوقف

أخطاء يمكن ملاحظتها

  • الإنهاء اعتمادًا على تشغيل اختبارات قديم أو فاشل، أو على تشغيل جزئي عندما يكون الفحص موسومًا بـ exact
  • أنبوب (pipe) أو || true يخفي إخفاقًا
  • تكرار push أو merge أو إصدار أو نشر
  • الآثار الجانبية بينما نتيجة أثر سابق ما زالت مجهولة
  • تعديل الوكيل للـ policy أو السجل مباشرةً

لا يفعل

خارج نطاق رؤيته

  • رؤية الآثار الجانبية داخل سكربت، ما لم تذكر الـ policy ذلك السكربت
  • الحكم على ما إذا كانت اختباراتك جيدة بما يكفي
  • بناء مخطط للتبعيات: يجب أن يذكر scope كل ما يعتمد عليه الفحص
  • احتساب الملفات التي يتجاهلها Git جزءًا من الدليل

يتركه لك

قرارات يتخذها شخص

  • حسم أثر جانبي لا يمكن قراءة نتيجته مجددًا
  • تمديد صلاحية إلى ما بعد expiresAt الخاص بها
  • اختيار ما يغطيه scope
  • تقرير متى تدور الجلسة في حلقة مفرغة
يمنع Core الأخطاء المذكورة أعلاه. لم يُقَس بعد ما إذا كان يقلل إعادة العمل أو القرارات الخاطئة في المهام الطويلة؛ وهذا هو الغرض من فترة الاستخدام الذاتي الحالية.
  1. B1محلل الـ shell لا يتوسع: الأمر الذي لا يستطيع قراءته يُسأل عنه قبل تشغيله، والاختبار المخفي داخل eval أو sh -c لا يُحتسب دليلًا أبدًا.
  2. B2يكتفي Core بإحصاء مجريات الجلسة. أما الحكم على ما إذا كانت تتقارب نحو حل فهو للوكيل أو لك.
  3. B3تُطابَق الـ pull requests والإصدارات باستخدام gh؛ ومن دونه تبقى مجهولة إلى أن تحسمها أنت.

06الحالةSTATUS

أين وصل المشروع.

يستبدل V6 محرك سير العمل في V5 بنواة صغيرة. تُعلن المواعيد عند تحققها.

  1. DONE مجمّد

    V5.0 RC1

    tag V5.0.rc1

    محرك سير عمل متعدد المضيفات. مجمّد على الفرع frozen/v5؛ ولا عمل جديد عليه.

  2. NOW قيد التنفيذ

    V6 Core pre-alpha

    packages/bw-core

    hooks لـ Claude Code، وscope للأدلة، واستخدام ذاتي على مستودعين.

  3. NEXT بعد الاستخدام الذاتي

    V6 Core alpha

    أول إصدار موسوم

    يُنشر حين تُظهر فترة الاستخدام الذاتي أخطاءً حقيقية تم اعتراضها وقليلًا من حالات المنع الخاطئة. وستلحق مضيفات أخرى كمحوّلات صغيرة.

STATEMENTبيان

PRE-ALPHA

Core قابل للاستخدام اليوم ويعمل على مستودعات المشرف نفسه. وقد يتغير تنسيق الـ policy قبل مرحلة alpha.

كل شيء هنا مجاني ومفتوح المصدر. لا توجد فئة مدفوعة ولا حساب ولا قياس عن بُعد.

LICENSINGالترخيص

الترخيص
الجزءالرخصةالحالة
V6 Core (packages/bw-core)Apache-2.0نشط
الموقع وبقية المستودعAGPL-3.0-onlyنشط
إضافة V5AGPL-3.0-onlyعلى frozen/v5مجمّد

07التوثيقDOCS

كل شيء موجود في المستودع.

الأدلة مكتوبة بالإنجليزية والصينية التقليدية. ولكل لغة على هذا الموقع ملف README قصير على GitHub.

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

أسئلة شائعة وإجابات مباشرة.

سؤال آخر؟ افتح issue على GitHub. GitHub Issues

هل يبطئ Claude Code؟

الـ hooks التي تتعامل مع فحص أو أثر جانبي تحسب الـ hash لشجرة العمل باستخدام Git، وهذا يستغرق أجزاءً من الثانية في مستودع عادي. المستودعات الضخمة جدًا تدفع كلفة أكبر في كل استدعاء من هذا النوع.

هل يمكن أن يعلق ويظل يعيد الوكيل إلى ما لا نهاية؟

يعيد الوكيل مع ذكر السبب ومع ملخص لمسار الجلسة حتى الآن: مرات التشغيل، والإخفاقات المتتالية، وعدد مرات الإعادة السابقة. ويمكن للوكيل حينها أن يتوقف ويخبرك بوضوح أي فحص يواصل الإخفاق.

هل يستطيع الوكيل إيقافه؟

ليس مباشرةً. يرفض Core تعديلات الوكيل على الـ policy والسجل، ويرفض bw init وحسم إجراء يدويًا. أما إلغاء تثبيت الإضافة، أو تغيير تلك الملفات بطرق ملتوية، فتحكمه قواعد الأذونات الخاصة بـ Claude Code نفسه، لذا أبقِ طلبات التأكيد تلك مفعّلة.

هل يرسل أي شيء إلى أي مكان؟

لا يوجد خادم ولا قياس عن بُعد. اتصالاته الشبكية الوحيدة هي استعلامات للقراءة فقط باستخدام git وgh وnpm الخاصة بك، للتأكد مما إذا كان أثر جانبي قد حدث. يبقى السجل في .git/better-workflows/.

وماذا عن Codex أو Gemini CLI أو Qwen Code؟

كانت تعمل مع V5، وهو مجمّد. Core محايد تجاه المضيف، ومحوّلاتها مخطط لها بعد مرحلة alpha.

جرّبه في ثوانٍ قليلة

تشغيل أمر ليس دليلًا. الملفات هي الدليل.

شغّل العرض دون Claude، ثم ثبّته على مستودع واحد واطلب تعديلًا.

التثبيت في Claude Codeاعرضه على GitHub