DESIGN.md फ़ाइल क्या है और इसे कैसे लिखें

DESIGN.md क्या है, और AGENTS.md में क्या शामिल नहीं है

DESIGN.md आपके रिपॉजिटरी रूट में मौजूद एक markdown फ़ाइल है जो AI कोडिंग एजेंट को यह बताती है कि कोड को इस तरह से क्यों बनाया गया है। AGENTS.md एक अलग सवाल का जवाब देता है: यहाँ काम कैसे करना है, जिसका मतलब है build कमांड, test कमांड, वह lint जो पास होना चाहिए, और वे paths जिन्हें नहीं छेड़ना है। DESIGN.md उन निर्णयों को रिकॉर्ड करता है जो पहले से तय हो चुके हैं, और यह बताता है कि उनमें से किसी एक को बदलने पर क्या खराब हो सकता है।

एक कोडिंग एजेंट, यानी Claude Code या Cursor जैसा टूल जो आपके रिपॉजिटरी को खुद पढ़ता और एडिट करता है, डिफ़ॉल्ट रूप से बहुत आत्मविश्वासी होता है। यदि उसे कोई ऐसा पैटर्न मिलता है जिसे वह नहीं पहचानता, तो वह उसे 'बेहतर' बनाने की कोशिश करता है। एक हाथ से लिखा हुआ cache, Redis (एक in-memory डेटा स्टोर) बन जाता है, क्योंकि मॉडल ने जितना भी कोड पढ़ा है, उसमें cache अक्सर ऐसा ही दिखता है। AGENTS.md इसे नहीं रोकता, क्योंकि make test दोनों ही स्थितियों में पास हो जाता है। जो नियम तोड़ा गया, वह कहीं भी ऐसा नहीं लिखा था जिसे एजेंट पढ़ सके।

यदि आपने अभी तक पहली फ़ाइल नहीं लिखी है, तो वहीं से शुरुआत करें। AGENTS.md और इसके साथ मौजूद HUMAN.md में इसके फॉर्मेट और इस बारे में जानकारी दी गई है कि प्रत्येक टूल इसे कहाँ खोजता है। इसके बाद का अध्याय वही है।

PUBLISHED DESIGN.md के अंदर वास्तव में क्या होता है

फॉर्मेट सीखने का सबसे तेज़ तरीका उन फाइलों को पढ़ना है जिन्हें कंपनियां अपने बारे में प्रकाशित करती हैं। रिपॉजिटरी official-design-md केवल उन्हीं को ट्रैक करती है। इसका समावेशन नियम (inclusion rule) एक पंक्ति का है, और वह पंक्ति ही इस संग्रह का मुख्य उद्देश्य है:

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

ये दोनों ही design system दस्तावेज़ हैं। वे बताते हैं कि किसी उत्पाद को कैसा दिखना चाहिए: रंग, टाइप, स्पेसिंग, मोशन। विषय-वस्तु से आगे बढ़कर पढ़ें, क्योंकि उपयोगी हिस्सा विषय के बजाय लेखन का स्वरूप है।

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 है। इसके नीचे उन चीजों की सूची है जिन्हें एक सक्षम जनरेटर तब चुनता है जब उसे ऐसा न करने के लिए नहीं कहा गया हो:

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 जो कमिट करने योग्य है, वह किसी न किसी डोमेन के लिए यही सूची है।

कंपनियां अपना खुद का DESIGN.md क्यों प्रकाशित करती हैं?

समुदाय ने इस दिशा में पहले ही कदम उठा लिया है। awesome-design-md में सार्वजनिक वेबसाइटों से रिवर्स-इंजीनियर की गई 73 फाइलें मौजूद हैं। प्रत्येक फाइल को नौ-खंडों वाले एक ही प्रारूप में लिखा गया है, ताकि किसी एजेंट को एक फाइल देकर उसके जैसा लुक तैयार किया जा सके। ये फाइलें उपयोगी हैं, लेकिन ये केवल अनुमान हैं। कंपनियों में से किसी ने भी इनकी समीक्षा नहीं की है।

फर्स्ट-पार्टी फाइल अलग होती है क्योंकि यह आउटपुट का विश्लेषण नहीं, बल्कि उसका स्रोत होती है। जब Vercel अपना टाइप स्केल बदलता है, तो vercel.com/design.md भी उसके साथ बदल जाता है। मार्च में स्क्रैप की गई एक कॉपी आपके एजेंट को पुराना स्केल ही सिखाती रहेगी, और आपके रिपॉजिटरी में ऐसी कोई चीज नहीं होगी जो आपको यह बताए कि वह कॉपी पुरानी हो चुकी है।

सात प्रकाशक एक छोटी संख्या है, और रिपॉजिटरी में भी यही कहा गया है: यह मानक नया है और आधिकारिक तौर पर इसे अपनाने वालों की संख्या बढ़ रही है। दोनों संग्रहों का रखरखाव VoltAgent द्वारा किया जाता है, जो एक ओपन सोर्स एजेंट फ्रेमवर्क है और अपनी खुद की फाइल भी प्रकाशित करता है। इसलिए, इस सूची को एक ट्रैकर के रूप में पढ़ें, न कि एक निष्पक्ष जनगणना के रूप में। फिर भी, यह देखने लायक है कि वे सात कौन हैं। ये वे कंपनियां हैं जिनका फ्रंट-एंड कोड अन्य डेवलपर्स सबसे अधिक कॉपी करते हैं, और उनकी फाइलें इस बात का उदाहरण बनती जा रही हैं कि DESIGN.md क्या है। AGENTS.md द्वारा अपनाए गए रास्ते की तुलना करें: agents.md में अब 60,000 से अधिक ओपन सोर्स प्रोजेक्ट्स इस प्रारूप का उपयोग कर रहे हैं, और इसका प्रबंधन Linux Foundation के अंतर्गत Agentic AI Foundation के पास है। एजेंट-पठनीय फाइलों के लिए कन्वेंशन तेजी से स्थापित हो रहे हैं, और वे शीर्ष स्तर से निर्धारित हो रहे हैं।

जब प्रोजेक्ट में कोई यूजर इंटरफेस न हो तो DESIGN.md में क्या शामिल करें

VPS पर चलने वाले अधिकांश सॉफ्टवेयर में निर्दिष्ट करने के लिए कोई विजुअल भाषा नहीं होती है। फिर भी यह फाइल महत्वपूर्ण है, क्योंकि इसका तंत्र रंगों से संबंधित नहीं है। यह उन बाधाओं (constraints) को लिखने के बारे में है जिनका उल्लंघन एक आत्मविश्वासी एडिटर अनजाने में कर सकता है।

Invariants (अपरिवर्तनीय नियम)। प्रत्येक के लिए एक वाक्य, जो यह बताए कि किसी भी बदलाव के बाद क्या सत्य बना रहना चाहिए। "प्रत्येक write queue.enqueue() के माध्यम से होनी चाहिए। डेटाबेस में सीधा write करने से ऑडिट लॉग छूट जाता है, और ऑडिट लॉग ही वह है जिसे कंप्लायंस एक्सपोर्ट पढ़ता है।" कारण के साथ लिखा गया एक invariant उस कार्य के दौरान भी सुरक्षित रहता है जिसकी आपने कल्पना नहीं की थी। केवल एक invariant एक प्राथमिकता (preference) की तरह लगता है, और प्राथमिकताओं को अक्सर ऑप्टिमाइज़ेशन के नाम पर हटा दिया जाता है।

Rejected alternatives (अस्वीकृत विकल्प)। स्पष्ट विकल्प, और यह क्यों खारिज किया गया। "हम कैशिंग के लिए Redis का उपयोग नहीं करते हैं। सर्विस एक सिंगल VPS पर चलती है, इसलिए इन-प्रोसेस मैप तेज है और यह एक कम डेमन है जिसे जीवित रखने की आवश्यकता है। जब दूसरा एप्लिकेशन सर्वर मौजूद हो, तब इस पर दोबारा विचार करें।" उस पैराग्राफ के बिना, यदि किसी एजेंट को कैश तेज करने के लिए कहा जाए तो वह Redis जोड़ देगा, और ऐसा करना सही भी होगा: आपने उसे बाधा के बारे में नहीं बताया था। यह वह सेक्शन है जो पूरी फाइल की सार्थकता सिद्ध करता है।

Boundaries (सीमाएं)। वे स्थान जहाँ एक छोटा सा बदलाव बड़ा प्रभाव (blast radius) डाल सकता है। डेटाबेस स्कीमा। वह पब्लिक रूट प्रीफिक्स जिसके खिलाफ ग्राहक पहले से ही स्क्रिप्टिंग कर रहे हैं। वह कॉन्फ़िगरेशन फाइल जिसे एप्लिकेशन शुरू होने से पहले एक डिप्लॉयमेंट पढ़ता है। वह क्रॉन एंट्री जो यह मानती है कि इसकी केवल एक कॉपी चलती है। इन्हें नाम दें, और बताएं कि प्रत्येक में बदलाव की क्या कीमत है। यदि एजेंट ओपन वेब तक भी पहुंच सकता है, जैसे कि सर्च बैकएंड के रूप में जुड़े एक सेल्फ-होस्टेड SearXNG इंस्टेंस के माध्यम से, तो यह भी एक ऐसी सीमा है जिसे लिखना सार्थक है, क्योंकि फाइल में यह स्पष्ट होना चाहिए कि कौन सा प्राप्त टेक्स्ट कोड को प्रभावित करने की अनुमति रखता है और कौन सा केवल आपको वापस कोट करने के लिए है।

Vocabulary (शब्दावली)। यदि कोड 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 (अस्वीकृत विकल्प), और बाकी को हेडिंग के रूप में छोड़ दें। चार ईमानदार पंक्तियों वाली एक फाइल पर्याप्त है। चालीस अनुमानित पंक्तियों वाली फाइल काम नहीं करती। यदि रिपॉजिटरी में कई पैकेज हैं, तो एक रूट फाइल सभी के लिए उपयुक्त नहीं होगी, और वही प्रति-निर्देशिका विभाजन जो monorepo में nested AGENTS.md फाइलों के लिए काम करता है, यहाँ भी लागू होता है: उन निर्णयों के लिए एक छोटी रूट फाइल जो सभी साझा करते हैं, और प्रत्येक पैकेज के बगल में एक छोटी फाइल जिसमें उसके अपने निर्णय होते हैं।

कुछ टूल्स रिपॉजिटरी रूट में मौजूद हर 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

Implementation details

Security considerations

एंटी-पैटर्न: एक DESIGN.md जो README को दोहराता है

सबसे आम खराब संस्करण पढ़ने में तो अच्छा लगता है, लेकिन कुछ सिखाता नहीं है। यह इस बात से शुरू होता है कि प्रोजेक्ट क्या करता है, फीचर्स की सूची देता है, इसे इंस्टॉल करने का तरीका बताता है, और लाइसेंस के साथ समाप्त होता है। इसकी हर पंक्ति पहले से ही README में मौजूद होती है, और इनमें से कोई भी यह नहीं बताती कि कोई चीज़ वैसी क्यों है जैसी वह है।

यह आपको दो बार नुकसान पहुँचाता है। पहली लागत संदर्भ (context) की है। जिस फाइल को एजेंट हर टास्क की शुरुआत में पढ़ता है, उसकी कीमत हर टास्क पर चुकानी पड़ती है, और एक डुप्लिकेट इंस्टॉलेशन सेक्शन एक निश्चित विंडो के मुकाबले पूरी तरह से ओवरहेड है। उस विंडो का बजट बनाना अपने आप में एक कौशल है, जिसे managing the context window in Claude Code में कवर किया गया है। संक्षिप्त में: जो कुछ भी स्वचालित रूप से लोड होता है, वह रिपॉजिटरी में सबसे अधिक मूल्यवान टेक्स्ट होना चाहिए।

दूसरी लागत और भी खराब है। एक ही कथन की दो प्रतियाँ समय के साथ अलग-अलग हो जाती हैं। README कहता है कि सर्विस 8080 पर लिसन करती है, DESIGN.md अभी भी 3000 कहता है, और एजेंट के पास एक को दूसरे से बेहतर मानने का कोई तरीका नहीं है, इसलिए वह एक को चुनता है और उसके इर्द-गिर्द कोड लिखता है। एक ऐसी फाइल जो कभी-कभी गलत होती है, उसे उसी भरोसे के साथ देखा जाता है जैसे कि हमेशा सही रहने वाली फाइल को।

इसका परीक्षण त्वरित है। यदि कोई पैराग्राफ README में आराम से फिट हो सकता है, तो उसे DESIGN.md से हटा दें। जो बचता है, वह वह हिस्सा होना चाहिए जिसे आप कोड रिव्यू के दौरान जोर से कहेंगे, वह हिस्सा जो "हमने पहले ही वह कोशिश कर ली है" से शुरू होता है।

आपको कैसे पता चलेगा कि फाइल काम कर रही है?

इसके लिए कोई linter नहीं है। एक जांच है जिसे आप एक मिनट में चला सकते हैं।

एजेंट को एक ऐसा कार्य दें जो सीधे किसी invariant (अपरिवर्तनीय नियम) का उल्लंघन करता हो। "एक background job जोड़ें जो stale rows को expired के रूप में चिह्नित करे।" जो फाइल अपना काम सही ढंग से कर रही है, वह किसी भी कोड से पहले उत्तर में दिखाई देगी: एजेंट को आपको बताना चाहिए कि job queue.enqueue() के माध्यम से लिखती है, क्योंकि सीधा write ऑपरेशन audit log को छोड़ देगा। यदि यह database connection खोलकर लिखता है, तो दो में से एक बात सच है। या तो फाइल बिल्कुल भी नहीं पढ़ी जा रही है, या invariant को इतनी ढिलाई से लिखा गया है कि उस पर बहस की जा सकती है।

token count पर भी नज़र रखें, क्योंकि यह फाइल हर turn पर लोड होती है। यदि DESIGN.md जोड़ने के बाद context का उपयोग बढ़ जाता है और उत्तर बेहतर नहीं होते हैं, तो फाइल में ऐसा विवरण है जो एजेंट के पास पहले से था। Claude Code में token counters को पढ़ना दिखाता है कि वह बजट कहाँ खर्च होता है।

यह तब सबसे महत्वपूर्ण होता है जब एजेंट आपके लैपटॉप के बजाय सर्वर पर रहता है। tmux के साथ VPS पर Claude Code workspace जैसे सेटअप में, लंबे समय तक चलने वाले session में काम करने वाले एजेंट को कल की बातचीत याद नहीं रहती। repository ही उसकी याददाश्त है। आपने चैट में जो कुछ भी समझाया और कभी commit नहीं किया, वह अगले session तक गायब हो जाता है, और DESIGN.md वह जगह है जहाँ वह स्पष्टीकरण सुरक्षित रहता है।

उन निर्णयों से शुरुआत करें जिन पर आप बहस करते हैं

पहला संस्करण तैयार करने में बीस मिनट लगते हैं। उन पिछली कई pull requests को खोलें जहाँ किसी reviewer ने लिखा था "नहीं, हम यहाँ इसे अलग तरह से करते हैं"। उन टिप्पणियों में से प्रत्येक एक ऐसा invariant है जिसे कभी लिखा नहीं गया था, और प्रत्येक वह स्थान है जहाँ एक agent वही गलती करेगा, किसी इंसान की तुलना में अधिक तेजी से और अधिक बार। जब यह आपको विफल करे, तब फाइल में जोड़ें, किसी तय समय-सारणी पर नहीं। यदि आप अभी भी यह तय कर रहे हैं कि एक सामान्य development workflow में agents कहाँ फिट होते हैं, तो AI agents सीखने के लिए 2026 की मार्गदर्शिका अगला उचित पड़ाव है।

FAQ

क्या DESIGN.md एक आधिकारिक मानक है?

AGENTS.md की तरह यह आधिकारिक नहीं है। AGENTS.md का अपना स्थान agents.md पर है, 60,000 से अधिक ओपन सोर्स प्रोजेक्ट्स इसका उपयोग करते हैं, और यह Linux Foundation के अंतर्गत Agentic AI Foundation द्वारा प्रबंधित है। अगस्त 2026 तक, DESIGN.md के लिए कोई शासी निकाय (governing body) या प्रकाशित विनिर्देश (specification) नहीं है। इसकी विशेषता इसका फर्स्ट-पार्टी एडॉप्शन है: Vercel, Nuxt, Atlassian और Resend सहित सात कंपनियां इसे एक सार्वजनिक URL पर प्रकाशित करती हैं, और एक कम्युनिटी कलेक्शन में सार्वजनिक साइटों से रिवर्स-इंजीनियर की गई 73 और फाइलें मौजूद हैं। इसे एक ऐसी परंपरा मानें जिसे आप अभी अपना सकते हैं और स्वतंत्र रूप से विस्तारित कर सकते हैं, क्योंकि आपके सेक्शन नामों को मान्य करने वाला कोई मानक नहीं है।

क्या DESIGN.md को केवल AGENTS.md का एक सेक्शन होना चाहिए?

एक छोटे रिपॉजिटरी के लिए, हाँ। एक ऐसी फाइल जिसे एजेंट निश्चित रूप से पढ़ता है, दो फाइलों से बेहतर है जिनमें से एक को अनदेखा कर दिया जाए। इन्हें तब अलग करें जब AGENTS.md को स्कैन करना कठिन हो जाए, या जब आप देखें कि दोनों हिस्से अलग-अलग गति से बदल रहे हैं। AGENTS.md तब बदलता है जब बिल्ड बदलता है। DESIGN.md तब बदलता है जब कोई निर्णय बदलता है, जो कि दुर्लभ है और अधिक महत्वपूर्ण है। जब आप इन्हें अलग करें, तो AGENTS.md में एक लाइन जोड़ें जो एजेंट को कोड संपादित करने से पहले DESIGN.md पढ़ने के लिए कहे, क्योंकि हर टूल रूट में मौजूद हर मार्कडाउन फाइल को लोड नहीं करता है।

DESIGN.md एक आर्किटेक्चर डिसीजन रिकॉर्ड (ADR) से कैसे अलग है?

एक ADR (architecture decision record) किसी एक निर्णय का दिनांकित रिकॉर्ड होता है, और एक स्वस्थ प्रोजेक्ट में एक फोल्डर के भीतर ऐसे दर्जनों रिकॉर्ड जमा हो जाते हैं। यह एक इतिहास है, और इतिहास को लोड करना महंगा होता है, क्योंकि एजेंट को यह पता लगाने के लिए कि कौन से निर्णय अभी भी मान्य हैं, उन सभी को पढ़ना होगा। DESIGN.md वर्तमान स्थिति है, जिसे हर कार्य पर पूरी तरह से पढ़ने के लिए लिखा गया है। यदि आप पहले से ही ADR लिखते हैं, तो दोनों को रखें। ADR बताता है कि क्या और कब निर्णय लिया गया था। DESIGN.md बताता है कि आज क्या सत्य है, और यही वह फाइल है जिसे आप एजेंट को रेफर करते हैं।

DESIGN.md कितना लंबा होना चाहिए?

इतना छोटा कि इसे हर टर्न पर बिना किसी संकोच के लोड किया जा सके। प्रकाशित उदाहरण लंबे हैं क्योंकि वे पूरी विजुअल भाषा को निर्दिष्ट करते हैं: अगस्त 2026 तक Nuxt फाइल लगभग 2,100 शब्दों की है और Vercel फाइल लगभग 6,500 शब्दों की। एक बैकएंड सर्विस को आमतौर पर इससे बहुत कम की आवश्यकता होती है। एक पेज से शुरुआत करें और इसे केवल तब बढ़ाएं जब एजेंट कुछ ऐसा गलत करे जिसे एक वाक्य से रोका जा सकता था। लंबाई इसका पैमाना नहीं है। हर लाइन ऐसी होनी चाहिए जिसे एजेंट अन्यथा गलत कर देता।