كود أفضل من الـAI Agent: دليل البرومبتات

الـAI Agent سريع، لكنّه بشكلٍ افتراضيّ يُحسِّن هدفًا واحدًا: أن تعمل الميزة. وفي تطبيقٍ حقيقيّ على الإنتاج، هنا بالضبط تقع الفجوة بين عرضٍ تجريبيّ ونظامٍ يصمد أمام مستخدمين حقيقيين — إذ يختبئ الخطر في الأمان، وسلامة البيانات، والصلاحيات، والتزامن، وفي الـ edge cases التي لم يكتبها أحدٌ في الطلب.

لذلك توقّفتُ عن مطالبة الـAI Agent بأن «يبني الميزة الفلانية»، وصِرتُ أُرفق مع كلّ مهمة مجموعةً من التعليمات الجاهزة تفرض عليه سلوك مهندسٍ محترف. في ما يلي المجموعة التي أستخدمها فعليًا، مُرتَّبةً حسب الغرض. انسخ أيّ قالب، وألصقه مع مهمتك، واستبدل ما بين الأقواس {} بما يخصّ تقنيات مشروعك:

{FRAMEWORK} إطار العمل في الخادم {DB} قاعدة البيانات {FRONTEND LANGUAGES} لغات الواجهة: البُنية والتنسيق والتفاعل {ORM} طبقة الاستعلامات

هذه البرومبتات تصلح لأيّ تطبيق إنتاجيّ — لوحة SaaS، أو أداة داخلية، أو API، أو منصّة. وحين يحتاج البرومبت إلى مثال ملموس أضع واحدًا، لكنّ المبدأ هو المقصود؛ عدِّله ليناسب مجالك. وقد أبقيتُ نصوص البرومبتات بالإنجليزية كما تُكتب عادةً للـAI Agent — انسخها كما هي.

1 · الأمر الأساسي

يوضَع في أعلى كلّ مهمة تقريبًا. يمنع الـAI Agent من إعادة كتابة كودٍ يعمل دون تفكير، ويُلزمه بالفحص أوّلًا ثمّ المراجعة بعده.

Before making changes, inspect the existing implementation: architecture, models, views, templates, {FRONTEND LANGUAGES}, styles, URLs, forms, permissions, and related code.

Do not blindly rewrite working code. Follow the existing architecture and conventions.

Requirements:
- Use {FRAMEWORK} best practices.
- Follow SOLID, DRY, KISS, and separation of concerns.
- Keep business logic out of templates.
- Prefer reusable components / functions / services.
- Use {DB} efficiently; prevent N+1 queries and unnecessary calls.
- Maintain backwards compatibility unless the change explicitly requires otherwise.
- Do not break existing functionality or responsive behavior.
- Keep the code readable, maintainable, and production-ready.

After implementation:
1. Review your own changes.
2. Check edge cases, security, permissions, and validation.
3. Check responsiveness and performance.
4. Test the complete user flow.
5. Fix any issues you find before considering the task complete.

2 · تتبَّع المسار قبل لمس الكود القائم

أكثر برومبت يمنع الضرر. يجعل الـAI Agent يفهم المسار كاملًا قبل أن يغيّر جزءًا منه.

Before modifying this feature, trace the full flow first.

Identify: entry point, URL, view/controller, form/input layer, model,
service/business logic, template, {FRONTEND LANGUAGES}, related permissions,
related APIs, and side effects.

Then make the smallest clean change necessary.
Do not replace large existing sections unless there is a strong architectural reason.

3 · لا تثق بالواجهة الأمامية أبدًا

القاعدة التي تفصل لعبةً عن برمجيةٍ حقيقية. يجب ألّا يتمكّن المستخدم من إرسال role = admin (أو price = 1) فيُصدّقه الخادم.

Treat this as production software. Never trust values sent by the client for anything
with security or business meaning: amounts, prices, quotas, permissions, roles,
ownership, status flags, or record IDs.

Recalculate and validate every sensitive value on the server before acting on it.

4 · مراجعة أمنية

Review this change for security vulnerabilities, including:
- authorization bypass and IDOR (insecure direct object access)
- CSRF, XSS, and injection ({DB} / query injection)
- unsafe file uploads and mass assignment
- privilege escalation and sensitive-data exposure
- insecure redirects and session / authentication problems
- rate-limit abuse

Never trust IDs, amounts, roles, permissions, or ownership from the client.
Recalculate and validate sensitive values on the server.

5 · الصلاحيات وملكية البيانات

ما إن يصبح لتطبيقك أكثر من مستخدم حتى يصير هذا غير قابل للتفاوض — يجب ألّا يصل مستخدمٌ إلى بيانات مستخدمٍ آخر أبدًا. ويزداد الأمر حَرَجًا إن كنت multi-tenant.

Enforce authorization and data ownership on every request.

Every query that touches user- or account-owned data must be scoped to the
currently authenticated principal. A user must never read or modify another
user's (or account's) records, files, settings, or history — not by guessing an
ID, not through a related object, not via any endpoint.

Do not rely on hidden client-side IDs for access control.
Check ownership and permissions on the server for every read, write, update, and delete.

6 · القيم الحسّاسة يحسمها الخادم

Treat every business-critical value as server-authoritative.

Independently compute and validate on the server any value that carries meaning:
amounts and totals, quantities and limits, quotas and usage, entitlements and
plan/role, status and state transitions — before creating or confirming anything.
(For commerce that includes price, discounts, tax, and shipping.)

Never trust a value the client calculated.

7 · التزامن والموارد المحدودة

كثيرًا ما يغفل الـAI Agent عن هذه. يجب ألّا يظفر طلبان بآخر مكانٍ متاح في آنٍ واحد.

Consider race conditions and concurrent requests.

For any limited or one-time resource — a counter, a balance, stock, a single-use
token or coupon, a unique slot, a "run once" job — make sure two simultaneous
requests cannot produce invalid state. Use database transactions, atomic
operations, row-level locking, or unique constraints as appropriate.

Example: two requests must not both claim the last available unit, or redeem the same one-time token twice.

8 · عدم التكرار (idempotency) والنداءات الخارجية

Never treat an operation as done because the client reached a success page.

Confirm the real outcome server-side from the source of truth (the provider's
API/webhook, the job result, the external system). Webhook and callback handlers
must: verify signatures, be idempotent, handle retries and out-of-order delivery
safely, reject invalid events, and never double-apply an effect. Store the
external transaction/event IDs for reconciliation.
(Payments are the classic case: verify with the payment provider, never the browser.)

9 · النماذج والتحقّق

Audit the entire form and validation flow. Validation must exist BOTH
client-side and server-side — requests can bypass the frontend.

For every field: required vs optional, type, format, allowed ranges, business
rules, and input sanitization. Show clear, human-readable errors; never fail
silently. On failure, indicate what is wrong, where, and how to fix it, and
move focus to the first invalid section.

10 · كفاءة قاعدة البيانات

Review database usage as part of this task.

Avoid: queries inside loops, repeated queries, loading whole tables, and
unnecessary saves. Where appropriate, use your {ORM}'s eager-loading
(joins / prefetch), existence checks, column-only selects, bulk insert/update,
pagination, and indexes.

Do not optimize prematurely, but fix obvious scalability problems.

11 · اكتشِف المشكلات الخفيّة

أستخدمه باستمرار. يحوّل مهمةً ضيّقة إلى تنظيفٍ صغيرٍ وآمنٍ للكود المحيط.

Do not stop at the requested change.

While working in this area, inspect closely related code for obvious bugs,
broken edge cases, security issues, UX problems, and data-integrity risks.
Fix issues directly related to this task when it is safe to do so.
Do not refactor unrelated parts of the project.

12 · اجعله يختبر عمله فعلًا

Do not consider the task complete just because the code compiles or the page loads.
Test the feature as a real user.

Test: normal flow, empty inputs, invalid inputs, min/max values, duplicate
submission, refresh, back button, unauthorized user, another user's data, nonexistent
objects, network/API failure, mobile layout, and empty-database state.

Fix the problems you discover.

13 · مراجعة المهندس المحترف الأخيرة

لعلّه المفضّل لديّ لإلحاقه بمهمة كبيرة. يجعل الـAI Agent يُقيّم عمله كما يفعل المُراجِع — ثمّ يُصلحه.

Now perform a senior-engineer review of everything you changed, as if another
developer opened this as a pull request.

Look for: bugs, security holes, authorization mistakes, bad architecture,
duplicated logic, database inefficiencies, missing validation, missing edge
cases, race conditions, broken responsiveness, weak UX, and accessibility issues.

Do not just explain the problems — fix them, then review the result one final time.

ملفٌّ واحد يحكمها جميعًا

إن كان الـAI Agent لديك يدعم ملفّ قواعد — AGENTS.md أو PROJECT_RULES.md أو ملفّ قواعد Cursor أو Claude — فضَع المعيار كاملًا في مكانٍ واحد كي لا تُكرّر نفسك. هذا هو البرومبت الرئيسيّ الذي أُضيفه فعليًا إلى المشروع:

You are working on a production {FRAMEWORK} + {DB} + {FRONTEND LANGUAGES} application.
Operate like a senior software engineer, not a code generator.

Before implementing anything:
- inspect the existing implementation and understand the complete flow
- understand related models, views, templates, {FRONTEND LANGUAGES}, URLs, forms, permissions, and business logic
- follow existing architecture and conventions; reuse existing components when reasonable

Engineering standards: {FRAMEWORK} best practices, SOLID, DRY, KISS, separation
of concerns, clean readable code, reusable architecture, secure-by-default,
server-authoritative business logic.

Never trust the client for security- or business-critical values: amounts, prices,
quotas, permissions, roles, ownership, status flags, or record IDs.
For user- or account-owned resources, always enforce ownership on the server.

Pay special attention to: authentication, authorization, IDOR, CSRF, XSS,
injection, file-upload security, concurrency, transactions, data integrity,
and input validation.

Database: avoid N+1 and queries-in-loops; use eager-loading, pagination, and
indexes when justified; keep migrations production-safe and data-preserving.

Frontend: responsive from mobile to desktop; clean UI/UX; clear validation;
loading / error / success / empty states; prevent duplicate submissions;
accessible and consistent with the design system.

Business logic: compute and validate every authoritative value on the server;
handle concurrent access to shared or limited resources safely; make external
callbacks and retried operations idempotent; never trust a client-reported
"success" — confirm it against the source of truth. (Commerce is one example:
prices, stock, coupons, and payment verification all belong on the server.)

After every implementation: inspect your own diff; test the full flow, invalid
inputs, permissions, access to other users' data, edge cases, and mobile; check
performance, security, and database queries; fix anything you find.

Do not make unnecessary unrelated changes. Do not rewrite working architecture
without a strong reason. Prefer the smallest clean production-quality change.
Before declaring the task complete, review your work as if reviewing a pull
request, and fix anything you would reject.

الجزء الذي يهمّ فعلًا

لا يُبطئ أيٌّ من هذه الـAI Agent بقدرٍ تشعر به؛ إنّها فقط تنقل العمل — المراجعة، أو عُطل الإنتاج في الثانية صباحًا — إلى لحظة كتابة الكود. وإن أخذتَ قليلًا منها فقط، فاجعل هذه غير قابلة للتفاوض: الصلاحيات وملكية البيانات، والقيم التي يحسمها الخادم، والتزامن، وعدم تكرار العمليات (idempotency)، والاختبار الصادق للـ edge cases. هذا هو الحدّ الفاصل بين تطبيقٍ متوسّطٍ بناه الذكاء الاصطناعيّ ونظام إنتاجٍ جادّ. وما بعده يتبعه.