كيف تكتب ملف DESIGN.md لوكيل الذكاء الاصطناعي؟

ماهية ملف DESIGN.md وما لا يغطيه ملف AGENTS.md

ملف DESIGN.md هو ملف markdown موجود في المجلد الجذري لمستودعك، يوضح لوكيل البرمجة المعتمد على الذكاء الاصطناعي سبب هيكلة الكود بهذه الطريقة. أما ملف AGENTS.md فيجيب على سؤال مختلف: كيف تعمل هنا؟ وهذا يشمل أمر البناء، وأمر الاختبار، وأداة الـ lint التي يجب أن تجتازها، والمسارات التي يجب عدم المساس بها. يسجل ملف DESIGN.md القرارات التي تم الاستقرار عليها بالفعل، وما الذي يتعطل عند التراجع عن أحدها.

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

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

ما الذي يحتويه ملف DESIGN.md المنشور فعلياً

أسرع طريقة لتعلم التنسيق هي قراءة الملفات التي تنشرها الشركات عن نفسها. يتتبع المستودع official-design-md تلك الملفات فقط. قاعدة الإدراج فيه تتكون من سطر واحد، وهذا السطر هو جوهر المجموعة بأكملها:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

بحلول أغسطس 2026، يدرج المستودع سبعة ملفات: Atlassian وClerk وMintlify وNuxt وResend وVercel وVoltAgent. يوجد كل ملف في رابط عام ثابت، لذا يمكنك قراءة أحدها في الطرفية (terminal) الآن.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

كلاهما مستندات لنظام التصميم. وهي تصف كيف يجب أن يبدو المنتج: الألوان، والخطوط، والتباعد، والحركة. اقرأ ما يتجاوز الموضوع، لأن الجزء المفيد هو هيكل الكتابة وليس الموضوع نفسه.

يصل طول ملف Nuxt إلى حوالي 2100 كلمة، ومعظم محتواه عبارة عن قاعدة متبوعة بسببها:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

ملف Vercel أطول، حيث يبلغ حوالي 6500 كلمة في أغسطس 2026، وهو يخطو خطوة إضافية. أحد عناوينه هو Reject generated-design reflexes. وتحته توجد قائمة بما يلجأ إليه المولد القادر عندما لا يخبره أحد بعدم القيام بذلك:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

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

لماذا تنشر الشركات ملفات DESIGN.md الخاصة بها؟

لقد سبقنا المجتمع إلى ذلك. يحتوي مستودع awesome-design-md على 73 ملفاً تم استنتاجها هندسياً من مواقع عامة، وكل منها مكتوب وفق تنسيق موحد من تسعة أقسام، بحيث يمكن توجيه وكيل ذكاء اصطناعي إلى أحدها لإنتاج مظهر مشابه. هذه الملفات مفيدة لكنها تظل مجرد تخمينات؛ فلم يقم أحد داخل تلك الشركات بمراجعتها.

يختلف الملف الصادر عن الجهة المالكة (first-party) لأنه يمثل المصدر الأساسي وليس مجرد قراءة للمخرجات. فعندما تغير Vercel مقياس الخط لديها، يتغير ملف vercel.com/design.md تبعاً لذلك. أما النسخة التي تم جمعها (scraped) في شهر مارس فستستمر في تعليم وكيلك المقياس القديم، ولن يخبرك أي شيء في مستودعك بأن هذه النسخة أصبحت قديمة.

عدد الناشرين السبعة هو رقم صغير، والمستودع يقر بذلك: فالمعيار جديد والاعتماد الرسمي له في تزايد. يتم صيانة كلتا المجموعتين بواسطة VoltAgent، وهو إطار عمل مفتوح المصدر للوكلاء يقوم بنشر ملفه الخاص أيضاً، لذا اقرأ القائمة كأداة تتبع وليس كإحصاء محايد. ومع ذلك، لا يزال الأمر يستحق المتابعة بسبب هوية هؤلاء السبعة؛ فهم الشركات التي ينسخ المطورون الآخرون كود الواجهة الأمامية الخاص بها أكثر من غيرها، وأصبحت ملفاتهم بمثابة النموذج العملي لما يجب أن يكون عليه ملف DESIGN.md. قارن هذا بالمسار الذي سلكه ملف AGENTS.md: حيث يضم agents.md الآن أكثر من 60,000 مشروع مفتوح المصدر يستخدم هذا التنسيق، وتتولى إدارته مؤسسة Agentic AI Foundation تحت مظلة Linux Foundation. إن الأعراف الخاصة بالملفات القابلة للقراءة من قبل الوكلاء تترسخ بسرعة، وهي تترسخ بدءاً من القمة.

ما الذي يجب تضمينه في ملف DESIGN.md عندما لا يحتوي المشروع على واجهة مستخدم

معظم البرمجيات التي تعمل على خادم VPS لا تملك لغة بصرية لتحديدها. ومع ذلك، يظل هذا الملف ضرورياً، لأن الآلية لا علاقة لها بالألوان. الهدف هو تدوين القيود التي قد ينتهكها محرر واثق دون أن يلاحظ ذلك.

الثوابت (Invariants). جملة واحدة لكل ثابت، توضح أمراً يجب أن يظل صحيحاً بعد أي تعديل. مثال: "تتم كل عملية كتابة عبر queue.enqueue(). الكتابة المباشرة في قاعدة البيانات تتجاوز سجل التدقيق، وسجل التدقيق هو ما يقرأه تصدير الامتثال". الثابت المرفق بسببه يصمد أمام المهام التي لم تتوقعها أبداً. أما الثابت الذي يُذكر بمفرده فيُقرأ كتفضيل، والتفضيلات يتم تحسينها (حذفها) لاحقاً.

البدائل المرفوضة. الخيار البديهي وسبب استبعاده. مثال: "نحن لا نستخدم Redis للتخزين المؤقت. الخدمة تعمل على خادم VPS واحد، لذا فإن خريطة داخل العملية (in-process map) أسرع، وهي عملية أقل يجب الحفاظ على استمراريتها. أعد النظر في هذا عند وجود خادم تطبيقات ثانٍ". بدون هذه الفقرة، سيقوم الوكيل المكلف بتسريع التخزين المؤقت بإضافة Redis، وسيكون محقاً في ذلك: لأنك لم تخبره بالقيد. هذا القسم هو الذي يبرر وجود الملف بأكمله.

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

المصطلحات (Vocabulary). إذا كان الكود يستخدم tenant بينما يستخدم الفريق customer، فدوّن هذا الربط. الوكيل الذي يخمن بشكل خاطئ هنا سينتج كوداً يبدو سليماً ولكنه ينمذج شيئاً خاطئاً، وهو أصعب أنواع الأخطاء اكتشافاً أثناء المراجعة.

تصميم يمكنك نسخه اليوم

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

الثوابت

• يجب أن تظل جميع ملفات الإعداد قابلة للقراءة من قبل البشر ومخزنة في نظام تحكم في الإصدار.
• يجب أن تكون جميع العمليات قابلة للتكرار عبر الأتمتة دون تدخل يدوي.
• يجب أن تعتمد جميع الخدمات على مبدأ الامتيازات الأقل (Least Privilege).
• يجب أن تكون سجلات النظام مركزية ومتاحة للتحليل الفوري.

البدائل المرفوضة

• استخدام واجهات الإدارة الرسومية (GUI) لإعداد الخوادم، لأنها تفتقر إلى سجل التغييرات وتصعب عملية التوثيق.
• الاعتماد على التكوين اليدوي المباشر عبر SSH دون استخدام أدوات إدارة التكوين (Configuration Management).
• تخزين الأسرار (Secrets) كمتغيرات بيئة داخل ملفات الإعداد النصية العادية.

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

معايير الأمان

بروتوكول النشر

راجع AGENTS.md للحصول على تفاصيل حول الوكلاء المعتمدين.

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

النمط الخاطئ: ملف DESIGN.md يكرر محتوى README

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

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

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

الاختبار سريع. إذا كان الفقرة ستناسب ملف README، فاحذفها من DESIGN.md. ما يتبقى يجب أن يكون الجزء الذي ستقوله بصوت عالٍ في مراجعة الكود، الجزء الذي يبدأ بـ "لقد جربنا ذلك بالفعل".

كيف تعرف أن الملف يعمل؟

لا يوجد أداة فحص (linter) لهذا الغرض. لكن يمكنك إجراء اختبار سريع في دقيقة واحدة.

امنح الوكيل (agent) مهمة تتعارض مباشرة مع ثابت (invariant) معين. على سبيل المثال: "أضف مهمة خلفية تضع علامة 'منتهي الصلاحية' على الصفوف القديمة". الملف الذي يؤدي وظيفته بشكل صحيح سيظهر أثره في الإجابة قبل كتابة أي كود: يجب أن يخبرك الوكيل أن المهمة تكتب البيانات عبر queue.enqueue()، لأن الكتابة المباشرة ستتجاوز سجل التدقيق (audit log). إذا قام الوكيل بفتح اتصال بقاعدة البيانات والكتابة مباشرة، فهذا يعني أحد أمرين: إما أن الملف لا يُقرأ إطلاقاً، أو أن صياغة الثابت فضفاضة بما يكفي للسماح بالجدال حولها.

راقب أيضاً عدد الرموز (token count)، لأن هذا الملف يتم تحميله في كل دورة. إذا قفز استهلاك السياق بعد إضافة ملف DESIGN.md ولم تتحسن الإجابات، فهذا يعني أن الملف يحتوي على نصوص كان الوكيل يعرفها مسبقاً. يوضح قراءة عدادات الرموز في Claude Code أين تذهب ميزانية الرموز هذه.

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

ابدأ بالقرارات التي تثير الجدل

تستغرق النسخة الأولى عشرين دقيقة. افتح آخر عدة طلبات سحب (pull requests) حيث كتب المراجع "لا، نحن نقوم بذلك بطريقة مختلفة هنا". كل تعليق من هذه التعليقات يمثل ثابتاً لم يُدوّن قط، وكل واحد منها هو موضع سيرتكب فيه الوكيل نفس الخطأ، وبسرعة أكبر وبتكرار أكثر مما قد يفعله الإنسان. أضف إلى الملف عندما يخذلك، وليس وفق جدول زمني. إذا كنت لا تزال تحاول تحديد مكان ملاءمة الوكلاء في سير عمل التطوير الطبيعي، فإن دليل تعلم وكلاء الذكاء الاصطناعي لعام 2026 هو محطتك التالية المعقولة.

FAQ

هل يُعد ملف DESIGN.md معياراً رسمياً؟

ليس بالمعنى الذي يُعد به ملف AGENTS.md معياراً. يمتلك ملف AGENTS.md موقعاً خاصاً به على agents.md، ويستخدمه أكثر من 60,000 مشروع مفتوح المصدر، ويخضع لإشراف مؤسسة Agentic AI Foundation، وهي جزء من Linux Foundation. أما ملف DESIGN.md، فبحلول أغسطس 2026، لا يملك هيئة إدارية ولا مواصفات منشورة. ما يمتلكه هو تبنٍّ من قبل أطراف أولى؛ إذ تنشر سبع شركات، منها Vercel وNuxt وAtlassian وResend، هذا الملف عبر رابط عام، كما تضم مجموعة مجتمعية 73 ملفاً إضافياً تم استنتاجها من مواقع عامة. تعامل معه كعرف يمكنك تبنيه الآن وتطويره بحرية، لأنه لا توجد جهة تصادق على أسماء الأقسام التي تختارها.

هل يجب أن يكون DESIGN.md مجرد قسم داخل AGENTS.md؟

بالنسبة للمستودعات الصغيرة، نعم. ملف واحد يقرؤه الوكيل (agent) بالتأكيد أفضل من ملفين قد يتم تجاهل أحدهما. افصل بينهما عندما يتوقف ملف AGENTS.md عن كونه سهل القراءة، أو عندما تلاحظ أن الجزأين يتغيران بمعدلات مختلفة. يتغير ملف AGENTS.md بتغير البناء (build)، بينما يتغير ملف DESIGN.md بتغير القرارات، وهو أمر نادر الحدوث وله وزن أكبر. عند الفصل، أضف سطراً واحداً في AGENTS.md يوجه الوكيل لقراءة DESIGN.md قبل تعديل الكود، لأن ليس كل أداة تقوم بتحميل كل ملفات markdown الموجودة في المجلد الرئيسي.

كيف يختلف DESIGN.md عن سجل قرارات الهندسة (ADR)؟

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

ما هو الطول المناسب لملف DESIGN.md؟

يجب أن يكون قصيراً بما يكفي ليتم تحميله في كل دورة دون تكلفة إضافية. الأمثلة المنشورة طويلة لأنها تحدد لغة بصرية كاملة؛ فملف Nuxt يحتوي على حوالي 2,100 كلمة، وملف Vercel يحتوي على حوالي 6,500 كلمة بحلول أغسطس 2026. عادة ما تحتاج خدمات الواجهة الخلفية (backend) إلى أقل من ذلك بكثير. ابدأ بصفحة واحدة ولا تزد عليها إلا عندما يخطئ الوكيل في أمر كان يمكن تجنبه بجملة واحدة. الطول ليس المعيار؛ يجب أن يكون كل سطر معلومة قد يخطئ الوكيل فيها إذا لم تكن موجودة.