الهندسة بالوكلاء

SwarmForge بالتفصيل: كيف يعمل سرب وكلاء أنكل بوب فعلًا

ستة وكلاء ذكاء اصطناعي، وست أشجار عمل git، وطابور رسائل دائم، ومجموعة بوابات جودة هي أوامر shell لا نوايا حسنة. أما جزء tmux فهو أقل ما يثير الاهتمام في الأمر.

المشكلة التي بُني لأجلها

أعطِ وكيل برمجة واحدًا ميزة حقيقية، فسيكتب التنفيذ والاختبارات في نفس واحد، من الفهم نفسه، ومع النقاط العمياء نفسها. وإن كان قد أخطأ في قراءة المطلب، ترمّز الاختبارات ذلك الخطأ وتنجح. واطلب من الوكيل ذاته مراجعة عمله فسيوافق نفسه، لأن الاستدلال الذي أنتج الكود لا يزال في سياقه ولا يزال يبدو سليمًا. والحجم يزيد الأمر سوءًا لا تحسّنًا: المُخرَج معقول ووفير ورخيص، فيصبح الإنسان المراجع عنق الزجاجة ويبدأ بالتمرير السريع. يقامر SwarmForge على إجابة محددة لذلك: الجودة لا تأتي من المؤلف، فليأخذ كل تخصص مراجع وكيله الخاص، وسياقه الخاص، وشجرة عمله الخاصة، وفحصًا ينتهي بصفر أو لا ينتهي.

قرار التصميم الحامل ليس التوازي، بل أن الأدوار تتواصل فقط عبر كود مُودَع. فالوكيل المراجع لا يرى أبدًا شرح المؤلف عن سبب كون الكود جيدًا — يرى كوميتًا واسم مهمة، ويشغّل أدواته الخاصة عليهما.

ما هو، ميكانيكيًا

SwarmForge هيكل مكتوب بالـ shell وBabashka حول عناصر تملكها معظم الفرق أصلًا. كل دور نافذة tmux تشغّل واجهة سطر أوامر لوكيل على شجرة عمل git خاصة تحت .worktrees/، فلا يلمس وكيلان دليل العمل نفسه أبدًا. يأتي السلوك من نص عادي: constitution.prompt تدّعي الأسبقية على كل ما عداها وتطلب من الوكيل قراءة كل ملف في swarmforge/constitution/articles/ والالتزام به عند البدء وفي كل مهمة، إضافةً إلى مطالبة الدور في swarmforge/roles/<role>.prompt. المقالات المشتركة تغطي قواعد الهندسة والتسليم وسير العمل؛ والمقالات المحلية هي حيث يتجاوزها المشروع. والتواصل طابور قائم على الملفات يملكه خادم، ونوعا الرسائل الوحيدان المتاحان للوكيل هما تسليم git وملاحظة. أما سكربت ./swarm فهو مجرد إقلاع رقيق: يجلب أرشيف السكربتات إن كان الدليل غائبًا، ثم يمرّر الأمر إلى swarmforge/scripts/swarmforge.sh.

ثلاثة أشكال للسرب

كل فرع إجابة مختلفة عن سؤال: كم من الإجراءات تستحق هذه المهمة؟ فرع main توثيقي؛ والطوبولوجيات القابلة للتشغيل توجد على فروع pack. والتدفق حلقة لا طابور.

two-pack

coder → cleaner → coder

coder يعمل بمنهج الاختبار أولًا، وcleaner ينظّف ويراجع CRAP وDRY ويصلح البنية. أصغر حلقة تفصل مع ذلك بين الكتابة والحكم، والشكل الوحيد الذي يسهل تبرير كلفته في العمل الاعتيادي.

four-pack

specifier → coder → refactorer → architect → specifier

مواصفات القبول بصيغة Gherkin تدخل في المقدمة. يقوم refactorer بتنظيف يحفظ السلوك ويرفع التغطية، ويراجع architect البنية واتجاه التبعيات قبل أن تعود الحلقة إلى المواصفة.

six-pack

specifier → coder → cleaner → architect → hardener → QA

يضيف مرور تصليب يُطفِّر الكود لمعرفة أين تكون مجموعة الاختبارات عمياء، ودور ضمان جودة مستقل يتحقق عبر واجهة المستخدم. أربعة من الأدوار الستة تعمل بنمط الدفعات ليتوزّع ثمن الأدوات على شريط أولوية كامل.

كيف يقطع تغيير واحد الحلقة فعلًا

هذا هو six-pack، ويستحق أن يُقرأ كخط أنابيب من معايير الخروج لا كقائمة مسمّيات وظيفية. كل صف هو مطالبة دور في المستودع، وكل شرط خروج أمر يجب أن ينجح.

1

specifier

→ coder
يستلم
طلبًا من الإنسان، في شجرة عمل master
يفعل
يكتب مواصفات القبول بصيغة Gherkin ومواصفة مجموعة ضمان الجودة الشاملة، ويسأل حيث تكون النية غامضة، ويقلّم معاملات الأمثلة إلى القيم التي تؤثر فعلًا في تطفير القبول.
معيار الخروج
لا يُودِع حتى يوافق الإنسان صراحةً. هذه هي البوابة البشرية الوحيدة في الحلقة، وهي في المقدمة حيث تكون الأرخص.
2

coder

→ cleaner
يستلم
تسليم git يشير إلى كوميت واسم مهمة ثابت
يفعل
يكتب اختبارات وحدة مركّزة تعبّر عن السلوك المطلوب، وبعبارة مطالبة الدور نفسها: اختبارات تفشل أمام تنفيذ خاطئ معقول. ثم يكتب من كود الإنتاج ما يكفي لتنجح فقط. ولا تُقبل اختبارات القبول المُولَّدة صراحةً بديلًا عن اختبارات الوحدة.
معيار الخروج
التحقق المحلي ينجح. ولا يشغّل التطفير ولا CRAP ولا DRY — فتلك للأدوار اللاحقة، حتى لا يقيّم الـ coder عمله بنفسه.
3

cleaner

→ architect
يستلم
دفعة من التسليمات بالأولوية نفسها
يفعل
يشغّل أداة CRAP أولًا ويهبط بالتعقيد إلى 6 أو أقل، ثم أداة DRY لإزالة التكرار، ثم أداة التطفير في نمط المسح والعدّ فقط — مع تقسيم أي ملف يتجاوز 100 موضع تطفير — ويرفع التغطية حيث يكون ذلك معقولًا.
معيار الخروج
السلوك دون تغيير، والاختبارات لا تزال خضراء، والتعقيد والتكرار انخفضا. ويُمنع صراحةً من تشغيل اختبارات التطفير أو إضافة سلوك.
4

architect

→ hardener
يستلم
دفعة من الكوميتات المنظَّفة
يفعل
يقسّم الكود إلى وحدات بحدود حقيقية، ويُبقي التبعيات متجهة إلى الداخل، ويطارد الدورات وتسرّب أطر العمل، ويعزل سياسة التطبيق عن واجهة المستخدم ونظام الملفات وقاعدة البيانات والشبكة. ويضيف فحوص بنية آلية حيث يكون ذلك عمليًا.
معيار الخروج
السلوك محفوظ والمجموعة خضراء. ويُمنع تشغيل git merge يدويًا: الدمج يجري عبر ready_for_next.sh فقط.
5

hardener

→ QA
يستلم
دفعة من الكوميتات التي رُوجعت بنيويًا
يفعل
يشغّل أداة تطفير اللغة ملفًا ملفًا، تفاضليًا مقابل البيانات الموجودة، مع ما يصل إلى ثمانية عمّال متوازين، ويعالج الطفرات الباقية قبل المتابعة. ثم مرور تطفير قبول Gherkin بمستوى soft، ثم CRAP، ثم DRY، بهذا الترتيب تحديدًا.
معيار الخروج
كل أداة في السلسلة نظيفة قبل تشغيل التي بعدها. وهذا هو الدور الذي يقرّر إن كانت الاختبارات تختبر شيئًا فعلًا.
6

QA

→ specifier
يستلم
دفعة من الكوميتات المُصلَّبة
يفعل
تحقق نهائي مستقل: مواصفة القبول، والمجموعة الشاملة المُدارة عبر واجهة المستخدم بلا اختصارات عبر الـ API، واختبارات الوحدة والخصائص، وفحوص إصدار المشروع. ويعيد إنتاج أي إخفاق قبل تغيير أي كود.
معيار الخروج
يشغّل CRAP وDRY مرة أخرى قبل الإتمام. وإن تعارضت مجموعة ضمان الجودة مع Gherkin أو مع اختبارات الوحدة، يتوقف ويسأل إنسانًا بدل انتقاء منتصر.

النقل هو الجزء غير المعتاد

معظم أطر الوكلاء تتيح للوكلاء التحدث معًا. ويرفض SwarmForge ذلك عن قصد: خادم يملك التوصيل، ونظام الملفات هو الطابور، وtmux لا يُستخدم إلا لنكز نافذة خالية من العمل.

الطوبولوجيا ملف إعداد واحد

conf

الـ six-pack المُرفق يضع كل دور على الخادم الخلفي نفسه مع تمكين تجاوز الأذونات، ويجعل النصف الخلفي من الحلقة كله مستهلكًا للدفعات. ويجب أن يطابق اسم الدور اسم ملف المطالبة، وهو في هذا المستودع مكتوب hardender.

# swarmforge/swarmforge.conf
# window-invisible <role> <agent> <worktree> [task|batch] [extra-cli-args...]
window-invisible specifier codex master           --yolo
window-invisible coder     codex coder            --yolo
window-invisible cleaner   codex cleaner    batch --yolo
window-invisible architect codex architect  batch --yolo
window-invisible hardender codex hardender  batch --yolo
window-invisible QA        codex QA         batch --yolo

الطابور دليل، والموقع هو الحالة

text

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

.swarmforge/handoffs/
  outbox/
    tmp/            # drafts land here, then get renamed in atomically
  sent/
  failed/           # malformed or undeliverable, with diagnostics
  inbox/
    new/
    in_process/
    completed/

# filename sorts the queue for you
<priority>_<timestamp>_<sequence>_from_<sender>_to_<recipients>.handoff
# priority 00-99, lower first; UTC YYYYMMDDTHHMMSSZ

الوكيل يطلب فقط ولا يوصّل أبدًا

sh

يكتب الوكيل مسوّدة بأربع ترويسات ويستدعي سكربت البوابة. ولا يستطيع كتابة id أو from أو recipient أو أي طابع زمني — فهي محفوظة، حتى لا يزوّر المُدقَّق عليه أصل السجل. ولا يكتب SHA أيضًا: السكربت يوحّد ويتحقق من أن الكوميت كائن حقيقي غير ملتبس من عشرة أحرف.

# ./tmp/handoff.txt — drafted inside the assigned worktree
type: git_handoff
to: hardender
priority: 00
task: task-1-cave-setup

# hand it to the protocol gate; the daemon does delivery
swarm_handoff.sh ./tmp/handoff.txt

# receiving side, driven by the role's mode in .swarmforge/roles.tsv
ready_for_next.sh     # -> TASK: / BATCH: / NO_TASK, plus the payload
done_with_current.sh  # -> stamps completed_at, then pulls the next item

البوابات التي على hardener اجتيازها، بالترتيب

sh

هذا ما يجعل السرب أكثر من لعب أدوار. فالدستور يثبّت هذه الأدوات عند البدء طازجةً من مستودعات المؤلف — crap4go وcrap4java وcrap4clj للتعقيد، وmutate4go وclj-mutate وmutate4java للتطفير، وعائلة dry4* للتكرار — ومطالبة الدور تحدّد ترتيب تشغيلها.

# hardener: nothing advances until the previous check is clean
mutate4go ./...            # one file at a time, differential, <= 8 workers
gherkin-mutator --level soft   # mutate the acceptance examples too
crap4go ./...              # complexity against coverage
dry4go ./...               # duplication

# then, and only then
swarm_handoff.sh ./tmp/handoff.txt   # to: QA

لماذا يأخذ كل مكوّن هذا الشكل

إذا قرأتها كهندسة، فمعظم القرارات التي تبدو غريبة هي دفاعات ضد أنماط فشل محددة للوكلاء.

الرسالة كوميت لا شرح

تسليم git يحمل اسم مهمة وكوميتًا مُتحقَّقًا منه. ولا يستطيع حمل حجّة المؤلف عن جودة كوده، لأن الحجّة تدفع الوكيل التالي إلى الموافقة عليها. أما الكوميت فيدفع إلى التحقق. وهذه أكثر فكرة قابلة للنقل في المشروع.

تنبيهات الإيقاظ عامة ويُسمح بفقدانها

إشعار tmux من الخادم يقول فقط إن بريدًا وصل وإن على الوكيل تشغيل ready_for_next.sh إن كان خاليًا. ولا يسمّي ملفًا أبدًا، فلا يستطيع وكيل أن ينتقي العنصر المثير ويتجاوز ترتيب الطابور، ويمكن للوكيل المشغول تجاهله بأمان لأن إكمال مهمة يجذب التالية أيضًا.

الملاحظات محدودة بثمانين حرفًا وغير مُشجَّعة

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

لكل دور شجرة عمل لا فرع فقط

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

النصف الخلفي من الحلقة يستهلك دفعات

يأخذ cleaner وarchitect وhardener وQA كل التسليمات ذات الأولوية نفسها كوحدة واحدة. وتشغيلات التطفير والتغطية وفحوص البنية مكلفة لكل استدعاء ورخيصة لكل ملف إضافي، فالدفعة هي الفرق بين بوابة تُشغَّل وبوابة تُعطَّل.

المعيار شجرة مطالبات بأسبقية معلنة

constitution.prompt تدّعي السلطة، والمقالات تحمل القواعد، والمقالات المحلية تتجاوزها للمشروع، ومطالبات الأدوار تجلس فوق ذلك، ويُطلب من الوكيل إعادة قراءة كل ذلك في كل مهمة. فيتحول معيار كتابة الكود من وثيقة عن العمل إلى مُدخَل له.

الحكم

النصف القيّم من SwarmForge هو الدستور وترتيب البوابات: أدوار مُسمّاة بمسؤولية واحدة، ومعايير خروج هي أوامر قابلة للتنفيذ، وقاعدة صارمة بأن مؤلف التغيير لا يقيّمه أبدًا. هذا النصف جيد فعلًا، وهو بروحه مستقل عن اللغة، ويمكنك تنفيذه هذا الربع في نظام التكامل المستمر الذي تشغّله بالفعل — بلا tmux إطلاقًا. أما النصف الآخر، الخادم وطابور الملفات الدائم، فمبنيّ ببراعة لكنه يحل في معظمه مشكلة يمكنك تجنّبها: إن كانت بواباتك تعمل في التكامل المستمر على طلب دمج، فستحصل على الاستدامة وسجل التدقيق وترتيب الأولوية مجانًا من أدوات يشغّلها فريقك أصلًا.

اقرأه كتنفيذ مرجعي لسير عمل، لا كمنصة للتبنّي. ابدأ بالـ two-pack لتحسّ إن كان فصل الأدوار يفيد عملك أصلًا، واقتبس سلسلة البوابات في كل الأحوال، ولا تمدّ يدك إلى حلقة الأدوار الستة إلا حين تتجاوز كلفة العيب بوضوح كلفة ست تشغيلات وكيل لكل تغيير.

ما يصيبه

  • + بوابات الجودة أوامر بعتبات — تطفير، CRAP، DRY، تغطية — لا صفات في دليل أسلوب
  • + المراجع لا يرى استدلال المؤلف أبدًا، بل كوميتًا فقط، وهذه هي الطريقة الوحيدة لتكون مراجعة الوكيل ذات قيمة
  • + الترتيب يطابق تسلسلًا هندسيًا حقيقيًا: المواصفة، التنفيذ، التنظيف، إعادة الهيكلة، التصليب، التحقق المستقل
  • + عزل شجرة العمل يلغي تلف التعديل المتزامن بالبناء لا بالأقفال
  • + حالة الطابور تعيش على القرص مع سجل تدقيق يستحيل على الوكلاء بنيويًا تزويره، فالانهيار يُستأنف والتشغيل يُعاد بناؤه
  • + بوابة الموافقة البشرية الوحيدة تقع في وقت المواصفة، حيث يكون تغيير الرأي أرخص ما يكون
  • + كل شيء نص عادي قابل للرصد — نوافذ تقرأها، ومطالبات تعدّلها، وطابور تسرده بـ ls

ما يكلّفك

  • الإعداد المُرفق يشغّل كل وكيل بتجاوز الأذونات، فالتصميم كله يفترض قبولك بترك ستة وكلاء ينفّذون أوامر بلا رقابة في مستودعك
  • ست تشغيلات وكيل لكل تغيير عبث اقتصادي في العمل الصغير، ولا شيء في الحلقة يقرّر أن مهمة تستحق إجراءات أقل
  • سلسلة الأدوات القابلة للتنفيذ هي مشاريع المؤلف نفسه crap4* وmutate4* وdry4* لـ Go وClojure وJava — وخارج هذه اللغات لا ينطبق عقد البدء في الدستور وتوفّر مكافئاتك بنفسك
  • إعادة تثبيت تلك الأدوات من GitHub عند كل بدء بطيء ويعتمد على الشبكة ويشكّل سطح سلسلة توريد أصبح ملكك
  • zsh وtmux وBabashka على macOS هو المسار السعيد؛ وويندوز يعني WSL ووسيط طرفية
  • قاعدة التمرير تُلزم الدور بالإرسال إلى المرحلة التالية سواء غيّر شيئًا أم لا، فتولّد الحلقة حركةً حتى عندما لا تفعل مرحلةٌ شيئًا
  • مطالبات الأدوار ليست إلزامًا: لا شيء يمنع دورًا من تجاوز بوابته سوى الجملة التي تنهاه، فالضمانات الحقيقية بقوة نسختك في التكامل المستمر فقط
  • المشروع قيد العمل بشكل ظاهر — لوحة متابعة، ومؤشر حرارة، ومراقب نوافذ، وفروع pack متباعدة، وmain غير قابل للتشغيل بقصد

ما يستحق الاقتباس حتى لو لم تشغّله أبدًا

لا تدع المؤلف يقيّم العمل

  • - شغّل أدوات الجودة في خطوة منفصلة، بسياق منفصل عن الذي كتب الكود
  • - أعطِ خطوة المراجعة الفرق البرمجي والأدوات، لا تبرير المؤلف
  • - في تدفقات الوكلاء هذه ليست نظافة إجراءات بل الفرق بين مراجعة وختم مطاطي

اجعل كل بوابة رمز خروج

  • - للتعقيد والتكرار والتغطية والطفرات الباقية أدوات تُرجع قيمة غير الصفر
  • - ثبّت ترتيب تشغيلها وأوقف الخط عند أول فشل
  • - يتعامل الوكيل بصورة صحيحة مع أمر فاشل، وبصورة غامضة مع فقرة نصائح

اجعل التسليمات ضيقة ومُتحقَّقًا منها وقابلة للتدقيق

  • - مرجع كوميت مع سطر قصير يدفعان النية إلى الكود وإلى الرسالة
  • - تحقّق عند الحدود ليفشل الطلب المعطوب قبل أن تهدر المرحلة التالية تشغيلًا عليه
  • - أبعِد حقول الأصل عن متناول المُرسِل إن أردت لسجل التدقيق معنى

أبقِ المعيار حيث يحدث العمل

  • - القواعد المكتوبة كمقالات مطالبات تُقرأ في كل مهمة، بخلاف صفحة ويكي لا يفتحها أحد
  • - افصل القواعد المشتركة عن التجاوزات المحلية حتى لا يصبح استثناء فريق قاعدةً للجميع
  • - أدرِجها في إدارة الإصدارات مع الكود وراجع تغييراتها كما تراجع الكود

سير العمل هو الإسهام

إذا نزعت tmux وBabashka والتثبيت من أرشيف tar، يبقى ادعاء عن هندسة البرمجيات: التخصصات التي تُبقي الكود قابلًا للسكنى قابلة للفصل، وكل واحد منها يستحق دوره الخاص بتعليماته الخاصة، ولا يمكن لأي منها أن يُؤدّى بمصداقية على يد الطرف الذي كتب الكود. كان هذا صحيحًا قبل الوكلاء. وما غيّره الوكلاء هو حجم المخاطرة، فقد ارتفع حجم المُخرَج ولم يصبح الإنسان المراجع أسرع.

فخُذ الأجزاء التي تنجو من الترجمة. سمِّ مروراتك وأعطِ كل واحد مهمة واحدة. اجعل كل معيار خروج أمرًا. ضع البوابة البشرية في وقت المواصفة. وامنع مؤلف التغيير من أي دور في الحكم عليه. وأما إن كان هذا الخط ست نوافذ tmux أو مهندسين اثنين أو ملف تكامل مستمر بخمس وظائف مرتّبة، فذلك أقل أهمية بكثير من وجود البوابات وتشغيلها فعلًا.

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

ما الذي يلزم لتشغيل SwarmForge؟

zsh وgit وtmux وBabashka، بالإضافة إلى واجهة سطر أوامر مُهيّأة لوكيل مثل Claude أو Codex أو Copilot أو Grok. لا خدمة سحابية ولا طبقة تنسيق يجب إقامتها: السرب نوافذ tmux يمكنك مراقبتها، وشجرة عمل لكل دور على القرص، وطابور من الملفات النصية.

من أي فرع يبدأ الفريق؟

two-pack. دوران يكفيان لمعرفة إن كان فصل الكتابة عن الحكم يفيد عملك، ومن الصعب جدًا تبرير كلفة حلقة من ستة أدوار قبل ذلك. وفرع main توثيقي ولا يشغّل سربًا.

هل تشغيل الوكلاء بتجاوز الأذونات آمن؟

هذا أكبر سؤال تشغيلي يتركه لك التصميم. فالإعداد المُرفق يمرّر أعلام التجاوز لكل دور، وهو ما يجعل حلقة بلا رقابة ممكنة أصلًا. وإن جرّبت، فافعل ذلك على نسخة قابلة للتخلّص أو في حاوية بلا بيانات اعتماد، وأبقِ بوابات الجودة الحقيقية في التكامل المستمر حيث لا يستطيع السرب تجاوزها.

هل يعمل مع Go وClojure وJava فقط؟

التنسيق مستقل عن اللغة، لكن البوابات القابلة للتنفيذ ليست كذلك. فالدستور يسمّي أدوات التطفير وCRAP وDRY الخاصة بالمؤلف لتلك اللغات الثلاث. وعلى منصات أخرى تُبقي بنية الأدوار وتستبدل المكافئات، مثل Stryker أو PIT للتطفير، وأي تقرير يجمع التعقيد والتغطية لحساب CRAP.

هل يُلغي سرب الوكلاء الحاجة إلى ضمان الجودة؟

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

ما الفكرة الأجدر بالنسخ؟

أن الوكيل الذي كتب الكود هو أسوأ حاكم ممكن عليه، وأن العلاج سياق منفصل يحمل أداةً ذات رمز خروج. وكل ما عدا ذلك في المستودع تفصيل تنفيذي لهذه الجملة.

© 2026 - Ryware.