> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# خطط ثم نفذ ثم تحقق: حلقة العمل مع وكيل البرمجة
- URL: https://arabroot.io/articles/خطط-ثم-نفذ-ثم-تحقق-مع-وكيل-البرمجة/
- Published: 2026-11-20T06:06:33.000Z
- Updated: 2026-11-20T07:05:58.000Z
- Description: خطة قصيرة يراجعها إنسان، ثم خطوة واحدة في كل طلب، ثم دليل من أمر يرجع بنجاح أو فشل، مع مختبر يجرب الميزة نفسها بست طرق ويحكم عليها باختبارات لم يرها الوكيل.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, التطوير مع وكلاء الذكاء الاصطناعي

تعطي وكيل البرمجة Coding Agent تذكرة Ticket من ثلاثة أسطر، وتذهب لتصب القهوة، وعندما ترجع تجد رسالة واثقة تقول إن الميزة Feature أصبحت جاهزة، ومعها commit برسالة مرتبة. ثم تفتح الفرق Diff فتكتشف أن الوكيل كتب الكود في ملف جديد لا يستدعيه أحد، أو أنه حل مشكلة قريبة من مشكلتك وليست هي، أو أنه نسي قاعدة كانت في رأسك ولم تكتبها في التذكرة. وهنا تبدأ الدورة المعروفة: تصحح، فيعدل، فيفسد شيئاً آخر، فتصحح مرة ثانية، وبعد ساعة تكتشف أنك لو كتبت الكود بنفسك لكنت انتهيت.

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

في هذا المقال سوف نتناول:

- ما هي حلقة خطط ثم نفذ ثم تحقق Plan, Implement, Verify، وما الذي يخرج من كل خطوة.
- ماذا تكتب في الخطة، ولماذا يجب أن يراجعها إنسان قبل التنفيذ.
- كيف تنفذ بخطوات صغيرة، ومتى توقف الوكيل وتبدأ من جديد.
- التحقق: ما الذي يعتبر دليلاً، ولماذا لا يكفي أن تمر الاختبارات الموجودة.
- مختبر حقيقي: الميزة نفسها بست طرق مع Aider ونموذج محلي، واختبارات قبول مخفية تحكم على النتيجة.
- كيف تطبق الحلقة في الأدوات المعروفة، ومتى تختصرها.

وهذا المقال جزء من مرحلة سير العمل اليومي مع الوكيل، وإذا كانت المهمة ميزة كاملة تحتاج وصفاً قبل الخطة فقد شرحنا ذلك في مقال التطوير من المواصفة، وشرحنا ما يراه الوكيل من السياق Context في مقال هندسة السياق:

[![](https://arabroot.io/content/images/2026/11/spec-driven-development-cover-cover.webp)دليلالتطوير من المواصفة Spec-driven Development: الخطة قبل الكودكيف تعمل Spec Kit من GitHub، وما الفرق بين المواصفة والخطة والمهام، وماذا حدث عندما بنى نموذج محلي صغير الميزة نفسها بثلاث طرق تحت اختبارات قبول لم يرها.](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D9%85%D9%86-%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A9-spec-driven-development-%D8%A7%D9%84%D8%AE%D8%B7%D8%A9-%D9%82%D8%A8%D9%84-%D8%A7%D9%84%D9%83%D9%88%D8%AF/)[![](https://arabroot.io/content/images/2026/11/context-engineering-cover-cover.webp)دليلهندسة السياق Context Engineering: ما يراه الوكيل وما لا يراهما الذي يرسله الوكيل فعلاً مع طلبك، ولماذا يخطئ النموذج عندما يكون أمامه ملف لا يحتاجه أو سجل طويل أو جلسة قصت من أولها، مع تجارب على نموذج محلي تغير السياق وحده.](https://arabroot.io/articles/%D9%87%D9%86%D8%AF%D8%B3%D8%A9-%D8%A7%D9%84%D8%B3%D9%8A%D8%A7%D9%82-context-engineering-%D9%85%D8%A7-%D9%8A%D8%B1%D8%A7%D9%87-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84/)[![](https://arabroot.io/content/images/2026/11/agents-md-cover-cover.webp)دليلملف تعليمات المشروع AGENTS.md وCLAUDE.md: ماذا تكتب فيهأين تضع ملف تعليمات الوكيل، وكيف تجمعه Codex وClaude Code وCopilot من المجلدات، ومتى يقطع دون أن يعرف النموذج، وماذا يتغير فعلاً عندما تكتبه.](https://arabroot.io/articles/%D9%85%D9%84%D9%81-%D8%AA%D8%B9%D9%84%D9%8A%D9%85%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B4%D8%B1%D9%88%D8%B9-agents-md-%D9%88claude-md-%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D9%83%D8%AA%D8%A8-%D9%81%D9%8A%D9%87/)[![](https://arabroot.io/content/images/2026/11/ai-code-review-cover-cover.webp)دليلمراجعة كود الذكاء الاصطناعي دون أن تصبح شكليةكيف تراجع طلبات الدمج التي يكتبها الذكاء الاصطناعي بحسب خطرها، وتترك للبوابات الآلية ما تستطيع قياسه.](https://arabroot.io/articles/%D9%85%D8%B1%D8%A7%D8%AC%D8%B9%D8%A9-%D9%83%D9%88%D8%AF-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%AF%D9%88%D9%86-%D8%A7%D9%86-%D8%AA%D8%B5%D8%A8%D8%AD-%D8%B4%D9%83%D9%84%D9%8A%D8%A9/)

## ما هي حلقة خطط ثم نفذ ثم تحقق؟

الحلقة ثلاث خطوات، ولكل خطوة شيء ملموس يخرج منها وتستطيع أن تراجعه، وهذا هو الفرق بينها وبين النصيحة العامة «فكر قبل أن تكتب»:

- **التخطيط Plan:** يقرأ الوكيل الكود ويقترح خطة دون أن يعدل أي ملف: أي الدوال سوف تتغير وبأي ترتيب، وما الأسئلة المفتوحة التي يجب أن تقرر فيها قبل الكود. والذي يخرج من هذه الخطوة ملف قصير، تراجعه أنت وتحذف منه وتجيب عن أسئلته.
- **التنفيذ Implement:** ينفذ الوكيل خطوة واحدة من الخطة في كل طلب، ويعمل commit لكل خطوة. والذي يخرج منها فرق صغير تقرؤه في دقيقة، وتاريخ Git تستطيع أن ترجع فيه خطوة واحدة دون أن تخسر الباقي.
- **التحقق Verify:** يشغل الوكيل أمراً يرجع بنجاح أو فشل، مثل الاختبارات Tests أو فاحص الكود Linter أو البناء Build، ويقرأ النتيجة ويصلح إذا فشل، ثم يعطيك الدليل: الأمر الذي شغله ومخرجه. والذي يخرج منها دليل وليس ادعاءً.

![ثلاث محطات في دائرة: التخطيط Plan وتحته ملف PLAN.md ومراجعة إنسان، ثم التنفيذ Implement وتحته commit صغير لكل خطوة، ثم التحقق Verify وتحته مخرج الاختبارات وflake8، وسهم أحمر يرجع من التحقق إلى التنفيذ مكتوب عليه إذا فشل الاختبار، وسهم برتقالي يرجع من التنفيذ إلى التخطيط مكتوب عليه إذا ظهر قرار لم تحسمه الخطة، وفي الوسط سطر يقول إن كل محطة تخرج شيئاً تراجعه](https://arabroot.io/content/images/2026/11/plan-implement-verify-01-loop.webp)

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

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

## لماذا يحتاج الوكيل هذه الحلقة أكثر من الإنسان؟

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

والسبب الثاني أن الوكيل يتوقف عندما يبدو العمل منتهياً، وليس عندما يكون منتهياً. وهذا ما يقوله [توثيق أفضل الممارسات في Claude Code](https://code.claude.com/docs/en/best-practices?ref=arabroot.io) حرفياً تقريباً: الوكيل يتوقف عندما يبدو العمل منتهياً، وإذا لم يكن عنده شيء يشغله ليعرف هل انتهى فعلاً فإنك أنت تصبح مجموعة الاختبارات، وكل خطأ يبقى حتى تلاحظه بنفسك. ولذلك ينصح التوثيق نفسه بأن تعطي الوكيل فحصاً يرجع بنجاح أو فشل، وأن تطلب منه الدليل، أي الأمر الذي شغله ومخرجه، لأن عبارة «كل الاختبارات نجحت» وحدها لا تخبرك بشيء.

والسبب الثالث أن الشعور بالسرعة مع الوكيل يخدع، ففي [مقال الإنتاجية الحقيقية Productivity](https://arabroot.io/articles/%D9%87%D9%84-%D9%8A%D8%AC%D8%B9%D9%84%D9%83-%D9%88%D9%83%D9%8A%D9%84-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-coding-agent-%D8%A7%D8%B3%D8%B1%D8%B9-%D9%81%D8%B9%D9%84%D8%A7/) رأينا تجربة METR التي كان فيها المطورون الخبراء أبطأ بنسبة 19% مع الأدوات بينما كانوا يظنون أنهم أسرع، وجزء كبير من الوقت الضائع كان في مراجعة كود لا يناسب ما يريدون وتصحيحه. والحلقة في هذا المقال هي الطريقة العملية لتقليل هذا الوقت: تكتشف سوء الفهم في الخطة بدقيقتين، بدل أن تكتشفه في فرق من مئتي سطر.

## الخطوة الأولى: التخطيط Plan، ماذا تكتب في الخطة؟

الخطة التي نقصدها هنا ليست مواصفة Specification كاملة لميزة كبيرة، فتلك شرحناها في [مقال التطوير من المواصفة](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D9%85%D9%86-%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A9-spec-driven-development-%D8%A7%D9%84%D8%AE%D8%B7%D8%A9-%D9%82%D8%A8%D9%84-%D8%A7%D9%84%D9%83%D9%88%D8%AF/) بأدوات مثل Spec Kit، وإنما خطة لمهمة واحدة تكتب في دقائق، وفيها أربعة أجزاء:

- **ما الذي يتغير:** الملفات والدوال بالاسم، حتى لا يكتب الوكيل الكود في ملف جديد، أو يعدل دالة لا علاقة لها بالمهمة.
- **الخطوات بالترتيب:** خطوتان إلى خمس، وكل خطوة صغيرة بما يكفي لأن تكون commit واحداً تقرؤه في دقيقة.
- **القرارات Decisions:** إجابات الأسئلة المفتوحة، مثل ماذا يحدث في الحالة الحدية Edge Case، وما اسم الخطأ الذي يرفع، وما الذي يجب ألا يتغير.
- **متى ننتهي Done When:** الأمر الذي يجب أن ينجح، مثل `python -m unittest` و`flake8`، وليس وصفاً عاماً.

والذي يكتب المسودة الأولى هو الوكيل، لأنه يقرأ الكود أسرع منك ويعرف أين توجد الدوال، ولكن الذي يكتب القرارات هو أنت، لأنها معرفة لا توجد في الكود: قاعدة عمل اتفقتم عليها في اجتماع، أو سلوك يعتمد عليه نظام آخر. وأغلب الأدوات تعطيك وضعاً للتخطيط يقرأ فيه الوكيل ولا يعدل، مثل وضع Plan في Claude Code بحسب [صفحة أوضاع الصلاحيات](https://code.claude.com/docs/en/permission-modes?ref=arabroot.io)، ووضع Plan في Cline بحسب [صفحة Plan وAct](https://docs.cline.bot/features/plan-and-act?ref=arabroot.io)، ووضع ask في Aider الذي يقول عنه [توثيق الأوضاع](https://aider.chat/docs/usage/modes.html?ref=arabroot.io) إنه يناقش الكود ويجيب عن الأسئلة ولا يعدل أي شيء، وينصح بالتنقل بين `/ask` و`/code`.

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

## الخطوة الثانية: التنفيذ Implement، خطوة واحدة في كل طلب

بعد أن تراجع الخطة يأتي الخطأ الأشهر: أن تعطي الوكيل الخطة كلها وتقول له «نفذها خطوة خطوة». والمشكلة أن عبارة «خطوة خطوة» في رسالة واحدة لا تعني للنموذج أن يتوقف بين الخطوات، وإنما تعني أن يكتب رداً واحداً طويلاً فيه كل شيء، وكلما طال الرد زادت فرصة أن يخرج عن الخطة، وهذا بالضبط ما حدث في المختبر كما سيأتي. والطريقة الصحيحة أن يكون كل طلب خطوة واحدة باسمها، مع الملفات التي تحتاجها هذه الخطوة فقط، وأن ينتهي كل طلب بـ commit مستقل.

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

## الخطوة الثالثة: التحقق Verify، ما الذي يعتبر دليلاً؟

التحقق أن يشغل الوكيل أمراً يعرف نتيجته دون أن يسأل أحداً: الاختبارات، أو فاحص الكود، أو البناء، أو سكربت يقارن المخرج بملف متوقع. وفي Aider مثلاً تعطيه أمر الاختبارات بالخيار `--test-cmd` ومعه `--auto-test`، فيشغله بعد كل تعديل، وإذا فشل أرسل المخرج إلى النموذج ليصلح، كما في [صفحة الفحص والاختبار](https://aider.chat/docs/usage/lint-test.html?ref=arabroot.io)، ومعه فحص الكود التلقائي `--auto-lint` المفعل افتراضياً.

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

وللتحقق درجات من حيث من يفرضه:

- **في الطلب:** تكتب «شغل الاختبارات واستمر حتى تنجح»، والوكيل يقرر بنفسه متى يكتفي.
- **في بيئة التشغيل:** مثل `--auto-test` في Aider، أو خطاف Stop Hook في Claude Code الذي يرجع الوكيل إلى العمل إذا فشل سكربتك، كما في توثيق أفضل الممارسات.
- **في Git وخط CI:** خطاف pre-commit أو فحص في خط النشر يمنع الدمج، وهذا لا يعتمد على الوكيل أصلاً، وشرحناه في [مقال Git Hooks مع pre-commit](https://arabroot.io/articles/git-hooks-%D9%85%D8%B9-pre-commit-%D8%A7%D9%81%D8%AD%D8%B5-%D8%A7%D9%84%D9%83%D9%88%D8%AF-%D9%82%D8%A8%D9%84-%D8%A7%D9%86-%D9%8A%D8%AF%D8%AE%D9%84-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D9%88%D8%AF%D8%B9/).
- **بمراجع لم يكتب الكود:** جلسة جديدة أو زميل يراجع الفرق مقابل الخطة، وشرحنا طريقة المراجعة في [مقال مراجعة كود الذكاء الاصطناعي](https://arabroot.io/articles/%D9%85%D8%B1%D8%A7%D8%AC%D8%B9%D8%A9-%D9%83%D9%88%D8%AF-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%AF%D9%88%D9%86-%D8%A7%D9%86-%D8%AA%D8%B5%D8%A8%D8%AD-%D8%B4%D9%83%D9%84%D9%8A%D8%A9/).

![خمسة صفوف من الأعلى إلى الأسفل مع عدد متزايد من الدروع: في الطلب حيث الوكيل يقرر بنفسه متى يكتفي، وفي بيئة التشغيل مع auto-test وStop hook حيث الأداة تعيده إلى العمل إذا فشل الفحص، وفي Git مع pre-commit hook الذي يعمل قبل كل commit إلا إذا تجاوزته الأداة بالخيار no-verify، وفي خط CI مع required check وحماية الفرع حيث لا يدمج شيء دون نجاحه، ومراجع لم يكتب الكود يقارن الفرق بالخطة](https://arabroot.io/content/images/2026/11/plan-implement-verify-05-verify-levels.webp)

درجات التحقق من حيث من يفرضه: كلما نزلت صار أصعب أن يتجاوزه الوكيل أو أنت.

## المختبر: الميزة نفسها بست طرق

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

- **الوكيل:** Aider 0.86.2 في Container، وهو وكيل في الطرفية يعمل commit لكل تعديل، وشرحناه في [مقال الوكلاء مفتوحة المصدر](https://arabroot.io/articles/%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D9%85%D9%81%D8%AA%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%B5%D8%AF%D8%B1-aider-%D9%88cline-%D9%88openhands/).
- **النموذج:** `qwen2.5-coder:3b` على Ollama 0.40.13، على معالج Intel Core i7-7700K دون بطاقة رسومية، بنافذة سياق 8192 توكن وحد لطول الرد 2048 توكن. واخترنا نموذجاً صغيراً عن قصد، لأن النموذج الكبير يغطي على الطريقة السيئة بذكائه، أما الصغير فيظهر أثر الطريقة بوضوح.
- **الحرارة:** Aider يرسل الطلب لهذا النموذج بحرارة Temperature صفر، فالنتيجة تقريباً ثابتة إذا أعدت التشغيل بالطلب نفسه والملفات نفسها.
- **الحكم:** بعد كل تشغيل نطبع تاريخ Git والفرق ونتيجة اختبارات المستودع وflake8، ثم نشغل اختبارات القبول المخفية.

والمستودع تقويم صغير لحجز غرف الاجتماعات، فيه كلاس `Calendar` بدالة `book` تنشئ الحجز دون أي فحص، وثلاثة اختبارات للسلوك الموجود. والتذكرة التي أعطيناها للوكيل في كل الطرق هي نفسها:

```text
Prevent double booking: a room cannot have two bookings that overlap in time. When someone tries,
raise a BookingConflict error that tells the caller which existing booking is in the way.
```

والتذكرة تبدو واضحة، ولكن خلفها قرارات لم تكتب، واختبارات القبول الثمانية تمثل هذه القرارات، كما يفهمها فريق اتفق عليها:

1. الحجز المتداخل في الغرفة نفسها يرفع `BookingConflict`.
2. الخطأ يحمل رقم الحجز الموجود في خاصية اسمها `conflicting_id`.
3. الحجزان المتلاصقان، أي أن ينتهي واحد عندما يبدأ الآخر، لا يتعارضان.
4. الغرفة الأخرى لا تتعارض.
5. الحجز داخل حجز آخر، أو المحيط به، تعارض.
6. نهاية قبل البداية أو مساوية لها ترفع `ValueError`.
7. الحجز الملغى يحرر وقته.
8. الحجز المرفوض لا يستهلك رقماً، فالحجز التالي يأخذ الرقم الذي كان سيأخذه.

ولاحظ أن ثلاثة من الثمانية، أي الثالث والرابع والسابع، تنجح على الكود الأصلي قبل أي تعديل، لأنه لا يرفض شيئاً أصلاً، ولذلك فإن النتيجة 3 من 8 تعني عملياً أن الميزة لم تنفذ.

### الطريقة A: التذكرة وحدها

في الطريقة الأولى أعطينا Aider الملف `booking.py` والتذكرة كما هي، وهذا ما يفعله أغلب المطورين في الأسبوع الأول مع الوكيل:

```bash
aider --model ollama_chat/qwen2.5-coder:3b --model-settings-file /lab/model.settings.yml \
  --map-tokens 1024 --no-pretty --no-stream --yes-always \
  booking.py --message "$TICKET"
```

والمخرج سوف يكون كما يلي، مختصراً:

```text
Here is the updated `calendar.py` file:

calendar.py
```
"""Meeting-room bookings for a small office app."""
...
class BookingConflict(Exception):
    """Error raised when a booking conflicts with an existing booking."""
    def __init__(self, existing_booking):
        self.existing_booking = existing_booking
...
Tokens: 1.1k sent, 454 received.

calendar.py
Applied edit to calendar.py
Commit 082bc14 feat(calendar): add method to prevent double booking
== elapsed 454 s
```

في المخرج أعلاه لاحظ التالي:

- كتب النموذج الملف كاملاً، ولكن باسم `calendar.py` بدل `booking.py`، ولأننا وافقنا مسبقاً على كل شيء بالخيار `--yes-always` فإن Aider أنشأ ملفاً جديداً بهذا الاسم وعمل له commit، بينما بقي `booking.py` الذي يستعمله المشروع كما هو.
- رسالة الـ commit مرتبة بصيغة Conventional Commits وتقول إنه أضاف منع الحجز المزدوج، وهذا صحيح فقط في ملف لا يستدعيه أحد.
- الخطأ يحمل الحجز كاملاً في خاصية `existing_booking`، وليس رقمه، لأن التذكرة قالت «يخبر بالحجز الذي في الطريق» ولم تحدد كيف.

والحكم كان كما يلي:

```text
== diff stat since initial
 calendar.py | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
== repo tests
OK
== hidden acceptance
test_1_overlap_raises_booking_conflict ... ERROR
test_2_conflict_names_the_existing_booking ... ERROR
test_3_back_to_back_is_allowed ... ok
test_4_other_room_is_free ... ok
test_5_inside_and_around_are_conflicts ... ERROR
test_6_end_before_start_is_value_error ... FAIL
test_7_cancel_frees_the_slot ... ok
test_8_rejected_booking_does_not_use_an_id ... FAIL
FAILED (failures=2, errors=3)
```

ولاحظ هنا السطر `repo tests OK`: اختبارات المستودع كلها نجحت، لأنها تختبر السلوك القديم الذي لم يتغير، فلو كان التحقق الوحيد عندك هو «هل نجحت الاختبارات؟» لقبلت هذه النتيجة. والذي كشفها هو أول سطر في `git diff --stat`: ملف جديد لم تطلبه، وهذه أول عادة في المراجعة.

### الطريقة B: التذكرة مع القرارات، دون خطوة تخطيط

في الطريقة الثانية أضفنا إلى التذكرة القرارات نفسها التي تمثلها اختبارات القبول، مكتوبة في سطور قصيرة، دون أي خطوة تخطيط:

```text
Decisions: BookingConflict is a new exception class in booking.py with an attribute conflicting_id
(the id of the existing booking). Bookings that touch (one ends exactly when the next starts) do not
overlap. Other rooms never conflict. If end <= start raise ValueError. A rejected booking must not use
up an id: only increment _next_id after the checks pass. Cancelled bookings free their slot.
```

والنتيجة هذه المرة تعديل من 13 سطراً في `booking.py` خلال 222 ثانية، وcommit واحد، ونجحت اختبارات القبول الثمانية كلها:

```text
Tokens: 1.2k sent, 413 received.
Applied edit to booking.py
Commit d314ceb feat(booking): add BookingConflict exception and modify book method to check for overlapping bookings
== elapsed 222 s
...
Ran 8 tests in 0.001s
OK
```

والدرس الأول من المختبر هنا: أغلب ما يحتاجه الوكيل ليس ذكاءً أكثر، وإنما القرارات التي في رأسك. فالنموذج نفسه، بالحرارة نفسها، انتقل من 3 إلى 8 عندما كتبنا له خمسة أسطر من القرارات. ولكن انتظر قبل أن تحكم بأن الطريقة B كافية، فهذا هو الكود الذي كتبه:

```python
        for b in self._bookings:
            if b.room == room and b.start <= end and b.end > start:
                raise BookingConflict(b.id)
```

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

```python
c = Calendar()
c.book('A', d(2026, 11, 22, 10), d(2026, 11, 22, 11), 'sara')
c.book('A', d(2026, 11, 22, 9), d(2026, 11, 22, 10), 'omar')   # ends exactly when sara starts
```

والمخرج سوف يكون كما يلي:

```text
BookingConflict 1
```

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

### خطوة التخطيط: ماذا سأل الوكيل وماذا نسي؟

في الطريقة الثالثة بدأنا بخطوة تخطيط حقيقية: طلبنا من Aider في وضع ask، أي دون أي تعديل، أن يكتب خطة مرقمة ويذكر كل سؤال مفتوح وكل حالة حدية يجب أن نقرر فيها قبل الكود:

```bash
aider ... booking.py --chat-mode ask --message "We need to implement this ticket: $TICKET Do not write code yet.
Write a short numbered plan: which functions change, in what order, and list every open question or edge
case we must decide before coding."
```

وكان الرد، مختصراً، كما يلي:

```text
1. **Identify the Functions Involved:**
   - `book`: This function needs to check for overlapping bookings before adding a new one.
   - `bookings_for`: This function should be updated to handle overlapping bookings when listing bookings for a room.
...
3. **Open Questions or Edge Cases:**
   - What should happen if a booking is canceled and then a new booking is attempted to overlap with the canceled booking?
   - Should the `BookingConflict` error include details about the conflicting booking?
   - How should the `BookingConflict` error be raised?
   - Should the `Calendar` class handle edge cases like invalid times or times that are too far in the future?
...
Tokens: 609 sent, 447 received.
== elapsed 139 s
```

في الخطة أعلاه لاحظ التالي:

- طرحت الخطة ثلاثة أسئلة مفيدة من القرارات الثمانية: الحجز الملغى، وما يحمله الخطأ، والأوقات غير الصحيحة. وهذه أسئلة لم تكن في التذكرة، وهذه هي الفائدة الأولى للخطوة.
- لم تسأل عن الحجزين المتلاصقين، ولا عن رقم الحجز المرفوض، فهذان قراران أضفناهما نحن عند المراجعة، والخطة لا تغني عن تفكيرك.
- اقترحت الخطة تغيير `bookings_for` لتستبعد الحجوزات المتداخلة من القائمة، وهذه خطوة خاطئة لا يطلبها أحد، كانت سوف تغير سلوكاً يعتمد عليه غيرنا. وهذه هي الفائدة الثانية: أن ترى سوء الفهم وهو سطر في خطة، لا وهو كود في commit.
- الخطوة كلها أخذت 139 ثانية وأقل من ألف توكن، وهي أرخص خطوة في الحلقة.

ثم راجعنا الخطة كما يفعل أي مطور: حذفنا الخطوة الخاطئة، وأجبنا عن الأسئلة، وأضفنا القرارين الناقصين، وكتبنا متى ننتهي، فأصبح الملف `PLAN.md` كما يلي:

```markdown
# Plan: prevent double booking (ticket BK-12)

Reviewed by the developer after the agent's plan step. Changes from the agent's draft:
step 2 (filtering overlapping bookings out of bookings_for) is removed, and the open questions are answered.

## Decisions
- BookingConflict is a new exception class in booking.py with an attribute conflicting_id (the id of the existing booking).
- Two bookings overlap when new.start < old.end and old.start < new.end. Touching bookings (one ends exactly when the next starts) do not overlap.
- Only bookings in the same room can conflict.
- If end <= start, raise ValueError.
- A rejected booking must not use up an id: increment _next_id only after all checks pass.
- Cancelled bookings free their slot (cancel already removes them; nothing to add).
- Do not change bookings_for or cancel.

## Steps
1. Add the BookingConflict class above Calendar.
2. In Calendar.book: check end <= start, then check every booking of the same room for an overlap, then create the booking.
3. Add one test per decision to test_booking.py.

## Done when
- python -m unittest passes and flake8 reports nothing.
```

![عمودان: في اليمين مسودة الوكيل في وضع ask خلال 139 ثانية، فيها تعديل book باللون الأخضر، وتعديل bookings_for باللون الأحمر، وثلاثة أسئلة خضراء عن الحجز الملغى وتفاصيل الخطأ والأوقات غير الصحيحة، وسطران برتقاليان لما لم يسأله عن المتلاصقين ورقم الحجز المرفوض، وفي اليسار PLAN.md بعد المراجعة بالخطوة الأولى وحذف تعديل bookings_for والقرارات والإضافتين، وأسهم من كل سطر في المسودة إلى ما صار إليه](https://arabroot.io/content/images/2026/11/plan-implement-verify-03-plan-review.webp)

ما سأله الوكيل في خطته، وما نسيه، والخطوة الخاطئة التي حذفناها قبل التنفيذ.

ولاحظ أن قرار التداخل مكتوب هنا كشرط دقيق `new.start < old.end and old.start < new.end`، لأن الطريقة B علمتنا أن عبارة «المتلاصقان لا يتعارضان» تحتمل خطأً في جهة واحدة.

### الطريقة C وD: الخطة كلها في طلب واحد

في الطريقة C أعطينا Aider الملف `booking.py`، والخطة للقراءة فقط بالخيار `--read`، وطلباً واحداً هو «نفذ PLAN.md خطوة خطوة». وفي الطريقة D الشيء نفسه مع خطوة التحقق، أي `--test-cmd` و`--auto-test` وflake8، ومع ملف الاختبارات في المحادثة. وتوقعنا أن تكون هاتان أفضل الطرق، ولكن هذا ما حدث في الطريقة C:

```text
Sure, I'll implement the changes step by step. Let's start with the `booking.py` file.
### Step 1: Add the `BookingConflict` class
...
### Step 2: Update `test_booking.py`
...
### Step 3: Update `PLAN.md`
...
### Step 4: Update `README.md`
...
### Step 5: Update `requirements.txt`
### Step 6: Update `setup.py`
### Step 7: Update `LICENSE`
### Step 8: Update `CONTRIBUTING.md`
...
Tokens: 1.3k sent, 2.0k received.
== elapsed 623 s
== git log
51944be initial: booking calendar
```

في المخرج أعلاه لاحظ التالي:

- الخطوة الأولى في الرد كانت صحيحة تقريباً، فيها الكلاس والشرط الصحيح، ولكن عبارة «خطوة خطوة» جعلت النموذج يكمل وحده: عدل الاختبارات، ثم أعاد كتابة الخطة نفسها، ثم اخترع ملفات README وsetup.py وLICENSE وCONTRIBUTING لمشروع لا توجد فيه هذه الملفات، حتى وصل إلى حد الألفي توكن.
- كتب الرد بصيغة diff بينما طلب Aider الملف كاملاً، ومع خليط الملفات المخترعة لم يطبق Aider أي تعديل، ولم يدخل Git أي commit، والنتيجة 3 من 8.
- الطريقة D انتهت بالشيء نفسه بعد 624 ثانية: رد طويل بخطوات مكررة، ثم رسالة `The LLM did not conform to the edit format`، ولم يطبق شيء. وفي مسودتها اختبار اسمه `test_book_conflict_touching` يتوقع تعارضاً للحجزين المتلاصقين، أي عكس القرار المكتوب في الخطة بالضبط.

وهذا هو الدرس الثاني، وهو أهم من الأول: الخطة الجيدة لا تنفع إذا أعطيتها كلها في طلب واحد، لأن «خطوة خطوة» في رسالة واحدة تعني للنموذج رداً واحداً طويلاً، وكلما طال الرد ابتعد عن الخطة. ومع النماذج الكبيرة لا يصل الأمر غالباً إلى ملف LICENSE مخترع، ولكن الظاهرة نفسها موجودة بشكل أخفى: فرق كبير فيه أشياء لم تطلبها، وهي العلامة التي ذكرها Kent Beck في [مقاله عن البرمجة مع الوكيل](https://newsletter.kentbeck.com/p/augmented-coding-beyond-the-vibes?ref=arabroot.io) حين كتب أنه يراقب الوظائف التي لم يطلبها حتى لو كانت خطوة تالية منطقية.

![مقارنة بين صندوقين: في اليمين بالأحمر طلب واحد يقول نفذ الخطة خطوة خطوة، يخرج منه رد طويل فيه ثماني خطوات تبدأ بملف booking.py وtest_booking.py ثم PLAN.md وREADME.md وrequirements.txt وsetup.py وLICENSE وCONTRIBUTING.md حتى حد الألفي توكن ولم يطبق منه شيء، وفي اليسار بالأخضر طلب لكل خطوة ثم commit صغير ثم قراءة الفرق بـ git diff ثم الخطوة التالية أو جلسة جديدة](https://arabroot.io/content/images/2026/11/plan-implement-verify-04-request-size.webp)

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

### الطريقة E: خطوة واحدة في كل طلب، مع التحقق

في الطريقة E طبقنا ما يقوله القسم السابق من المقال حرفياً: الخطة نفسها بعد المراجعة، ولكن طلب لكل خطوة باسمها، ومع خطوة التحقق في كل طلب، أي `--test-cmd` و`--auto-test` وflake8:

```bash
aider ... booking.py --read PLAN.md $VERIFY --message "Do step 1 of PLAN.md only: add the BookingConflict class."
aider ... booking.py --read PLAN.md $VERIFY --message "Do step 2 of PLAN.md only: change Calendar.book as described, following every decision."
aider ... test_booking.py --read booking.py --read PLAN.md $VERIFY --message "Do step 3 of PLAN.md only: add one test per decision to test_booking.py."
```

والطلب الأول رجع بعد 245 ثانية بهذا الـ commit:

```text
$ git show 224dc93 --stat --format='%h %s'
224dc93 feat: add the BookingConflict class
 booking.py | 11 +++++++++++

+        if end <= start:
+            raise ValueError("End time must be after start time.")
+        for b in self._bookings:
+            if b.room == room and b.start < end and end < b.end:
+                raise BookingConflict(b.id)
```

في المخرج أعلاه لاحظ التالي:

- طلبنا الخطوة الأولى فقط، فنفذ الوكيل الخطوتين الأولى والثانية معاً، ورسالة الـ commit تقول إنه أضاف الكلاس فقط. وهذا يكفي ليقول لك لماذا تقرأ الفرق ولا تكتفي بالرسالة.
- شرط التداخل `b.start < end and end < b.end` يقارن النهاية الجديدة مرتين ولا يقارن البداية الجديدة أبداً، رغم أن الشرط الصحيح مكتوب في الخطة حرفاً بحرف. فالحجز من 9:30 إلى 10:30 فوق حجز من 9 إلى 10 لا يعتبر تعارضاً.
- اختبارات المستودع الثلاثة نجحت بعد التعديل، لأنها لا تعرف شيئاً عن الميزة الجديدة.

والطلب الثاني أخذ 212 ثانية ورجع بفرق فارغ، فلم يتغير شيء ولم يعمل commit. أما الطلب الثالث، أي كتابة اختبار لكل قرار، فبدأ باختبارات معقولة ثم دخل في الحلقة نفسها التي رأيناها في مقالات سابقة من المسار: اختبار بعد اختبار بالاسم نفسه مع كلمتين زيادة، حتى وصل إلى حد الألفي توكن في منتصف سطر. وهنا عملت خطوة التحقق كما يجب، فشغل Aider فاحص الكود بعد التعديل:

```text
Applied edit to test_booking.py
Commit b9bb137 feat(test_booking.py): add one test per decision to test_booking.py
test_booking.py:166:22: E999 SyntaxError: '(' was never closed
## Running: flake8 test_booking.py
...
Tokens: 5.7k sent, 2.0k received.
Applied edit to test_booking.py
Commit 0e5bf3b test_booking.py
test_booking.py:168:150: E999 SyntaxError: expected '('
...
Tokens: 8.0k sent, 2.0k received.
Commit 4d1d2ab fix: correct syntax error in test_booking.py
...
litellm.APIConnectionError: Ollama_chatException - litellm.Timeout: Connection timed out after 1200.0 seconds.
...
Only 3 reflections allowed, stopping.
== elapsed 7356 s
```

في المخرج أعلاه لاحظ التالي:

- flake8 أمسك خطأ الصياغة Syntax Error بعد كل محاولة، والوكيل رجع في كل مرة بالملف نفسه تقريباً وفيه الحلقة نفسها، فانقطع في مكان آخر. أي أن التحقق كشف المشكلة، ولكن النموذج لم يستطع أن يخرج منها.
- Aider يعمل commit قبل أن يشغل الفحص، ولذلك دخل التاريخ ثلاثة commits لملف لا يعمل، أحدها برسالة `fix: correct syntax error` وهو لم يصلح شيئاً. وهذا سبب إضافي لأن يكون الوكيل على فرع خاص، وهو ما نشرحه في مقال Git مع الوكلاء.
- الحد الأقصى للمحاولات في Aider ثلاث، ثم توقف. والمحاولات كلها أخذت قرابة ساعتين، لأن كل محاولة ترسل الملف المكسور كله مع مخرج الفحص، فكبر الطلب من 1.6 ألف توكن إلى 8 آلاف، والمعالج يقرؤها بنحو 20 توكناً في الثانية.

والنتيجة النهائية للطريقة E كانت 4 من 8، واختبارات المستودع نفسها لا تعمل بسبب خطأ الصياغة:

```text
== repo tests
FAILED (errors=1)
== hidden acceptance
test_1_overlap_raises_booking_conflict ... FAIL
test_2_conflict_names_the_existing_booking ... FAIL
test_3_back_to_back_is_allowed ... ok
test_4_other_room_is_free ... ok
test_5_inside_and_around_are_conflicts ... FAIL
test_6_end_before_start_is_value_error ... ok
test_7_cancel_frees_the_slot ... ok
test_8_rejected_booking_does_not_use_an_id ... FAIL
FAILED (failures=4)
```

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

### ماذا لو أضفنا التحقق دون خطة؟

بقي سؤال: هل يكفي التحقق وحده؟ أي أن نعطي التذكرة كما هي، ولكن مع `--auto-test` وflake8 وملف الاختبارات في المحادثة. والنتيجة كانت كما يلي:

```text
Applied edit to booking.py
Commit 2142bd0 feat: add method to prevent double booking by checking for overlapping bookings
Ran 3 tests in 0.000s
OK
== elapsed 135 s
...
test_2_conflict_names_the_existing_booking ... ERROR
test_6_end_before_start_is_value_error ... FAIL
FAILED (failures=1, errors=1)
```

في المخرج أعلاه لاحظ التالي:

- هذه المرة عدل الوكيل `booking.py` الصحيح وليس ملفاً جديداً، والفرق الوحيد عن الطريقة A أن ملف الاختبارات كان في المحادثة، فرأى النموذج أن الكود يستورد من `booking`. أي أن الملفات التي تعطيها جزء من الطلب.
- شغل Aider الاختبارات بنفسه بعد التعديل فنجحت الثلاثة، فاعتبر المهمة منتهية. والتحقق هنا كان صادقاً، ولكنه كان يفحص السلوك القديم فقط.
- نجحت 6 من 8، وفشلت اثنتان لقرارين لم يكتبهما أحد: الخطأ يحمل الحجز لا رقمه، ولا يوجد فحص للنهاية قبل البداية.

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

![ستة صفوف بأعمدة أفقية من ثمانية: التذكرة وحدها 3 من 8 في 454 ثانية وكتب ملفاً جديداً باسم خاطئ، والتذكرة مع التحقق 6 من 8 في 135 ثانية والاختبارات القديمة نجحت، والتذكرة مع القرارات 8 من 8 في 222 ثانية ونجا خطأ لم يختبره أحد، والخطة في طلب واحد 3 من 8 في 623 ثانية مع ملفات مخترعة، والخطة والتحقق في طلب واحد 3 من 8 في 624 ثانية وخالف صيغة التعديل، وخطوة لكل طلب مع التحقق 4 من 8 في 7,813 ثانية بشرط خاطئ وحلقة في الاختبارات](https://arabroot.io/content/images/2026/11/plan-implement-verify-02-results.webp)

نتيجة الطرق الست على اختبارات القبول الثمانية، مع الزمن وما حدث في كل طريقة.

## كيف تطبق الحلقة في أداتك؟

كل الأدوات المعروفة فيها ما تحتاجه للخطوات الثلاث، وإن اختلفت الأسماء. والجدول التالي يجمع ما في التوثيق الرسمي لكل أداة:

| الأداة      | التخطيط                                                                | التنفيذ بخطوات                                            | التحقق                                                                                 |
| ----------- | ---------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Claude Code | وضع Plan الذي يقرأ ولا يعدل، أو أن تطلب منه أن يسألك حتى يكتب SPEC.md  | جلسة جديدة تبدأ من الخطة، ونقاط الرجوع بالأمر /rewind     | أمر الاختبار في CLAUDE.md، والأمر /goal، وخطاف Stop Hook يرجعه إلى العمل إذا فشل الفحص |
| Codex CLI   | أن تطلب الخطة في رسالة دون تعديل، مع وضع الصندوق للقراءة فقط read-only | رسالة لكل خطوة، وcommit بعد كل خطوة                       | أوامر الاختبار في AGENTS.md يشغلها الوكيل بنفسه                                        |
| Cline       | وضع Plan الذي يمنع التعديل وتنفيذ الأوامر                              | وضع Act مع موافقتك على كل تعديل، ونقاط الرجوع Checkpoints | الأوامر في الطرفية يتابع مخرجها                                                        |
| Aider       | الأمر /ask أو الخيار \--chat-mode ask                                  | رسالة لكل خطوة، وcommit تلقائي لكل تعديل                  | \--test-cmd مع \--auto-test، و\--lint-cmd مع \--auto-lint                              |
| OpenCode    | وكيل plan للقراءة يمنع التعديل افتراضياً                               | وكيل build للتنفيذ                                        | الأوامر في ملف التعليمات                                                               |

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

## متى تختصر الحلقة؟

الحلقة الكاملة لها ثمن، وليست كل مهمة تستحقه. والذي يحدد ذلك حجم المهمة وعدد القرارات فيها، كما في الجدول التالي:

| المهمة                                           | التخطيط                                                                                                                                                                                                                                                                                           | التنفيذ                         | التحقق                        |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------- |
| تعديل سطر واحد أو إعادة تسمية في ملف             | لا تحتاجه                                                                                                                                                                                                                                                                                         | طلب واحد                        | الاختبارات الموجودة           |
| إصلاح خطأ تعرف مكانه                             | لا تحتاجه، والطلب يذكر الملف والسبب                                                                                                                                                                                                                                                               | طلب واحد                        | اختبار يعيد الخطأ ثم ينجح     |
| ميزة صغيرة فيها قرارات                           | نعم، خطة قصيرة وقرارات مكتوبة                                                                                                                                                                                                                                                                     | طلب لكل خطوة                    | اختبار لكل قرار               |
| ميزة تلمس أكثر من وحدة أو واجهة يعتمد عليها غيرك | مواصفة ثم خطة، كما في [مقال التطوير من المواصفة](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D9%85%D9%86-%D8%A7%D9%84%D9%85%D9%88%D8%A7%D8%B5%D9%81%D8%A9-spec-driven-development-%D8%A7%D9%84%D8%AE%D8%B7%D8%A9-%D9%82%D8%A8%D9%84-%D8%A7%D9%84%D9%83%D9%88%D8%AF/) | طلب لكل خطوة، وربما فرع لكل جزء | اختبارات القبول ومراجعة بشرية |
| استكشاف أو نموذج أولي سوف ترميه                  | لا                                                                                                                                                                                                                                                                                                | طلبات حرة                       | تشغيل يدوي يكفي               |

ولاحظ أن الصف الثاني أهم مما يبدو: إذا كنت تعرف أين الخطأ ولماذا، فإن ذكر ذلك في الطلب يغنيك عن خطوة التخطيط كلها، وهذا ما رأيناه في [مختبر الوكلاء مفتوحة المصدر](https://arabroot.io/articles/%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D9%85%D9%81%D8%AA%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%B5%D8%AF%D8%B1-aider-%D9%88cline-%D9%88openhands/)، حين فشل النموذج الصغير في كل مرة تركنا له البحث، ونجح بسطر واحد عندما حددنا له الدالة وسبب الخطأ. والتخطيط في الحقيقة طريقة لتصل إلى هذا الطلب الدقيق عندما لا تعرف كل شيء من البداية.

## كم تكلف كل خطوة؟ الأرقام من المختبر

قد يبدو أن خطوة التخطيط وقت إضافي لا تحتاجه، ولكن الأرقام في المختبر تقول العكس: خطوة التخطيط أخذت 139 ثانية، وأرسلت 609 توكنات واستقبلت 447، أي أنها أرخص طلب في التجربة كلها. أما الطلب الذي يفشل فإنه يكلف أكثر بكثير، لأن كل محاولة إصلاح ترسل كل ما سبق من جديد: في الطريقة E بدأ طلب الاختبارات بـ 1.6 ألف توكن، ثم 5.7 آلاف في المحاولة الأولى للإصلاح، ثم 8 آلاف في الثانية، لأن Aider يرسل الملف كله مع مخرج الفحص في كل مرة، والنموذج يرد بألفي توكن في كل مرة.

وعلى معالج دون بطاقة رسومية يتحول هذا مباشرة إلى وقت، فالمعالج يقرأ نحو 20 توكناً في الثانية من هذا النموذج، فكل ألف توكن إضافية في الطلب دقيقة انتظار تقريباً قبل أن يبدأ الرد. ومع نموذج في السحابة يتحول إلى مال، لأنك تدفع ثمن كل توكن في كل محاولة، وشرحنا كيف تحسب ذلك في [مقال تكلفة وكلاء البرمجة](https://arabroot.io/articles/%D9%83%D9%85-%D8%AA%D9%83%D9%84%D9%81-%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-coding-agents-%D9%81%D9%8A-%D8%A7%D9%84%D8%B3%D9%86%D8%A9/). وفي الحالتين فإن القاعدة واحدة: المحاولة الفاشلة الثانية أغلى من الأولى، والثالثة أغلى من الثانية، ولذلك فإن إيقاف الوكيل بعد محاولتين وبدء جلسة جديدة بطلب أدق ليس صبراً قليلاً، وإنما حساب صحيح.

والجدول التالي يجمع الأرقام كما خرجت من Aider ومن السكربت:

| الخطوة                | المرسل              | المستقبل           | الزمن       | النتيجة                                |
| --------------------- | ------------------- | ------------------ | ----------- | -------------------------------------- |
| التخطيط في وضع ask    | 609 توكنات          | 447                | 139 ثانية   | خطة فيها ثلاثة أسئلة مفيدة وخطوة خاطئة |
| التذكرة مع القرارات B | 1.2 ألف             | 413                | 222 ثانية   | 8 من 8                                 |
| الخطة في طلب واحد C   | 1.3 ألف ثم 3.5 آلاف | 2 ألف ثم 38        | 623 ثانية   | لم يطبق شيء                            |
| الخطوة الأولى في E    | 1.3 ألف             | 322                | 245 ثانية   | تعديل من 11 سطراً بشرط خاطئ            |
| خطوة الاختبارات في E  | من 1.6 إلى 8 آلاف   | 2 ألف في كل محاولة | 7,356 ثانية | ملف لا يعمل وثلاثة commits             |

## الحلقة في فريق: أين تعيش الخطة؟

عندما تعمل وحدك فإن الخطة ملف في مجلد المهمة تحذفه بعد أن تنتهي، أما في الفريق فلها مكان أفضل: وصف طلب الدمج Pull Request. والسبب أن من يراجع طلب الدمج يحتاج أن يعرف ماذا كان المطلوب قبل أن يحكم على الكود، والخطة بعد المراجعة هي بالضبط هذا: القرارات التي اتخذت، والخطوات، ومتى ننتهي. فإذا وضعتها في وصف الطلب فإن المراجع يقارن الفرق بالخطة، وهي طريقة المراجعة التي يوصي بها [توثيق أفضل الممارسات في Claude Code](https://code.claude.com/docs/en/best-practices?ref=arabroot.io) عندما يقترح أن يراجع مراجع مستقل الفرق مقابل ملف المواصفة، ويتحقق أن كل متطلب منفذ وأن الحالات الحدية المذكورة لها اختبارات، ويتجاوز ملاحظات الشكل.

ويحذر التوثيق نفسه من نقطة مهمة في المراجعة: المراجع الذي يطلب منه أن يجد مشاكل سوف يجد شيئاً دائماً، فإذا أصلحت كل ملاحظة فإنك تنتهي بطبقات تجريد Abstraction زائدة واختبارات لحالات لا يمكن أن تحدث. ولذلك فإن المراجعة مقابل الخطة أدق من المراجعة العامة، لأنها تسأل سؤالاً محدداً: هل نفذ ما اتفقنا عليه، ولم يضف ما لم نتفق عليه؟ وشرحنا بقية المراجعة، من قائمة الأخطاء المتكررة في كود الذكاء الاصطناعي إلى البوابات الآلية قبل الدمج، في [مقال مراجعة كود الذكاء الاصطناعي](https://arabroot.io/articles/%D9%85%D8%B1%D8%A7%D8%AC%D8%B9%D8%A9-%D9%83%D9%88%D8%AF-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%AF%D9%88%D9%86-%D8%A7%D9%86-%D8%AA%D8%B5%D8%A8%D8%AD-%D8%B4%D9%83%D9%84%D9%8A%D8%A9/).

وإذا كان الفريق يستعمل أداة واحدة فاكتب طريقة الحلقة في ملف التعليمات المشترك: أين توضع الخطة، وما الأوامر التي تعتبر التحقق، وما اسم الفرع، حتى لا يعيد كل مطور شرحها للوكيل في كل جلسة، كما في [مقال ملف تعليمات المشروع](https://arabroot.io/articles/%D9%85%D9%84%D9%81-%D8%AA%D8%B9%D9%84%D9%8A%D9%85%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%B4%D8%B1%D9%88%D8%B9-agents-md-%D9%88claude-md-%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D9%83%D8%AA%D8%A8-%D9%81%D9%8A%D9%87/).

## ماذا يعلمنا المختبر؟

- **القرارات أهم من الخطوات:** أكبر تحسن في النتيجة جاءت من خمسة أسطر قرارات، من 3 إلى 8 في الطريقة B. وخطوة التخطيط قيمتها أنها تجعلك تكتب هذه الأسطر، لأنها تريك الأسئلة التي لم تفكر فيها.
- **الخطة تريك سوء الفهم وهو رخيص:** اقترح الوكيل تعديل `bookings_for` دون أن يطلبه أحد، فحذفنا السطر من الخطة في ثانية، بدل أن نكتشفه في فرق بعد عشر دقائق.
- **الخطة لا تسأل كل شيء:** نسيت الخطة سؤالين من ثمانية، فمراجعتك للخطة جزء من الخطوة، لا إضافة اختيارية.
- **الخطة كلها في طلب واحد تفسدها:** «نفذ خطوة خطوة» في رسالة واحدة أعطت ردوداً طويلة خرجت عن الخطة، واخترعت ملفات، ولم يطبق منها شيء. والنموذج الكبير لا يصل إلى هذا الحد غالباً، ولكن الميل نفسه موجود: كلما كبر الطلب كبر الفرق وابتعد عما طلبت.
- **الخطوة الواحدة لا تضمن الالتزام:** في الطريقة E عمل الوكيل في الخطوة الأولى ما يخص الخطوة الثانية أيضاً، ورسالة الـ commit وصفت الخطوة الأولى فقط، ولذلك فإن قراءة الفرق بعد كل خطوة جزء من التنفيذ.
- **التحقق قوي بقدر الفحص:** الاختبارات القديمة نجحت في كل الطرق تقريباً، حتى عندما كتب الوكيل الكود في ملف لا يستدعيه أحد. والتحقق الذي يعني شيئاً هو اختبار لكل قرار، ونجاح كل اختبارات القبول في الطريقة B لم يمنع خطأً في حالة لم يكتب لها أحد اختباراً.
- **الفحص الآلي يمسك ما لا يمسكه الوكيل:** في الطريقة E أمسك flake8 خطأ الصياغة Syntax Error في ملف الاختبارات بعد كل محاولة، والوكيل نفسه كان يقول إنه أصلحه.

وقد يتساءل البعض: هل تنطبق هذه النتائج على النماذج الكبيرة التي يستعملها أغلب المطورين في العمل، أم هي مشكلة نموذج من ثلاثة مليارات معامل على معالج عادي؟ والإجابة أن الأرقام نفسها لن تتكرر، فالنموذج الكبير لن يخترع ملف LICENSE لمشروع لا يحتاجه، ولن يدخل في حلقة اختبارات بأسماء متكررة في الغالب. ولكن الأنماط نفسها موجودة في كل النماذج بدرجات أقل: القرار الذي لم تكتبه يقرره النموذج بنفسه، والطلب الكبير يخرج فرقاً أكبر مما طلبت، ورسالة الـ commit تصف النية لا الفعل، والاختبار القديم ينجح مهما تغير الكود الجديد. والفرق أن النموذج الكبير يخطئ في مهام أكبر وبشكل أذكى، فيصعب عليك أن تلاحظ الخطأ، ولذلك فإن الحلقة معه أهم لا أقل. واخترنا النموذج الصغير في المختبر لأنه يظهر هذه الأنماط بوضوح في مهمة من عشرين سطراً، بدل أن نحتاج مشروعاً كاملاً لنراها.

## أخطاء شائعة Common Mistakes

- **أن تتجاوز مراجعة الخطة:** الخطة التي لا يقرؤها إنسان مجرد نص إضافي في السياق، وقد تحمل خطوة خاطئة إلى التنفيذ كما هي.
- **أن تعطي الخطة كلها في طلب واحد:** طلب لكل خطوة، وcommit لكل خطوة، وقراءة الفرق بعد كل واحدة.
- **أن تثق بعبارة «كل الاختبارات نجحت»:** اسأل أي اختبارات، واطلب المخرج، واسأل هل لكل قرار في الخطة اختبار.
- **أن تترك الوكيل يكتب الاختبارات والكود في الطلب نفسه:** الاثنان من الافتراضات نفسها، وراجع الاختبارات قبل الكود.
- **أن تصحح للمرة الثالثة في المحادثة نفسها:** ارجع إلى آخر commit سليم، وابدأ جلسة جديدة بطلب فيه ما تعلمته.
- **أن تتجاهل الملفات الجديدة في الفرق:** الملف الذي لم تطلبه، مثل `calendar.py` في الطريقة A، أول علامة على أن الوكيل فهم شيئاً آخر.
- **أن تترك الوكيل دون حد لطول الرد مع النماذج المحلية:** الرد الذي لا ينتهي يضيع الوقت ويملأ السياق، وشرحنا ذلك في [مقال النماذج المحلية](https://arabroot.io/articles/%D9%88%D9%83%D9%8A%D9%84-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A8%D9%86%D9%85%D9%88%D8%B0%D8%AC-%D9%85%D8%AD%D9%84%D9%8A-%D9%85%D8%B9-ollama-%D9%85%D8%A7%D8%B0%D8%A7-%D8%AA%D8%AA%D9%88%D9%82%D8%B9/).

## قائمة تحقق Checklist لكل مهمة

- **قبل التنفيذ:** خطة مكتوبة فيها الملفات والدوال بالاسم، والخطوات، والقرارات، ومتى ننتهي، وراجعتها وحذفت منها ما لم تطلبه.
- **لكل قرار في الخطة:** اختبار يفحصه، يكتبه الوكيل في خطوة مستقلة وتقرؤه، أو تكتبه أنت قبل التنفيذ.
- **في التنفيذ:** طلب لكل خطوة، والملفات التي تحتاجها الخطوة فقط، وcommit لكل خطوة على فرع منفصل.
- **بعد كل خطوة:** `git diff --stat` أولاً، ثم الفرق، ثم الفحص.
- **في التحقق:** الأمر ومخرجه، لا الادعاء، وفحص في خط CI لا يعتمد على الوكيل.
- **إذا فشل مرتين:** رجوع إلى آخر commit سليم وجلسة جديدة بطلب أفضل.

## تدريب عملي

1. شغل المختبر من مجلد `lab` على جهازك، وغير النموذج إلى أكبر نموذج تتسع له ذاكرتك، وقارن نتيجة الطرق الست بما في الجدول.
2. أضف إلى اختبارات القبول اختباراً للحجز الذي ينتهي عند بداية حجز موجود، وشغل الطريقة B مرة أخرى، ولاحظ هل يكشف خطأ الشرط.
3. خذ تذكرة حقيقية صغيرة من عملك، واطلب من وكيلك خطة في وضع التخطيط، واكتب كم سؤالاً طرحت الخطة لم يكن في التذكرة، وكم خطوة حذفتها.
4. أضف إلى ملف التعليمات في مشروعك أمر الاختبار وأمر الفحص، وراقب هل يشغلهما الوكيل دون أن تطلب.

## الخلاصة

- حلقة العمل مع الوكيل ثلاث خطوات لكل منها ناتج تراجعه: خطة قصيرة، ثم commit صغير لكل خطوة، ثم دليل من أمر يرجع بنجاح أو فشل.
- الخطة يكتب مسودتها الوكيل، ويكتب قراراتها الإنسان، وقيمتها أنها تريك الأسئلة التي لم تخطر لك وسوء الفهم قبل أن يصبح كوداً.
- في المختبر رفعت خمسة أسطر من القرارات النتيجة من 3 إلى 8 من 8، بينما فشلت الخطة الكاملة في طلب واحد في الطريقتين C وD، ولم يطبق منها شيء.
- نفذ خطوة واحدة في كل طلب، واقرأ الفرق بعد كل خطوة، لأن الوكيل قد يتجاوز الخطوة التي طلبتها.
- التحقق قوي بقدر الفحص: الاختبارات القديمة نجحت حتى عندما كتب الوكيل الكود في ملف لا يستدعيه أحد، فاكتب اختباراً لكل قرار.
- الفحص الذي لا يجوز تجاوزه مكانه خارج الوكيل، في خطاف أو خط CI.
- إذا صححت الشيء نفسه مرتين فارجع إلى آخر commit سليم وابدأ جلسة جديدة بطلب أفضل.

وفي المقالات التالية من هذه المرحلة بإذن الله نتعمق في خطوتين من هذه الحلقة: كتابة الاختبارات قبل الكود مع الوكيل، وطريقة إدارة Git مع الوكلاء حتى يبقى الرجوع رخيصاً:

[![](https://arabroot.io/content/images/2026/11/tdd-with-agents-cover-cover.webp)دليلالتطوير بالاختبار أولاً TDD مع وكلاء البرمجةاكتب الاختبارات التي تقول ما هو الصحيح، واقفلها، ثم دع الوكيل يصل إلى الأخضر، مع مختبر يقارن الكود أولاً بالاختبار أولاً ويحكم عليهما باختبارات قبول لم يرها الوكيل.](https://arabroot.io/articles/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1-%D8%A8%D8%A7%D9%84%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1-%D8%A7%D9%88%D9%84%D8%A7-tdd-%D9%85%D8%B9-%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9/)[![](https://arabroot.io/content/images/2026/11/git-hygiene-agents-cover-cover.webp)دليلGit مع وكلاء البرمجة: فروع وWorktrees ورجوع آمنفرع وWorktree لكل مهمة، وcommit صغير برسالة تقول من كتبه، وفحص لا يتجاوزه الوكيل، وطريق معروف للرجوع، مع مختبر حقيقي فيه خطاف لم يعمل وcommit أوقف المشروع وجده git bisect.](https://arabroot.io/articles/git-%D9%85%D8%B9-%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D9%81%D8%B1%D9%88%D8%B9-%D9%88worktrees-%D9%88%D8%B1%D8%AC%D9%88%D8%B9-%D8%A7%D9%85%D9%86/)[![](https://arabroot.io/content/images/2026/11/use-coding-agents-well-cover-cover.webp)دليلكيف تستخدم وكيل البرمجة Coding Agent بفعالية؟عادات يومية تفرق بين من يوفر وقته مع الوكيل ومن يضيعه في إصلاح كوده، مع مختبر يعطي الوكيل الهدف نفسه بأربع صيغ للطلب ويحكم عليها باختبارات لم يرها.](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D8%B3%D8%AA%D8%AE%D8%AF%D9%85-%D9%88%D9%83%D9%8A%D9%84-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-coding-agent-%D8%A8%D9%81%D8%B9%D8%A7%D9%84%D9%8A%D8%A9/)[![](https://arabroot.io/content/images/2026/11/ai-testing-cover-cover.webp)دليلاختبارات يكتبها الذكاء الاصطناعي: متى تثق بها؟أين يساعدك الذكاء الاصطناعي في كتابة الاختبارات وأين يخدعك، ولماذا يبقى قرار ما هو الصحيح بيد الإنسان.](https://arabroot.io/articles/%D8%A7%D8%AA%D9%85%D8%AA%D8%A9-%D8%A7%D9%84%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1%D8%A7%D8%AA-%D8%A8%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A/)

## سجل التحديثات

- 20 نوفمبر 2026: كتابة المقال، وتشغيل المختبر بست طرق بـ Aider 0.86.2 مع Ollama 0.40.13 ونموذج Qwen2.5-Coder 3B على معالج دون بطاقة رسومية، ومراجعة توثيق Claude Code وAider وCline.