SSD Nodes Learn Hosting plans →
मार्गदर्शक Matt Connorद्वारे Matt Connor · अपडेटेड 2026-10-30

DESIGN.md: AGENTS.md नंतरची महत्त्वाची फाइल

AGENTS.md agent ला कसे काम करायचे ते सांगते; DESIGN.md code ची रचना का अशी आहे हे स्पष्ट करते, त्यामुळे ठरवलेले decisions पुन्हा बदलले जात नाहीत.

DESIGN.md म्हणजे काय आणि AGENTS.md मध्ये काय समाविष्ट नसते

DESIGN.md ही तुमच्या repository च्या root मध्ये असलेली markdown file आहे. code ची रचना अशी का आहे, हे ती AI coding agent ला सांगते. AGENTS.md वेगळ्या प्रश्नाचे उत्तर देते: येथे कसे काम करायचे. यामध्ये build command, test command, पास होणे आवश्यक असलेले lint आणि ज्या paths मध्ये बदल करू नयेत ते समाविष्ट असतात. DESIGN.md मध्ये आधीच निश्चित केलेले decisions आणि त्यापैकी एखादा decision बदलल्यास काय बिघडते, याची नोंद असते.

Coding agent म्हणजे तुमचे repository स्वतः वाचून त्यात बदल करणारे Claude Code किंवा Cursor सारखे tool. ते default ने आत्मविश्वासाने काम करते. त्याला अपरिचित pattern आढळल्यास ते pattern सुधारण्याचा प्रयत्न करते. Hand-written cache चे रूपांतर Redis मध्ये होते. Redis हा in-memory data store आहे. कारण model ने वाचलेल्या बहुतेक code मध्ये cache अशाच प्रकारे दिसतो. AGENTS.md हे थांबवू शकत नाही, कारण make test दोन्ही प्रकारे pass होते. मोडलेला rule असा होता की agent वाचू शकेल अशा कोणत्याही ठिकाणी तो लिहिलेला नव्हता.

तुम्ही पहिली file अजून लिहिली नसेल, तर तिथून सुरुवात करा. त्याच्या शेजारी असलेली AGENTS.md आणि HUMAN.md format आणि प्रत्येक tool ती file कुठे शोधते, हे स्पष्ट करतात. यानंतरचा भाग त्या chapter नंतरचा आहे.

प्रकाशित DESIGN.md मध्ये प्रत्यक्षात काय असते

हा format समजून घेण्याचा सर्वात जलद मार्ग म्हणजे कंपन्या स्वतःबद्दल प्रकाशित केलेल्या files वाचणे. official-design-md repository मध्ये फक्त अशाच files चा मागोवा घेतला जातो. त्याचा समावेश नियम एका ओळीत आहे, आणि ती ओळच या collection चा मुख्य उद्देश स्पष्ट करते:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

October 2026 पर्यंत त्यात अकरा नावे आहेत: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel आणि VoltAgent. प्रत्येक file public URL वर उपलब्ध आहे. त्यांपैकी बहुतेक publisher च्या स्वतःच्या domain वर आहेत आणि उर्वरित public GitHub repository मध्ये आहेत. त्यामुळे तुम्ही आत्ताच terminal मध्ये एखादी file वाचू शकता.

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

ही दोन्ही design system documents आहेत. त्यात product कसे दिसावे हे वर्णन केले आहे: colour, type, spacing आणि motion. विषयाकडे न थांबता लिखाणाची रचना समजून घ्या. उपयुक्त भाग विषय नसून लिखाणाचा format आहे.

October 27, 2026 पर्यंत Nuxt file मध्ये साधारण 2,000 words आहेत. तिच्या बहुतेक भागात कारणासह दिलेला rule आहे. सुरुवातीला dark mode हा default theme असल्याचे सांगितले आहे. त्यात brand green #00DC82 दिला आहे आणि brand colours बाबत ही नोंद आहे: "Logos, social images, and print साठी. UI code मध्ये त्यांचा raw values म्हणून वापर करू नका." शेवटच्या भागाजवळ Reject these या heading चा section आहे. त्यात पुढील मजकूर आहे:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

October 2026 पर्यंत Vercel file अधिक मोठी असून तिच्यात साधारण 6,000 words आहेत. ती यापेक्षा एक पाऊल पुढे जाते. तिच्या headings पैकी एक heading Reject generated-design reflexes आहे. त्याखाली, कोणीही वापरू नका असे सांगितले नसताना सक्षम generator कोणत्या गोष्टी वापरतो याची list आहे:

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 ची व्याख्या केली आहे. सक्षम model ने तयार केलेल्या default गोष्टींची ही लिखित list असते. Model ने त्या गोष्टी तयार करणे थांबवावे म्हणून ही list प्रकाशित केली जाते. Commit करण्यास योग्य प्रत्येक DESIGN.md ही एखाद्या domain साठीची अशीच list असते.

कंपन्या स्वतःचे DESIGN.md का प्रकाशित करतात?

समुदायाने ही सुरुवात आधीच केली होती. awesome-design-md मध्ये सार्वजनिक वेबसाइटवरून संकलित केलेल्या 84 फाइल्स आहेत. 27 October 2026 रोजी README मधील मोजणीनुसार ही संख्या आहे. प्रत्येक फाइल त्याच नऊ-विभागांच्या स्वरूपात लिहिलेली आहे. त्यामुळे एखाद्या agent ला ती फाइल दाखवून त्याच्यासारखा look तयार करता येतो. या फाइल्स उपयुक्त आहेत, पण त्या अजूनही अंदाजांवर आधारित आहेत. त्यांचे पुनरावलोकन संबंधित कंपन्यांमधील कोणीही केलेले नाही.

first-party फाइल वेगळी असते, कारण ती output चे वाचन नसून मूळ source असते. Vercel ने type scale बदलल्यास vercel.com/design.md देखील त्यासोबत बदलते. March मध्ये scraped केलेली copy तुमच्या agent ला जुना scale शिकवत राहते. तुमच्या repository मध्ये ती copy stale झाली आहे, असे सांगणारे काहीही नसते.

अकरा publishers ही अजूनही लहान संख्या आहे आणि repository मध्येही ते स्पष्टपणे नमूद केले आहे: standard नवीन आहे आणि अधिकृत adoption वाढत आहे. दोन्ही collections ची देखभाल VoltAgent करते. VoltAgent हे open source agent framework आहे आणि ते स्वतःची फाइलही प्रकाशित करते. त्यामुळे ही यादी neutral census म्हणून नव्हे, तर tracker म्हणून वाचा. तरीही ही यादी लक्ष ठेवण्यासारखी आहे, कारण त्यातील कंपन्या महत्त्वाच्या आहेत. इतर developers ज्या कंपन्यांचा front-end code सर्वाधिक copy करतात, त्यांपैकी अनेक कंपन्या यात आहेत. तसेच नवीन entries — Ant Design, Microsoft FAST, Juspay आणि Oxide Computer — ही इतर teams ज्या design systems वर आधारित काम करतात अशी systems आहेत. DESIGN.md म्हणजे काय, याचे worked example त्यांच्या फाइल्स बनत आहेत. AGENTS.md ने घेतलेला मार्ग तुलना करण्यासारखा आहे: agents.md स्वरूप वापरणाऱ्या open source projects ची संख्या आता 60,000 पेक्षा जास्त आहे. तसेच त्याची stewardship Linux Foundation अंतर्गत Agentic AI Foundation कडे आहे. DESIGN.md नेही त्याच मार्गावर सुरुवात केली आहे. 21 April 2026 रोजी Google ने या स्वरूपासाठी draft specification open source केली. ती google-labs-code/design.md म्हणून प्रकाशित करण्यात आली असून त्यात token schema आणि Apache-2.0 licence अंतर्गत CLI आहे. October 2026 पर्यंत हे स्वरूप alpha version वर आहे आणि अजूनही active development मध्ये आहे. त्याची देखभाल neutral foundation ऐवजी Google Labs करते. तसेच ते visual identity चे वर्णन करते. त्यामुळे backend file ला आवश्यक असलेल्या invariants विषयी त्यात काहीही सांगितलेले नाही. Agent-readable files साठीच्या conventions जलद गतीने स्थिर होत आहेत आणि ही दिशा वरच्या स्तराकडून ठरत आहे.

प्रकल्पाला user interface नसल्यास DESIGN.md मध्ये काय लिहावे

VPS वर चालणाऱ्या बहुतांश software साठी visual language निर्दिष्ट करण्याची गरज नसते. तरीही या file चे स्थान कायम राहते, कारण तिचा उपयोग colour शी संबंधित नाही. आत्मविश्वासाने काम करणारा editor नकळत ज्या constraints चे उल्लंघन करू शकतो, त्या constraints लिहून ठेवणे हा तिचा उद्देश आहे.

Invariants

प्रत्येक invariant एका वाक्यात लिहा. प्रत्येक edit नंतरही कोणती गोष्ट सत्य राहिली पाहिजे ते त्यात सांगा. “प्रत्येक write queue.enqueue() मधूनच जाते. थेट database write केल्यास audit log वगळला जातो, आणि compliance export audit log मधून data वाचतो.” कारणासह लिहिलेला invariant तुम्ही अपेक्षित न केलेल्या task मध्येही टिकतो. कारण नसलेला invariant केवळ preference वाटतो, आणि preferences अनेकदा काढून टाकल्या जातात.

Rejected alternatives

सहज सुचणारा पर्याय कोणता होता आणि तो का नाकारला, हे लिहा. “Caching साठी Redis वापरत नाही. Service एकाच VPS वर चालते, त्यामुळे in-process map अधिक वेगवान आहे आणि चालू ठेवण्यासाठी एक daemon कमी आहे. दुसरा application server उपलब्ध झाल्यावर या निर्णयाचा पुनर्विचार करा.” हा परिच्छेद नसल्यास cache अधिक वेगवान करण्यास सांगितलेल्या agent कडून Redis जोडले जाईल. ते योग्यच ठरेल, कारण constraint त्याला सांगितलेले नाही. हा section संपूर्ण file चे प्रयोजन सिद्ध करतो.

Boundaries

लहान edit मुळे मोठा परिणाम होऊ शकतो अशी ठिकाणे नमूद करा. Database schema. ग्राहक आधीपासून scripts मध्ये वापरत असलेला public route prefix. Application सुरू होण्यापूर्वी deploy कडून वाचली जाणारी config file. फक्त एकच copy चालू आहे असे गृहीत धरणारी cron entry. प्रत्येकाचे नाव लिहा आणि त्यात बदल केल्यास काय परिणाम होतो ते सांगा. Agent ला open web वरही प्रवेश मिळत असल्यास, search backend म्हणून जोडलेले self-hosted SearXNG instance मार्फत, तीदेखील लिहून ठेवण्यासारखी boundary आहे. कारण कोणत्या fetched text मुळे code वर परिणाम होऊ शकतो आणि कोणता text केवळ तुम्हाला परत उद्धृत करता येतो, हे file मध्ये स्पष्ट असले पाहिजे.

Vocabulary

Code मध्ये tenant आणि team मध्ये customer असे शब्द वापरले जात असल्यास त्यांचे mapping लिहून ठेवा. येथे चुकीचा अंदाज लावणारा agent वाचायला योग्य पण चुकीच्या संकल्पनेचे code तयार करू शकतो. 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 file त्या सर्वांसाठी योग्य ठरणार नाही. अशा वेळी monorepo मधील nested AGENTS.md files साठी उपयुक्त असलेली directory-निहाय विभागणी येथेही लागू होते: सर्व packages साठी समान असलेल्या निर्णयांसाठी छोटी root file, आणि स्वतःचे निर्णय असलेल्या प्रत्येक package च्या बाजूला आणखी छोटी file.

काही tools repository root मधील प्रत्येक markdown file load करतात, तर काही फक्त त्यांना सांगितलेली file load करतात. त्यामुळे असे गृहीत धरू नका. AGENTS.md मध्ये एक pointer जोडा:

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

प्रतिरूप-विरोधी पद्धत: README ची पुनरावृत्ती करणारी DESIGN.md

सर्वाधिक आढळणारी चुकीची आवृत्ती वाचायला चांगली असते, पण काहीही शिकवत नाही. ती प्रकल्प काय करतो यापासून सुरुवात करते, वैशिष्ट्यांची यादी देते, ते कसे install करायचे हे स्पष्ट करते आणि licence ने समाप्त होते. यातील प्रत्येक गोष्ट आधीच README मध्ये आहे. यापैकी कोणतीही गोष्ट एखादी बाब अशी का आहे, हे सांगत नाही.

यासाठी तुम्हाला दोनदा किंमत मोजावी लागते. पहिली किंमत म्हणजे context. प्रत्येक task च्या सुरुवातीला agent वाचत असलेल्या file साठी प्रत्येक task वेळी खर्च होतो. निश्चित window मध्ये duplicated install section हा पूर्णपणे अनावश्यक भार असतो. त्या window चे नियोजन करणे हे स्वतः एक कौशल्य आहे; त्याची माहिती Claude Code मधील context window चे व्यवस्थापन येथे दिली आहे. थोडक्यात: आपोआप load होणारा मजकूर repository मधील सर्वाधिक उपयुक्त मजकूर असावा.

दुसरी किंमत अधिक गंभीर आहे. एकाच विधानाच्या दोन प्रती कालांतराने वेगळ्या होतात. README मध्ये service 8080 वर ऐकते असे म्हटलेले असते, DESIGN.md मध्ये अजूनही 3000 लिहिलेले असते, आणि agent कडे यांपैकी कोणत्या विधानाला प्राधान्य द्यायचे याचा कोणताही मार्ग नसतो. त्यामुळे तो एक विधान निवडतो आणि त्याभोवती code लिहितो. कधीकधी चुकीची असणारी file नेहमी बरोबर असणाऱ्या file इतक्याच विश्वासाने तपासली जाते.

ही चाचणी जलद आहे. एखादा परिच्छेद README मध्ये सहज बसत असेल, तर तो DESIGN.md मधून काढून टाका. उरलेला भाग असा असावा, जो तुम्ही code review मध्ये स्पष्टपणे सांगाल; ज्याची सुरुवात "आम्ही हे आधीच करून पाहिले आहे" अशी होते.

फाइल कार्यरत आहे हे कसे समजते?

यासाठी linter उपलब्ध नाही. मात्र एका मिनिटात चालवता येणारी एक तपासणी आहे.

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

Token count वरही लक्ष ठेवा, कारण ही फाइल प्रत्येक turn वर load होते. DESIGN.md जोडल्यानंतर context usage वाढला आणि उत्तरे अधिक चांगली झाली नाहीत, तर agent ला आधीपासून माहीत असलेला मजकूर फाइलमध्ये पुन्हा लिहिला आहे. Claude Code मधील token counters वाचणे या प्रक्रियेत तो budget कुठे वापरला जातो हे दाखवते.

Agent तुमच्या laptop ऐवजी server वर चालत असेल, तेव्हा हे सर्वाधिक महत्त्वाचे ठरते. tmux सह VPS वरील Claude Code workspace सारख्या दीर्घकाळ चालणाऱ्या session मध्ये काम करणाऱ्या agent कडे मागील दिवसाच्या संभाषणाची स्मृती नसते. Repository हीच स्मृती असते. Chat मध्ये तुम्ही स्पष्ट केलेली आणि commit न केलेली प्रत्येक गोष्ट पुढील session पर्यंत नाहीशी होते. ती माहिती टिकून राहावी यासाठी DESIGN.md मध्ये नोंद केली जाते.

ज्या निर्णयांवर तुम्ही वारंवार चर्चा करता, त्यांपासून सुरुवात करा

पहिली आवृत्ती तयार करण्यासाठी वीस मिनिटे लागतात. अलीकडील pull requests पैकी शेवटची काही उघडा, ज्यामध्ये reviewer ने "no, we do it differently here" असे लिहिले आहे. यापैकी प्रत्येक टिप्पणी ही लिहून न ठेवलेली invariant आहे. तसेच, प्रत्येक ठिकाणी agent माणसापेक्षा अधिक वेगाने आणि अधिक वेळा तीच चूक करेल. जेव्हा ही फाइल तुमच्यासाठी अपयशी ठरते, तेव्हा त्यात भर घाला. हे ठरावीक वेळापत्रकानुसार करू नका. सामान्य development workflow मध्ये agents कुठे समाविष्ट करायचे हे तुम्ही अजून ठरवत असाल, तर AI agents शिकण्यासाठी 2026 चे मार्गदर्शक हा पुढील योग्य स्रोत ठरू शकतो.

FAQ

DESIGN.md अधिकृत मानक आहे का?

AGENTS.md ज्याप्रमाणे अधिकृत मानक आहे, त्याप्रमाणे नाही. AGENTS.md साठी agents.md हे अधिकृत संकेतस्थळ आहे, 60,000 पेक्षा अधिक open source प्रकल्प त्याचा वापर करतात आणि Linux Foundation च्या Agentic AI Foundation अंतर्गत त्याचे stewardship केले जाते. DESIGN.md ची प्रकाशित specification आहे; परंतु तिचे neutral steward नाही. Google ने 21 April 2026 रोजी draft specification open source केली. ती Apache-2.0 licence अंतर्गत google-labs-code/design.md repository मध्ये उपलब्ध आहे. October 2026 पर्यंत ती alpha version मध्ये असून तिचा सक्रिय विकास सुरू आहे. त्यात visual identity चे वर्णन आहे: colours, typography, layout आणि components. DESIGN.md चा first-party adoption देखील आहे: Vercel, Nuxt, Atlassian आणि Resend यांसह eleven companies आणि projects एक DESIGN.md प्रकाशित करतात. October 27, 2026 पर्यंत community collection मध्ये public sites मधून घेतलेल्या आणखी 84 प्रती होत्या. Backend file मध्ये invariants आणि नाकारलेले alternatives ठेवायचे असल्यास, DESIGN.md ला आता स्वीकारता येणारी आणि मुक्तपणे विस्तारित करता येणारी convention माना. कारण त्या section names साठी कोणतीही specification नाही.

DESIGN.md हा फक्त AGENTS.md मधील एक section असावा का?

लहान repository साठी, होय. Agent नक्की वाचतो अशी एक file, agent दुर्लक्षित करू शकतो अशा दोन files पेक्षा चांगली असते. AGENTS.md पटकन scan करता येत नाही असे दिसू लागल्यास, किंवा दोन्ही भाग वेगवेगळ्या दराने बदलत असल्याचे जाणवल्यास, त्यांना वेगळे करा. Build बदलल्यावर AGENTS.md बदलतो. एखादा decision बदलल्यावर DESIGN.md बदलतो. असे बदल कमी वेळा होतात आणि त्यांचे महत्त्व अधिक असते. Files वेगळ्या करताना AGENTS.md मध्ये agent ने code edit करण्यापूर्वी DESIGN.md वाचावे, अशी एक line जोडा. कारण प्रत्येक tool root मधील प्रत्येक markdown file load करत नाही.

DESIGN.md आणि architecture decision record मध्ये काय फरक आहे?

ADR (architecture decision record) हा एका decision ची date सहित नोंद असतो. सक्षम project मध्ये अशा अनेक नोंदी एका folder मध्ये साठत जातात. हा इतिहास असतो. हा इतिहास load करणे खर्चिक असते, कारण कोणते decisions अजूनही लागू आहेत हे ठरवण्यासाठी agent ला त्या सर्व नोंदी वाचाव्या लागतील. DESIGN.md ही वर्तमान स्थिती असते. प्रत्येक task वेळी पूर्णपणे वाचता यावी, अशा पद्धतीने ती लिहिलेली असते. तुम्ही आधीपासून ADRs लिहित असल्यास, दोन्ही ठेवा. ADR मध्ये काय आणि कधी ठरवले ते सांगितले जाते. DESIGN.md मध्ये आजची सत्य स्थिती सांगितली जाते. Agent ला दाखवायची file DESIGN.md हीच असते.

DESIGN.md किती लांब असावी?

प्रत्येक turn वेळी सहज load करता येईल इतकी संक्षिप्त असावी. प्रकाशित examples लांब आहेत, कारण त्यात संपूर्ण visual language निर्दिष्ट केलेली असते: October 2026 पर्यंत Nuxt file मध्ये अंदाजे 2,000 words आणि Vercel file मध्ये अंदाजे 6,000 words आहेत. Backend service साठी सहसा यापेक्षा खूप कमी मजकूर पुरतो. एका page पासून सुरुवात करा. एखाद्या agent कडून अशी चूक झाल्यावरच ती वाढवा, जी एकाच sentence ने टाळता आली असती. Length हे मोजमाप नाही. प्रत्येक line अशी असावी की ती नसती तर agent कडून अन्यथा चूक झाली असती.

हा लेख उपयुक्त होता का?