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

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.

August 2026 पर्यंत त्यात सात नावे आहेत: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel आणि VoltAgent. प्रत्येक file स्थिर public URL वर आहे, त्यामुळे तुम्ही आत्ताच 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 कसे दिसावे हे त्यात सांगितलेले असते: रंग, type, spacing आणि motion. विषयाकडे दुर्लक्ष करून पुढे वाचा, कारण उपयुक्त भाग विषय नसून लेखनाची रचना आहे.

Nuxt file सुमारे 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 file अधिक मोठी, सुमारे 6,500 शब्दांची आहे. ती आणखी एक पायरी पुढे जाते. तिच्या एका 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 ची व्याख्या करते. confident model ने तयार केलेल्या defaults ची ही written list असते. model ने ते तयार करणे थांबवावे म्हणून ती प्रकाशित केली जाते. commit करण्यास योग्य प्रत्येक DESIGN.md ही एखाद्या domain साठी अशीच list असते.

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

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

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

सात publishers ही लहान संख्या आहे आणि repository मध्येही ते स्पष्टपणे नमूद केले आहे: हा standard नवीन आहे आणि official adoption वाढत आहे. दोन्ही collections ची देखभाल VoltAgent करते. VoltAgent हे open source agent framework आहे आणि ते स्वतःची फाइलही प्रकाशित करते. त्यामुळे ही यादी neutral census न मानता tracker म्हणून वाचा. तरीही या यादीकडे लक्ष ठेवणे योग्य आहे, कारण त्या सात कंपन्या कोणत्या आहेत हे महत्त्वाचे आहे. इतर developers ज्या कंपन्यांच्या front-end code ची सर्वाधिक नक्कल करतात, त्या याच कंपन्या आहेत. DESIGN.md म्हणजे काय, याचे worked example म्हणून त्यांच्या फाइल्स आकार घेत आहेत. AGENTS.md ने घेतलेला मार्ग तुलना करण्यासारखा आहे: agents.md नुसार आता 60,000 पेक्षा जास्त open source projects हा format वापरतात आणि त्याची stewardship Linux Foundation अंतर्गत Agentic AI Foundation कडे आहे. Agents-readable फाइल्ससाठीच्या 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 अंतर्गत त्याचे व्यवस्थापन केले जाते. August 2026 पर्यंत DESIGN.md साठी कोणतीही नियामक संस्था किंवा प्रकाशित specification नाही. मात्र त्याचा first-party adoption आहे: Vercel, Nuxt, Atlassian आणि Resend यांसह सात कंपन्या ते public URL वर प्रकाशित करतात. तसेच community collection मध्ये public sites वरून reverse-engineer केलेल्या आणखी 73 आवृत्त्या आहेत. तुम्ही ते आत्ताच स्वीकारून मुक्तपणे विस्तारित करू शकता, अशी convention म्हणून त्याकडे पाहा. तुमच्या section names ची पडताळणी करणारी कोणतीही यंत्रणा नाही.

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

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

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

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

DESIGN.md किती मोठी असावी?

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