---
title: "الجلسة السابعة | AI-Assisted Coding — Professional Engineering Workflow"
aliases:
  - "Session 07 - AI-Assisted Coding"
  - "AI Camp v2 - Session 07"
tags:
  - AI-Camp-v2
  - Systems
  - AI-Assisted-Coding
  - Coding-Agents
  - Code-Review
  - Testing
session: 7
duration: "2.5 hours"
duration_minutes: 150
track: Systems
status: planned
language: ar
project: "Camp Feedback API Feature"
---

# الجلسة السابعة: AI-Assisted Coding — From Autocomplete to Engineering Agents



##  نظرة عامة

تعلّم هذه الجلسة الطالب كيف يستفيد من أدوات **AI-Assisted Coding** ضمن سير عمل هندسي احترافي، مع الحفاظ على **ملكيته للقرارات التقنية والمسؤولية عن الشيفرة الناتجة**.

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

> [!abstract] الهدف الرئيسي
> تحويل الوكيل البرمجي من مجرد مولّد للشيفرة إلى **مساعد هندسي يعمل ضمن مواصفات وحدود واضحة**، دون الاعتماد على نتائجه اعتمادًا أعمى.

##  مخرجات التعلّم

بنهاية الجلسة، يستطيع الطالب:

- التمييز بين **Autocomplete وAI Chat وAgent Mode وCloud Coding Agents**.
- اختيار نمط المساعدة المناسب لحجم المهمة ومخاطرها.
- إعداد تعليمات مشروع واضحة من خلال `AGENTS.md` أو `CLAUDE.md` بحسب الأداة المستخدمة.
- كتابة **Feature Specification** يتضمن المتطلبات ومعايير القبول والقيود.
- تطبيق **Spec-First** و**Test-First** على مهمة صغيرة قابلة للإنجاز.
- مراجعة خطة الوكيل قبل التنفيذ ومراقبة التعديلات التي يجريها.
- كشف المشكلات الشائعة: منطق غير صحيح، حزم مختلقة، اختبارات غير كافية، أو تسريب أسرار.
- فتح **Pull Request** يتضمن اختبارات وتعليقات مراجعة بشرية حقيقية.

---

##  المحاور النظرية

### 1. AI Coding Spectrum — مستويات المساعدة البرمجية

| المستوى | الوظيفة | مسؤولية المطور |
|---|---|---|
| **Autocomplete** | اقتراح إكمالات قصيرة أثناء الكتابة. | التحقق من كل اقتراح وفهم سياقه. |
| **AI Chat** | شرح الشيفرة، الإجابة عن الأسئلة، واقتراح حلول. | مراجعة دقة الشرح وملاءمة الحل. |
| **Agent Mode** | قراءة ملفات متعددة، وتعديلها، وتشغيل أوامر أو اختبارات ضمن الصلاحيات المتاحة. | تحديد الصلاحيات وفحص الخطة والتغييرات والنتائج. |
| **Cloud Coding Agent** | تنفيذ مهمة ضمن بيئة مخصصة، ثم إتاحة النتائج وقد يتضمن سير العمل PR للمراجعة. | مراجعة الـDiff والاختبارات والمخاطر قبل الدمج. |

> [!tip] قاعدة أساسية
> تزداد قيمة المساعدة الآلية مع جودة المتطلبات والسياق. **كلما زادت صلاحيات الأداة، زادت أهمية حدود التنفيذ والمراجعة البشرية**.

### 2. Tool Landscape — الأدوات التي ستُعرض

- **GitHub Copilot:** الإكمال التلقائي، المساعدة داخل بيئات التطوير، وأنماط العمل الوكيلة والمراجعة.
- **Claude Code:** التعامل مع مستودع المشروع عبر أدوات البرمجة، وإعداد التعليمات، والتخطيط قبل التحرير.
- **OpenAI Codex:** تنفيذ مهام برمجية ومراجعة التعديلات، مع إمكانات للعمل محليًا أو في بيئة مخصصة بحسب المسار المستخدم.




### 3. Context Engineering & Project Instructions

- تحديد هدف التعديل والملفات ذات الصلة.
- توضيح معمارية المشروع والمعايير المتفق عليها.
- وضع تعليمات الاختبارات والتوثيق وأسلوب كتابة الشيفرة.
- استخدام ملفات تعليمات مثل `AGENTS.md` و`CLAUDE.md` عندما تدعمها الأداة.
- تقليل الضوضاء في السياق وعدم نسخ كامل المشروع إلى Prompt بلا حاجة.

**عناصر التعليمات الجيدة:**

1. هدف المهمة ومخرجاتها.
2. الملفات والمكونات المتوقع تأثرها.
3. قواعد المشروع وقيوده.
4. حالات الاختبار المطلوبة.
5. معايير التوقف وطلب التوضيح.
6. شكل التقرير النهائي عن التغييرات.

### 4. Spec-First & Test-First Development

**Spec-First:** نكتب ما يجب أن تفعله الميزة قبل طلب تنفيذها.

**Test-First:** نحدد حالات القبول والاختبارات قبل التنفيذ أو بالتوازي معه، ثم نتحقق من أنها تكشف السلوك غير الصحيح.

> [!important] Green Tests Are Not Enough
> نجاح الاختبارات لا يثبت جودة الميزة إذا كانت الاختبارات نفسها لا تغطي المتطلبات المهمة أو أعاد الوكيل تعديلها لتناسب سلوكًا خاطئًا. يجب فحص **المتطلبات والتغييرات والاختبارات معًا**.

### 5. Human Code Review & Safety

- مراجعة الـDiff ملفًا ملفًا وفهم سبب كل تعديل.
- كشف الاعتماديات غير الضرورية أو أسماء الحزم غير الموجودة.
- التحقق من معالجة الأخطاء والحالات الحدية.
- مراجعة صلاحيات الأدوات والأوامر التي ينفذها الوكيل.
- عدم تضمين مفاتيح API أو كلمات المرور أو بيانات العملاء في Prompts أو المستودع.
- تجنب الأوامر المدمرة والتغييرات غير المطلوبة.

---

## 🧪 التطبيق العملي: Camp Feedback API Feature

### سيناريو المشروع

يحتوي Starter Repository على تطبيق **FastAPI** بسيط لمعسكر الذكاء الاصطناعي. المطلوب إضافة ميزة تمكّن الطلاب من تقديم تقييم للجلسة، مع إتاحة ملخص للنتائج.

**مقترح نطاق الميزة:**

- `POST /feedback`: استقبال `session_id` و`rating` (من 1 إلى 5) وتعليق اختياري.
- `GET /feedback/summary`: إعادة عدد التقييمات ومتوسط التقييم لجلسة محددة.
- تحقق من المدخلات ورسائل خطأ واضحة.
- اختبارات للسلوك الصحيح والمدخلات غير الصالحة.

> [!note] تحضير مسبق
> يكون هيكل FastAPI والتشغيل والاختبارات الأساسية مجهزًا قبل الجلسة. لا يطلب من الطلاب تصميم تطبيق كامل أو قاعدة بيانات إنتاجية من الصفر خلال 150 دقيقة.

### المرحلة 1 — Feature Specification

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

### المرحلة 2 — Plan Before Editing

- [ ] تقديم التعليمات والسياق المناسب للوكيل.
- [ ] طلب خطة تنفيذ قبل إجراء التعديلات.
- [ ] مراجعة الملفات التي يقترح تغييرها.
- [ ] استبعاد أي تعديل خارج نطاق الميزة.

### المرحلة 3 — Implementation & Tests

- [ ] تنفيذ التعديلات باستخدام الأداة المختارة.
- [ ] تشغيل الاختبارات القائمة.
- [ ] إنشاء أو تحسين اختبارات قبول الميزة.
- [ ] فحص المدخلات غير الصالحة وحالات الفشل.
- [ ] تشغيل الخدمة وتجربة نقاط النهاية محليًا.

### المرحلة 4 — Review & Pull Request

- [ ] مراجعة `git diff` بالكامل.
- [ ] التحقق من عدم إضافة أسرار أو اعتماديات غير مبررة.
- [ ] كتابة تعليقات مراجعة بشرية على أسطر محددة.
- [ ] إصلاح المشكلات المكتشفة وإعادة الاختبارات.
- [ ] فتح **Pull Request** يتضمن ما أُنجز وكيف اختُبر.

### المرحلة 5 — Compare AI Tools

تنفذ مجموعتان المهمة نفسها باستخدام أداتين مختلفتين إن توفرت الأدوات.

| معيار المقارنة | ما الذي نقيسه؟ |
|---|---|
| **Correctness** | هل طُبقت المتطلبات دون تغيير السلوك القديم؟ |
| **Test Quality** | هل تكشف الاختبارات حالات الخطأ الحقيقية؟ |
| **Scope Discipline** | هل بقي التعديل ضمن الملفات والمتطلبات المطلوبة؟ |
| **Maintainability** | هل الشيفرة واضحة وقابلة للفهم والتطوير؟ |
| **Security** | هل تجنبت التغييرات الأسرار والصلاحيات غير الضرورية؟ |
| **Human Review Effort** | كم مراجعة وتصحيحًا احتاجت النتيجة؟ |

> [!warning] المقارنة ليست حكمًا عامًا على الأدوات
> تجربة واحدة لا تكفي لإعلان «أفضل أداة»؛ تتأثر النتائج بنوع المهمة وجودة التعليمات وإعداد البيئة وخبرة المستخدم.

---

## ⏱️ الجدول الزمني — 150 دقيقة

| الوقت | المدة | النشاط |
|---|---:|---|
| **00:00–00:10** | 10 د | مقدمة وأمثلة عن AI-Assisted Development |
| **00:10–00:25** | 15 د | Autocomplete → Chat → Agents |
| **00:25–00:45** | 20 د | Context Engineering وملفات التعليمات |
| **00:45–01:00** | 15 د | Spec-First وTest-First والمخاطر |
| **01:00–01:10** | 10 د | استراحة |
| **01:10–01:55** | 45 د | Live Build لميزة FastAPI |
| **01:55–02:15** | 20 د | Pair Lab ومقارنة أداتين |
| **02:15–02:25** | 10 د | اختبارات ومراجعة Diff |
| **02:25–02:30** | 5 د | خلاصة وتكليف Pull Request |
| **الإجمالي** | **150 د** | |

## 📦 المخرجات المطلوبة (Deliverables)

- [ ] Feature Specification من صفحة أو فقرة منظمة.
- [ ] تعديلات FastAPI تعمل محليًا.
- [ ] اختبارات تغطي النجاح وبعض حالات الخطأ.
- [ ] `README.md` أو توثيق مختصر يوضح تشغيل الميزة.
- [ ] **Pull Request** ناتج عن عمل الطالب بمساعدة AI.
- [ ] تعليقات مراجعة كتبها الطالب بنفسه.
- [ ] فقرة Reflection توضح ما أصاب فيه الوكيل، وما أخطأ، وما صححه الطالب.

### معايير تقييم مقترحة

| المعيار | الوزن |
|---|---:|
| تحقيق المتطلبات وصحة التنفيذ | 30% |
| جودة الاختبارات والحالات الحدية | 25% |
| المراجعة البشرية واكتشاف المشكلات | 25% |
| وضوح PR والتوثيق | 10% |
| الأمان والانضباط في نطاق التعديل | 10% |

## 🧰 تحضيرات المدرب

- [ ] تجهيز Starter Repository وبيئة تشغيل FastAPI.
- [ ] تجهيز حساب/مسار وصول قانوني لأداة Coding Agent واحدة على الأقل.
- [ ] توفير مهمة واحدة واضحة ومعايير قبول ثابتة.
- [ ] إعداد اختبارات مرجعية لا يراها الطلاب كاملة في البداية.
- [ ] تحضير مثال لتعديل يحتوي خللًا منطقيًا رغم نجاح بعض الاختبارات.
- [ ] التأكد من خلو المستودع من بيانات حساسة وأسرار.
- [ ] توفير بديل مسجل أو لقطات للتجربة عند انقطاع الخدمة.

## 🔗 مراجع رسمية

- [GitHub Copilot — Overview](https://docs.github.com/en/copilot/get-started/about-github-copilot)
- [GitHub Copilot in IDEs](https://docs.github.com/en/copilot/concepts/copilot-surfaces/copilot-in-ides)
- [Claude Code — Best Practices](https://code.claude.com/docs/en/best-practices)
- [Claude Code — Common Workflows](https://code.claude.com/docs/en/common-workflows)
- [OpenAI Codex — Cloud](https://developers.openai.com/codex/cloud)
- [OpenAI Codex — AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md)

---

## 🏁 خلاصة الجلسة

يتعلم الطالب استخدام AI Coding بوصفه جزءًا من **سير عمل هندسي قابل للمراجعة**، يبدأ من متطلبات واضحة وينتهي باختبارات وPull Request وفحص بشري للنتائج.

> [!success] الرسالة الأساسية
> **AI can accelerate implementation, but the engineer remains accountable for requirements, correctness, security, and quality.**
