DESIGN.md: AGENTS.md नंतरची आवश्यक फाइल

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

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

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

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

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

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

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 documents आहेत. एखादे 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.

हे वाक्य या file type ची व्याख्या करते. आत्मविश्वासाने काम करणारे model तयार करते त्या defaults ची ही लिखित यादी असते. Model ने ते defaults तयार करणे थांबवावे म्हणून ही यादी प्रकाशित केली जाते. Commit करण्यास योग्य असलेली प्रत्येक DESIGN.md एखाद्या domain साठी अशीच यादी असते.

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

समुदायाने ही सुरुवात आधीच केली होती. awesome-design-md मध्ये सार्वजनिक वेबसाइट्सवरून रिव्हर्स-इंजिनिअर केलेल्या 73 फाइल्स आहेत. प्रत्येक फाइल त्याच नऊ-विभागीय स्वरूपात लिहिलेली आहे. त्यामुळे एजंटला त्यापैकी एखाद्या फाइलकडे निर्देश करून त्यासारखे दिसणारे डिझाइन तयार करता येते. या फाइल्स उपयुक्त आहेत, परंतु त्या अजूनही अंदाजांवर आधारित आहेत. संबंधित कंपन्यांमधील कोणीही त्यांचे पुनरावलोकन केलेले नाही.

फर्स्ट-पार्टी फाइल वेगळी असते, कारण ती आउटपुटच्या वाचनाऐवजी त्याचा स्रोत असते. Vercel ने त्याचा टाइप स्केल बदलला, तर vercel.com/design.md देखील त्यासोबत बदलते. March मध्ये स्क्रॅप केलेली प्रत तुमच्या एजंटला जुना स्केल शिकवत राहते. तुमच्या repository मधील कोणतीही गोष्ट ती प्रत कालबाह्य झाली आहे असे सांगत नाही.

सात प्रकाशकांची संख्या कमी आहे आणि repository मध्येही तेच नमूद केले आहे: हे standard नवीन आहे आणि अधिकृत स्वीकार वाढत आहे. दोन्ही संग्रहांची देखभाल VoltAgent करते. VoltAgent हे open source agent framework असून ते स्वतःची फाइलही प्रकाशित करते. त्यामुळे या यादीकडे तटस्थ जनगणना म्हणून नव्हे, तर प्रगतीचा मागोवा घेणारे साधन म्हणून पाहा. तरीही ही यादी पाहणे महत्त्वाचे आहे, कारण त्या सात कंपन्या कोण आहेत. इतर विकासक ज्या कंपन्यांचा front-end code सर्वाधिक कॉपी करतात, त्या याच कंपन्या आहेत. त्यांच्या फाइल्स DESIGN.md काय असते याचे प्रत्यक्ष उदाहरण बनत आहेत. AGENTS.md ने घेतलेला मार्ग तुलना करण्यासारखा आहे: agents.md आता हे स्वरूप वापरणाऱ्या 60,000 पेक्षा अधिक open source projects ची नोंद करते. या प्रकल्पांची देखरेख Linux Foundation अंतर्गत Agentic AI Foundation कडे आहे. एजंटला वाचता येणाऱ्या फाइल्ससाठीच्या प्रथा वेगाने निश्चित होत आहेत आणि या प्रथा अग्रगण्य संस्थांकडून निश्चित होत आहेत.

वापरकर्ता इंटरफेस नसलेल्या प्रकल्पातील DESIGN.md मध्ये काय असावे

VPS वर चालणाऱ्या बहुतेक सॉफ्टवेअरमध्ये निर्दिष्ट करण्यासाठी दृश्य शैली नसते. तरीही ही फाइल उपयुक्त ठरते, कारण तिचा संबंध रंगांशी नसतो. एखादा जाणकार संपादक नकळत मोडू शकतो अशा मर्यादा स्पष्टपणे लिहून ठेवणे हा तिचा उद्देश असतो.

अपरिवर्तनीय नियम. प्रत्येक नियम एका वाक्यात लिहा आणि कोणत्याही संपादनानंतर काहीतरी सत्य राहिलेच पाहिजे, असे नमूद करा. “प्रत्येक लेखन queue.enqueue() मधूनच होते. डेटाबेसमध्ये थेट लेखन केल्यास audit log टाळला जातो, आणि compliance export मध्ये हाच audit log वाचला जातो.” कारणासह लिहिलेला अपरिवर्तनीय नियम तुम्ही अपेक्षित न केलेल्या कामाच्या वेळीही टिकून राहतो. कारणाशिवाय लिहिलेला नियम पसंतीसारखा दिसतो आणि पसंती नंतरच्या सुधारणांमध्ये काढून टाकली जाते.

नाकारलेले पर्याय. स्पष्टपणे योग्य वाटणारा पर्याय कोणता होता आणि तो का नाकारला, हे लिहा. “कॅशिंगसाठी Redis वापरत नाही. सेवा एका VPS वर चालते, त्यामुळे प्रक्रियेतील map अधिक वेगवान आहे आणि चालू ठेवण्यासाठी आणखी एक daemon आवश्यक राहत नाही. दुसरा application server उपलब्ध झाल्यावर याचा पुन्हा विचार करा.” हा परिच्छेद नसल्यास, कॅश वेगवान करण्यास सांगितलेल्या agent कडून Redis जोडले जाईल. ते योग्यच ठरेल, कारण ही मर्यादा तुम्ही त्याला सांगितलेली नसते. हा विभाग संपूर्ण फाइलचे प्रयोजन सिद्ध करतो.

सीमा. ज्या ठिकाणी छोटे संपादन मोठ्या प्रमाणात परिणाम करू शकते, ती ठिकाणे नमूद करा. Database schema. ग्राहक आधीपासून scripts मध्ये वापरत असलेला public route prefix. Application सुरू होण्यापूर्वी deploy कडून वाचली जाणारी config file. त्या प्रोग्रामची एकच प्रत चालू आहे असे गृहीत धरणारी cron entry. प्रत्येक ठिकाणाचे नाव द्या आणि त्यात बदल केल्यास काय किंमत मोजावी लागेल, ते सांगा.

परिभाषा. कोडमध्ये tenant आणि टीमच्या संभाषणात customer वापरले जात असल्यास, त्यांचे परस्पर संबंध लिहून ठेवा. येथे चुकीचा अंदाज लावणारा agent वाचायला योग्य पण चुकीची संकल्पना मांडणारा कोड तयार करतो. 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 आणि नाकारलेले पर्याय. उर्वरित भाग फक्त heading म्हणून ठेवा. चार प्रामाणिक ओळी असलेली फाइल उपयोगी ठरते. अंदाजाने लिहिलेल्या चाळीस ओळींची फाइल उपयोगी ठरत नाही.

काही साधने 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.

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

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

याची किंमत तुम्हाला दोनदा मोजावी लागते. पहिली किंमत म्हणजे संदर्भ. प्रत्येक कार्याच्या सुरुवातीला agent वाचत असलेल्या फाइलची किंमत प्रत्येक कार्यासाठी मोजावी लागते. निश्चित context window मध्ये पुनरावृत्ती केलेला installation विभाग हा निव्वळ अतिरिक्त भार असतो. या window चे नियोजन करणे हे स्वतंत्र कौशल्य आहे. ते Claude Code मधील context window चे व्यवस्थापन येथे स्पष्ट केले आहे. थोडक्यात: आपोआप लोड होणारा मजकूर repository मधील सर्वाधिक उपयुक्त मजकूर असावा.

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

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

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

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

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

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

एजंट तुमच्या laptop ऐवजी server वर चालत असेल, तेव्हा हे सर्वाधिक महत्त्वाचे ठरते. tmux सह VPS वरील Claude Code workspace मधील setup प्रमाणे, long-running session मध्ये काम करणाऱ्या एजंटला कालच्या संभाषणाची आठवण नसते. Repository हीच memory असते. तुम्ही chat मध्ये स्पष्ट केलेली आणि 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 पेक्षा जास्त open source प्रकल्प ते वापरतात. तसेच Linux Foundation चा भाग असलेल्या Agentic AI Foundation अंतर्गत त्याचे व्यवस्थापन केले जाते. August 2026 पर्यंत DESIGN.md साठी कोणतीही प्रशासकीय संस्था किंवा प्रकाशित specification नाही. मात्र त्याचा first-party adoption आहे: Vercel, Nuxt, Atlassian आणि Resend यांसह सात कंपन्या सार्वजनिक URL वर अशी फाइल प्रकाशित करतात. तसेच community collection मध्ये सार्वजनिक sites वरून reverse-engineer केलेल्या आणखी 73 फाइल्स आहेत. ही पद्धत तुम्ही आता स्वीकारू शकता आणि मुक्तपणे वाढवू शकता, कारण तुमच्या section names ची पडताळणी करणारी कोणतीही यंत्रणा नाही.

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

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

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

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

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

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