DESIGN.md అంటే ఏమిటి? AGENTS.md తర్వాతి ఫైల్

DESIGN.md అంటే ఏమిటి, AGENTS.md ఏ విషయాలను కవర్ చేయదు

DESIGN.md అనేది మీ repository root లో ఉండే markdown ఫైల్. కోడ్ ఈ విధంగా ఎందుకు రూపొందించబడిందో ఇది AI coding agent కు వివరిస్తుంది. AGENTS.md వేరే ప్రశ్నకు సమాధానం ఇస్తుంది: ఇక్కడ ఎలా పని చేయాలి? అంటే build command, test command, తప్పనిసరిగా pass కావాల్సిన lint, అలాగే మార్చకూడని paths ఏమిటి అన్నది. ఇప్పటికే ఖరారైన నిర్ణయాలను DESIGN.md నమోదు చేస్తుంది. వాటిలో ఏదైనా మార్చితే ఏమి విఫలమవుతుందో కూడా ఇది వివరిస్తుంది.

Coding agent అంటే మీ repository ని స్వయంగా చదివి, మార్చే Claude Code లేదా Cursor వంటి tool. ఇది సాధారణంగా తన నిర్ణయాలపై నమ్మకంగా ఉంటుంది. తనకు పరిచయం లేని pattern కనిపిస్తే, దాన్ని మెరుగుపరుస్తుంది. చేతితో రాసిన cache Redis (in-memory data store) గా మారవచ్చు, ఎందుకంటే model చదివిన code లో cache సాధారణంగా అలానే ఉంటుంది. AGENTS.md దీన్ని ఆపదు, ఎందుకంటే make test రెండు సందర్భాల్లోనూ pass అవుతుంది. ఉల్లంఘించబడిన నియమం agent చదవగలిగే ఎక్కడా రాసి ఉండదు.

మీరు ఇంకా మొదటి ఫైల్‌ను రాయకపోతే, అక్కడి నుంచే ప్రారంభించండి. దాని పక్కన ఉండే AGENTS.md మరియు HUMAN.md లో format గురించి, ప్రతి tool దాన్ని ఎక్కడ చూస్తుందో వివరించబడింది. దీనికి తరువాతి chapter ఇప్పుడు అందించబడుతోంది.

ప్రచురించిన DESIGN.md లో వాస్తవంగా ఏమి ఉంటుంది

ఫార్మాట్‌ను నేర్చుకోవడానికి వేగవంతమైన మార్గం, కంపెనీలు తమ గురించి ప్రచురించిన ఫైళ్లను చదవడం. official-design-md repository అటువంటి ఫైళ్లను మాత్రమే track చేస్తుంది. దాని inclusion rule ఒకే పంక్తిలో ఉంటుంది. ఈ 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లో ఒకదాన్ని చదవవచ్చు.

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. విషయం మీద కాకుండా, రాత యొక్క నిర్మాణంపై దృష్టి పెట్టండి. ఉపయోగకరమైన భాగం topic కాదు, writing shape.

Nuxt fileలో సుమారు 2,100 words ఉన్నాయి. అందులో ఎక్కువ భాగం కారణంతో కూడిన 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 wordsగా ఉంది. అది మరో అడుగు ముందుకు వేస్తుంది. దాని headingsలో ఒకటి 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.

ఈ sentence file typeను నిర్వచిస్తుంది. ఒక confident model ఉత్పత్తి చేసే defaults జాబితాను ఇది లిఖిత రూపంలో అందిస్తుంది. ఆ model వాటిని ఉత్పత్తి చేయడం ఆపేందుకు ఈ జాబితాను publish చేస్తారు. commit చేయదగిన ప్రతి DESIGN.md ఏదో ఒక domain కోసం అలాంటి జాబితానే.

కంపెనీలు తమ స్వంత DESIGN.md ను ఎందుకు ప్రచురిస్తాయి?

కమ్యూనిటీ ముందుగానే ప్రారంభించింది. awesome-design-md లో public websites నుంచి reverse-engineer చేసిన 73 files ఉన్నాయి. ప్రతి file ఒకే తొమ్మిది-section format లో రాయబడింది. అందువల్ల ఒక file ను agent కు ఇచ్చి, దానికి దగ్గరగా కనిపించే output ను రూపొందించవచ్చు. ఆ files ఉపయోగకరమైనవే. అయితే అవి ఇప్పటికీ ఊహలపై ఆధారపడినవి. వాటిని సంబంధిత కంపెనీలలో ఎవరూ review చేయలేదు.

First-party file భిన్నంగా ఉంటుంది. ఎందుకంటే అది output ను చదివి చేసిన వివరణ కాదు; అసలు source. Vercel తన type scale ను మార్చినప్పుడు, vercel.com/design.md కూడా దానితో మారుతుంది. March లో scrape చేసిన copy మాత్రం పాత scale నే మీ agent కు బోధిస్తూనే ఉంటుంది. ఆ copy పాతబడిందని మీ repository లోని ఏదీ తెలియజేయదు.

ఏడు publishers అనేది చిన్న సంఖ్య. Repository కూడా ఇదే విషయాన్ని చెబుతోంది: ఈ standard కొత్తది, official adoption పెరుగుతోంది. రెండు collections ను VoltAgent నిర్వహిస్తోంది. ఇది open source agent framework, అలాగే తన స్వంత file ను కూడా ప్రచురిస్తుంది. అందువల్ల ఆ జాబితాను neutral census గా కాకుండా tracker గా చూడాలి. అయినప్పటికీ, ఆ ఏడు publishers ఎవరో గమనించడం విలువైనది. ఇతర developers ఎక్కువగా copy చేసే front-end code ఈ కంపెనీలదే. వాటి files, DESIGN.md ఎలా ఉండాలో చూపించే worked example గా మారుతున్నాయి. AGENTS.md తీసుకున్న మార్గంతో పోల్చండి: agents.md ఇప్పుడు 60,000 కంటే ఎక్కువ open source projects ఈ format ను ఉపయోగిస్తున్నట్లు లెక్కిస్తోంది. దీని stewardship Linux Foundation కింద ఉన్న Agentic AI Foundation వద్ద ఉంది. Agent-readable files కోసం conventions వేగంగా స్థిరపడుతున్నాయి. అవి ప్రధాన సంస్థల నుంచి ఏర్పడుతున్నాయి.

UI లేని ప్రాజెక్ట్‌లో DESIGN.md లో ఏమి ఉండాలి

VPS పై నడిచే చాలా సాఫ్ట్‌వేర్‌కు నిర్దిష్ట దృశ్య భాష అవసరం ఉండదు. అయినప్పటికీ ఈ ఫైల్‌కు ఉపయోగం ఉంది, ఎందుకంటే దీని ఉద్దేశానికి రంగులతో సంబంధం లేదు. అనుభవం ఉన్న ఎడిటర్ కూడా తెలియక ఉల్లంఘించే నియమాలను స్పష్టంగా రాయడమే దీని ఉద్దేశం.

మారకూడని నియమాలు. ప్రతి నియమాన్ని ఒక వాక్యంలో రాయండి. ఏ మార్పు చేసినా తప్పనిసరిగా నిజంగా ఉండాల్సిన విషయాన్ని పేర్కొనండి. "ప్రతి write queue.enqueue() ద్వారా మాత్రమే జరగాలి. నేరుగా database లో write చేస్తే audit log దాటవేయబడుతుంది; compliance export చదివేది audit log నే." కారణాన్ని కూడా జతచేసిన invariant, మీరు ఊహించని task వచ్చినా అమలులో నిలుస్తుంది. కారణం లేని invariant కేవలం preference లా కనిపిస్తుంది, preferences సాధారణంగా తొలగించబడతాయి.

తిరస్కరించిన ప్రత్యామ్నాయాలు. మొదట సహజంగా కనిపించిన ఎంపిక ఏమిటి, అది ఎందుకు తిరస్కరించబడిందో రాయండి. "Caching కోసం Redis ఉపయోగించము. ఈ service ఒకే VPS పై నడుస్తుంది. అందువల్ల process లోని map వేగంగా ఉంటుంది, అలాగే నడుస్తూ ఉండాల్సిన daemon ఒకటి తగ్గుతుంది. రెండో application server వచ్చినప్పుడు ఈ నిర్ణయాన్ని మళ్లీ పరిశీలించండి." ఆ పేరా లేకపోతే, cache ను వేగవంతం చేయమని అడిగిన agent Redis ను జోడిస్తుంది. అది సరైనదే, ఎందుకంటే ఆ constraint గురించి మీరు దానికి చెప్పలేదు. మొత్తం ఫైల్ విలువను నిరూపించే విభాగం ఇదే.

పరిధులు. చిన్న మార్పు పెద్ద ప్రభావాన్ని కలిగించే ప్రదేశాలను పేర్కొనండి. Database schema. కస్టమర్లు ఇప్పటికే scripts ద్వారా ఉపయోగిస్తున్న public route prefix. Application ప్రారంభమయ్యే ముందు deploy చదివే config file. ఆ service యొక్క ఒక copy మాత్రమే నడుస్తుందని భావించే cron entry. వీటిని పేరుతో పేర్కొని, ప్రతిదాంట్లో మార్పు చేయడానికి అయ్యే ప్రభావాన్ని వివరించండి. Agent కు open web ను కూడా, తన search backend గా అనుసంధానించిన self-hosted SearXNG instance ద్వారా, చేరుకునే అవకాశం ఉంటే, అది కూడా రాయాల్సిన boundary. ఎందుకంటే ఏ fetched text code పై ప్రభావం చూపవచ్చో, ఏది మీకు తిరిగి quote చేయడానికి మాత్రమే అనుమతించబడుతుందో ఈ ఫైల్ స్పష్టంగా పేర్కొనాలి.

పదజాలం. Code లో tenant అని, team లో customer అని అంటుంటే, ఆ mapping ను రాయండి. ఇక్కడ agent తప్పుగా అర్థం చేసుకుంటే, చదవడానికి సరైనదిగా కనిపించే కానీ తప్పు అంశాన్ని model చేసే 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 గా మాత్రమే ఉంచండి. నిజాయితీగా రాసిన నాలుగు పంక్తులు సరిపోతాయి. ఊహించి రాసిన నలభై పంక్తులు ఉపయోగకరం కావు.

కొన్ని 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: తప్పు విధానం

అత్యంత సాధారణమైన చెడు రూపం చదవడానికి బాగుంటుంది, కానీ ఏమీ బోధించదు. అది project ఏమి చేస్తుందో చెప్పడంతో ప్రారంభమవుతుంది, features ను జాబితా చేస్తుంది, install విధానాన్ని వివరిస్తుంది, చివర్లో licence తో ముగుస్తుంది. ఇవన్నీ ఇప్పటికే READMEలో ఉన్నాయి. వీటిలో ఏదీ ఏదైనా నిర్ణయం ఎందుకు తీసుకున్నామో చెప్పదు.

దీంతో మీకు రెండుసార్లు నష్టం జరుగుతుంది. మొదటి నష్టం context. ప్రతి task ప్రారంభంలో agent చదివే file కోసం ప్రతి taskలో ఖర్చు చేయాలి. నిర్ణీత windowలో install sectionను పునరావృతం చేయడం పూర్తిగా అదనపు భారమే. ఆ windowను సరిగ్గా వినియోగించడం కూడా ప్రత్యేకమైన నైపుణ్యమే. దీనిని Claude Codeలో context window నిర్వహణలో వివరించాం. సంక్షిప్తంగా: స్వయంచాలకంగా load అయ్యే ఏదైనా repositoryలో అత్యధిక విలువ కలిగిన text అయి ఉండాలి.

రెండవ నష్టం మరింత తీవ్రమైనది. ఒకే statementకు రెండు copies ఉంటే అవి కాలక్రమంలో వేర్వేరుగా మారతాయి. READMEలో service 8080పై listens అని ఉంటుంది, DESIGN.mdలో ఇంకా 3000 అని ఉంటుంది. ఏది ముఖ్యమో నిర్ణయించడానికి agentకు మార్గం ఉండదు. కాబట్టి అది ఒకదాన్ని ఎంచుకుని, దాని ఆధారంగా code రాస్తుంది. కొన్నిసార్లు తప్పుగా ఉండే fileను, ఎల్లప్పుడూ సరైన fileను చూసేంతే నమ్మకంతో పరిశీలిస్తారు.

పరీక్ష సులభం. ఏదైనా paragraph READMEలో సహజంగా సరిపోతే, దాన్ని DESIGN.md నుంచి తొలగించండి. మిగిలేది code reviewలో మీరు నేరుగా చెప్పే విషయం అయి ఉండాలి; “దాన్ని ఇప్పటికే ప్రయత్నించాం” అని ప్రారంభమయ్యే విషయం అయి ఉండాలి.

ఫైల్ సరిగ్గా పనిచేస్తోందని ఎలా తెలుసుకోవాలి?

దీనికి linter లేదు. ఒక నిమిషంలో అమలు చేయగల పరీక్ష ఉంది.

Invariant ను నేరుగా పరీక్షించే task ను agent కు ఇవ్వండి. ఉదాహరణకు, “stale rows ను expired గా గుర్తించే background job ను జోడించండి.” ఫైల్ తన పని చేస్తోందని code కంటే ముందే సమాధానంలో కనిపిస్తుంది: direct write చేస్తే audit log దాటవేయబడుతుందని, అందువల్ల job queue.enqueue() ద్వారా రాస్తుందని agent చెప్పాలి. అది database connection తెరిచి నేరుగా రాస్తే, రెండు విషయాల్లో ఒకటి నిజం. ఆ ఫైల్ అసలు చదవబడటం లేదు, లేదా invariant ను చాలా అస్పష్టంగా రాశారు కాబట్టి దానిపై వాదించవచ్చు.

token count ను కూడా గమనించండి, ఎందుకంటే ప్రతి turn లో ఈ ఫైల్ load అవుతుంది. DESIGN.md జోడించిన తర్వాత context usage పెరిగి, సమాధానాలు మెరుగుపడకపోతే, agent కు ఇప్పటికే తెలిసిన prose ను ఫైల్ మళ్లీ కలిగి ఉందని అర్థం. Claude Code లో token counters ను చదవడం ఆ budget ఎక్కడ వినియోగమవుతుందో చూపిస్తుంది.

Agent మీ laptop పై కాకుండా server పై నడుస్తున్నప్పుడు ఇది మరింత ముఖ్యమవుతుంది. tmux తో VPS పై Claude Code workspace వంటి long-running session లో పనిచేసే agent కు నిన్నటి conversation గుర్తుండదు. Repository నే memory గా పనిచేస్తుంది. Chat లో మీరు వివరించి, commit చేయని ప్రతిదీ తదుపరి session నాటికి పోతుంది. ఆ వివరణను నిల్వ చేసి కొనసాగించేది DESIGN.md.

మీరు తరచుగా విభేదించే నిర్ణయాలతో ప్రారంభించండి

మొదటి సంస్కరణకు ఇరవై నిమిషాలు పడుతుంది. సమీక్షకుడు “లేదు, మేము ఇక్కడ దీన్ని వేరుగా చేస్తాము” అని రాసిన ఇటీవల pull requestలను పరిశీలించండి. అలాంటి ప్రతి వ్యాఖ్య రాతపూర్వకంగా నమోదు చేయని ఒక invariant. అలాగే, ఒక వ్యక్తి చేసే దానికంటే agent అదే తప్పును మరింత వేగంగా, మరింత తరచుగా చేసే అవకాశం ఉన్న స్థలం కూడా అది. అది మీకు విఫలమైనప్పుడు fileలో చేర్చండి; నిర్ణీత షెడ్యూల్ ప్రకారం కాదు. సాధారణ development workflowలో agentsను ఎక్కడ ఉపయోగించాలో ఇంకా నిర్ణయించుకుంటుంటే, AI agents నేర్చుకోవడానికి 2026 గైడ్ తదుపరి ఉపయోగకరమైన వనరుగా ఉంటుంది.

FAQ

DESIGN.md అధికారిక ప్రమాణమా?

AGENTS.md ఉన్న విధంగా కాదు. AGENTS.md కోసం agents.md అనే అధికారిక స్థానం ఉంది. 60,000 కంటే ఎక్కువ open source projects దీన్ని ఉపయోగిస్తున్నాయి. Linux Foundation లోని Agentic AI Foundation దీని నిర్వహణను చూసుకుంటుంది. August 2026 నాటికి DESIGN.md కు ఎటువంటి నిర్వహణ సంస్థ లేదా ప్రచురిత specification లేదు. అయితే దీన్ని నేరుగా స్వీకరించిన సంస్థలు ఉన్నాయి. Vercel, Nuxt, Atlassian, Resend సహా ఏడు కంపెనీలు దీన్ని public URL వద్ద ప్రచురిస్తున్నాయి. ఒక community collection లో public sites నుంచి reverse-engineer చేసిన మరో 73 ఉదాహరణలు ఉన్నాయి. దీన్ని ఇప్పుడే స్వీకరించి, అవసరానికి అనుగుణంగా స్వేచ్ఛగా విస్తరించగల convention గా పరిగణించండి. ఎందుకంటే మీ section names ను validate చేసే వ్యవస్థ ఏదీ లేదు.

DESIGN.md ను AGENTS.md లోని ఒక section గా ఉంచాలా?

చిన్న repository కు అవును. Agent తప్పకుండా చదివే ఒక file, agent పట్టించుకోని రెండు files కంటే మెరుగైనది. AGENTS.md ను ఒక చూపులో పరిశీలించడం కష్టమయ్యే సమయంలో, లేదా రెండు భాగాలు వేర్వేరు వేగంతో మారుతున్నాయని గమనించినప్పుడు వాటిని విడగొట్టండి. Build మారినప్పుడు AGENTS.md మారుతుంది. ఒక decision మారినప్పుడు DESIGN.md మారుతుంది. DESIGN.md మార్పులు తక్కువగా ఉంటాయి, కానీ వాటి ప్రభావం ఎక్కువగా ఉంటుంది. విడగొట్టినప్పుడు AGENTS.md లో ఒక line జోడించి, code edit చేయడానికి ముందు DESIGN.md చదవాలని agent కు చెప్పండి. ఎందుకంటే ప్రతి tool root లోని ప్రతి markdown file ను load చేయదు.

DESIGN.md, architecture decision record మధ్య తేడా ఏమిటి?

ADR (architecture decision record) అనేది ఒక decision కు సంబంధించిన తేదీతో కూడిన record. ఒక మంచి project లో ఇలాంటి records డజన్ల కొద్దీ ఒక folder లో చేరుతాయి. అది history. ఆ history ను load చేయడం ఖరీదైనది. ఏ నిర్ణయాలు ఇంకా వర్తిస్తున్నాయో తెలుసుకోవడానికి agent వాటన్నింటినీ చదవాల్సి ఉంటుంది. DESIGN.md ప్రస్తుత స్థితిని వివరిస్తుంది. ప్రతి task సమయంలో పూర్తిగా చదవడానికి అనుకూలంగా ఇది రాయబడుతుంది. మీరు ఇప్పటికే ADRs రాస్తుంటే రెండింటినీ ఉంచండి. ADR లో ఏమి, ఎప్పుడు నిర్ణయించారో ఉంటుంది. DESIGN.md లో ఈరోజు నిజంగా ఉన్న స్థితి ఉంటుంది. Agent కు సూచించాల్సిన ప్రధాన file ఇదే.

DESIGN.md ఎంత పొడవుగా ఉండాలి?

ప్రతి turn లో ఎటువంటి సంకోచం లేకుండా load చేయగలిగేంత చిన్నదిగా ఉండాలి. ప్రచురిత ఉదాహరణలు మొత్తం visual language ను specify చేస్తాయి కాబట్టి పొడవుగా ఉంటాయి. August 2026 నాటికి Nuxt file సుమారు 2,100 పదాలు, Vercel file సుమారు 6,500 పదాలు ఉన్నాయి. Backend service కు సాధారణంగా ఇంత అవసరం ఉండదు. ఒక page తో ప్రారంభించండి. ఒక sentence ఉంటే agent చేసిన తప్పును నివారించగలిగేదని తెలిసినప్పుడు మాత్రమే దాన్ని పెంచండి. పొడవు కొలమానం కాదు. ప్రతి line agent సాధారణంగా చేసే ఒక తప్పును నివారించేదిగా ఉండాలి.