من المتطلبات إلى الكود: سير عمل قابل للتتبع لوكيل ذكاء اصطناعي

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

يبني هذا الدرس السجل عن قصد: سلسلة واحدة من متطلب مكتوب إلى طلب سحب مدمج، تكون كل حلقة فيها شيئًا يمكنك فتحه. ويحل Spec Kit من GitHub الفجوة نفسها بملفات داخل المستودع. أما هذا الدليل فيحلها بنظام عمل، باستخدام Sharkly لأنه يُبقي السلسلة كاملة على Task واحد، مع أن النمط قابل للنقل إلى أي متتبع يستطيع حمل الروابط نفسها. وإن كنت تريد حلقة التشغيل أولًا، فابدأ بدليلنا عن إدارة مشاريع وكلاء الذكاء الاصطناعي.

باختصار

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

ما الذي يجب أن يعنيه التتبع فعلًا

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

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

الخطوة 1: اكتب المتطلب في صورة Task

الـ Task هو الوحدة الأساسية للعمل المتتبع في Sharkly، والـ Space المُهيَّأ لتطوير البرمجيات يبدأ بأنواع المهام Requirement وBug وTask وUser Story. استخدم Requirement أو User Story للمهمة الأب. فالنوع هو الذي يحدد الحقول المخصصة وحالات الـ Workflow التي تنطبق، وبذلك يستطيع الـ Requirement حمل حالة مراجعة خاصة به دون تلويث سير عمل الـ Bug.

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

اربط المستودعات على مستوى الـ Space حتى ترثها كل مهمة فرعية. والوكيل الذي لا توجد له ارتباطات مستودعات يعود إلى مستودعات Git الخاصة بالـ Space، وهذا ما تريده لميزة تتضمن عدة Tasks.

الخطوة 2: دع وكيلًا يرسم شكل التقسيم، ثم أكّده

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

هذه هي الحلقة التي تتخطاها معظم الفرق، وهي التي تجعل التقسيم قابلًا للتتبع بدل أن يكون ارتجالًا. فالاقتراح مرئي قبل أن يصبح عملًا: احذف المهمة الفرعية التي توسّع النطاق، وأضف خطوة الترحيل التي أغفلها الوكيل. وتبقى المهام الفرعية في الـ Space نفسه الذي فيه المهمة الأب، وترفض Sharkly أن تكون المهمة أبًا لنفسها أو أن تنشأ حلقات، فيبقى التسلسل شجرة.

استخدم وكيلًا واحدًا لمتطلب يستطيع دور واحد تغطيته. واستخدم Crew عندما يحتاج القائد إلى تفسير الهدف وإشراك أعضاء وكلاء آخرين مثل كاتب اختبارات، ثم جمع نتائجهم في Task واحد. أما تغيير يمس ثلاثة ملفات، فإن الـ Crew يضيف أجزاء متحركة دون أن يضيف تتبعًا. ودليلنا عن Sharkly Crews يشرح نموذج القائد أولًا.

انسخ أي شيء يُقرَّر في المحادثة إلى وصف الـ Task. فالمحادثة على Task ليست تعليقًا ولا تظهر في Activity، وبالتالي فالقرار الذي يعيش هناك وحده يكون غير مرئي للسلسلة.

الخطوة 3: نفّذ في بيئة معزولة، مع أثر يمكن تتبعه

أسند كل مهمة فرعية إلى وكيل عبر عنصر التحكم Assignee، ثم أخرجها من Backlog. تتحقق Sharkly من فئة الحالة وجاهزية التنفيذ، وتضع التشغيل في قائمة الانتظار، وترسله إلى الـ Computer المحدد، حيث تجهّز الخدمة المحلية مجلد مهام معزولًا وتشغّل الـ Runtime.

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

يعود التقدم وأحداث التتبع والنتيجة إلى الـ Task. ويسجّل سجل التنفيذ سبب إدراج التشغيل في قائمة الانتظار، ووقت بدايته وانتهائه، واستدعاءات الأدوات وأحداث الـ Runtime، ومصدر التشغيل، وتفاصيل الفشل. هذا السجل هو الحلقة الرابعة.

الخطوة 4: اربط طلب السحب بالمعرّف

اربط منظمة GitHub مرة واحدة، ثم ضع معرّف الـ Task في عنوان طلب السحب أو وصفه أو اسم الفرع المصدر. وكلٌّ من SH-312 المجرّد وFixes SH-312 ينشئ الرابط. وتضيف الارتباطات العكسية تعليقًا يحتوي على رابط الـ Task في طلب السحب، وهي مفعّلة افتراضيًا للمستودعات الخاصة.

والآن الحدود، لأنها مهمة للتتبع: كلمات مثل fixes وcloses لا تحمل أي معنى إضافي، ودمج طلب سحب لا يغيّر حالة الـ Task. Sharkly تربط التغيير بالـ Task، لكنها لا تقرر أن الـ Task انتهى. وتبقى الحالة قرارًا بشريًا، وهذا هو جوهر الحلقة السادسة. وشرحنا عن إسناد تذكرة Jira إلى وكيل ذكاء اصطناعي والحصول على طلب سحب في المقابل يعرض الرابط نفسه من جهة المتتبع.

الخطوة 5: راجع مقابل المتطلب، ثم اقبل

يستطيع الوكيل ترك الـ Task في انتظار مراجعة بشرية، وتصل هذه الإشارة إلى Inbox الشخص المسؤول تحت Primary. اقرأ ثلاثة أشياء بالترتيب: معايير القبول من الخطوة الأولى، وتعليق الوكيل الذي يسرد الفحوصات التي أجراها وما بقي غير مؤكد، وسجل التنفيذ. وبعد ذلك فقط اقرأ الـ diff.

وإن كان هناك Task اختبار منفصل يتحقق من التغيير، فسجّل هذه العلاقة صراحةً. يستطيع مالكو المنظمة والمسؤولون إنشاء أنواع روابط مخصصة، والمثال الوارد في الوثائق نفسه، validates / is validated by، هو الرابط الذي يحقق التتبع في هذه الحلقة. والعلاقات لا تغيّر الحالة من تلقاء نفسها، لذا يبقى القبول تغيير حالة يقوم به شخص.

وهناك قاعدة فئوية تحميك هنا: نقل الـ Task إلى Completed يجعله نهائيًا لكنه لا يلغي تشغيلًا نشطًا بالفعل. فإن كان الوكيل ما زال يعمل، فألغِ التشغيل أولًا ثم اتخذ قرارك.

أين تنكسر السلسلة

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

استنتاجات تُترك في المحادثة. جلسات Agent Chat المستقلة تخص الشخص الذي أنشأها. وإن حُسم التصميم هناك، فلا علم للـ Task بذلك.

تشغيلات تبدأ خارج الـ Task. إجراء Run Agent في سير عمل الأتمتة لا ينشئ Task؛ إذ يُسجَّل التشغيل على الوكيل. وهذا مقبول لفحص ليلي، لكنه خاطئ لعمل الميزات.

ملفات بدلًا من سجل. ملفات spec.md وplan.md وtasks.md في Spec Kit سلسلة قوية لمطور واحد يعمل في مستودع واحد. استخدمها حين يكون الفريق كله أنت. أما حين يحتاج شخص ثانٍ إلى المراجعة أو القبول أو السؤال عمّا حدث دون فتح نسختك المحلية، فاستخدم نظام عمل مشتركًا. Sharkly ليست بديلًا عن Claude Code أو Codex أو أدوات التنفيذ الأخرى؛ بل هي الطبقة التي تُبقي السلسلة مرئية حولها. وتغطي الوثائق كل مفهوم بمزيد من التفصيل على docs.sharkly.ai.

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

هل يعني «من المتطلبات إلى الكود» أن الوكيل هو من يكتب المتطلب؟ لا. يكتب الشخص المتطلب ومعايير قبوله. ويمكن للوكيل أن يبحث في قاعدة الكود ويقترح تقسيمًا في وضع Plan، لكن الاقتراح لا يصبح Tasks إلا بعد أن يؤكده شخص.

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

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

ما حجم أول ميزة قابلة للتتبع؟ متطلب واحد، ومهمتان أو ثلاث مهام فرعية، ووكيل واحد. وشرحنا عن إدارة مشاريع Claude Code يشغّل الحلقة من البداية إلى النهاية على Task واحد.