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 خود پڑھتا اور edit کرتا ہے۔ یہ agent default طور پر پُراعتماد ہوتا ہے۔ اسے کوئی ایسا 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 کے اندر اصل میں کیا ہوتا ہے

فارمیٹ سیکھنے کا تیز ترین طریقہ یہ ہے کہ وہ فائلیں پڑھی جائیں جو کمپنیاں اپنے بارے میں شائع کرتی ہیں۔ repository official-design-md صرف ایسی فائلوں کو track کرتی ہے۔ اس کی شمولیت کا اصول ایک سطر پر مشتمل ہے، اور یہی سطر اس مجموعے کا بنیادی مقصد ہے:

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۔ ہر فائل ایک مستقل public URL پر موجود ہے، اس لیے آپ ابھی terminal میں کوئی ایک فائل پڑھ سکتے ہیں۔

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

یہ دونوں design system documents ہیں۔ ان میں بتایا گیا ہے کہ کسی product کی ظاہری شکل کیسی ہونی چاہیے: رنگ، typography، spacing اور motion۔ موضوع سے آگے دیکھیں، کیونکہ مفید حصہ موضوع نہیں بلکہ تحریر کی ساخت ہے۔

Nuxt کی فائل تقریباً 2,100 الفاظ پر مشتمل ہے، اور اس کا بیشتر حصہ ایسی rule پر مشتمل ہے جس کے ساتھ اس کی وجہ بھی دی گئی ہے:

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.

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

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

کمیونٹی نے اس سمت میں پہلے کام شروع کر دیا تھا۔ awesome-design-md میں public websites سے reverse-engineer کی گئی 73 files شامل ہیں۔ ہر file اسی نو حصوں والے format میں لکھی گئی ہے، تاکہ کسی agent کو ایک file دکھا کر اس جیسا look تیار کروایا جا سکے۔ یہ files مفید ہیں، لیکن اب بھی اندازوں پر مبنی ہیں۔ متعلقہ کمپنیوں میں سے کسی نے ان کا جائزہ نہیں لیا۔

First-party file اس لیے مختلف ہوتی ہے کہ یہ output کی تشریح کے بجائے اصل source ہوتی ہے۔ جب Vercel اپنا type scale تبدیل کرتا ہے تو vercel.com/design.md بھی اس کے ساتھ تبدیل ہوتی ہے۔ مارچ میں scrape کی گئی copy آپ کے agent کو پرانا scale سکھاتی رہتی ہے، اور repository میں کوئی چیز یہ نہیں بتاتی کہ copy پرانی ہو چکی ہے۔

سات publishers کی تعداد کم ہے، اور repository بھی یہی بات کہتی ہے: standard نیا ہے اور official adoption بڑھ رہی ہے۔ دونوں collections کو VoltAgent maintain کرتا ہے۔ یہ ایک open source agent framework ہے جو اپنی file بھی publish کرتا ہے۔ اس لیے اس list کو neutral census کے بجائے tracker سمجھیں۔ پھر بھی اس پر نظر رکھنا مفید ہے، کیونکہ یہ سات publishers کون ہیں۔ یہ وہ کمپنیاں ہیں جن کا front-end code دوسرے developers سب سے زیادہ copy کرتے ہیں، اور ان کی files اس بات کی عملی مثال بن رہی ہیں کہ DESIGN.md کیا ہوتی ہے۔ AGENTS.md نے جو راستہ اختیار کیا، اس کا موازنہ کریں: agents.md کے format کو اب 60,000 سے زیادہ open source projects استعمال کر رہے ہیں، اور اس کی stewardship Linux Foundation کے تحت Agentic AI Foundation کے پاس ہے۔ Agents کے لیے قابلِ مطالعہ files کے conventions تیزی سے طے ہو رہے ہیں، اور یہ عمل بڑی کمپنیوں کی قیادت میں ہو رہا ہے۔

جب پروجیکٹ میں user interface نہ ہو تو DESIGN.md میں کیا شامل کریں

VPS پر چلنے والے زیادہ تر سافٹ ویئر کے لیے کوئی visual language متعین کرنے کی ضرورت نہیں ہوتی۔ پھر بھی یہ فائل اپنی اہمیت برقرار رکھتی ہے، کیونکہ اس کا تعلق رنگوں سے نہیں ہے۔ اس کا مقصد وہ constraints تحریر کرنا ہے جن کی خلاف ورزی ایک پراعتماد editor بصورتِ دیگر انجانے میں کر سکتا ہے۔

Invariants

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

مسترد شدہ متبادل

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

حدود

وہ مقامات درج کریں جہاں چھوٹی سی edit کا اثر بہت وسیع ہو سکتا ہے۔ Database schema۔ Public route prefix جس کے خلاف customers پہلے ہی scripts چلا رہے ہیں۔ وہ config file جسے application start ہونے سے پہلے deploy پڑھتا ہے۔ وہ cron entry جو فرض کرتی ہے کہ اس کی صرف ایک copy چل رہی ہے۔ ان کی نشان دہی کریں اور بتائیں کہ ہر ایک میں تبدیلی کی کیا لاگت ہوگی۔ اگر agent open web تک بھی رسائی رکھتا ہے، مثلاً search backend کے طور پر configured self-hosted SearXNG instance کے ذریعے، تو یہ بھی ایسی boundary ہے جسے تحریر کرنا چاہیے، کیونکہ فائل میں واضح ہونا چاہیے کہ fetched text میں سے کون سا حصہ code پر اثر انداز ہو سکتا ہے اور کون سا صرف آپ کو واپس quote کیا جا سکتا ہے۔

اصطلاحات

اگر code میں tenant لکھا جاتا ہے اور team 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 کے طور پر چھوڑ دیں۔ چار دیانت دار سطروں والی فائل مفید ہے، جبکہ اندازے سے لکھی گئی چالیس سطروں والی فائل مفید نہیں۔ اگر repository میں متعدد packages ہوں تو ایک root فائل سب کے لیے موزوں نہیں ہوگی۔ یہاں بھی وہی per-directory تقسیم استعمال کریں جو monorepo میں nested AGENTS.md files کے لیے مؤثر ہے: ان فیصلوں کے لیے ایک مختصر root فائل جو تمام packages میں مشترک ہوں، اور ہر ایسے package کے ساتھ ایک چھوٹی فائل جس کے اپنے فیصلے ہوں۔

کچھ tools repository root میں موجود ہر markdown فائل load کرتے ہیں، جبکہ کچھ صرف وہ فائل load کرتے ہیں جس کا انہیں نام دیا گیا ہو۔ اس لیے یہ فرض نہ کریں۔ 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 ہے۔ agent ہر task کے آغاز پر جو file پڑھتا ہے، اس کی قیمت ہر task میں ادا ہوتی ہے، اور duplicated install section ایک محدود window میں خالص اضافی بوجھ ہوتا ہے۔ اس window کا بجٹ بنانا اپنی جگہ ایک skill ہے، جس کی وضاحت Claude Code میں context window کا انتظام میں کی گئی ہے۔ مختصر بات یہ ہے: جو متن خودکار طور پر load ہوتا ہے، repository میں اس کی value سب سے زیادہ ہونی چاہیے۔

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

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

فائل کے درست کام کرنے کا کیسے پتا چلتا ہے؟

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

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

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

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

جن فیصلوں پر آپ کے درمیان اختلاف ہوتا ہے، ان سے شروع کریں

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

FAQ

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

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

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

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

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

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

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

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