Plannotator: كيف تراجع خطة وكيل البرمجة وتعلّق عليها قبل أن يكتب أي كود

يفتح Plannotator خطة وكيل البرمجة في المتصفح لتضع عليها ملاحظاتك وترسلها قبل كتابة الكود. إليك طريقة التثبيت والأوامر وتفاصيل الخصوصية الدقيقة.

Graphic of a browser window with a marked-up plan and comment bubbles, illustrating the Plannotator tool for reviewing coding agent plans.

اقترح وكيل البرمجة لديك للتو خطة من اثنتي عشرة خطوة، وينتظر موافقتك قبل أن يبدأ في إعادة كتابة مشروعك. تمرّ عليها سريعًا في الطرفية، وتكتب “looks good” (تبدو جيدة)، وتأمل ألا تحذف الخطوة التاسعة شيئًا تحبه.

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

ما تحتاج إليه

  • وكيل برمجة مدعوم. يذكر ملف README كلًّا من Claude Code وCodex وCopilot CLI وGemini CLI وOpenCode وKiro وDroid وAmp وPi.
  • طرفية ومتصفح. فـPlannotator، بحسب ملف README الخاص به، “a local, browser-based review surface” (واجهة مراجعة محلية تعمل في المتصفح).
  • Git، إذ تقول وثائق تثبيت Plannotator إن برنامج التثبيت يحتاج إليه من أجل المهارات (skills).

Plannotator مجاني، ومرخّص بترخيص مزدوج Apache 2.0 أو MIT، ويُظهر مستودعه على GitHub (backnotprop/plannotator) نحو 11,400 نجمة حتى 15 نوفمبر 2026. أُنشئ المستودع في 28 ديسمبر 2025، ونُشر أحدث إصدار منه، v0.28.65، في اليوم نفسه. الأوامر أدناه منسوخة من ملف README والوثائق كما كانت في 15 نوفمبر 2026 وجرت مطابقتها مع تلك الصفحات؛ وأسطر الطرفية تجتاز فحص الصياغة، لكننا لم نثبّت Plannotator لكتابة هذا المقال.

الخطوة 1: ثبّت البرنامج

على macOS أو Linux أو WSL:

الطرفية
curl -fsSL https://plannotator.ai/install.sh | bash

على Windows PowerShell:

الكود
irm https://plannotator.ai/install.ps1 | iex

بحسب الوثائق، يضيف برنامج التثبيت الأمر plannotator، ويتحقق من الملف الذي نزّلته عبر مجموع التحقق SHA-256، ويثبّت الخطافات (hooks) والمهارات الأساسية للوكلاء الذين يعثر عليهم. وعند التشغيل الأول يسألك إن كنت تريد إضافة مهارات إضافية؛ والإجابة الافتراضية هي لا. تأكّد من نجاح التثبيت:

الكود
plannotator --version

إن كان تمرير سكربت مباشرة إلى الطرفية يقلقك، فالوثائق توفر تثبيتًا للملف التنفيذي وحده (--minimal)، وطريقة لتثبيت إصدار محدد والتحقق من مصدره.

الخطوة 2: اربط وكيلك

يحتاج Claude Code إلى خطوة إضافية واحدة. شغّل داخل Claude Code ما يلي:

الكود
/plugin marketplace add backnotprop/plannotator
/plugin install plannotator@plannotator

ثم أعد تشغيل Claude Code. بحسب ملف README، لا يحتاج Codex وGemini CLI إلى أي شيء آخر (يتطلب Gemini الإصدار 0.36.0 أو أحدث)، ويحتاج OpenCode إلى "plugin": ["@plannotator/opencode@latest"] في opencode.json، أما Pi فيستخدم pi install npm:@plannotator/pi-extension. وإن كانت الخطافات والمهارات جديدة عليك، فدليلنا عن مهارات الوكلاء في Claude Code يشرح كل الأجزاء.

الخطوة 3: اجعل وكيلك يكتب خطة

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

خلف الكواليس، يسير التدفق بحسب ملف README على النحو التالي:

  1. ينهي الوكيل خطته ويطلب الخروج من وضع التخطيط (يسمّي ملف README هذه الخطوة ExitPlanMode).
  2. يعمل خطاف ما، ويفتح خادم محلي الخطة في متصفحك.
  3. تضيف تعليقاتك، ثم توافق أو ترفض.
  4. إذا رفضت، تعود ملاحظات منظّمة إلى الوكيل فيراجع خطته. ويعرض فرق الخطة (diff) ما تغيّر.

يقول موقع Plannotator إن بإمكانك التعليق على الأقسام، أو تحديد نص لحذفه، أو كتابة نص بديل، ثم الموافقة أو الرفض مع إرفاق تلك الملاحظات.

النتيجة المتوقعة: تبويب في المتصفح يعرض خطتك، جاهز لإضافة التعليقات.

الخطوة 4: علّق على ما لديك أصلًا

لا يقتصر Plannotator على الخطط. هذه الأوامر مأخوذة من ملف README:

الكود
/plannotator-last
/plannotator-annotate README.md
/plannotator-annotate src/
/plannotator-review

الأول يعلّق على آخر رسالة من وكيلك. والثاني والثالث لوضع ملاحظات على ملف أو مجلد. أما الأخير فيفتح عارض فروق بأسلوب طلبات السحب (pull request) لتغييراتك غير المحفوظة في Git، ويمكنك بدلًا من ذلك تمرير رابط طلب سحب على GitHub أو طلب دمج على GitLab. وفي Codex، استبدل الشرطات المائلة بمهارات $plannotator-*.

ماذا يفعل ببياناتك

يقول ملف README إن Plannotator “does not collect usage telemetry or analytics” (لا يجمع بيانات قياس الاستخدام ولا التحليلات)، وإن الخطط والفروق والتعليقات تبقى محلية افتراضيًا. لكنه يذكر أيضًا استثناءات تستحق المعرفة:

  • تتحقق كل شاشة مراجعة عند تحميلها من أحدث إصدار على GitHub. ويقول ملف README إنه لا توجد حاليًا طريقة لتعطيل هذا التحقق.
  • ميزة “Ask AI” (اسأل الذكاء الاصطناعي) ترسل السؤال والسياق ذا الصلة إلى المزوّد الذي ضبطته.
  • مشاركة الخطة تُنشئ رابطًا. وبحسب ملف README، تُضمَّن المشاركات الصغيرة داخل الرابط نفسه دون تشفير، فيستطيع أي شخص يملك الرابط قراءتها. أما المشاركات الكبيرة فتُشفَّر قبل الرفع، وتنتهي صلاحية النصوص المستضافة بعد 7 أيام.

أخطاء شائعة وحلولها

  • plannotator: command not found. افتح طرفية جديدة. تقول الوثائق إن متغير PATH ربما تغيّر.
  • صفحة المراجعة لا تُحمَّل عبر SSH أو داخل حاوية. عبر SSH، يقول ملف README إن Plannotator ينتقل إلى المنفذ الثابت 19432، والسطر الخاص بملف ~/.ssh/config هو LocalForward 19432 localhost:19432. وداخل حاوية، أو لاستخدام منفذ آخر، اضبط PLANNOTATOR_REMOTE=1 وPLANNOTATOR_PORT=9999، ثم وجّه ذلك المنفذ بدلًا منه. جديد على SSH؟ اطّلع على دليلنا لمفاتيح SSH.
  • الوضع البعيد مفتوح على مصراعيه. يحذّر ملف README من أن الخادم في الوضع البعيد يستمع على 0.0.0.0 دون تسجيل دخول، فيستطيع أي شخص يصل إلى المنفذ استخدامه. أبقِ المنفذ مغلقًا أمام الشبكات التي لا تثق بها.
  • لا تظهر أي نافذة على الإطلاق. الإعداد PLANNOTATOR_BROWSER=none لا يفتح أي متصفح، ويُطبع رابط الجلسة دائمًا.
  • لم يعد Claude ينتظرك. في Claude Code 2.1.287 أو أحدث، يقول ملف README إن Claude ينهي دوره ويصله قرارك لاحقًا على شكل رسالة. اضبط PLANNOTATOR_CLAUDE_MOD=0 لاستعادة التدفق الكلاسيكي.
  • الإضافة لا تتحدّث. شغّل claude plugin marketplace update plannotator، ثم claude plugin update plannotator@plannotator، ثم أعد التشغيل.
  • تريد التخلص منه. جرّب أولًا بـplannotator uninstall --dry-run، ثم شغّل plannotator uninstall. وهو يحتفظ افتراضيًا بخططك وسجلّك.

الخلاصة

خطة تقرؤها فعلًا أقل كلفة من فروق كود تضطر إلى تفكيكها لاحقًا. وإذا كنت تترك وكيلك يتحكم في متصفح أيضًا، فاطّلع على دليل إعداد Chrome DevTools MCP.

المصادر

آخر تحقق من الروابط في 15 نوفمبر 2026.

بقلم Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

عن Mindloop Experience

الردود

اكتب ردًّا

المزيد من Mindloop Experience

كل مقالات Mindloop Experience

يمكنك التصفيق حتى 50 مرة.