Backlog.md

حين يعمل أكثر من وكيل برمجي على المشروع، قد يصبح السؤال الأصعب ليس «هل كتب الكود؟» بل: ما المهمة التي كان ينفذها؟ ما شروط قبولها؟ ولماذا اتُّخذ هذا القرار؟ Backlog.md يحوّل هذه المعلومات إلى ملفات Markdown داخل المشروع، ويعرضها من الطرفية أو لوحة Kanban محلية أو عبر MCP. النتيجة أن المهمة وخطتها وقرارك تبقى بجوار الكود وقابلة للمراجعة، بدل أن تضيع داخل محادثة وكيل واحدة.

🧭 ما أداة Backlog.md؟

Backlog.md مدير مهام مفتوح المصدر ومبني على Markdown لأي مجلد أو مستودع Git. كل مهمة ملف نصي مقروء، ويمكن أن يحتوي الوصف ومعايير القبول والخطة والملاحظات والاعتماديات والملخص النهائي. تستطيع استخدامه وحدك من سطر الأوامر، أو فتح لوحة محلية في المتصفح، أو ربطه بأدوات مثل Codex وClaude Code وCursor عبر تعليمات CLI أو موصل MCP.

لا يحتاج خادمًا مركزيًا أو حسابًا. Git اختياري؛ يمكنك تشغيله لمشروع غير برمجي عبر --no-git. عند استخدام Git تصبح ملفات المهام جزءًا من تاريخ المشروع، ويمكن مراجعة تغييراتها ومشاركتها بالطريقة نفسها التي تشارك بها الكود.

رسم توضيحي أصلي لمسار Backlog.md؛ ليس لقطة من واجهة المنتج.

🎯 كيف ستفيدك؟

تناسب الأداة مطورًا منفردًا أو فريقًا صغيرًا يستخدم وكلاء برمجية ويريد أن يراجع نطاق العمل قبل الكود. بدل أن تقول للوكيل «أضف البحث» ثم تنتظر مئات الأسطر، اطلب منه تقسيم الفكرة إلى مهام صغيرة، وضع معايير قبول واضحة، ثم كتابة خطة داخل المهمة قبل التنفيذ. بعد اعتمادك للخطة ينفذ مهمة واحدة ويعرض الاختبارات وفروقات Git.

القيمة المضافة ليست أن Backlog.md يكتب الكود؛ بل أنه يضع ثلاث نقاط توقف واضحة للمراجعة:

1. مراجعة وصف المهمة ومعايير القبول.
2. مراجعة خطة التنفيذ والملفات المتوقعة.
3. مراجعة الكود والاختبارات والنتيجة قبل الإغلاق.

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

رسم توضيحي للمسار الموصى به في وثائق المشروع، وليس قياسًا لجودة المخرجات.

🌟 الميزات والقدرات الرئيسية

1. مهام Markdown قابلة للمراجعة

ينشئ Backlog.md ملفات مهام داخل مجلد محلي مثل backlog/ أو .backlog/. تستطيع المهمة أن تحمل سبب وجودها، الوصف، المسؤول، الأولوية، الحالة، معايير القبول، Definition of Done، الخطة، الملاحظات، المراجع، الاعتماديات والملخص النهائي. يوصي المشروع باستخدام أوامر CLI أو MCP أو الواجهة بدل تعديل الملفات يدويًا حتى تبقى أنواع الحقول والبيانات الوصفية متسقة.

• أين تجدها: داخل مجلد backlog في المشروع، أو عبر backlog task <id>.
• كيف تستخدمها: أنشئ مهمة ثم أضف وصفًا ومعايير قبول قبل التنفيذ.
• مثال توضيحي: backlog task create "Add unified search" --ac "Search tasks, docs, and decisions".
• الفائدة: يستطيع الإنسان والوكيل التالي قراءة المقصود من المهمة دون استرجاع محادثة قديمة.
• القيد: ملف Markdown لا يجعل المعايير جيدة تلقائيًا؛ يجب أن تكتب شروطًا قابلة للتحقق.

رسم توضيحي لبنية المهمة، وليس نموذجًا حرفيًا لكل الحقول في الإصدار.

2. نقاط مراجعة للوكلاء قبل التنفيذ

بعد backlog init يمكن للأداة إضافة تعليمات قصيرة إلى AGENTS.md أو ملف التعليمات المناسب، ثم يقرأ الوكيل backlog instructions overview. المسار المقترح هو: تقسيم الفكرة إلى مهام، مراجعة المواصفة، كتابة خطة لمهمة واحدة، اعتماد الخطة، التنفيذ والتحقق، ثم إغلاق المهمة.

تعليمات CLI هي الخيار الافتراضي الموصى به. يوجد MCP اختياري لـCodex وClaude Code وGemini CLI وKiro وCursor. MCP لا يجعل الوكيل مستقلًا عن صلاحياته؛ هو يتيح له قراءة مهام المشروع وتعديلها عبر أدوات منظّمة.

• الفائدة: تراجع نطاقًا صغيرًا قبل أن يتحول سوء الفهم إلى تعديل كبير.
• القيد: «مهمة واحدة = جلسة واحدة = PR واحد» توصية سير عمل وليست قاعدة يفرضها النظام.

3. لوحة Kanban في الطرفية والمتصفح المحلي

الأمر backlog board يعرض لوحة تفاعلية في الطرفية. والأمر backlog browser يشغّل واجهة محلية على 127.0.0.1:6420 افتراضيًا، مع السحب والإفلات، إنشاء المهام وتعديلها، تحرير معايير القبول وتحديثات متزامنة بين العرض والملفات. الخادم مربوط بالواجهة المحلية فقط، لذلك لا يفتح لوحة للفريق عبر الشبكة تلقائيًا.

يمكنك كذلك تصدير اللوحة إلى Markdown باستخدام backlog board export أو تضمينها داخل README. يفيد هذا في إرسال لقطة حالة قابلة للقراءة دون تشغيل خدمة مركزية.

4. الواجهة نفسها للإنسان والوكيل والأتمتة

تستطيع إدارة البيانات عبر CLI أو TUI أو الويب أو MCP. أوامر القراءة تدعم --plain و--json، وتوفر القوائم ترقيمًا للصفحات في الإصدار v1.53.0. يمكن لسكريبت صغير أن يقرأ المهام بصيغة JSON، بينما يراجع الإنسان اللوحة نفسها بصريًا.

يدعم Backlog.md أيضًا الوثائق والقرارات والمعالم والاعتماديات والبحث. تعرض تفاصيل المهمة ما تعتمد عليه وما يعتمد عليها، وتكشف الدورات أو المراجع الغامضة بدل حلها بالتخمين.

رسم توضيحي؛ جميع الواجهات تعمل على ملفات المشروع نفسها.

🪜 مثال عملي خطوة بخطوة

مثال توضيحي لم أنفذه على مشروعك: تريد إضافة بحث موحد داخل تطبيقك.

1. ثبّت الأداة ثم شغّل backlog init "My Project" داخل المشروع.
2. اختر تعليمات CLI لوكيلك، أو اختر MCP فقط إذا كنت تحتاج أدوات MCP مباشرة.
3. اطلب من الوكيل: «قسّم ميزة البحث الموحد إلى مهام صغيرة في Backlog.md، مع وصف ومعايير قبول، ولا تكتب كودًا بعد».
4. افتح backlog board أو backlog browser واقرأ المهام. عدّل المعايير إذا كانت عامة مثل «يعمل جيدًا» إلى نتائج قابلة للفحص.
5. اختر مهمة واحدة، واطلب من الوكيل كتابة خطة التنفيذ داخلها وانتظار اعتمادك.
6. راجع الملفات المقترحة وطريقة الاختبار. اعتمد الخطة أو أعدها للتعديل.
7. اسمح بالتنفيذ، ثم راجع الاختبارات وgit diff والملخص النهائي.
8. انقل المهمة إلى Done بعد التحقق. استخدم backlog task complete لإزاحتها من اللوحة مع حفظ سجلها وروابط اعتمادها، أو archive للمهمة الملغاة أو المكررة.

لو كان المشروع صغيرًا جدًا، يمكنك تخطي الوكيل واستخدام Backlog.md كمدير مهام عادي من الطرفية أو المتصفح.

⚖️ ماذا تضيف مقارنة بالطريقة اليدوية؟

هذه مقارنة لمسار العمل، وليست وعدًا بتوفير وقت أو ضمانًا لجودة التنفيذ.

⚙️ الإعدادات المهمة

يبدأ backlog init بإعداد بسيط: اسم المشروع، مجلد backlog، مكان ملف الإعداد، وطريقة ربط الوكلاء. وللتحكم المتقدم استخدم backlog config.

• remoteOperations: مفعّل افتراضيًا، ويسمح بعمليات Git البعيدة اللازمة لرؤية المهام عبر الفروع. اضبطه على false إذا أردت العمل دون جلب من الشبكة.
• autoCommit: معطّل افتراضيًا؛ تغييرات المهام تعدّل الملفات ولا تنشئ commit تلقائيًا.
• checkActiveBranches: يفحص حالة المهام عبر الفروع النشطة، وقد يزيد الكلفة على مستودع كبير.
• bypassGitHooks: معطّل افتراضيًا. تفعيله يستخدم --no-verify عند commits التلقائية؛ لا تفعله بلا سبب.
• onStatusChange: يستطيع تشغيل أمر shell عند تغير الحالة، لكنه معطّل افتراضيًا ويجب التعامل معه كتنفيذ كود محلي.

🚀 التثبيت والبدء

أمر npm الرسمي:

npm i -g backlog.md

ثم داخل مشروع:

backlog init "My Project"
backlog task create "Add unified search"
backlog board

توجد بدائل موثقة عبر Bun وHomebrew وNix. على macOS وLinux وWindows توجد حزم أو مسارات تثبيت مدعومة. إذا أردت تشغيلًا لمرة واحدة فاستخدم الاسم الكامل npx backlog.md؛ الأمر npx backlog دون تثبيت قد يحل إلى حزمة أخرى غير هذه الأداة.

لم أنفذ التثبيت أو المثال. تحقق من النسخة بعد التثبيت باستخدام backlog --version، ثم قارنها بأحدث إصدار موثق.

🔗 التكاملات والتوافق

• وكلاء البرمجة: توثق الأداة Claude Code وCodex وGemini CLI وKiro وCursor عبر تعليمات CLI أو MCP.
• Git: اختياري؛ مفيد للتاريخ والتعاون ومراجعة تغييرات المهام.
• الأنظمة: macOS وLinux وWindows وفق README، مع ملاحظات خاصة لمعمارية Apple Silicon وIntel.
• التصدير: لوحة Markdown وJSON مستقر لعمليات القراءة، مع وضع مراقبة للقوائم.
• VS Code: يوجد امتداد مجتمعي، وليس جزءًا من الأداة الأساسية.

💰 التكلفة والتشغيل المحلي

الكود مرخّص برخصة MIT، ولا تتطلب الأداة نفسها اشتراكًا أو API مدفوعًا. يمكن استخدامها بلا وكيل AI. إذا ربطتها بخدمة نموذج مدفوعة فتكلفة النموذج منفصلة عن Backlog.md.

المهام وملفات الإعداد تبقى داخل مجلد المشروع. README يصرح بعدم وجود حساب أو Telemetry، والواجهة تعمل محليًا. لكن «محلي» لا يعني «دون شبكة» دائمًا: التثبيت يحتاج تنزيل الحزمة، وremoteOperations مفعّل افتراضيًا وقد يجلب بيانات Git البعيدة. عطّله عند الحاجة إلى عمل دون اتصال.

⚠️ الحدود ومتى لا تستخدمها

• ليست خدمة SaaS مشتركة بوجود حي وصلاحيات فريق؛ التعاون يعتمد غالبًا على Git وعمليات الدمج.
• الواجهة المحلية لا تُعرض للأجهزة الأخرى افتراضيًا، وهذا جيد للخصوصية لكنه لا يوفر لوحة مشتركة جاهزة.
• قد تظهر تعارضات ملفات إذا عدّل أكثر من فرع المهمة نفسها؛ ميزات الفروع تقلل التخمين لكنها لا تلغي تعارض Git.
• فحص الفروع النشطة قد يبطئ المشاريع الكبيرة؛ يمكن تعطيله أو تقليل مدة الفروع النشطة.
• لا تستبدل Jira أو Linear عندما تحتاج صلاحيات مؤسسية، تقارير عابرة لعدة فرق أو تدفقات موافقات معقدة.
• لا تجعل كثرة الحقول المهمة أكبر من العمل نفسه؛ استخدم أقل قدر كافٍ من الوصف والقبول والخطة.

🔐 الأمان والصلاحيات

backlog init قد يضيف تعليمات إلى ملفات مثل AGENTS.md، ويصرح README بأنه يحافظ على المحتوى غير المرتبط. راجع فرق الملفات قبل الالتزام. موصل MCP يمنح الوكيل أدوات لقراءة مهام المشروع وتعديلها؛ نطاقه يبقى مرتبطًا بصلاحيات عملية الوكيل وملفات المشروع.

راجع أي إعداد يشغّل أوامر محلية، خصوصًا onStatusChange. لا تفعل bypassGitHooks إذا كانت hooks جزءًا من فحوص الحماية لديك. الواجهة تربط نفسها بـ127.0.0.1، لكن ملفات backlog قد تحتوي معلومات حساسة؛ لا ترفعها إلى مستودع عام دون مراجعة. كذلك لا تضع مفاتيح API أو أسرارًا داخل وصف المهمة.

📚 المصادر وتاريخ التحقق

تحققت في 1 أكتوبر 2026 من المستودع الأصلي، README، مرجع CLI، الإعداد المتقدم، الإصدارات والرخصة.

أحدث إصدار ظاهر كان v1.53.0 بتاريخ 24 سبتمبر 2026. أظهر GitHub نحو 6.9 آلاف نجمة و437 تفرعًا وقت الفحص؛ هذه أرقام شعبية متغيرة وليست تقييمًا للجودة أو الأمان. لم أثبّت الأداة، ولم أنفذ المثال، ولم أختبر موصل MCP على مشروع فعلي.