أساسيات الهندسة الوكيلة: دورة مكثفة في 45 دقيقة

8 مفاهيم، 80% من الاستخدام الحقيقي

المتطلب السابق: الدورة المكثفة في البرمجة الوكيلة. تلك الصفحة تعلّم الأدوات: Claude Code وOpenCode وplan mode وCLAUDE.md والمهارات وMCP والhooks. هذه الصفحة تعلّم الانضباط الذي تستخدم به تلك الأدوات. الأدوات بلا انضباط تنتج vibe code؛ والانضباط بلا أدوات يبقى نظرية.

"الكود ليس رخيصاً. الكود السيئ أصبح أغلى من أي وقت مضى." Matt Pocock

"Vibe coding يرفع الحد الأدنى لما يستطيع الجميع فعله في البرمجيات. أما agentic engineering فتحافظ على معيار الجودة الذي كان موجوداً في البرمجيات الاحترافية." Andrej Karpathy

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

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

يعلمك هذا الفصل خط سير يجعل هذه الكفاءة قابلة للتكرار: فكرة -> grilling -> PRD -> قضايا -> تنفيذ -> مراجعة -> QA. يعمل الخط عبر مهارات صغيرة قابلة للتركيب، ويظل صالحاً في Claude Code وOpenCode. الأداة متغير؛ الطريقة ثابتة.

بنهاية الفصل ستستطيع:

1. تحديد موقع عملك على طيف vibe coding -> agentic engineering واختيار مستوى الانضباط المناسب للمخاطر.
2. تشخيص أنماط الفشل الستة في البرمجة بالذكاء الاصطناعي وتطبيق علاج كل نمط.
3. تشغيل دورة كاملة: grill -> PRD -> vertical-slice issues -> AFK implementation.
4. كتابة SKILL.md لا يحمّله الوكيل إلا عند الحاجة.
5. إعادة تشكيل قاعدة كود من وحدات سطحية إلى وحدات عميقة حتى تعمل حلقات التغذية الراجعة مع الوكيل.
6. استخدام مفردات العمل: smart zone وdumb zone وclearing وcompaction وhandoff وAFK وtracer bullet وjagged intelligence.

لمحة عن خط السير

#	المرحلة	ما يحدث	المدخل -> النتيجة	المهارة	القسم
1	فكرة -> تصور مشترك	يسأل الوكيل أسئلة سقراطية حتى يتضح التصميم	رغبة -> مفهوم تصميم	grill-me	§6.1
2	تصور -> وجهة	تتحول المحادثة إلى PRD	محادثة -> PRD	to-prd	§6.2
3	PRD -> backlog	ينقسم PRD إلى قضايا رأسية صغيرة	PRD -> tracer-bullet issues	to-issues	§6.3
4	قضية -> شريحة	تنفذ شريحة واحدة بطريقة test-first	issue -> diff قابل للمراجعة	tdd	§6.4
5	شرائح -> backlog فارغ	تعمل حلقة AFK داخل sandbox حتى تنهي القضايا	issues -> PRs	orchestrator	§6.5
6	diff -> قرار	يقرأ الإنسان الفرق ويشغل QA	PR -> merge أو issue جديدة	حكم بشري	§6.6
7	صحة قاعدة الكود	يعثر النظام على وحدات سطحية ويقترح تعميقها	codebase -> RFC	improve-codebase-architecture	§7.4

المراحل 1 إلى 3 هي وردية النهار: الإنسان حاضر في الحلقة. المرحلتان 4 و5 هما وردية الليل: يعمل الوكيل في sandbox. المرحلة 6 تعود إلى الإنسان. المرحلة 7 عادة أسبوعية تعيد مشكلات البنية إلى backlog.

إذا كنت جديداً في البرمجة.

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

1. من Vibe Coding إلى الهندسة الوكيلة

1.1 Software 3.0: نموذج حوسبة جديد

Software 1.0 هو الكود الذي يكتبه الإنسان صراحة. Software 2.0 هو الأوزان التي يتعلمها نموذج من البيانات. Software 3.0 هو طبقة تعليمات وسياق وأدوات تجعل النموذج يكتب أو يشغل أجزاء من البرنامج بالنيابة عنك. هذا لا يلغي الهندسة؛ بل ينقل جزءاً من الهندسة إلى تصميم السياق والواجهات والقيود.

في Software 3.0، لم تعد تسأل فقط: "هل كتبت الدالة؟" بل تسأل أيضاً: "هل صممت مساحة عمل يستطيع الوكيل أن يفهمها؟ هل وضعت أسماء وحدوداً تجعل القرار الصحيح هو القرار السهل؟ هل يستطيع مراجع منفصل أن يفهم ما فعله الوكيل من diff والاختبارات؟"

1.2 Vibe Coding يرفع الأرضية؛ والهندسة الوكيلة تحفظ السقف

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

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

2. ثلاثة قيود يرثها كل وكيل برمجة

2.1 المنطقة الذكية والمنطقة الغبية

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

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

2.2 مشكلة Memento

الوكيل لا يملك ذاكرة بشرية مستمرة. يملك محادثة، ملفات، وربما مخزناً خارجياً. إذا كان القرار مهماً، فاكتبه في مكان دائم: docs/decisions/، AGENTS.md، issue، أو test. ما لا يكتب يصبح ضجيجاً يختفي عند /clear أو compaction.

2.3 الذكاء المتعرج

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

3. أنماط الفشل الستة في البرمجة بالذكاء الاصطناعي

الفشل 1: "الوكيل لم يفعل ما أردته."

السبب غالباً ليس غباء النموذج، بل غموض الوجهة. العلاج: استخدم grill-me قبل التنفيذ، واكتب مفهوم تصميم واضحاً، وحوّل المحادثة إلى PRD صغير.

الفشل 2: "الوكيل كثير الكلام."

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

الفشل 3: "الكود لا يعمل."

هذا فشل تحقق. العلاج: TDD، وتشغيل الاختبارات محلياً، ورفض الملخصات بلا أدلة. لا تقبل "يجب أن يعمل"؛ اطلب الأمر الذي شغله والنتيجة التي ظهرت.

الفشل 4: "بنينا كرة طين."

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

الفشل 5: "عقلي لا يواكب ما يحدث."

التنفيذ أسرع من فهمك. العلاج: شرائح رأسية صغيرة، commits صغيرة، handoff notes، ومراجع منفصل. لا تسمح للوكيل أن يفتح عشر جبهات ثم يطلب منك مراجعة رواية كاملة.

الفشل 6: "أراجع كوداً أكثر مما أبني."

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

4. سير العمل من البداية إلى النهاية

4.1 نموذج وردية النهار ووردية الليل

النهار للقرارات: تعريف المشكلة، تضييق النطاق، اختيار الواجهة، وقراءة diff. الليل للتنفيذ المتكرر داخل sandbox: قضية واحدة، اختبار، تنفيذ، commit، ثم القضية التالية. لا تخلطهما. إذا بدأ الوكيل يقرر الوجهة أثناء AFK، فقد خرج من منطق الهندسة إلى التخمين.

4.2 حدود "المواصفات إلى الكود"

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

4.3 الشرائح الرأسية وTracer Bullets

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

5. المهارات كعملية مشفرة

5.1 ما المهارة، وما ليست عليه

المهارة ليست prompt محفوظاً فقط. إنها مجلد يحتوي SKILL.md وربما أمثلة أو سكربتات أو مراجع. قيمتها أنها تشفر طريقة عمل قابلة لإعادة الاستخدام: كيف تسأل، كيف تتحقق، ما الذي لا تفعله، ومتى تتوقف.

5.2 أين تعيش المهارات

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

5.3 تشريح SKILL.md

---
name: tdd
description: Use when implementing one issue with red-green-refactor.
---

# TDD

1. Read the issue and identify the interface.
2. Write the failing test first.
3. Implement the smallest code that passes.
4. Refactor without changing behavior.
5. Report the exact command and result.

الملف الجيد يجيب عن ثلاثة أسئلة: متى تستخدم المهارة؟ ما الخطوات؟ ما الدليل المقبول على الانتهاء؟

5.4 المبادئ اليومية الخمسة

المبدأ	المهارة المناسبة
لا تبدأ بتخمين الهدف	grill-me
حوّل الكلام إلى وجهة مكتوبة	to-prd
قسّم العمل إلى شرائح	to-issues
نفذ بشريحة واختبار	tdd
حسّن البنية بوعي	improve-codebase-architecture

تحميل المهارات يعتمد على اتباع النموذج للتعليمات

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

6. خط السير عملياً

6.1 المرحلة 1: شواء الفكرة

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

Use grill-me. I want to add lightweight gamification to the course platform.
Do not propose an implementation yet. Ask questions until the design concept is clear.

6.2 المرحلة 2: من المحادثة إلى PRD

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

# PRD: Course Platform Gamification

## Problem Statement
Learners need visible progress signals without turning the course into a game.

## Solution
Award points for completion events and show a compact progress surface.

## Out of Scope
Leaderboards, social competition, and paid rewards.

6.3 المرحلة 3: من PRD إلى قضايا رأسية

to-issues لا يقسم العمل إلى "backend ثم frontend". يقسمه إلى شرائح رأسية: كل قضية تضيف سلوكاً صغيراً قابلاً للمراجعة. القضية الجيدة تذكر الملفات المحتملة، معيار القبول، وأمر التحقق.

6.4 المرحلة 4: التنفيذ بأسلوب TDD على شريحة واحدة

لا تطلب من الوكيل "نفذ PRD". اطلب "نفذ القضية 3 فقط، باستخدام tdd". الواجهة أهم من التفاصيل.

# gamification/service.py - interface sketch
class GamificationService:
    def award_points(self, student_id: str, reason: str, amount: int) -> None: ...
    def total_points(self, student_id: str) -> int: ...

export interface PointAward {
  studentId: string;
  reason: string;
  amount: number;
}

export interface PointEventStore {
  append(event: PointAward): Promise<void>;
  totalFor(studentId: string): Promise<number>;
}

6.5 المرحلة 5: حلقة AFK

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

# ralph.sh - shape only
while has_open_issues; do
  issue="$(pick_next_issue)"
  create_sandbox "$issue"
  run_agent_with_tdd "$issue"
  run_tests
  commit_or_report_failure
done

النسخة المتوازية تستخدم orchestrator في TypeScript أو Python، لكنها تحافظ على القاعدة نفسها: كل عامل يملك sandbox وقضية واحدة ومخرجاً قابلاً للمراجعة.

6.6 المرحلة 6: مراجعة الإنسان وQA

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

7. مبادئ البنية لقواعد كود صديقة للوكلاء

7.1 الوحدات العميقة بدلاً من الوحدات السطحية

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

7.2 اختبر عند الواجهة

إذا اختبرت كل دالة صغيرة، ستخاف من إعادة البناء. اختبر العقد الذي يهم المستهلك. هذا يمنح الوكيل حرية تغيير الداخل مع الحفاظ على السلوك.

7.3 صمم الواجهة، وفوّض التنفيذ

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

7.4 مهارة improve-codebase-architecture

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

8. مفردات العمل

المصطلح	المعنى العملي
smart zone	المنطقة التي يعمل فيها الوكيل جيداً بسبب وضوح السياق والاختبارات
dumb zone	منطقة التخمين: سياق زائد، هدف غامض، أو بنية مشوشة
clearing	تنظيف السياق قبل بدء جلسة جديدة
compaction	ضغط المحادثة الطويلة حتى لا تتحول إلى ضجيج
handoff	مستند ينقل الحالة من جلسة إلى أخرى
AFK	تشغيل الوكيل بعيداً عنك ضمن حدود واضحة
tracer bullet	شريحة صغيرة تثبت المسار من البداية إلى النهاية
jagged intelligence	قدرة قوية في مواضع وفشل مفاجئ في مواضع أخرى

9. تمارين عملية

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

تمرين 2: اكتب شريحة رأسية كـ tracer bullet. اختر ميزة غير مكتملة، واكتب أصغر قصة تعبر النظام كله. نفذها تحت tdd. إذا لم تنته في جلسة واحدة، فهي كبيرة.

تمرين 3: عمّق وحدة. شغل improve-codebase-architecture على repo تعرفه. اختر مرشحاً واحداً، وارسم واجهته الجديدة قبل التنفيذ. قارن عدد الرموز العامة القديمة بالجديدة؛ إذا لم ينخفض السطح، فالمقترح ليس تعميقاً حقيقياً.

قائمة تحقق يومية:

• هل بدأت بـ /clear؟
• هل استخدمت grill-me لأي تغيير غير بسيط؟
• هل القضايا شرائح رأسية لا مراحل أفقية؟
• هل كل شريحة تمر عبر tdd؟
• هل تعمل AFK داخل sandbox؟
• هل المراجع جلسة منفصلة عن المنفذ؟
• هل قرأت diff لا الملخص؟

10. الخاتمة: المبرمج الاستراتيجي

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

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

الجملة التي تستحق أن تحملها معك: "يمكنك تفويض التفكير، لكن لا يمكنك تفويض الفهم." الوكيل يكتب ويبحث ويجرب. ما يبقى لك هو فهم سبب بناء النظام، ومن يعتمد عليه، وما الذي يجب ألا يفعله أبداً. بلا هذا الفهم، لا يملك الوكيل وجهة.

قراءات إضافية

• Matt Pocock، Software Fundamentals Matter More Than Ever.
• Matt Pocock، Full Walkthrough: Workflow for AI Coding.
• Matt Pocock، Dictionary of AI Coding.
• Andrej Karpathy، From Vibe Coding to Agentic Engineering.
• Boris Cherny، Why Coding Is Solved, and What Comes Next.
• John Ousterhout، A Philosophy of Software Design.
• David Thomas وAndrew Hunt، The Pragmatic Programmer.
• Eric Evans، Domain-Driven Design.
• Kent Beck، Extreme Programming Explained.

المهارات المرافقة لهذا الفصل

• grill-me: مقابلة سقراطية تنتج مفهوم التصميم.
• grill-with-docs: grilling يكتب CONTEXT.md وADRs.
• to-prd: تحويل المحادثة إلى PRD.
• to-issues: تقسيم PRD إلى قضايا tracer-bullet.
• tdd: red-green-refactor، شريحة واحدة في كل مرة.
• improve-codebase-architecture: العثور على الوحدات السطحية وكتابة RFC للتعميق.