Written with AI assistance from the source video. The video is the authority.
Log in to leave a comment
No posts yet
عند ربط وكيل الذكاء الاصطناعي (AI Agent) ببيئة تطوير فعلية، سرعان ما تظهر قيوده وسلبياته. فهو يميل إلى الإفراط في استخدام نمط المصنع (Factory Pattern) بشكل آلي دون فهم سياق المجال (Domain Context)، أو يستمر في توليد دواءل مساعدة (Utility Functions) عديمة الفائدة بشكل لا نهائي. وفقًا لتقرير تحليل التعديلات (Commits) لعام 2024 الصادر عن GitClear، والذي شمل 623 مليون سطر كود، فإن انتشار أدوات الذكاء الاصطناعي أدى إلى زيادة تكرار الكود بنسبة 81%، بينما انخفضت نسبة إعادات الهيكلة (Refactoring) لتنظيف الكود القديم من 25% إلى أقل من 10%. وبسبب انحياز الحداثة (Recency Bias) في نافذة السياق (Context Window)، يهرب الوكيل باستمرار نحو الأنماط القياسية الأكثر شيوعًا في بيانات التدريب لتجنب المخاطر. لذلك، يجب كبح سلوكيات الوكيل الخاطئة عبر تحديد قواعد المعمارية ومنطق المزامنة المشترك بين الفريق بشكل صريح في ملفات السياق.
للتحكم في الإرشادات المتضاربة بين أدوات التطوير المختلفة، يجب أولاً وضع ملف AGENTS.md في جذر المشروع ليكون بمثابة المصدر الوحيد للحقيقة (Single Source of Truth). تقرأ أدوات مثل Cursor وClaude Code هذه القواعد. لقد تم الاستغناء عن ملف .cursorrules المنفرد منذ فترة طويلة؛ وبدلاً من ذلك، يُفضل تقسيم القواعد إلى ملفات MDC داخل دليل .cursor/rules/، وفي بيئة Claude Code يتم استدعاء @AGENTS.md داخل CLAUDE.md لمنع تسرب القواعد وتجاوزها.
apps/api/src/common/dto.services/shared/uow.عندما يتجاوز إجمالي طول السياق 800 سطر (ما يعادل 2,000 رمز تقريبًا)، يبدأ الوكيل في تجاهل القيود المكتوبة في الأعلى. لذلك، يجب أن يحتفظ ملف AGENTS.md فقط بالمحظورات الأساسية التي لا يمكن التنازل عنها، بينما تنقل السجلات التفصيلية لقرارات المعمارية البرمجية إلى الدليل docs/context/.
AGENTS.md في جذر المشروع وتدوين قيود مثل منع الواجهات ذات التنفيذ المنفرد ومنع الكتل الدفاعية لـ try-catch.globs) وقيود YAML Frontmatter في الملف .cursor/rules/backend-constraints.mdc.@AGENTS.md إلى ملف CLAUDE.md لمواءمة البيئة.تختبئ الفخاخ خلف الكود الذي يبدو مثاليًا والذي يكتبه الوكيل. أظهرت دراسة أجرتها Veracode عام 2024 أن 45% من الكود المقترح بواسطة الذكاء الاصطناعي يحتوي على ثغرات أمنية بمستوى OWASP Top 10. كما يميل الوكيل إلى إخفاء الأخطاء عبر إحاطة المنطق المعرض للفشل بكتل try-catch وإرجاع كائنات فارغة أو null بنسبة أعلى بـ 47% مقارنة بما يكتبه البشر. فضلاً عن ذلك، تتكرر مشكلات إغفال القفل التفاؤلي (Optimistic Locking) في عمليات Read-Modify-Write أو مشكلة N+1 الناجمة عن الاستعلام المتكرر لقاعدة البيانات داخل الحلقات التكرارية.
| مجال التحقق | عناصر التحقق التفصيلية | الأنماط الخطرة وفخاخ الوكيل | معايير حظر الدمج (Merge Block) |
|---|---|---|---|
| الثغرات الأمنية | استخدام Parameterized Query، عزلة المستأجرين (Tenant Isolation)، التحقق من الحزم غير المصرح بها | حقن SQL القائم على ربط النصوص، استدعاء حزم غير معتمدة ناتجة عن الهلوسة | حظر الدمج عند إغفال التحقق من المدخلات أو إضافة تبعيات خارجية مجهولة المصدر |
| اختناقات الأداء | التحميل الكسول في ORM، الحلقات المتداخلة في Hot Path، الفهارس (Indexes) | استعلامات تتنقل بين الكيانات الفردية داخل الحلقة، تصفية الجداول الكاملة في الذاكرة | حظر الدمج عند وجود استدعاءات لقاعدة البيانات أو API خارجي داخل الحلقة، أو عند عدم تطبيق الترقيم (Paging) |
| سلامة الأنواع (Type Safety) | التحقق الصارم من الأنواع (Strict Type)، معالجة استثناءات الحدود، التحكم في التزامن | الإفراط في استخدام as any، إخفاء الأخطاء عبر Empty Catch Blocks |
حظر الدمج عند وجود any أو التحويل القسري العشوائي بـ as، وحظر كتل Catch الخالية من تسجيل الأخطاء (Logging) |
غالباً ما تقتصر أكواد الاختبار التي يكتبها الوكيل على نسخ أسلوب التنفيذ وتكراره، وهي اختبارات تحصيل حاصل لا تكشف العيوب البرمجية الحقيقية في منطق الأعمال. يجب تطبيق قاعدة صارمة مفادها: "إذا كانت هناك دالة مساعدة موجودة بالفعل، يتم حذف الدالة الجديدة التي أنشأها الوكيل وإعادة استخدام الكود الحالي".
any في قالب طلبات السحب (PR Template).as any أو await داخل الحلقات التكرارية.عند إدخال منطق تسوية معقد أو معالجة طلبات قائمة على آلة الحالة (State Machine) في موجه واحد (Single Prompt)، يتأثر الوكيل وينحصر في حلقة استدعاء الأدوات أو يخرج كودًا ظاهريًا فارغًا. يعود ذلك إلى تشابك ترتيب توزيع الرموز (Tokens) عند محاولة معالجة تصميم المخطط، وواجهات API، ومعالجة الاستثناءات، وقواعد الأعمال دفعة واحدة.
[الرحلة 1: نمذجة البيانات] -> إنشاء كيانات DB ومخططات Zod │ ▼ (تمرير المخرجات كسياق) [الرحلة 2: تعريف الواجهة] -> تعريف DTOs للـ API، والأخطاء المخصصة، وتوقيعات الخدمات │ ▼ (تمرير مخرجات المرحلتين 1+2 كسياق) [الرحلة 3: تنفيذ منطق الأعمال] -> إتمام المعاملات، وانتقال الحالات، والتحكم في التزامن
تبادل هذه العمليات يدويًا أمر مرهق للغاية. من الأفضل كتابة نص برمجي مؤتمت عبر CLI (scripts/agent-decomposed-build.ts) لربط مخرجات الخطوة السابقة لتصبح السياق المدخل للخطوة التالية.
`typescript
import { execSync } from 'child_process';
import * as fs from 'fs';
interface TaskPipeline {
featureName: string;
stage1Prompt: string;
stage2Prompt: string;
stage3Prompt: string;
}
async function runDecomposedAgentPipeline(pipeline: TaskPipeline) {
console.log([Stage 1] Executing Data Modeling for ${pipeline.featureName}...);
const stage1Output = execSync(claude --print "${pipeline.stage1Prompt}").toString();
fs.writeFileSync(./tmp/${pipeline.featureName}_stage1.ts, stage1Output);
console.log([Stage 2] Executing Interface Definition...);
const stage2InputPrompt = ${pipeline.stage2Prompt}\n\nContext Models:\n${stage1Output};
const stage2Output = execSync(claude --print "${stage2InputPrompt}").toString();
fs.writeFileSync(./tmp/${pipeline.featureName}_stage2.ts, stage2Output);
console.log([Stage 3] Executing Business Logic Implementation...);
const stage3InputPrompt = ${pipeline.stage3Prompt}\n\nContext Models:\n${stage1Output}\n\nContext Contracts:\n${stage2Output};
const stage3Output = execSync(claude --print "${stage3InputPrompt}").toString();
fs.writeFileSync(./src/services/${pipeline.featureName}.service.ts, stage3Output);
console.log([Pipeline Complete] Business logic generated cleanly without cognitive stagnation.);
}
`
scripts/agent-decomposed-build.ts لربط المخرجات السابقة بالسياق للموجه التالي.كلما زاد استخدام أدوات البرمجة بالذكاء الاصطناعي، تراكمت "أكواد للكتابة فقط" تفقد المبررات والأسباب التي بنيت عليها. الكود الذي لا يسجل الموازنات (Trade-offs) المعمارية يتحول لاحقًا إلى عبء يصعب على البشر التعامل معه. يجب فرض كتابة تعليقات قياسية بأسلوب TSDoc داخل الكود المصدر في ملف AGENTS.md عند توليد الوكيل للبرمجيات.
`typescript
/**
ولمنع التضارب في إعدادات الوكيل بين المطورين، يجب رفع ملف AGENTS.md كـ "مصدر واحد للحقيقة"، وتشغيل نص برمجي للمزامنة (tools/sync-agent-rules.ts) مع CLAUDE.md و.cursor/rules/global.mdc عند إجراء Commit.
`typescript
import * as fs from 'fs';
import * as path from 'path';
const AGENTS_MD_PATH = path.join(__dirname, '../AGENTS.md');
const CLAUDE_MD_PATH = path.join(__dirname, '../CLAUDE.md');
const CURSOR_RULE_PATH = path.join(__dirname, '../.cursor/rules/global.mdc');
function syncRules() {
if (!fs.existsSync(AGENTS_MD_PATH)) {
console.error('Error: AGENTS.md does not exist.');
process.exit(1);
}
const baseRules = fs.readFileSync(AGENTS_MD_PATH, 'utf-8');
const claudeContent = # AUTOMATICALLY GENERATED FROM AGENTS.md - DO NOT EDIT DIRECTLY\n\n${baseRules};
fs.writeFileSync(CLAUDE_MD_PATH, claudeContent);
const mdcHeader = ---\ndescription: Global Agent Rule Sync\nglobs: **/*\nalwaysApply: true\n---\n\n;
fs.writeFileSync(CURSOR_RULE_PATH, ${mdcHeader}${baseRules});
console.log('Successfully synchronized AGENTS.md to CLAUDE.md and Cursor MDC rules.');
}
syncRules();
`