ما هو ملف DESIGN.md ولماذا تحتاجه بعد AGENTS.md؟

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

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

وكيل البرمجة، أي أداة مثل Claude Code أو Cursor تقرأ مستودعك وتعدله تلقائيًا، يتصرف بثقة افتراضيًا. فعندما يعثر على نمط لا يتعرف إليه، يحسّنه. وقد يحوّل ذاكرة تخزين مؤقت مكتوبة يدويًا إلى 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. يوجد كل ملف في عنوان URL عام ومستقر، لذا يمكنك قراءة أحدها الآن في الطرفية.

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

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

يتكوّن ملف Nuxt من نحو 2,100 كلمة، ومعظم محتواه قاعدة مرفقة بسببها:

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 أطول، إذ يبلغ نحو 6,500 كلمة في أغسطس 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 ملفا أُعيدت هندستها من مواقع ويب عامة. كُتب كل ملف وفق التنسيق نفسه المؤلف من تسعة أقسام، بحيث يمكنك توجيه وكيل إليه لإنتاج تصميم قريب من ذلك المظهر. هذه الملفات مفيدة، لكنها تظل تخمينات. لم يراجعها أحد من تلك الشركات.

يختلف ملف الجهة الأصلية لأنه المصدر نفسه، وليس وصفا للناتج. عندما تغيّر Vercel مقياس الخطوط لديها، يتغير vercel.com/design.md معها. أما النسخة التي جرى استخراجها في مارس، فتواصل تعليم وكيلك المقياس القديم. ولن يخبرك أي شيء في مستودعك بأن النسخة أصبحت قديمة.

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

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

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

الثوابت. اكتب جملة واحدة لكل ثابت، توضّح أمرًا يجب أن يظل صحيحًا بعد أي تعديل. «تمر كل عملية كتابة عبر queue.enqueue(). تتجاوز الكتابة المباشرة إلى قاعدة البيانات سجل التدقيق، بينما يعتمد تصدير الامتثال على سجل التدقيق.» يصمد الثابت المرفق بسببه أمام مهمة لم تتوقعها. أما الثابت وحده فيبدو تفضيلًا، والتفضيلات تُزال أثناء التحسين.

البدائل المرفوضة. اذكر الخيار البديهي وسبب رفضه. «لا نستخدم Redis للتخزين المؤقت. تعمل الخدمة على VPS واحد، لذلك تكون الخريطة داخل العملية أسرع، كما أن ذلك يلغي خدمة daemon إضافية يجب إبقاؤها قيد التشغيل. أعد النظر في هذا القرار عند وجود خادم تطبيقات ثانٍ.» من دون هذه الفقرة، إذا طُلب من وكيل تسريع التخزين المؤقت، فسيضيف Redis، وسيكون محقًا في ذلك: فأنت لم تذكر القيد. هذا هو القسم الذي يبرر الملف بأكمله.

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

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

ملف DESIGN.md يمكنك نسخه اليوم

# 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.

اكتب اليوم القسمين اللذين يمكنك صياغتهما من الذاكرة: الثوابت والبدائل المرفوضة، واترك بقية الأقسام كعناوين فقط. يكفي ملف يتضمن 4 أسطر صادقة. أما ملف يتضمن 40 سطرًا تخمينيًا فلا يكفي.

تُحمّل بعض الأدوات كل ملف markdown في جذر المستودع، بينما تُحمّل أدوات أخرى الملف الذي يُحدَّد لها فقط، لذلك لا تفترض سلوكًا معينًا. أضف إشارة إلى 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، ولا يوضح أيٌّ منه سبب اتخاذ القرارات بهذه الطريقة.

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

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

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

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

لا توجد أداة lint لهذا الغرض. لكن يمكنك إجراء فحص في دقيقة واحدة.

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

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

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

ابدأ بالقرارات التي تختلفون حولها

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

FAQ

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

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

هل ينبغي أن يكون DESIGN.md قسمًا من AGENTS.md فقط؟

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

ما الفرق بين DESIGN.md وسجل قرار معماري؟

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

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

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