DESIGN.md: AGENTS.md کے بعد کون سی فائل؟

DESIGN.md کیا ہے، اور AGENTS.md میں کیا شامل نہیں

DESIGN.md آپ کی repository کے root میں موجود ایک markdown فائل ہے جو AI coding agent کو بتاتی ہے کہ code اس ساخت میں کیوں ہے۔ AGENTS.md ایک مختلف سوال کا جواب دیتی ہے: یہاں کام کیسے کرنا ہے۔ اس میں build command، test command، وہ lint شامل ہوتے ہیں جس کا کامیاب ہونا ضروری ہے، اور وہ paths بھی جنہیں تبدیل نہیں کرنا چاہیے۔ DESIGN.md میں پہلے سے طے شدہ فیصلے درج ہوتے ہیں، اور یہ بھی کہ ان میں سے کسی فیصلے کو واپس لینے سے کیا خراب ہوتا ہے۔

Coding agent، یعنی Claude Code یا Cursor جیسے tool جو آپ کی repository کو خود پڑھ کر اس میں ترمیم کرتے ہیں، پہلے سے پُراعتماد ہوتا ہے۔ اسے کوئی ایسا pattern ملے جسے وہ پہچان نہ سکے تو وہ اسے بہتر بنانے کی کوشش کرتا ہے۔ ہاتھ سے لکھی ہوئی cache، Redis بن جاتی ہے، جو in-memory data store ہے، کیونکہ model نے پڑھے ہوئے زیادہ تر code میں cache اسی طرح دیکھی ہوتی ہے۔ AGENTS.md اسے نہیں روکتی، کیونکہ make test دونوں صورتوں میں کامیاب ہو جاتا ہے۔ جو rule ٹوٹا، وہ کہیں بھی تحریر نہیں کیا گیا تھا جہاں agent اسے پڑھ سکتا۔

اگر آپ نے ابھی پہلی فائل نہیں لکھی تو وہیں سے شروع کریں۔ AGENTS.md اور اس کے ساتھ موجود HUMAN.md میں format اور یہ بتایا گیا ہے کہ ہر tool اسے کہاں تلاش کرتا ہے۔ اس کے بعد آنے والا chapter اسی سلسلے کا اگلا حصہ ہے۔

شائع کردہ 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.

August 2026 تک اس میں سات نام شامل ہیں: Atlassian، Clerk، Mintlify، Nuxt، Resend، Vercel اور VoltAgent۔ ہر فائل ایک مستحکم عوامی URL پر موجود ہے، اس لیے آپ ابھی terminal میں ان میں سے کوئی فائل پڑھ سکتے ہیں۔

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

یہ دونوں design system دستاویزات ہیں۔ ان میں بتایا گیا ہے کہ کسی product کی ظاہری شکل کیسی ہونی چاہیے: رنگ، type، spacing اور motion۔ موضوع پر زیادہ توجہ نہ دیں، کیونکہ مفید حصہ موضوع کے بجائے تحریر کا ڈھانچہ ہے۔

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"`.

August 2026 میں Vercel کی فائل زیادہ طویل، تقریباً 6,500 الفاظ پر مشتمل ہے، اور یہ ایک قدم آگے جاتی ہے۔ اس کی ایک heading 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.

یہ جملہ فائل کی قسم واضح کرتا ہے۔ یہ ان defaults کی تحریری فہرست ہے جو ایک پراعتماد model تیار کرتا ہے، اور اسے اس لیے شائع کیا جاتا ہے کہ model انہیں تیار کرنا بند کر دے۔ commit کرنے کے قابل ہر DESIGN.md کسی نہ کسی domain کے لیے یہی فہرست ہوتی ہے۔

کمپنیاں اپنی DESIGN.md فائلیں کیوں شائع کرتی ہیں؟

کمیونٹی نے یہ کام پہلے کیا۔ awesome-design-md میں عوامی ویب سائٹس سے ریورس انجینئرنگ کے ذریعے تیار کی گئی 73 فائلیں شامل ہیں۔ ہر فائل ایک ہی نو حصوں کے فارمیٹ میں لکھی گئی ہے، تاکہ کسی ایجنٹ کو ایسی فائل دے کر تقریباً اسی طرز کا ڈیزائن تیار کروایا جا سکے۔ یہ فائلیں مفید ہیں، لیکن اب بھی قیاس پر مبنی ہیں۔ متعلقہ کمپنیوں میں سے کسی نے ان کا جائزہ نہیں لیا۔

فرسٹ پارٹی فائل اس لیے مختلف ہوتی ہے کہ یہ آؤٹ پٹ کی تشریح نہیں بلکہ اصل ماخذ ہوتی ہے۔ جب Vercel اپنے type scale میں تبدیلی کرتا ہے، تو vercel.com/design.md بھی اس کے ساتھ تبدیل ہوتی ہے۔ مارچ میں scrape کی گئی نقل آپ کے ایجنٹ کو پرانا scale سکھاتی رہتی ہے، اور آپ کے repository میں ایسی کوئی چیز نہیں ہوتی جو بتائے کہ یہ نقل پرانی ہو چکی ہے۔

سات ناشرین کی تعداد کم ہے، اور repository بھی یہی بات واضح کرتا ہے: یہ standard نیا ہے اور official adoption بڑھ رہی ہے۔ دونوں collections کو VoltAgent برقرار رکھتا ہے۔ VoltAgent ایک open source agent framework ہے جو اپنی فائل بھی شائع کرتا ہے۔ اس لیے اس فہرست کو غیر جانب دار census کے بجائے tracker سمجھیں۔ پھر بھی اس پر نظر رکھنا مفید ہے، کیونکہ ان سات ناشرین کی شناخت اہم ہے۔ یہ وہ کمپنیاں ہیں جن کے front-end code کو دوسرے developers سب سے زیادہ نقل کرتے ہیں، اور ان کی فائلیں اس بات کی عملی مثال بن رہی ہیں کہ DESIGN.md کیا ہوتی ہے۔ AGENTS.md کے سفر کا موازنہ کریں: agents.md کے فارمیٹ کو استعمال کرنے والے open source projects کی تعداد اب 60,000 سے زیادہ ہے، اور اس کی نگرانی Linux Foundation کے تحت Agentic AI Foundation کے پاس ہے۔ ایجنٹ کے لیے قابل مطالعہ فائلوں کے conventions تیزی سے مستحکم ہو رہے ہیں، اور ان کی تشکیل اوپر کی سطح سے ہو رہی ہے۔

جب پروجیکٹ میں صارف کا انٹرفیس نہ ہو تو DESIGN.md میں کیا شامل کیا جائے

VPS پر چلنے والے زیادہ تر سافٹ ویئر کے لیے کوئی بصری زبان متعین کرنے کی ضرورت نہیں ہوتی۔ پھر بھی یہ فائل اہم ہے، کیونکہ اس کا مقصد رنگوں سے متعلق نہیں ہے۔ اس میں وہ پابندیاں درج کی جاتی ہیں جن کی خلاف ورزی ایک پراعتماد ایڈیٹر بھی غیر ارادی طور پر کر سکتا ہے۔

ناقابلِ تغیر اصول۔ ہر اصول ایک جملے میں لکھیں اور ایسی بات بیان کریں جو کسی بھی ترمیم کے بعد درست رہنی چاہیے۔ "ہر write queue.enqueue() کے ذریعے ہوتی ہے۔ براہِ راست database write سے audit log میں اندراج نہیں ہوتا، جبکہ compliance export اسی audit log سے ڈیٹا پڑھتا ہے۔" وہ ناقابلِ تغیر اصول جس کے ساتھ اس کی وجہ بھی درج ہو، ایسے task کے دوران بھی برقرار رہتا ہے جس کا آپ نے پہلے تصور نہ کیا ہو۔ صرف اصول لکھنے سے وہ محض ترجیح معلوم ہوتا ہے، اور ترجیحات کو عموماً ختم کر دیا جاتا ہے۔

مسترد کیے گئے متبادل۔ واضح نظر آنے والا اختیار اور اسے مسترد کرنے کی وجہ لکھیں۔ "ہم caching کے لیے Redis استعمال نہیں کرتے۔ سروس ایک واحد VPS پر چلتی ہے، اس لیے process کے اندر موجود map زیادہ تیز ہے، اور ایک daemon کم ہے جسے فعال رکھنا پڑتا ہے۔ دوسرے application server کے موجود ہونے پر اس فیصلے کا دوبارہ جائزہ لیں۔" اس پیراگراف کے بغیر، cache کو تیز کرنے کے لیے کہا گیا agent Redis شامل کر دے گا، اور ایسا کرنا درست بھی ہوگا: آپ نے اسے پابندی سے آگاہ نہیں کیا تھا۔ یہی وہ حصہ ہے جو پوری فائل کی افادیت ثابت کرتا ہے۔

حدود۔ وہ مقامات جہاں معمولی ترمیم کا اثر بہت وسیع ہو سکتا ہے۔ database schema۔ public route prefix جس کے خلاف صارفین پہلے ہی scripts چلا رہے ہیں۔ وہ config file جسے deploy، application شروع ہونے سے پہلے پڑھتا ہے۔ وہ cron entry جو یہ فرض کرتی ہے کہ اس کی صرف ایک copy چل رہی ہے۔ ان سب کے نام لکھیں اور بتائیں کہ ہر ایک میں تبدیلی کی کیا قیمت ہوگی۔

اصطلاحات۔ اگر code میں tenant لکھا ہے اور ٹیم customer کہتی ہے تو دونوں کے درمیان mapping درج کریں۔ یہاں غلط اندازہ لگانے والا agent ایسا code تیار کرتا ہے جو بظاہر درست پڑھتا ہے، مگر غلط چیز کو model کرتا ہے۔ 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 اور مسترد کیے گئے متبادل۔ باقی حصوں کو صرف headings کے طور پر چھوڑ دیں۔ چار دیانت دار سطروں والی فائل قابلِ استعمال ہے۔ چالیس قیاسی سطروں والی فائل قابلِ استعمال نہیں۔

کچھ tools repository کے root میں موجود ہر markdown فائل لوڈ کرتے ہیں، جبکہ کچھ صرف وہی فائل لوڈ کرتے ہیں جس کا انہیں بتایا جائے۔ اس لیے مفروضہ قائم نہ کریں۔ AGENTS.md کی طرف ایک pointer شامل کریں:

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

وہ غلط طرزِ عمل: ایسا DESIGN.md جو README کو دہراتا ہے

سب سے عام خراب ورژن پڑھنے میں اچھا لگتا ہے، لیکن کچھ سکھاتا نہیں۔ یہ پروجیکٹ کے کام کی وضاحت سے شروع ہوتا ہے، خصوصیات کی فہرست دیتا ہے، انسٹال کرنے کا طریقہ بتاتا ہے، اور لائسنس پر ختم ہوتا ہے۔ یہ سب کچھ پہلے ہی README میں موجود ہوتا ہے، اور ان میں سے کوئی بات یہ نہیں بتاتی کہ کسی چیز کو اس طرح بنانے کی وجہ کیا ہے۔

اس کی قیمت آپ کو دو بار ادا کرنی پڑتی ہے۔ پہلی قیمت سیاق و سباق کی ہے۔ ایک ایسی فائل جسے ایجنٹ ہر کام کے آغاز میں پڑھتا ہے، ہر کام پر دوبارہ پڑھی جاتی ہے، اور مقررہ context window میں انسٹالیشن کا دہرایا گیا حصہ خالص اضافی بوجھ ہوتا ہے۔ اس window کی منصوبہ بندی خود ایک مہارت ہے، جس کا احاطہ Claude Code میں context window کا انتظام میں کیا گیا ہے۔ مختصر بات یہ ہے: جو بھی مواد خودکار طور پر لوڈ ہو، وہ repository میں موجود سب سے زیادہ اہمیت رکھنے والا متن ہونا چاہیے۔

دوسری قیمت زیادہ سنگین ہے۔ ایک ہی بیان کی دو نقول وقت کے ساتھ مختلف ہو جاتی ہیں۔ README کہتی ہے کہ سروس 8080 پر سنتی ہے، DESIGN.md اب بھی 3000 کہتی ہے، اور ایجنٹ کے پاس یہ طے کرنے کا کوئی طریقہ نہیں ہوتا کہ کس بیان کو ترجیح دے۔ چنانچہ وہ ایک کو منتخب کر کے اسی کے مطابق code لکھ دیتا ہے۔ جو فائل کبھی کبھی غلط ہو، اسے بھی اسی اعتماد سے استعمال کیا جاتا ہے جس اعتماد سے ہمیشہ درست فائل استعمال کی جاتی ہے۔

جانچ فوری ہے۔ اگر کوئی پیراگراف README میں آسانی سے شامل ہو سکتا ہے، تو اسے DESIGN.md سے نکال دیں۔ باقی وہ حصہ ہونا چاہیے جو آپ code review میں زبانی طور پر بیان کرتے، یعنی وہ حصہ جو "ہم یہ پہلے ہی آزما چکے ہیں" سے شروع ہوتا ہے۔

آپ کیسے جانتے ہیں کہ فائل کام کر رہی ہے؟

اس کے لیے کوئی linter نہیں ہے۔ ایک جانچ ہے جسے آپ ایک منٹ میں چلا سکتے ہیں۔

ایجنٹ کو ایسا کام دیں جو براہ راست کسی invariant تک پہنچے۔ "ایک background job شامل کریں جو stale rows کو expired کے طور پر نشان زد کرے۔" جو فائل اپنا کام کر رہی ہو، اس کا اثر کسی بھی code سے پہلے جواب میں ظاہر ہو جاتا ہے: ایجنٹ کو بتانا چاہیے کہ job queue.enqueue() کے ذریعے write کرتی ہے، کیونکہ براہ راست write کرنے سے audit log نظرانداز ہو جائے گا۔ اگر ایجنٹ database connection کھول کر write کرتی ہے، تو ان میں سے ایک بات درست ہے۔ یا تو فائل بالکل پڑھی نہیں جا رہی، یا invariant کو اتنے مبہم انداز میں لکھا گیا ہے کہ اس پر بحث کی جا سکتی ہے۔

token count بھی دیکھیں، کیونکہ یہ فائل ہر turn پر load ہوتی ہے۔ اگر DESIGN.md شامل کرنے کے بعد context usage بڑھ جائے اور جوابات بہتر نہ ہوں، تو فائل میں ایسا prose موجود ہے جو ایجنٹ پہلے ہی جانتا تھا۔ Claude Code میں token counters پڑھنا سے معلوم ہوتا ہے کہ یہ budget کہاں خرچ ہو رہا ہے۔

یہ بات اس وقت سب سے زیادہ اہم ہوتی ہے جب ایجنٹ آپ کے laptop کے بجائے کسی server پر چل رہا ہو۔ کسی long-running session میں کام کرنے والے ایجنٹ، مثلاً tmux کے ساتھ VPS پر Claude Code workspace کے setup میں، اسے گزشتہ دن کی گفتگو یاد نہیں رہتی۔ repository ہی memory ہے۔ chat میں آپ نے جو کچھ سمجھایا اور commit نہیں کیا، وہ اگلے session تک ختم ہو جاتا ہے، اور DESIGN.md میں وہ وضاحت محفوظ ہوتی ہے تاکہ برقرار رہے۔

ان فیصلوں سے شروع کریں جن پر آپ بحث کرتے ہیں

پہلا ورژن بیس منٹ لیتا ہے۔ حالیہ pull requests میں سے وہ آخری کئی pull requests کھولیں جن میں کسی reviewer نے لکھا ہو: "نہیں، ہم یہاں اسے مختلف طریقے سے کرتے ہیں۔" ان میں سے ہر تبصرہ ایک ایسی invariant ہے جسے کبھی تحریری شکل نہیں دی گئی، اور ہر تبصرہ وہ مقام ہے جہاں agent وہی غلطی کسی انسان کے مقابلے میں زیادہ تیزی اور زیادہ مرتبہ کرے گا۔ جب یہ فائل آپ کے لیے ناکام ہو، تب اس میں اضافہ کریں؛ کسی مقررہ شیڈول کے مطابق نہیں۔ اگر آپ ابھی یہ طے کر رہے ہیں کہ عام development workflow میں agents کو کہاں شامل کیا جائے، تو AI agents سیکھنے کے لیے 2026 کی گائیڈ اگلا مناسب مرحلہ ہے۔

FAQ

کیا DESIGN.md ایک سرکاری معیار ہے؟

اس معنی میں نہیں جس معنی میں AGENTS.md ہے۔ AGENTS.md کا مرکزی مقام agents.md ہے، 60,000 سے زیادہ open source projects اسے استعمال کرتے ہیں، اور اس کی نگرانی Agentic AI Foundation کے پاس ہے، جو Linux Foundation کا حصہ ہے۔ August 2026 تک DESIGN.md کی کوئی نگران تنظیم یا شائع شدہ specification نہیں ہے۔ اس کی موجودہ حیثیت first-party adoption کی ہے: Vercel، Nuxt، Atlassian اور Resend سمیت سات companies اسے public URL پر شائع کرتی ہیں، جبکہ ایک community collection میں public sites سے reverse-engineer کی گئی مزید 73 files موجود ہیں۔ اسے ایک ایسی convention سمجھیں جسے آپ ابھی اپنا سکتے ہیں اور آزادانہ طور پر بڑھا سکتے ہیں، کیونکہ کوئی چیز آپ کے section names کی توثیق نہیں کرتی۔

کیا DESIGN.md کو صرف AGENTS.md کا ایک section ہونا چاہیے؟

چھوٹے repository کے لیے، ہاں۔ ایک ایسی file جسے agent یقینی طور پر پڑھتا ہو، ان دو files سے بہتر ہے جن میں سے ایک نظرانداز ہو جائے۔ انہیں اس وقت الگ کریں جب AGENTS.md کو تیزی سے scan کرنا مشکل ہو جائے، یا جب آپ دیکھیں کہ دونوں حصے مختلف رفتار سے تبدیل ہو رہے ہیں۔ AGENTS.md build تبدیل ہونے پر تبدیل ہوتی ہے۔ DESIGN.md کسی decision کے تبدیل ہونے پر تبدیل ہوتی ہے، جو کم ہوتا ہے اور زیادہ اہمیت رکھتا ہے۔ Files الگ کرتے وقت AGENTS.md میں ایک line شامل کریں جس میں agent کو code edit کرنے سے پہلے DESIGN.md پڑھنے کی ہدایت ہو، کیونکہ ہر tool root میں موجود ہر markdown file load نہیں کرتا۔

DESIGN.md، architecture decision record سے کیسے مختلف ہے؟

ADR (architecture decision record) ایک decision کا تاریخ کے ساتھ record ہوتا ہے، اور ایک صحت مند project میں ایسی درجنوں files ایک folder میں جمع ہو جاتی ہیں۔ یہ history ہوتی ہے، اور history load کرنا مہنگا ہوتا ہے، کیونکہ agent کو یہ معلوم کرنے کے لیے تمام files پڑھنا پڑیں گی کہ ان میں سے کون سی باتیں اب بھی درست ہیں۔ DESIGN.md موجودہ حالت بیان کرتی ہے اور اسے ہر task پر مکمل طور پر پڑھنے کے لیے لکھا جاتا ہے۔ اگر آپ پہلے ہی ADRs لکھتے ہیں تو دونوں رکھیں۔ ADR بتاتی ہے کہ کیا فیصلہ کیا گیا اور کب کیا گیا۔ DESIGN.md بتاتی ہے کہ آج کیا درست ہے، اور agent کو دکھانے کے لیے یہی file استعمال کریں۔

DESIGN.md کتنی طویل ہونی چاہیے؟

اتنی مختصر کہ ہر turn پر اسے پڑھنے سے افسوس نہ ہو۔ شائع شدہ مثالیں طویل ہیں، کیونکہ وہ ایک مکمل visual language کی specification دیتی ہیں: August 2026 تک Nuxt file تقریباً 2,100 words اور Vercel file تقریباً 6,500 words پر مشتمل ہے۔ ایک backend service کو عموماً اس سے بہت کم مواد درکار ہوتا ہے۔ ایک page سے شروع کریں، اور اسے صرف اس وقت بڑھائیں جب agent کوئی ایسی غلطی کرے جسے ایک جملہ روک سکتا تھا۔ طوالت معیار نہیں ہے۔ ہر line ایسی بات ہونی چاہیے جسے agent بصورتِ دیگر غلط کر دیتا۔