ما هو ملف DESIGN.md لوكلاء البرمجة؟

وكلاء البرمجة واثقون وسريعون، ولكنهم يفتقرون إلى المعرفة المعمارية حول قاعدة بياناتك البرمجية حتى تخبرهم بخلاف ذلك. امنح Claude Code أو Codex تذكرة غامضة وسيكتبان بسعادة شيفرة برمجية قابلة للتجميع، وتجتاز اختبارًا سريعًا، وتنتهك بهدوء الحدود بين طبقة النطاق (domain layer) وطبقة HTTP الخاصة بك. لم يقرأ الوكيل مستندات التصميم الخاصة بك. لقد قرأ الملفات التي تمكن من رؤيتها، وطابق الأنماط، وخمن. ملف DESIGN.md يحل مشكلة التخمين عن طريق تدوين نيتك المعمارية في المكان الوحيد الذي ينظر إليه الوكيل دائمًا: المستودع نفسه.

ملخص سريع

DESIGN.md هو ملف مستودع تقليدي مجتمعي يسجل النوايا المعمارية لقاعدة بيانات برمجية، والقيود، وقرارات التصميم بتنسيق Markdown بسيط، بحيث يقوم وكلاء البرمجة (Claude Code, Codex, Cursor) بتوليد شيفرة برمجية تتناسب مع النظام بدلاً من مقاومته. إنه يجيب عن سؤال "لماذا تتخذ الشيفرة البرمجية هذا الشكل؟"، بينما يجيب AGENTS.md عن سؤال "كيف أقوم بالبناء والاختبار؟".

مقدمة

هذا هو نمط الفشل الذي يواجهه كل فريق يتبنى وكلاء البرمجة في غضون أسبوع واحد. تطلب من وكيل إضافة نقطة نهاية للاسترداد إلى خدمة المدفوعات. يقوم بإرجاع معالج (handler) يعمل ويدعو قاعدة البيانات مباشرة من وحدة التحكم (controller)، ويتجاهل خطأ البوابة (gateway error)، ويخترع نوعًا جديدًا للمال لأنه لم يلاحظ أنك تمتلك واحدًا بالفعل. الفروقات نظيفة. والاختبارات ناجحة. ولكنه خاطئ أيضًا بثلاث طرق لا يمكن اكتشافها إلا من قبل مراجع (reviewer) يعرف البنية المعمارية. الوكيل ليس سيئًا في البرمجة؛ ولكنه أعمى عن القرارات التي تعيش في ذهنك، أو في صفحة على Notion، أو في سلسلة محادثات Slack من ثمانية أشهر مضت.

DESIGN.md هو الحل الذي اتفق عليه عدد متزايد من الفرق. إنه ملف Markdown واحد، ملتزم في جذر المستودع (repo root)، يخبر أي وكيل بالحقائق الأساسية حول نظامك: قواعد الطبقات، الثوابت التي يجب ألا تُكسر أبدًا، الأنماط التي اخترتها عن قصد، وتلك التي رفضتها. إنه ليس مواصفات بائع ولا توجد لجنة تملكها؛ إنه تقليد، بنفس طريقة ARCHITECTURE.md وCONTRIBUTING.md كتقاليد. ولكنه يتوافق بشكل طبيعي مع ملفات التعليمات الخاصة بالأدوات التي يقرأها الوكلاء بالفعل، وبالنسبة لأعمال API والخلفية (backend)، فهو أحد أكثر المستندات فعالية يمكنك كتابتها.

ما هو DESIGN.md بالفعل

DESIGN.md هو سجل نص عادي لـ سبب ظهور شيفرتك البرمجية بهذا الشكل. ليس ما تفعله (هذا هو README)، ولا كيفية تشغيله (هذا هو AGENTS.md)، بل هو المنطق الذي يشرحه مهندس كبير لموظف جديد في اليوم الأول قبل السماح له بلمس أي شيء مهم.

فكر في المحادثات التي لا توجد في أي ملف. "نحن لا نستدعي بوابة الدفع من مسار الطلب؛ كل شيء يمر عبر جدول الصندوق الصادر (outbox table) لأن البوابة تتعطل تحت الضغط." "المال دائمًا هو عدد صحيح من الوحدات الصغرى (السنتات)؛ لقد حظرنا الأرقام العشرية بعد حادثة التقريب." "تجميعة Account هي المسؤولة عن تعديلات الرصيد؛ لا يوجد شيء آخر يكتب إلى دفتر الأستاذ." هذه قرارات تصميم. إنها غير مرئية للوكيل الذي يقرأ الشيفرة المصدرية، لأن المصدر يظهر نتيجة القرار، وليس القرار أو منطقه. يمكن للوكيل أن يرى أن Account.debit() موجودة. ولكنه لا يستطيع أن يرى أنك تعمدت جعلها المسار الوحيد للكتابة، لذلك سيضيف مسارًا ثانيًا بكل سرور.

هذا التقليد له جذور في ممارسات أقدم وراسخة. نمط ARCHITECTURE.md (الذي شاع بفضل مقال أليكس كلادوف الذي يُستشهد به على نطاق واسع) يجادل بأن المستودع يجب أن يحتوي على خريطة عالية المستوى لقاعدة الشيفرة البرمجية تشرح الهيكل والثوابت دون محاولة البقاء متزامنة سطرًا بسطر مع الشيفرة. سجلات قرارات البنية المعمارية (ADRs) تلتقط القرارات الفردية ومنطقها بمرور الوقت. DESIGN.md هو ما تحصل عليه عندما تكتب هذا النوع من المستندات لجمهور يشمل وكيل برمجة: مقتضب، تصريحي، موجه نحو القرار، وموجود في المكان الذي سيحمله الوكيل بالفعل.

خاصيتان تجعلانه يعمل. إنه في المستودع، لذلك يقرأه الوكيل بنفس الأدوات التي يقرأ بها الشيفرة؛ لا تحتاج إلى مكون إضافي (plugin) أو استدعاء API. وهو يتعلق بالنية، لذلك يبقى مفيدًا حتى مع تحرك الملفات. أعد تسمية حزمة وستتلف لقطات شاشة README الخاصة بك؛ قاعدة "منطق النطاق لا يستورد أبدًا إطار عمل الويب" لا تزال صحيحة.

DESIGN.md مقابل AGENTS.md مقابل CLAUDE.md مقابل README

تتداخل هذه الملفات بما يكفي لإرباك الناس وتختلف بما يكفي ليكون دمجها في ملف واحد خطأً. النسخة المختصرة: README للمستخدمين الجدد، AGENTS.md هو العقد التشغيلي للوكلاء، CLAUDE.md هو ملف التعليمات الخاص بـ Claude، وDESIGN.md هو المنطق المعماري الذي يستفيد منه الجميع.

AGENTS.md هو الآن تنسيق حقيقي ومعتمد على نطاق واسع؛ يصفه مشروع agents.md بأنه "تنسيق بسيط ومفتوح لتوجيه وكلاء البرمجة"، ويُستخدم عبر عشرات الآلاف من المشاريع ويُشرف عليه تحت مظلة مؤسسة Agentic AI التابعة لمؤسسة لينكس (Linux Foundation). وظيفته تشغيلية: خطوات البناء، أوامر الاختبار، أسلوب الشيفرة، اتفاقيات الالتزام، الأشياء التي تخبرها لزميل جديد لإبقائه قادرًا على العمل. وفقًا لوثائق ذاكرة Claude Code من Anthropic، يلعب CLAUDE.md نفس الدور الإرشادي لـ Claude على وجه التحديد؛ حتى أن الوثائق توصي بأنه إذا كان لديك بالفعل AGENTS.md، فيجب عليك إنشاء CLAUDE.md يستورده باستخدام @AGENTS.md بحيث تقرأ كلتا الأداتين مصدرًا واحدًا للحقيقة.

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

العلاقة تكاملية وليست تنافسية. إعداد نظيف لبيئة Claude + Codex يبدو كالتالي: README.md للبشر؛ AGENTS.md واحد يحتوي على البناء/الاختبار/النمط؛ CLAUDE.md الذي هو مجرد @AGENTS.md بالإضافة إلى سطرين خاصين بـ Claude فقط؛ وDESIGN.md الذي يحمل البنية المعمارية، مرتبطًا من AGENTS.md بحيث يقوم كل وكيل بتحميله عند الطلب. لا تكرار، كل ملف له وظيفة واحدة. إذا كنت ترغب في جولة أعمق حول هيكلة سياق Claude عبر هذه الملفات، فإن سير عمل Claude Code يستعرض نموذج الذاكرة عمليًا.

ما يجب وضعه في DESIGN.md (مع قالب)

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

غطِ هذه النقاط:

• شكل النظام: الطبقات أو الوحدات والاتجاه الذي تتدفق فيه التبعيات. جملة واحدة لكل حد.
• الثوابت: الأشياء التي يجب أن تكون صحيحة دائمًا. اذكرها كحقائق مطلقة. "الأرصدة لا تصبح سالبة أبدًا خارج السحب على المكشوف المصرح به." "كل استدعاء خارجي يكون متساوي المفعول (idempotent) بمفتاح الطلب."
• القرارات الرئيسية ومنطقها: الخيارات التي تبدو عشوائية حتى تعرف السبب. قم بتضمين لماذا؛ المنطق هو ما يمنع الوكيل من "إصلاحها".
• البدائل المرفوضة: ما لم تفعله عمدًا، حتى لا يقترحه الوكيل كفكرة جديدة. يمنع هذا القسم وحده فئة كبيرة من الاقتراحات السيئة.
• قواعد البيانات والنطاق: تمثيل المال، معالجة الوقت/المناطق الزمنية، المعرفات، الحذف الناعم (soft-delete)، تعدد المستأجرين (multi-tenancy).
• مصدر الحقيقة لعقد API: أين توجد مواصفات OpenAPI والقاعدة التي تجعلها موثوقة على الأنواع المكتوبة يدويًا.
• أين تذهب الشيفرة الجديدة: خريطة قصيرة "إذا كنت تضيف X، فإنه ينتمي إلى Y" بحيث تتوقف الوكلاء عن تشتيت المنطق.
• خارج النطاق / لا تلمس: الملفات المولدة، الوحدات القديمة قيد الترحيل، أي شيء يجب على الوكيل تركه وشأنه.

إليك قالب كامل، مكتوب لخدمة API واقعية للمدفوعات. انسخه، احذف ما لا ينطبق، واملأ البقية.

# DESIGN.md: خدمة واجهة برمجة تطبيقات المدفوعات

يسجل هذا الملف النية المعمارية والقرارات التي تقف وراءها.
اقرأ هذا قبل إنشاء أو تعديل الشيفرة. إذا تعارض أي تغيير مع قاعدة هنا،
توقف وقم بالإشارة إليه بدلاً من تجاوزها.

## شكل النظام

طبقي، التبعيات تشير إلى الداخل فقط:

  http (المعالجات، DTOs)  ->  app (حالات الاستخدام)  ->  domain (الكيانات،
  الثوابت)  <-  infra (قاعدة البيانات، عملاء البوابة)

- لا يحتوي `domain/` على أي استيرادات من `http/`، `app/`، أو أي إطار عمل.
- ينفذ `infra/` الواجهات المعلنة في `domain/` أو `app/`.
- لا يلمس `http/` قاعدة البيانات أو بوابة الدفع مباشرة أبدًا.
  إنه يستدعي حالة استخدام في `app/`.

## الثوابت (يجب أن تكون صحيحة دائمًا)

- قيد دفتر الأستاذ غير قابل للتعديل بمجرد كتابته. التصحيحات هي قيود تعويضية
  جديدة، وليست تحديثات أو عمليات حذف أبدًا.
- رصيد الحساب مشتق من قيود دفتر الأستاذ، ولا يتم تخزينه كحقل
  قابل للتعديل يمكن للشيفرة تعيينه مباشرة.
- المال هو عدد صحيح من الوحدات الصغرى (سنتات) بالإضافة إلى رمز عملة ISO-4217.
  ليس رقمًا عشريًا أبدًا. لا تخلط العملات أبدًا في عملية واحدة.
- كل استدعاء لبوابة دفع خارجية يكون متساوي المفعول (idempotent)، ومفتاح بواسطة
  `idempotency_key`. يجب ألا تؤدي عمليات إعادة المحاولة إلى رسوم مضاعفة.
- الأرصدة لا تصبح سالبة أبدًا ما لم تسمح بذلك سياسة سحب على المكشوف
  `OverdraftPolicy` صريحة لذلك الحساب.

## القرارات الرئيسية والمنطق

- **نمط الصندوق الصادر (Outbox pattern) لاستدعاءات البوابة.** تكتب المعالجات صف
  نوايا في نفس معاملة قاعدة البيانات كتغيير العمل، ثم يقوم عامل
  باستدعاء البوابة. المنطق: البوابة تتعطل تحت الضغط؛
  القيام بذلك مباشرة جعل زمن استجابة الطلب ومعالجة الفشل غير مملوكة.
  لا تستدعي البوابة من معالج الطلب.
- **مسار كتابة واحد لكل تجميعة.** فقط `Account.post_entry()`
  يكتب في دفتر الأستاذ. المنطق: مسار كتابة ثانٍ تسبب في
  انحراف الرصيد في مارس 2025. أضف سلوكًا جديدًا كطرق على
  التجميعة، وليس استعلامات جديدة.
- **توليد الأحداث (Event sourcing) لدفتر الأستاذ فقط.** بقية النظام هو
  CRUD. المنطق: نحتاج إلى مسار تدقيق مثالي للمال ولا شيء آخر،
  وكان توليد الأحداث الكامل مكلفًا جدًا في أماكن أخرى.

## البدائل المرفوضة (لا تعيد إدخالها)

- التحميل الكسول (lazy-loading) لـ ORM عبر التجميعات؛ تسبب في N+1s وحدود معاملات غير واضحة.
  تعيد المستودعات تجميعات محملة بالكامل.
- تخزين الرصيد كعمود يتم تحديثه في مكانه؛ انظر حادثة انحراف الرصيد.
  الرصيد مشتق دائمًا.
- مكتبة `Money` عامة مسحوبة من السجل؛ لدينا مكتبتنا الخاصة
  `domain/money.py`؛ استخدمها.
- Webhooks متزامنة للتجار من مسار الطلب؛ إنها
  تعطل وتفشل بصمت. استخدم قائمة انتظار الإشعارات.

## قواعد البيانات والنطاق

- جميع الطوابع الزمنية هي UTC، مخزنة كـ timestamptz، ومُنسقة بتنسيق RFC 3339
  عند الحافة. لا تعبر أوقات وتواريخ غير واضحة حدود الدالة.
- المعرفات هي ULIDs يتم إنشاؤها في طبقة التطبيق، وليست زيادة تلقائية في قاعدة البيانات أبدًا.
- لا يتم استخدام الحذف الناعم (Soft delete). تكون السجلات إما نشطة أو منقولة إلى
  جدول أرشيف بواسطة حالة استخدام صريحة.
- تعدد المستأجرين (Multi-tenant): كل استعلام محدد بنطاق `tenant_id`. طريقة المستودع
  بدون نطاق مستأجر هي خطأ.

## مصدر الحقيقة لعقد API

- مواصفات OpenAPI 3.1 في `api/openapi.yaml` هي الموثوقة.
  أنواع الطلبات/الاستجابات مولدة منها؛ لا تعدل يدويًا
  الأنواع المولدة في `http/generated/`.
- نقاط النهاية الجديدة أو المتغيرة: قم بتحديث `api/openapi.yaml` أولاً، ثم
  أعد التوليد، ثم نفذ. تم تصميم ومراجعة المواصفات في
  Apidog قبل تغييرات الشيفرة.
- تتبع استجابات الخطأ RFC 9457 (problem+json). استخدم
  الدالة المساعدة المشتركة `problem()`؛ لا تخترع أشكال أخطاء مخصصة.

## أين تذهب الشيفرة الجديدة

- نقطة نهاية جديدة: توجيه في `http/routes/`، DTO في `http/dto/`،
  حالة استخدام في `app/usecases/`، منطق النطاق في `domain/`.
- تكامل خارجي جديد: عميل في `infra/clients/`، واجهة
  في `app/ports/`.
- اهتمام شامل (المصادقة، التسجيل، التساوي المفعول): middleware في
  `http/middleware/`، لا يكون أبدًا ضمنيًا في المعالجات.

## خارج النطاق / لا تلمس

- `http/generated/`: يُعاد توليده من OpenAPI، وتُفقد التعديلات.
- `legacy/billing_v1/`: مجمد، قيد الترحيل. لا تقم بتوسيعه.
- `migrations/`: لا تعدل أبدًا ترحيلًا مطبقًا؛ أضف واحدًا جديدًا.

## عند الشك

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

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

كيف يستهلك وكلاء البرمجة DESIGN.md بالفعل

لا يمتلك الوكلاء محللاً خاصًا لـ DESIGN.md. إنهم يستهلكونه بنفس الطريقة التي يستهلكون بها أي ملف: عن طريق قراءته بأدوات الملفات الخاصة بهم والتعامل مع المحتويات كسياق. لذا فإن آليات تحميله مهمة، وتختلف قليلاً حسب الأداة.

النمط الموثوق به هو الإشارة إلى DESIGN.md من ملف التعليمات الذي يحمله كل وكيل بالفعل عند بدء التشغيل. بالنسبة لـ Claude Code، هذا هو CLAUDE.md؛ تصف وثائق الذاكرة بنية استيراد @path حيث يقوم @DESIGN.md بتوسيع الملف في السياق عند بدء الجلسة. بالنسبة لبيئة AGENTS.md، تضيف سطرًا في AGENTS.md يشير إليه ("قواعد البنية والتصميم: راجع DESIGN.md؛ اقرأه قبل التغييرات الهيكلية"). سيلتقط الوكلاء الذين يتجولون في شجرة الدليل أقرب AGENTS.md، ويرون المؤشر، ويسحبون DESIGN.md عندما يلامس العمل البنية المعمارية. في كلتا الحالتين لا تقوم بتكرار المحتوى؛ أنت تحافظ على الملف التشغيلي القصير قصيرًا وتسمح للملف العميق بأن يكون عميقًا.

ثلاث ملاحظات عملية من كيفية تصرف هذه الأدوات:

أولاً، يتعامل الوكيل مع الملف كسياق، وليس كقواعد مفروضة. وثائق Claude Code صريحة بأن محتوى CLAUDE.md هو إرشادات يحاول النموذج اتباعها، وليس قيدًا صارمًا. وينطبق الشيء نفسه على أي شيء تشير إليه منه. لهذا السبب يصيغ القالب كل شيء كحقائق مطلقة قابلة للاختبار ويضيف تعليمات صريحة "عند الشك"؛ فالنصوص الغامضة يتم تجاهلها تحت الضغط، والقواعد الواضحة يتم اتباعها غالبًا.

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

ثالثًا، يغير الملف اقتصاديات المراجعة، وليس فقط التوليد. حتى عندما يتجاهله الوكيل جزئيًا، يمكن للمراجع الإشارة إلى القاعدة المخترقة ويقوم الوكيل بإصلاحها في جولة واحدة ("هذا يكسر قاعدة مسار الكتابة الواحدة في DESIGN.md"). حلقة التغذية الراجعة هذه، التي ترسي التصحيح في القرار المكتوب، هي حيث يكمن الكثير من القيمة الحقيقية. تعتمد الفرق التي تبني أدوات وكيلها الخاص على هذا بالضبط؛ انظر بناء Claude Code الخاص بك لمعرفة كيفية ربط هذه الحلقة في التدفقات الذاتية.

الأنماط الخاطئة وكيفية منعه من التلف

أسرع طريقة لجعل DESIGN.md بلا قيمة هي كتابته كصفحة ويكي. ملف التصميم الفاسد أسوأ من عدم وجوده، لأن الوكلاء والبشر يثقون به ويضللون بسببه. تجنب هذه الأمور.

إعادة صياغة الشيفرة. "فئة UserService تتعامل مع المستخدمين" لا تخبر الوكيل شيئًا لا يستطيع قراءته من user_service.py. إذا كانت الجملة صحيحة بمجرد قراءة الملف، فاحذفها. احتفظ فقط بما لا تستطيع الشيفرة إخبارك به: المنطق، الثوابت، المسارات المرفوضة.

زحف البرامج التعليمية. الإرشادات التفصيلية خطوة بخطوة حول "كيفية إضافة ميزة" تنتمي إلى CONTRIBUTING.md أو مهارة، وليست هنا. في اللحظة التي يحتوي فيها DESIGN.md على أوامر shell ومقتطفات نسخ ولصق، يكون هذا المستند خاطئًا وسيتعفن بسرعة الأدوات.

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

لا مالك، لا محفز للمراجعة. ملف تصميم لا يتحمل أحد مسؤوليته يتغير بمرور ربع سنة. اربطه بمحفز: راجع DESIGN.md في أي طلب سحب (PR) يضيف وحدة، يغير حدود طبقة، أو يقدم تبعية خارجية جديدة. ضع تلك القاعدة في قالب طلب السحب. تضيف بعض الفرق عنصر قائمة تحقق، "هل يغير هذا قرارًا في DESIGN.md؟ إذا كان كذلك، فحدثه في نفس طلب السحب."

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

التناقض مع ملفات التعليمات الأخرى. إذا قال AGENTS.md شيئًا واحدًا عن معالجة الأخطاء وقال DESIGN.md شيئًا آخر، يختار الوكلاء واحدًا عشوائيًا. احتفظ بالقواعد التشغيلية في AGENTS.md / CLAUDE.md والقواعد المعمارية في DESIGN.md، ولا تدعها تتداخل. عندما يجب أن يشير أحدهما إلى الآخر، فإن أحدهما يشير إلى الآخر؛ لا يؤكدان كلاهما نفس الحقيقة.

DESIGN.md الصحي هو قصير، كثيف، تصريحي، له مالك، ويتم مراجعته بناءً على محفز. إذا كان ملفك طويلاً، وسرديًا، وتم لمسه آخر مرة قبل عام، فإن الوكلاء يقرأون خيالًا.

DESIGN.md لقواعد بيانات API والخلفية

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

ضع هذه الأمور الخاصة بـ API في DESIGN.md وسترتفع جودة مخرجات الوكيل في تذاكر الخلفية:

العقد هو مصدر الحقيقة، واذكر مكانه. اذكر بوضوح أن مواصفات OpenAPI هي الموثوقة وأن الأنواع المولدة لا يجب تعديلها يدويًا. يحب الوكلاء "التعديل المساعد" لنوع مولد لجعل البناء ينجح؛ سطر واحد في DESIGN.md يوقف ذلك. أشر إلى مسار ملف المواصفات. إذا صممت العقد أولاً في Apidog وقمت بتصدير مستند OpenAPI إلى المستودع، فيمكن لـ DESIGN.md الخاص بك تسمية هذا الملف كشيء يجب أن تتوافق معه كل نقطة نهاية، وسيكون للوكيل هدف واضح. يتم تغطية الحجة لتصميم العقد قبل الشيفرة في تصميم واجهات برمجة التطبيقات لوكلاء الذكاء الاصطناعي؛ فالعقد الذي يركز على التصميم أولاً هو بالضبط ما يجعل المعالجات المولدة بواسطة الوكلاء آمنة للقبول.

حدود المعاملات والاتساق. أين تبدأ المعاملة وأين تنتهي؟ ما المسموح به بداخلها؟ "الاستدعاءات الخارجية لا تحدث أبدًا داخل معاملة قاعدة بيانات؛ استخدم الصندوق الصادر (outbox)." يعود الوكلاء إلى الاستدعاء المباشر الساذج في كل مرة ما لم يحظر الملف ذلك.

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

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

نطاق المصادقة والتأجير. "كل استعلام محدد بنطاق المستأجر (tenant-scoped)؛ طريقة المستودع غير المحددة بنطاق هي خطأ." هذا ثابت أمني، وهو غير مرئي في أي استعلام فردي، لذا فهو بالضبط نوع القاعدة الذي يجب تدوينه.

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

بالنسبة لعمل الخلفية، العائد ملموس: انتهاكات أقل للطبقات، لا استدعاءات بوابة داخلية مفاجئة، أشكال أخطاء وتصفح متسقة، ومعالجات متوافقة مع العقد لأن الوكيل تم توجيهه إلى مواصفات OpenAPI بدلاً من تخمين المخطط. يتوقف الوكيل عن الابتكار ويبدأ في الامتثال. إذا كنت تريد أن يقوم الوكيل أيضًا باختبار واجهة برمجة التطبيقات (API) التي كتبها للتو، فإن الجمع بين العقد والتصميم هو ما يسمح للأدوات والوكلاء بالاختبار مقابل واجهة معروفة؛ قم بتنزيل Apidog يمنحك مساحة عمل التصميم أولاً، وتصدير OpenAPI الذي يشير إليه DESIGN.md الخاص بك، وخادم MCP ومصحح أخطاء وكيل الذكاء الاصطناعي للتحقق من أن نقاط النهاية المولدة تتطابق فعليًا مع العقد.

الخاتمة

• DESIGN.md يسجل لماذا تتخذ شيفرتك البرمجية شكلها الحالي: الثوابت، القرارات، والبدائل المرفوضة التي لا يستطيع الوكيل قراءتها من المصدر.
• إنه يكمل ولا يحل محل AGENTS.md وCLAUDE.md: تبقى تلك الملفات قصيرة وتشغيلية؛ بينما يحمل DESIGN.md البنية المعمارية العميقة ويُشار إليه منهما.
• اكتبه بشكل تصريحي، كحقائق مطلقة قابلة للاختبار بالإضافة إلى قاعدة "عند الشك، أشر إلى المشكلة ولا تتجاوزها"، بحيث يعمل كحاجز حماية، وليس نصًا سلبيًا.
• يؤتي ثماره الأكبر في قواعد بيانات API والخلفية، حيث تكون حدود العقد، والمعاملات، والتساوي المفعول، ونطاق التأجير غير مرئية ومكلفة عند الخطأ فيها.
• حافظ عليه من التلف بوجود مالك ومحفز مراجعة مرتبط بقالب طلب السحب الخاص بك؛ لا تقم أبدًا بمزامنته سطرًا بسطر مع الشيفرة.
• أكبر مكسب لعمل الخلفية هو تسمية مواصفات OpenAPI على أنها موثوقة بحيث يمتثل الوكلاء للعقد بدلاً من اختراع المخططات.
• صمم هذا العقد أولاً. قم بتنزيل Apidog لتصميم واجهات برمجة التطبيقات بطريقة التصميم أولاً، وتصدير مواصفات OpenAPI التي يشير إليها DESIGN.md الخاص بك، واختبر أن نقاط النهاية المولدة بواسطة الوكيل تتطابق معها بالفعل.

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

هل DESIGN.md معيار رسمي مثل AGENTS.md؟

لا. AGENTS.md هو تنسيق محدد ومعتمد على نطاق واسع ويُشرف عليه الآن تحت مظلة مؤسسة Agentic AI التابعة لمؤسسة لينكس (Linux Foundation). DESIGN.md هو تقليد مجتمعي لا يوجد له مالك واحد أو مواصفات، وينتمي إلى نفس عائلة ARCHITECTURE.md و ADRs. تعامل معه كنمط مفيد تقوم بتكييفه، وليس كمعيار تلتزم به.

هل أحتاج إلى DESIGN.md إذا كان لدي بالفعل AGENTS.md أو CLAUDE.md؟

إذا كانت بنية نظامك تحتوي على قيود غير واضحة، فنعم. يُقصد بـ AGENTS.md وCLAUDE.md أن يبقيا قصيرين وتشغيليين؛ توصي وثائق Claude Code بإبقاء CLAUDE.md تحت 200 سطر تقريبًا. المنطق المعماري العميق لا يتسع هناك دون تضخيمه والإضرار بالالتزام به، لذا تضعه في DESIGN.md وتشير إليه. بالنسبة للملف التشغيلي نفسه، انظر كيفية كتابة ملفات AGENTS.md.

كيف يختلف DESIGN.md عن ARCHITECTURE.md؟

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

كم يجب أن يكون طول DESIGN.md؟

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

كيف أجعل الوكيل يقرأه بالفعل؟

أشر إليه من الملف الذي يحمله الوكيل بالفعل عند بدء التشغيل. بالنسبة لـ Claude Code، استورده من CLAUDE.md باستخدام @DESIGN.md. بالنسبة لبيئة AGENTS.md، أضف سطر إشارة في AGENTS.md يخبر الوكلاء بقراءة DESIGN.md قبل التغييرات الهيكلية. لا تلصق المحتوى بأكمله في الملف القصير؛ أشر إليه حتى يبقى الملف التشغيلي قصيرًا.

هل سيتبع الوكيل دائمًا DESIGN.md؟

لا، ويجب عليك التصميم مع أخذ ذلك في الاعتبار. ملفات تعليمات الوكيل هي سياق يحاول النموذج اتباعه، وليست تكوينات مفروضة. اكتب القواعد كحقائق مطلقة وواضحة، وأضف تعليمات صريحة "أشر إلى التعارضات، لا تتجاوزها"، واعتمد على حلقة المراجعة؛ فالإشارة إلى قاعدة تم انتهاكها في DESIGN.md تؤدي إلى إصلاح سريع وصحيح حتى لو فاتت المحاولة الأولى.

هل يساعد DESIGN.md في مشاكل عقود API على وجه التحديد؟

كثيرًا. أعلى قيمة له في الاستخدام الخلفي هي التصريح بأن مواصفات OpenAPI موثوقة وتحديد اسم الملف، بحيث يمتثل الوكلاء للعقد بدلاً من اختراع المخططات أو تعديل الأنواع المولدة يدويًا. تصميم هذا العقد أولاً في أداة مثل Apidog يمنح الوكيل هدفًا واضحًا يمكن لـ DESIGN.md الخاص بك أن يشير إليه مباشرة.

أين يجب أن يتواجد DESIGN.md في المستودع؟

في جذر المستودع، بجانب README.md وAGENTS.md، حتى يجده الوكلاء والبشر دون أي بحث. في مستودع أحادي (monorepo)، يعمل ملف DESIGN.md جذري للقواعد على مستوى النظام بالإضافة إلى ملف لكل حزمة للهندسة المعمارية المحلية بشكل جيد، مما يعكس كيفية قراءة الوكلاء لأقرب AGENTS.md في شجرة الدليل.