كيفية إعداد 5 وكلاء ذكاء اصطناعي لبناء واجهة برمجة تطبيقات كاملة (من المواصفات إلى الاختبار)

Ashley Innocent

Ashley Innocent

19 مارس 2026

كيفية إعداد 5 وكلاء ذكاء اصطناعي لبناء واجهة برمجة تطبيقات كاملة (من المواصفات إلى الاختبار)

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

توقف عن استخدام مساعد ذكاء اصطناعي عام واحد لكل شيء. قم بإعداد 5 وكلاء متخصصين لبناء واجهة برمجة تطبيقات (API) كاملة: مهندس الواجهة الخلفية (Backend Architect) يصمم النظام، ومحسن قاعدة البيانات (Database Optimizer) يراجع المخطط، ومطور الواجهة الأمامية (Frontend Developer) يبني العميل، ومراجع الكود (Code Reviewer) يتحقق من الأمان، ومدقق الواقع (Reality Checker) يتحقق من الصحة قبل الشحن.

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

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

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

في هذا البرنامج التعليمي، ستقوم بإعداد 5 وكلاء من مجموعة The Agency وتشغيل سير عمل بناء واجهة برمجة تطبيقات (API) كاملة. ستقوم بالدمج مع Apidog لاختبار واجهة برمجة التطبيقات وتوثيقها، مما يضمن التحقق من صحة نقاط النهاية الخاصة بك مقابل مواصفات OpenAPI قبل النشر.

تحميل التطبيق

الوكلاء الخمسة الذين ستستخدمهم

الوكيل القسم المسؤولية
مهندس الواجهة الخلفية الهندسة تصميم واجهة برمجة التطبيقات (API)، مخطط قاعدة البيانات، المصادقة
محسن قاعدة البيانات الهندسة توصيات الفهرسة، تحسين الاستعلامات
مطور الواجهة الأمامية الهندسة مكونات React، عميل واجهة برمجة التطبيقات، إدارة الحالة
مدقق الكود الهندسة تدقيق الأمان، أمان الأنواع، معالجة الأخطاء
مدقق الواقع الاختبار التحقق المستند إلى الأدلة، إثبات لقطة الشاشة

تثبيت الوكلاء:

# استنساخ مستودع The Agency
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# نسخ الوكلاء إلى Claude Code
cp engineering/engineering-backend-architect.md ~/.claude/agents/
cp engineering/engineering-database-optimizer.md ~/.claude/agents/
cp engineering/engineering-frontend-developer.md ~/.claude/agents/
cp engineering/engineering-code-reviewer.md ~/.claude/agents/
cp testing/testing-reality-checker.md ~/.claude/agents/

الخطوة 1: مهندس الواجهة الخلفية يصمم النظام

ابدأ جلسة Claude Code جديدة:

تفعيل وضع مهندس الواجهة الخلفية.

صمم واجهة برمجة تطبيقات REST لمنصة تجارة إلكترونية تحتوي على:
- مصادقة المستخدم (JWT مع رموز التحديث)
- كتالوج المنتجات مع الفئات والتصفية
- إدارة عربة التسوق
- معالجة الطلبات مع تتبع الحالة
- دمج خطاف دفع الويب (webhook)

المخرجات:
1. مواصفات OpenAPI 3.0
2. مخطط قاعدة بيانات PostgreSQL مع العلاقات
3. هيكل مجلد المشروع (Express.js + TypeScript)
4. رسم بياني لتدفق المصادقة

المخرجات المتوقعة:

سيقوم مهندس الواجهة الخلفية بإخراج:

مواصفات OpenAPI (جزئية):

openapi: 3.0.0
info:
  title: E-commerce API
  version: 1.0.0
paths:
  /auth/login:
    post:
      summary: User login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
      responses:
        '200':
          description: JWT tokens
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken: { type: string }
                  refreshToken: { type: string }

مخطط قاعدة البيانات:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL CHECK (price >= 0),
    category_id UUID REFERENCES categories(id),
    inventory_count INTEGER DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    total_amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(50) DEFAULT 'pending',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

هيكل المجلدات:

src/
├── controllers/
│   ├── auth.controller.ts
│   ├── products.controller.ts
│   └── orders.controller.ts
├── middleware/
│   ├── auth.middleware.ts
│   └── validation.middleware.ts
├── routes/
│   ├── auth.routes.ts
│   ├── products.routes.ts
│   └── orders.routes.ts
├── services/
│   ├── auth.service.ts
│   ├── products.service.ts
│   └── orders.service.ts
├── models/
│   ├── User.ts
│   ├── Product.ts
│   └── Order.ts
└── index.ts

احفظ المخرجات. ستقوم بتمريرها إلى الوكيل التالي.

الخطوة 2: محسن قاعدة البيانات يراجع المخطط

افتح جلسة جديدة:

تفعيل وضع محسن قاعدة البيانات.

راجع مخطط PostgreSQL هذا لواجهة برمجة تطبيقات للتجارة الإلكترونية:

[الصق المخطط من الخطوة 1]

تحقق من:
1. الفهارس المفقودة على المفاتيح الخارجية والأعمدة التي يتم الاستعلام عنها بشكل متكرر
2. أداء الاستعلام على بحث المنتجات (الاسم، الفئة، النطاق السعري)
3. القيود الصحيحة لسلامة البيانات
4. الجداول المفقودة لميزات التجارة الإلكترونية الشائعة (التقييمات، قوائم الأمنيات)
5. أنماط الحذف الناعم (soft delete) لمسارات التدقيق

أخرج عبارات ALTER TABLE محددة وتعريفات جداول جديدة.

المخرجات المتوقعة:

توصيات الفهرسة:

-- إضافة فهارس على المفاتيح الخارجية
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);

-- إضافة فهرس لبحث المنتج
CREATE INDEX idx_products_name_search ON products USING gin(to_tsvector('english', name));
CREATE INDEX idx_products_price ON products(price) WHERE inventory_count > 0;

-- إضافة فهرس مركب لتصفية الفئات
CREATE INDEX idx_products_category_price ON products(category_id, price);

الجداول المفقودة:

CREATE TABLE reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    product_id UUID REFERENCES products(id),
    user_id UUID REFERENCES users(id),
    rating INTEGER CHECK (rating >= 1 AND rating <= 5),
    comment TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(product_id, user_id)
);

CREATE TABLE cart_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    product_id UUID REFERENCES products(id),
    quantity INTEGER DEFAULT 1 CHECK (quantity > 0),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, product_id)
);

القيود المراد إضافتها:

-- التحقق من تنسيق البريد الإلكتروني
ALTER TABLE users ADD CONSTRAINT chk_email_format
    CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$');

-- عمود الحذف الناعم
ALTER TABLE products ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE NULL;
CREATE INDEX idx_products_deleted_at ON products(deleted_at) WHERE deleted_at IS NULL;

طبق هذه التوصيات على مخططك.

الخطوة 3: مطور الواجهة الأمامية يبني العميل

افتح جلسة جديدة:

تفعيل وضع مطور الواجهة الأمامية.

أنشئ لوحة تحكم React لواجهة برمجة تطبيقات التجارة الإلكترونية هذه:

[الصق مواصفات OpenAPI من الخطوة 1]

المتطلبات:
- TypeScript مع الوضع الصارم
- React Query لإدارة حالة الخادم
- قائمة المنتجات مع الفلاتر (الفئة، النطاق السعري، البحث)
- عربة تسوق مع تحديثات في الوقت الفعلي
- سجل الطلبات مع تتبع الحالة
- معالجة الأخطاء وحالات التحميل بشكل صحيح
- تصميم متجاوب (للهاتف، الجهاز اللوحي، سطح المكتب)

المخرجات:
1. إعداد المشروع (Vite + React + TypeScript)
2. عميل واجهة برمجة تطبيقات مع خطافات React Query
3. المكونات الأساسية (ProductList, ProductCard, Cart, OrderHistory)
4. حدود الأخطاء وهياكل التحميل

المخرجات المتوقعة:

عميل واجهة برمجة التطبيقات:

// src/lib/api-client.ts
import { QueryClient, useQuery, useMutation } from '@tanstack/react-query';

const API_BASE = 'http://localhost:3000/api';

async function fetcher<T>(endpoint: string, options?: RequestInit): Promise<T> {
  const response = await fetch(`${API_BASE}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Request failed');
  }

  return response.json();
}

export function useProducts(filters?: ProductFilters) {
  const params = new URLSearchParams(filters as Record<string, string>);
  return useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetcher<Product[]>(`/products?${params}`),
  });
}

export function useAddToCart() {
  return useMutation({
    mutationFn: (item: CartItem) =>
      fetcher<CartItem>('/cart', {
        method: 'POST',
        body: JSON.stringify(item),
      }),
  });
}

مكون قائمة المنتجات:

// src/components/ProductList.tsx
import { useProducts } from '@/lib/api-client';
import { ProductCard } from './ProductCard';
import { FilterSidebar } from './FilterSidebar';
import { Skeleton } from './ui/skeleton';

export function ProductList() {
  const [filters, setFilters] = useState<ProductFilters>({});
  const { data: products, isLoading, error } = useProducts(filters);

  if (error) {
    return <Alert variant="destructive">{error.message}</Alert>;
  }

  return (
    <div className="flex gap-4">
      <FilterSidebar filters={filters} onFilterChange={setFilters} />
      <div className="flex-1 grid grid-cols-1 md:grid-cols-3 gap-4">
        {isLoading ? (
          Array.from({ length: 6 }).map((_, i) => (
            <Skeleton key={i} className="h-64" />
          ))
        ) : products?.length === 0 ? (
          <EmptyState message="No products found" />
        ) : (
          products?.map(product => (
            <ProductCard key={product.id} product={product} />
          ))
        )}
      </div>
    </div>
  );
}

حدود الأخطاء:

// src/components/ErrorBoundary.tsx
export class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error: Error | null }
> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="p-4 bg-red-50 border border-red-200 rounded">
          <h2 className="text-lg font-semibold text-red-800">Something went wrong</h2>
          <p className="text-red-600">{this.state.error?.message}</p>
          <Button onClick={() => window.location.reload()} className="mt-2">
            Reload
          </Button>
        </div>
      );
    }

    return this.props.children;
  }
}

الخطوة 4: مدقق الكود يتحقق من كل شيء

افتح جلسة جديدة:

تفعيل وضع مدقق الكود.

راجع قاعدة الكود هذه بحثًا عن:

1. الثغرات الأمنية:
   - مخاطر حقن SQL
   - ثغرات XSS
   - حماية CSRF
   - إمكانيات تجاوز المصادقة

2. التوافق مع الوضع الصارم لـ TypeScript:
   - لا يوجد "any" ضمني
   - تعريفات أنواع صحيحة
   - معالجة القيم الخالية/غير المعرفة

3. فجوات معالجة الأخطاء:
   - رفض الوعود غير الملتقطة
   - كتل try/catch مفقودة
   - الأعطال الصامتة

[الصق الكود من الخطوات 1-3]

أخرج تقريرًا بتقييمات الخطورة (حرجة، عالية، متوسطة، منخفضة) وإصلاحات محددة.

المخرجات المتوقعة:

تقرير الأمان:

## مشكلات حرجة

### 1. حقن SQL في بحث المنتجات
**الموقع:** `src/controllers/products.controller.ts:24`
**المشكلة:** إدخال المستخدم مدمج مباشرة في استعلام SQL
```typescript
// ضعيف
const query = `SELECT * FROM products WHERE name LIKE '%${search}%'`;

الإصلاح: استخدم استعلامات معلمة (parameterized queries)

const query = 'SELECT * FROM products WHERE name LIKE $1';
await db.query(query, [`%${search}%`]);

مشكلات عالية الخطورة

2. حماية CSRF مفقودة

الموقع: src/index.tsالمشكلة: لا يوجد وسيط CSRF للعمليات التي تغير الحالة الإصلاح: أضف وسيط csurf

import csrf from 'csurf';
app.use(csrf({ cookie: true }));

مشكلات متوسطة الخطورة

3. وجود "any" ضمني في استجابة واجهة برمجة التطبيقات

الموقع: src/lib/api-client.ts:8المشكلة: نوع any عام لدالة fetcher الإصلاح: أضف قيود أنواع مناسبة

async function fetcher<T extends Record<string, unknown>>(
  endpoint: string,
  options?: RequestInit
): Promise<T> { ... }

تقرير أمان الأنواع:

## انتهاكات TypeScript

1. `products.controller.ts:45` - تعليق توضيحي لنوع الإرجاع مفقود
2. `auth.middleware.ts:12` - "any" ضمني في كتلة الالتقاط
3. `orders.service.ts:78` - كائن قد يكون غير معرف

قم بتشغيل `tsc --noEmit` لرؤية القائمة الكاملة. أصلح قبل النشر.

طبق الإصلاحات قبل المتابعة.

الخطوة 5: مدقق الواقع يتحقق من الصحة قبل الشحن

افتح جلسة جديدة:

تفعيل وضع مدقق الواقع.

واجهة برمجة تطبيقات التجارة الإلكترونية هذه جاهزة للتحقق من الإنتاج.

قم بتشغيل عملية التحقق الواقعي الإلزامي:

1. تحقق من وجود الملفات
2. قارن الميزات المزعومة بالكود الفعلي
3. اطلب دليل لقطة شاشة من اختبارات Playwright
4. راجع test-results.json لمقاييس الأداء

عنوان URL للمشروع: http://localhost:3000
نتائج الاختبار: ./public/qa-screenshots/test-results.json

المخرجات: اجتياز (PASS) أو يحتاج إلى عمل (NEEDS WORK) مع مشكلات حظر محددة.

المخرجات المتوقعة:

أوامر التحقق الواقعي:

# 1. تحقق من وجود الملفات
ls -la src/controllers/ src/services/ src/routes/
ls -la src/components/ src/lib/

# 2. قارن الميزات المزعومة
grep -r "jwt\|jsonwebtoken" . --include="*.ts" || echo "NO JWT FOUND"
grep -r "bcrypt\|argon2" . --include="*.ts" || echo "NO PASSWORD HASHING FOUND"
grep -r "rateLimit\|express-rate-limit" . --include="*.ts" || echo "NO RATE LIMITING FOUND"

# 3. تشغيل التقاط لقطات الشاشة بواسطة Playwright
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

# 4. مراجعة نتائج الاختبار
cat public/qa-screenshots/test-results.json

تقرير التحقق:

## نتائج التحقق الواقعي

### التحقق من الملفات: اجتياز (PASS)
- جميع ملفات المتحكمات موجودة
- جميع ملفات المكونات موجودة

### التحقق من الميزات: يحتاج إلى عمل (NEEDS WORK)
- مصادقة JWT: موجودة
- تجزئة كلمة المرور: موجودة
- تحديد المعدل: غير موجود (معطل)

### إثبات لقطة الشاشة: يحتاج إلى عمل (NEEDS WORK)
- تخطيط سطح المكتب: اجتياز (PASS)
- تخطيط الجهاز اللوحي: اجتياز (PASS)
- تخطيط الهاتف المحمول: فشل (شبكة المنتجات معطلة عند 375 بكسل)

### مقاييس الأداء: يحتاج إلى عمل (NEEDS WORK)
- متوسط وقت التحميل: 2.3 ثانية (الهدف: <1 ثانية)
- أخطاء الكونسول: 3 (الهدف: 0)
- طلبات الشبكة الفاشلة: 1 (الهدف: 0)

## الحالة النهائية: يحتاج إلى عمل (NEEDS WORK)

### المشكلات المعطلة:
1. لم يتم تطبيق تحديد المعدل
2. تخطيط الهاتف المحمول معطل في قائمة المنتجات
3. 3 أخطاء كونسول تحتاج إلى إصلاح
4. وقت التحميل يتجاوز الهدف المحدد بـ 1 ثانية

### غير معطلة:
- أضف هياكل التحميل إلى سجل الطلبات
- تحسين رسائل الخطأ

أصلح المشكلات المعطلة وأعد تشغيل مدقق الواقع.

ملخص سير العمل

┌─────────────────────────────────────────────────────────────────┐
│  مهندس الواجهة الخلفية                                           │
│  → مواصفات OpenAPI، مخطط قاعدة البيانات، هيكل المجلدات         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  محسن قاعدة البيانات                                             │
│  → توصيات الفهرسة، الجداول المفقودة، القيود                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  مطور الواجهة الأمامية                                           │
│  → مكونات React، عميل واجهة برمجة التطبيقات، معالجة الأخطاء     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  مدقق الكود                                                      │
│  → تدقيق الأمان، أمان الأنواع، فجوات معالجة الأخطاء             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  مدقق الواقع                                                     │
│  → التحقق المستند إلى الأدلة، إثبات لقطة الشاشة، اجتياز/فشل     │
└─────────────────────────────────────────────────────────────────┘

تنفيذ الوكلاء بالتوازي (متقدم)

قم بتشغيل الوكلاء بالتوازي لتقليل الوقت الإجمالي:

# الطرفية 1: مهندس الواجهة الخلفية
claude "تفعيل وضع مهندس الواجهة الخلفية. صمم واجهة برمجة تطبيقات للتجارة الإلكترونية..."

# الطرفية 2: محسن قاعدة البيانات (انتظر مخرجات المخطط)
claude "تفعيل وضع محسن قاعدة البيانات. راجع هذا المخطط..."

# الطرفية 3: مطور الواجهة الأمامية (انتظر مواصفات واجهة برمجة التطبيقات)
claude "تفعيل وضع مطور الواجهة الأمامية. أنشئ لوحة تحكم React..."

# الطرفية 4: مدقق الكود (انتظر الكود)
claude "تفعيل وضع مدقق الكود. راجع قاعدة الكود هذه..."

# جميع الطرفيات: مدقق الواقع (التحقق النهائي)
claude "تفعيل وضع مدقق الواقع. قم بتشغيل عمليات التحقق الإلزامية..."

مع التنفيذ المتوازي، يمكنك إكمال سير العمل في 2-4 ساعات بدلاً من 6-8 ساعات.

ما بنيته

المخرجات الوكيل المخرجات
تصميم واجهة برمجة التطبيقات مهندس الواجهة الخلفية مواصفات OpenAPI، مخطط قاعدة البيانات، هيكل المجلدات
تحسين المخطط محسن قاعدة البيانات توصيات الفهرسة، جداول إضافية، قيود
الواجهة الأمامية مطور الواجهة الأمامية مكونات React، عميل واجهة برمجة التطبيقات، حدود الأخطاء
تدقيق الأمان مدقق الكود تقرير الثغرات الأمنية، إصلاحات أمان الأنواع
التحقق النهائي مدقق الواقع إثبات لقطة الشاشة، شهادة اجتياز/فشل (PASS/FAIL)

الخطوات التالية

خمسة وكلاء متخصصين. واجهة برمجة تطبيقات كاملة واحدة. لا توجيهات عامة.

هذه هي قوة التخصص. كل وكيل يعرف مجاله. كل وكيل لديه قوائم تحقق. كل وكيل يقدم مخرجات محددة.

دورك الآن: اختر مشروعًا، وفعّل الوكلاء، واشحن أسرع.

الدروس المستفادة الرئيسية


الأسئلة الشائعة

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات