تفاوت فایل DESIGN.md و AGENTS.md در پروژه‌های هوش مصنوعی

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

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

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

مرزها. نقاطی که یک ویرایش کوچک در آن‌ها، اثر تخریبی بزرگی دارد. طرحواره دیتابیس (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 را تکرار می‌کند

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

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

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

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

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

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

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

تعداد توکن‌ها را نیز زیر نظر داشته باشید، زیرا این فایل در هر نوبت (turn) بارگذاری می‌شود. اگر پس از اضافه کردن 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 باشد؟

برای یک مخزن کوچک، بله. یک فایل که عامل (agent) قطعاً آن را می‌خواند، بهتر از دو فایل است که ممکن است یکی از آن‌ها نادیده گرفته شود. زمانی آن‌ها را جدا کنید که AGENTS.md دیگر به راحتی قابل اسکن نباشد، یا زمانی که متوجه شدید این دو بخش با نرخ‌های متفاوتی تغییر می‌کنند. AGENTS.md با تغییرات build تغییر می‌کند. DESIGN.md با تغییرات تصمیمات تغییر می‌کند که نادرتر است و وزن بیشتری دارد. هنگام جداسازی، یک خط به 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 معمولاً به فضای بسیار کمتری نیاز دارد. با یک صفحه شروع کنید و تنها زمانی آن را گسترش دهید که عامل چیزی را اشتباه انجام دهد که یک جمله می‌توانست از آن جلوگیری کند. طول، معیار نیست. هر خط باید نکته‌ای باشد که عامل در غیر این صورت آن را اشتباه انجام می‌دهد.