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 इसके फॉर्मेट और इस बात को कवर करता है कि प्रत्येक टूल इसे कहाँ खोजता है। इसके बाद जो है, वह उस अध्याय का अगला भाग है।

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

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 अपना type scale बदलता है, तो vercel.com/design.md भी उसके साथ बदल जाता है। मार्च में स्क्रैप की गई एक कॉपी आपके एजेंट को पुराना स्केल ही सिखाती रहेगी, और आपके रिपॉजिटरी में ऐसी कोई चीज नहीं होगी जो आपको बताए कि वह कॉपी पुरानी हो चुकी है।

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

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

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

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

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

Boundaries (सीमाएं)। वे स्थान जहाँ एक छोटा सा संपादन बड़े पैमाने पर प्रभाव डाल सकता है। डेटाबेस स्कीमा। वह public route prefix जिसके विरुद्ध ग्राहक पहले से ही स्क्रिप्टिंग कर रहे हैं। वह config file जिसे एप्लिकेशन शुरू होने से पहले एक deploy पढ़ता है। वह cron entry जो यह मानती है कि इसकी केवल एक ही कॉपी चल रही है। उन्हें नाम दें, और बताएं कि प्रत्येक में बदलाव करने की क्या कीमत है।

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.

उन दो sections को भरें जिन्हें आप आज memory से लिख सकते हैं, यानी invariants और rejected alternatives, और बाकी को headings के रूप में छोड़ दें। चार ईमानदार पंक्तियों वाली फाइल भी काम करती है। चालीस अनुमानित पंक्तियों वाली फाइल काम नहीं करती।

कुछ 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) की है। जिस फाइल को एजेंट हर कार्य की शुरुआत में पढ़ता है, उसकी कीमत हर कार्य पर चुकानी पड़ती है, और एक डुप्लिकेट इंस्टॉलेशन सेक्शन एक निश्चित विंडो के मुकाबले पूरी तरह से ओवरहेड है। उस विंडो का बजट बनाना अपने आप में एक कौशल है, जिसे 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 जैसे सेटअप में, लंबे समय तक चलने वाले सत्र में काम करने वाले एजेंट को कल की बातचीत याद नहीं रहती। Repository ही उसकी याददाश्त है। आपने चैट में जो कुछ भी समझाया और कभी commit नहीं किया, वह अगले सत्र तक गायब हो जाता है, और 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 (आर्किटेक्चर डिसीजन रिकॉर्ड) एक निर्णय का दिनांकित रिकॉर्ड है, और एक स्वस्थ प्रोजेक्ट में एक फोल्डर के भीतर ऐसे दर्जनों रिकॉर्ड जमा हो जाते हैं। यह एक इतिहास है, और इतिहास को लोड करना महंगा होता है, क्योंकि एजेंट को यह पता लगाने के लिए कि कौन से निर्णय अभी भी मान्य हैं, उन सभी को पढ़ना होगा। DESIGN.md वर्तमान स्थिति है, जिसे हर कार्य पर पूरा पढ़ने के लिए लिखा गया है। यदि आप पहले से ही ADR लिखते हैं, तो दोनों को रखें। ADR बताता है कि क्या तय किया गया था और कब। DESIGN.md बताता है कि आज क्या सच है, और यही वह फाइल है जिसे आप एजेंट को रेफर करते हैं।

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

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