تفاوت فایل DESIGN.md و AGENTS.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، این لیست شامل 11 مورد است: Ant Design، Atlassian، Clerk، Juspay، Microsoft FAST، Mintlify، Nuxt، Oxide Computer، Resend، Vercel و VoltAgent. هر فایل در یک URL عمومی قرار دارد؛ اکثر آن‌ها در دامنه خودِ ناشر و باقی در یک مخزن عمومی GitHub هستند، بنابراین می‌توانید همین حالا یکی از آن‌ها را در ترمینال بخوانید.

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

هر دوی این‌ها اسناد سیستم طراحی هستند. آن‌ها توصیف می‌کنند که یک محصول چگونه باید به نظر برسد: رنگ، تایپوگرافی، فاصله‌گذاری و حرکت. از موضوع اصلی فراتر بروید، زیرا بخش مفید، ساختار نوشتار است و نه خودِ موضوع.

فایل Nuxt تا تاریخ 27 اکتبر 2026 حدود 2000 کلمه است و بیشتر آن شامل یک قانون به همراه دلیل آن است. این فایل با بیان اینکه حالت تیره (dark mode) تم پیش‌فرض است، شروع می‌شود. این فایل رنگ سبز برند #00DC82 را لیست کرده و یادداشتی اضافه می‌کند که رنگ‌های برند «برای لوگوها، تصاویر شبکه‌های اجتماعی و چاپ هستند. از آن‌ها به عنوان مقادیر خام در کد رابط کاربری استفاده نکنید.» نزدیک به انتها، بخشی با عنوان Reject these شامل موارد زیر است:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

فایل Vercel طولانی‌تر است و تا اکتبر 2026 حدود 6000 کلمه دارد و یک گام فراتر می‌رود. یکی از عناوین آن 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 شامل 84 فایل است که از وب‌سایت‌های عمومی استخراج شده‌اند؛ طبق شمارش موجود در فایل README این مخزن تا تاریخ 27 اکتبر 2026، هر کدام از این فایل‌ها با فرمت نه‌بخشی یکسانی نوشته شده‌اند تا یک عامل (agent) بتواند با ارجاع به آن‌ها، خروجی مشابهی تولید کند. این فایل‌ها مفید هستند اما همچنان در حد حدس و گمان باقی می‌مانند. هیچ‌کس در آن شرکت‌ها محتوای آن‌ها را بازبینی نکرده است.

یک فایل «دست‌اول» (first-party) متفاوت است، زیرا منبع اصلی محسوب می‌شود، نه برداشتی از خروجی. وقتی Vercel مقیاس تایپوگرافی خود را تغییر می‌دهد، vercel.com/design.md نیز همراه با آن تغییر می‌کند. نسخه‌ای که در ماه مارس کپی (scraped) شده است، همچنان مقیاس قدیمی را به عامل شما آموزش می‌دهد و هیچ‌چیز در مخزن شما به شما اطلاع نمی‌دهد که آن کپی قدیمی شده است.

یازده ناشر هنوز تعداد کمی است و خود مخزن نیز به همین موضوع اشاره دارد: این استاندارد جدید است و پذیرش رسمی آن در حال رشد است. هر دو مجموعه توسط VoltAgent نگهداری می‌شوند؛ یک چارچوب عامل متن‌باز که فایل اختصاصی خود را نیز منتشر می‌کند، بنابراین این لیست را به عنوان یک ابزار ردیابی در نظر بگیرید، نه یک سرشماری بی‌طرف. با این حال، به دلیل نام‌های موجود در آن، ارزش دنبال کردن را دارد. چندین مورد از این شرکت‌ها همان‌هایی هستند که کدهای فرانت‌اند آن‌ها بیشترین کپی‌برداری را توسط سایر توسعه‌دهندگان دارد و ورودی‌های جدیدتر مانند Ant Design، Microsoft FAST، Juspay و Oxide Computer، سیستم‌های طراحی هستند که تیم‌های دیگر بر پایه آن‌ها می‌سازند. فایل‌های آن‌ها در حال تبدیل شدن به نمونه‌های عملی از ماهیت یک فایل DESIGN.md هستند. مسیر طی‌شده توسط AGENTS.md را مقایسه کنید: agents.md اکنون بیش از 60,000 پروژه متن‌باز را شامل می‌شود که از این فرمت استفاده می‌کنند و مسئولیت نظارت بر آن بر عهده Agentic AI Foundation تحت نظر Linux Foundation است. فایل DESIGN.md نیز همین مسیر را آغاز کرده است. در تاریخ 21 آوریل 2026، گوگل پیش‌نویس مشخصاتی را برای این فرمت به‌صورت متن‌باز منتشر کرد که با عنوان google-labs-code/design.md و همراه با یک طرحواره توکن (token schema) و یک CLI تحت مجوز Apache-2.0 در دسترس است. تا اکتبر 2026، این فرمت در نسخه آلفا قرار دارد و همچنان تحت توسعه فعال است؛ این فرمت توسط Google Labs نگهداری می‌شود (نه یک بنیاد بی‌طرف) و هویت بصری را توصیف می‌کند، بنابراین هیچ مطلبی درباره ثابت‌هایی (invariants) که یک فایل بک‌اند به آن نیاز دارد، ارائه نمی‌دهد. قراردادهای مربوط به فایل‌های قابل‌خواندن برای عامل‌ها به‌سرعت در حال تثبیت هستند و این تثبیت از سطوح بالا آغاز شده است.

محتوای فایل DESIGN.md در پروژه‌های فاقد رابط کاربری

بیشتر نرم‌افزارهایی که روی یک VPS اجرا می‌شوند، زبان بصری خاصی برای تعریف ندارند. با این حال، وجود این فایل همچنان ضروری است، زیرا مکانیزم عملکرد برنامه ارتباطی با رنگ و ظاهر ندارد. هدف از این فایل، مکتوب کردن محدودیت‌هایی است که یک ویرایشگرِ با اعتمادبه‌نفس ممکن است بدون توجه، آن‌ها را نقض کند.

ثابت‌ها (Invariants). برای هر مورد، یک جمله بنویسید که بیانگر اصلی باشد که پس از هر ویرایش باید صادق بماند. برای مثال: «هر عملیات نوشتن باید از طریق queue.enqueue() انجام شود. نوشتن مستقیم در دیتابیس باعث دور زدن لاگ حسابرسی (audit log) می‌شود و خروجی‌های مربوط به انطباق (compliance) از همین لاگ خوانده می‌شوند.» یک ثابت به همراه دلیل آن، در برابر وظایفی که پیش‌بینی نکرده‌اید، پایدار می‌ماند. اما یک ثابتِ بدون دلیل، صرفاً یک ترجیح به نظر می‌رسد و ترجیحات معمولاً در فرآیند بهینه‌سازی حذف می‌شوند.

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

مرزها (Boundaries). نقاطی که یک ویرایش کوچک در آن‌ها، پیامدهای گسترده‌ای دارد. طرحواره دیتابیس (database schema)، پیشوند مسیرهای عمومی (public route prefix) که مشتریان قبلاً بر اساس آن اسکریپت نوشته‌اند، فایل پیکربندی که اپلیکیشن پیش از شروع می‌خواند، یا ورودی cron که فرض می‌کند تنها یک نسخه از برنامه در حال اجراست. این موارد را نام ببرید و هزینه تغییر هر کدام را ذکر کنید. اگر عامل (agent) به وب آزاد دسترسی دارد، مثلاً از طریق یک نمونه SearXNG خودمیزبان که به عنوان موتور جستجوی آن متصل شده است، این نیز مرزی است که باید ثبت شود؛ زیرا فایل باید مشخص کند کدام متنِ دریافت‌شده اجازه دارد بر کد تأثیر بگذارد و کدام متن فقط باید به شما بازگردانده شود.

واژگان. اگر در کد از اصطلاح 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.

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

برخی ابزارها تمام فایل‌های 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 را تکرار می‌کند

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

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

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

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

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

هیچ ابزار linting برای این کار وجود ندارد. اما بررسی ساده‌ای وجود دارد که می‌توانید در یک دقیقه انجام دهید.

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

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

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

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

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

FAQ

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

نه به شکلی که AGENTS.md هست. AGENTS.md در agents.md میزبانی می‌شود، بیش از 60,000 پروژه متن‌باز از آن استفاده می‌کنند و تحت نظارت Agentic AI Foundation، بخشی از Linux Foundation، قرار دارد. DESIGN.md دارای یک مشخصات منتشرشده است اما متولی بی‌طرفی ندارد. گوگل در تاریخ 21 آوریل 2026 یک پیش‌نویس مشخصات را به‌صورت متن‌باز منتشر کرد که در مخزن google-labs-code/design.md تحت مجوز Apache-2.0 قرار دارد. تا اکتبر 2026، این فایل در نسخه alpha و همچنان تحت توسعه فعال است و یک هویت بصری را توصیف می‌کند: رنگ‌ها، تایپوگرافی، چیدمان و اجزا. DESIGN.md همچنین دارای پذیرش توسط خودِ ناشران (first-party adoption) است: یازده شرکت و پروژه، از جمله Vercel، Nuxt، Atlassian و Resend، یکی از آن را منتشر کرده‌اند و یک مجموعه اجتماعی تا تاریخ 27 اکتبر 2026، 84 نمونه دیگر را از سایت‌های عمومی استخراج کرده است. برای یک فایل بک‌اند شامل ثابت‌ها و جایگزین‌های ردشده، آن را به عنوان یک قرارداد در نظر بگیرید که می‌توانید همین حالا اتخاذ کرده و آزادانه گسترش دهید، زیرا هیچ مشخصاتی آن نام‌های بخش را پوشش نمی‌دهد.

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

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

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

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

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

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