فایل DESIGN.md چیست و چرا به آن نیاز داریم؟

فایل DESIGN.md چیست و AGENTS.md چه مواردی را پوشش نمی‌دهد

فایل DESIGN.md یک فایل markdown در ریشه مخزن شماست که به یک عامل برنامه‌نویسی هوش مصنوعی (AI coding agent) توضیح می‌دهد چرا کد به این شکل ساختار یافته است. فایل AGENTS.md به پرسش متفاوتی پاسخ می‌دهد: نحوه کار در اینجا؛ که شامل دستور build، دستور تست، lintهایی که باید پاس شوند و مسیرهایی که نباید تغییر کنند، می‌شود. فایل 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 طولانی‌تر است و در اوت 2026 حدود 6,500 کلمه دارد و یک گام فراتر می‌رود. یکی از سرفصل‌های آن Reject generated-design reflexes است. در زیر آن، فهرستی از مواردی قرار دارد که یک مولد توانمند (generator) به سراغ آن‌ها می‌رود، مگر اینکه کسی به او دستور داده باشد که چنین نکند:

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 که ارزش ثبت (commit) داشته باشد، در واقع همین فهرست برای یک حوزه خاص است.

چرا شرکت‌ها فایل DESIGN.md اختصاصی خود را منتشر می‌کنند؟

جامعهٔ کاربری پیش‌قدم بوده است. مخزن awesome-design-md شامل 73 فایل است که از وب‌سایت‌های عمومی مهندسی معکوس شده‌اند. هر کدام از این فایل‌ها با فرمت نه‌بخشی یکسانی نوشته شده‌اند تا یک عامل (agent) بتواند با ارجاع به آن‌ها، خروجی مشابهی تولید کند. این فایل‌ها مفید هستند، اما همچنان بر پایه حدس و گمان بنا شده‌اند و هیچ‌کس در آن شرکت‌ها صحت آن‌ها را تأیید نکرده است.

یک فایل رسمی (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() انجام شود. نوشتن مستقیم در دیتابیس باعث دور زدن لاگ حسابرسی (audit log) می‌شود و خروجی‌های انطباق (compliance export) دقیقاً از همین لاگ خوانده می‌شوند.» ثابتی که دلیل آن ذکر شده باشد، در مواجهه با وظایفی که پیش‌بینی نکرده‌اید، پایدار می‌ماند. ثابتی که بدون دلیل ذکر شود، صرفاً یک «ترجیح» تلقی شده و در فرآیند بهینه‌سازی حذف می‌شود.

جایگزین‌های ردشده. گزینه‌های بدیهی و دلیل رد شدن آن‌ها را بنویسید. «ما از Redis برای کش استفاده نمی‌کنیم. این سرویس روی یک VPS واحد اجرا می‌شود، بنابراین استفاده از یک map درون‌پردازشی (in-process map) سریع‌تر است و یک دیمون کمتر برای نگهداری وجود دارد. در صورت اضافه شدن دومین سرور اپلیکیشن، این تصمیم بازنگری شود.» بدون این پاراگراف، عاملی که وظیفه افزایش سرعت کش را دارد، Redis را اضافه می‌کند و حق هم دارد، چرا که شما محدودیت را به او نگفته بودید. این بخش، ارزش کل فایل را توجیه می‌کند.

مرزها. نقاطی که یک ویرایش کوچک در آن‌ها، دامنهٔ اثرگذاری (blast radius) بزرگی دارد. طرحواره دیتابیس (database schema)، پیشوند مسیرهای عمومی (public route prefix) که مشتریان از قبل برای آن اسکریپت نوشته‌اند، فایل پیکربندی که اپلیکیشن پیش از شروع می‌خواند، یا ورودی cron که فرض می‌کند تنها یک نسخه از آن در حال اجراست. این موارد را نام ببرید و بگویید تغییر در هر کدام چه هزینه‌ای در بر دارد.

واژگان. اگر کد از اصطلاح tenant استفاده می‌کند و تیم از اصطلاح customer، این معادل‌سازی را یادداشت کنید. عاملی که در این مورد حدس اشتباه بزند، کدی تولید می‌کند که از نظر خوانایی درست است اما مدل‌سازی آن غلط است؛ این دشوارترین نوع خطا برای شناسایی در فرآیند بازبینی (review) است.

یک فایل 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.

دو بخشی را که می‌توانید همین امروز از حفظ بنویسید، یعنی «ثابت‌ها» (invariants) و «جایگزین‌های ردشده» (rejected alternatives) پر کنید و بقیه را به صورت سرتیتر باقی بگذارید. فایلی با چهار خط صادقانه کارآمدتر از فایلی با چهل خط حدسی است.

برخی ابزارها تمام فایل‌های markdown موجود در ریشه مخزن را بارگذاری می‌کنند و برخی دیگر فقط فایلی را که به آن‌ها معرفی شده است؛ بنابراین فرض را بر هیچ‌کدام نگذارید. یک ارجاع به AGENTS.md اضافه کنید:

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

ثابت‌ها (Invariants)

جایگزین‌های ردشده (Rejected alternatives)

معماری سیستم

مدل داده

ملاحظات امنیتی

مقیاس‌پذیری و عملکرد

ارجاع به مستندات تکمیلی

برای جزئیات بیشتر در مورد نحوه تعامل با عامل‌های هوشمند، به AGENTS.md مراجعه کنید.

الگوی ضد: فایلی به نام DESIGN.md که محتوای README را تکرار می‌کند

رایج‌ترین نسخهٔ نامناسب، متنی است که به‌خوبی خوانده می‌شود اما چیزی نمی‌آموزد. این فایل با توضیح عملکرد پروژه آغاز می‌شود، لیست ویژگی‌ها را ارائه می‌دهد، نحوهٔ نصب را شرح می‌دهد و با ذکر مجوز (licence) به پایان می‌رسد. تمام این موارد قبلاً در README آمده‌اند و هیچ‌کدام توضیح نمی‌دهند که چرا هر بخش به شکلی که هست، طراحی شده است.

این کار دو هزینه برای شما دارد. هزینهٔ اول، «زمینه» (context) است. فایلی که عامل (agent) در ابتدای هر وظیفه می‌خواند، در هر بار اجرا هزینه دارد و بخش نصبِ تکراری، صرفاً سربار اضافی در یک پنجرهٔ محدود است. مدیریت بودجهٔ این پنجره مهارتی مستقل است که در مدیریت پنجره زمینه در Claude Code به آن پرداخته شده است. خلاصهٔ آن: هر چیزی که به‌طور خودکار بارگذاری می‌شود، باید ارزشمندترین متن در مخزن (repository) باشد.

هزینهٔ دوم بدتر است. دو نسخه از یک گزارهٔ واحد به‌مرور با هم اختلاف پیدا می‌کنند. README می‌گوید سرویس روی 8080 گوش می‌دهد، اما DESIGN.md همچنان عدد 3000 را نشان می‌دهد؛ عامل راهی برای اولویت‌بندی یکی بر دیگری ندارد، بنابراین یکی را انتخاب کرده و کد را بر اساس آن می‌نویسد. فایلی که گاهی اشتباه است، با همان اطمینانی مورد استناد قرار می‌گیرد که فایلی که همیشه درست است.

آزمون آن سریع است. اگر پاراگرافی به‌راحتی در README جای می‌گیرد، آن را از DESIGN.md حذف کنید. آنچه باقی می‌ماند باید بخشی باشد که در یک بازبینی کد (code review) با صدای بلند می‌گویید؛ همان بخشی که با «ما قبلاً این را امتحان کردیم» شروع می‌شود.

چگونه متوجه شویم که فایل به‌درستی کار می‌کند؟

هیچ ابزار linter خاصی برای این کار وجود ندارد. اما یک بررسی ساده وجود دارد که می‌توانید در عرض یک دقیقه انجام دهید.

به agent وظیفه‌ای بدهید که مستقیماً با یک invariant (ثابت منطقی) برخورد کند. مثلاً: "یک background job اضافه کن که ردیف‌های قدیمی را به عنوان منقضی‌شده علامت‌گذاری کند." فایلی که وظیفه خود را به‌درستی انجام می‌دهد، پیش از نوشتن هرگونه کدی در پاسخ ظاهر می‌شود: agent باید به شما بگوید که این job از طریق queue.enqueue() می‌نویسد، زیرا نوشتن مستقیم باعث نادیده گرفته شدن audit log می‌شود. اگر agent یک اتصال دیتابیس باز کند و مستقیماً بنویسد، یکی از دو حالت صادق است: یا فایل اصلاً خوانده نمی‌شود، یا invariant به قدری مبهم بیان شده که جای بحث دارد.

تعداد توکن‌ها را نیز زیر نظر داشته باشید، زیرا این فایل در هر نوبت بارگذاری می‌شود. اگر پس از اضافه کردن DESIGN.md مصرف context افزایش یافت و کیفیت پاسخ‌ها بهتر نشد، یعنی فایل حاوی متنی است که agent از قبل به آن آگاه بوده است. خواندن شمارنده‌های توکن در Claude Code نشان می‌دهد که این بودجه کجا صرف می‌شود.

این موضوع زمانی اهمیت بیشتری پیدا می‌کند که agent به جای لپ‌تاپ شما، روی یک سرور مستقر باشد. agentای که در یک session طولانی‌مدت کار می‌کند، مانند تنظیمات یک فضای کاری Claude Code روی VPS با tmux، هیچ حافظه‌ای از گفتگوی دیروز ندارد. مخزن (repository) همان حافظه است. هر چیزی که در چت توضیح داده‌اید و commit نکرده‌اید، تا session بعدی از بین می‌رود و DESIGN.md جایی است که این توضیحات باید ثبت شوند تا باقی بمانند.

با تصمیماتی که بر سر آن‌ها بحث می‌کنید شروع کنید

نسخه اول بیست دقیقه زمان می‌برد. چندین pull request اخیر را باز کنید که در آن‌ها یک بازبین نوشته است «نه، ما اینجا کار را به شکل دیگری انجام می‌دهیم». هر یک از این نظرات، یک اصل تغییرناپذیر است که هرگز مکتوب نشده است؛ و هر کدام از آن‌ها نقطه‌ای است که یک عامل (agent) همان اشتباه را سریع‌تر و مکررتر از یک انسان مرتکب خواهد شد. هر زمان که این مستندات در کار شما شکست خورد، آن را به فایل اضافه کنید، نه طبق یک زمان‌بندی مشخص. اگر هنوز در حال بررسی این هستید که عوامل (agents) چگونه در یک چرخه توسعه نرم‌افزار استاندارد جای می‌گیرند، راهنمای 2026 برای یادگیری عامل‌های هوش مصنوعی مقصد بعدی مناسبی است.

FAQ

آیا DESIGN.md یک استاندارد رسمی است؟

نه به شکلی که AGENTS.md هست. AGENTS.md در agents.md جایگاه رسمی دارد، بیش از 60,000 پروژه متن‌باز از آن استفاده می‌کنند و تحت نظارت Agentic AI Foundation، بخشی از Linux Foundation، قرار دارد. تا اوت 2026، فایل DESIGN.md هیچ نهاد ناظر و مشخصات منتشرشده‌ای ندارد. آنچه وجود دارد، پذیرش توسط شرکت‌های پیشرو است: هفت شرکت از جمله Vercel، Nuxt، Atlassian و Resend آن را در یک URL عمومی منتشر کرده‌اند و یک مجموعه اجتماعی شامل 73 نمونه دیگر است که از سایت‌های عمومی مهندسی معکوس شده‌اند. با آن به عنوان یک قرارداد (convention) برخورد کنید که می‌توانید همین حالا آن را بپذیرید و آزادانه گسترش دهید، زیرا هیچ مرجعی نام بخش‌های شما را اعتبارسنجی نمی‌کند.

آیا DESIGN.md باید فقط بخشی از AGENTS.md باشد؟

برای یک مخزن (repository) کوچک، بله. یک فایل که عامل (agent) قطعاً آن را می‌خواند، بهتر از دو فایل است که ممکن است یکی از آن‌ها نادیده گرفته شود. زمانی آن‌ها را جدا کنید که AGENTS.md دیگر به راحتی قابل اسکن نباشد، یا زمانی که متوجه شدید این دو بخش با نرخ‌های متفاوتی تغییر می‌کنند. فایل AGENTS.md با تغییرات build تغییر می‌کند. فایل DESIGN.md با تغییرات تصمیمات (decisions) تغییر می‌کند که نادرتر است و وزن بیشتری دارد. هنگام جداسازی، یک خط به AGENTS.md اضافه کنید و به عامل بگویید که پیش از ویرایش کد، DESIGN.md را بخواند، زیرا هر ابزاری همه فایل‌های markdown موجود در ریشه (root) را بارگذاری نمی‌کند.

تفاوت DESIGN.md با سند تصمیمات معماری (ADR) چیست؟

یک ADR (سند تصمیم معماری) سندی تاریخ‌دار از یک تصمیم واحد است و یک پروژه سالم ده‌ها مورد از آن‌ها را در یک پوشه جمع‌آوری می‌کند. این یک تاریخچه است و بارگذاری تاریخچه هزینه‌بر است، زیرا عامل باید همه آن‌ها را بخواند تا بفهمد کدام‌یک هنوز معتبر هستند. فایل DESIGN.md وضعیت فعلی است که نوشته شده تا در هر وظیفه به‌طور کامل خوانده شود. اگر از قبل ADR می‌نویسید، هر دو را نگه دارید. ADR می‌گوید چه چیزی و چه زمانی تصمیم‌گیری شده است. DESIGN.md می‌گوید امروز چه چیزی درست است و این همان فایلی است که باید به عامل معرفی کنید.

طول یک فایل DESIGN.md چقدر باید باشد؟

آن‌قدر کوتاه که بارگذاری آن در هر نوبت بدون پشیمانی باشد. نمونه‌های منتشرشده طولانی هستند زیرا یک زبان بصری کامل را مشخص می‌کنند: فایل Nuxt حدود 2,100 کلمه و فایل Vercel تا اوت 2026 حدود 6,500 کلمه است. یک سرویس backend معمولاً به فضای بسیار کمتری نیاز دارد. از یک صفحه شروع کنید و تنها زمانی آن را گسترش دهید که عامل چیزی را اشتباه انجام دهد که یک جمله می‌توانست از آن جلوگیری کند. طول فایل معیار نیست. هر خط باید نکته‌ای باشد که عامل در غیر این صورت آن را اشتباه انجام می‌داد.