AGENTS.md తర్వాత DESIGN.md ఎందుకు అవసరం?

DESIGN.md ఏమిటి, AGENTS.md ఏమి కవర్ చేయదు

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

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

మీరు ఇంకా మొదటి file రాయకపోతే, అక్కడి నుంచే ప్రారంభించండి. దాని పక్కనే ఉన్న AGENTS.md మరియు HUMAN.md formatను, ప్రతి tool దాన్ని ఎక్కడ వెతుకుతుందో వివరిస్తుంది. ఇప్పుడు వచ్చే విషయం దాని తర్వాతి chapter.

ప్రచురించిన 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 వద్ద ఉంటుంది. కాబట్టి మీరు ఇప్పుడే terminalలో ఒకదాన్ని చదవవచ్చు.

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

ఈ రెండూ design system పత్రాలు. ఒక product ఎలా కనిపించాలో ఇవి వివరిస్తాయి: రంగు, అక్షరరూపం, అంతరం, చలనం. విషయం మీదే దృష్టి పెట్టకుండా ముందుకు చదవండి. ఉపయోగకరమైన భాగం విషయం కాదు; రచన యొక్క నిర్మాణం.

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"`.

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 వాటిని రూపొందించడం ఆపేందుకు ఈ జాబితాను ప్రచురిస్తారు. commit చేయదగిన ప్రతి DESIGN.md ఏదో ఒక domain కోసం రూపొందించిన అలాంటి జాబితానే.

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

కమ్యూనిటీ ముందుగానే ప్రారంభించింది. awesome-design-md లో పబ్లిక్ వెబ్‌సైట్‌ల నుంచి రివర్స్-ఇంజినీర్ చేసిన 73 ఫైళ్లు ఉన్నాయి. ప్రతి ఫైల్‌ను ఒకే తొమ్మిది-విభాగాల ఫార్మాట్‌లో రాశారు. అందువల్ల ఒక agent కు వాటిలో ఒకదాన్ని చూపించి, దానికి దగ్గరగా ఉండే రూపాన్ని రూపొందించవచ్చు. ఆ ఫైళ్లు ఉపయోగకరమైనవే. అయితే అవి ఇప్పటికీ అంచనాలే. వాటిని ఆ కంపెనీలలో ఎవరూ సమీక్షించలేదు.

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

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

ప్రాజెక్ట్‌కు వినియోగదారు ఇంటర్‌ఫేస్ లేనప్పుడు DESIGN.mdలో ఏమి ఉండాలి

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

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

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

సరిహద్దులు. చిన్న సవరణకు పెద్ద ప్రభావ పరిధి ఉండే ప్రదేశాలను పేర్కొనాలి. Database schema. వినియోగదారులు ఇప్పటికే scriptsలో ఉపయోగిస్తున్న public route prefix. application ప్రారంభమయ్యే ముందు deploy చదివే config file. దాని ఒక్క copy మాత్రమే నడుస్తుందని భావించే cron entry. వాటి పేర్లు రాయండి. ప్రతి దానిలో మార్పు చేస్తే కలిగే వ్యయాన్ని కూడా పేర్కొనండి.

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

కొన్ని 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

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

దీంతో మీకు రెండుసార్లు నష్టం జరుగుతుంది. మొదటి నష్టం సందర్భానికి సంబంధించినది. ప్రతి పనిని ప్రారంభించేటప్పుడు agent చదివే ఫైల్‌కు ప్రతి పనిలోనూ ఖర్చు ఉంటుంది. స్థిరమైన context windowలో పునరావృతమైన install విభాగం పూర్తిగా అదనపు భారమే. ఆ windowను సమర్థంగా కేటాయించడం ఒక ప్రత్యేక నైపుణ్యం. దీని గురించి Claude Codeలో context windowను నిర్వహించడంలో వివరించబడింది. సంక్షిప్తంగా: స్వయంచాలకంగా లోడ్ అయ్యే కంటెంట్ repositoryలో అత్యధిక విలువ కలిగిన పాఠ్యంగా ఉండాలి.

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

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

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

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

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

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

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

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

మొదటి సంస్కరణకు ఇరవై నిమిషాలు పడుతుంది. Reviewer “లేదు, ఇక్కడ మేము వేరే విధంగా చేస్తాము” అని రాసిన చివరి కొన్ని pull requests తెరవండి. అలాంటి ప్రతి వ్యాఖ్య రాసి ఉంచని invariant. వ్యక్తి కంటే agent అదే తప్పును మరింత వేగంగా, మరింత తరచుగా చేసే అవకాశం ఉన్న ప్రదేశం కూడా అదే. ఇది విఫలమైనప్పుడు file కు చేర్చండి; నిర్ణీత షెడ్యూల్ ప్రకారం కాదు. సాధారణ 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 లేదు. అయితే దీనిని నేరుగా స్వీకరించిన సంస్థలు ఉన్నాయి. Vercel, Nuxt, Atlassian మరియు Resend సహా ఏడు కంపెనీలు తమ public URLలో DESIGN.mdను ప్రచురిస్తున్నాయి. ఒక community collectionలో public siteల నుంచి reverse-engineer చేసిన మరో 73 ఫైళ్లు ఉన్నాయి. దీన్ని ఇప్పుడే స్వీకరించి, అవసరానికి అనుగుణంగా స్వేచ్ఛగా విస్తరించవచ్చు. ఎందుకంటే మీ section పేర్లను ధృవీకరించే వ్యవస్థ ఏదీ లేదు.

DESIGN.mdను AGENTS.mdలోని ఒక sectionగా మాత్రమే ఉంచాలా?

చిన్న repositoryకి అవును. Agent ఖచ్చితంగా చదివే ఒక ఫైల్, agent పట్టించుకోని రెండు ఫైళ్ల కంటే మెరుగైనది. AGENTS.mdను సులభంగా పరిశీలించలేని స్థాయికి చేరుకున్నప్పుడు, లేదా రెండు భాగాలు వేర్వేరు వేగాలతో మారుతున్నట్లు గమనించినప్పుడు వాటిని విడదీయండి. Build మారినప్పుడు AGENTS.md మారుతుంది. ఒక నిర్ణయం మారినప్పుడు DESIGN.md మారుతుంది. ఇది తక్కువ తరచుగా జరుగుతుంది, కానీ దాని ప్రభావం ఎక్కువ. ఫైళ్లను విడదీసినప్పుడు, codeను సవరించే ముందు DESIGN.mdను చదవాలని agentకు చెప్పే ఒక పంక్తిని AGENTS.mdలో చేర్చండి. ఎందుకంటే rootలోని ప్రతి markdown ఫైల్‌ను ప్రతి tool load చేయదు.

DESIGN.md, architecture decision recordకు ఎలా భిన్నంగా ఉంటుంది?

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

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

ప్రతి turnలో చదవగలిగేంత చిన్నదిగా ఉండాలి. దాని గురించి తర్వాత పశ్చాత్తాపపడాల్సిన అవసరం రాకూడదు. ప్రచురిత ఉదాహరణలు మొత్తం visual languageను నిర్వచిస్తాయి కాబట్టి పొడవుగా ఉంటాయి. August 2026 నాటికి Nuxt ఫైల్ సుమారు 2,100 పదాలు, Vercel ఫైల్ సుమారు 6,500 పదాలు ఉన్నాయి. Backend serviceకు సాధారణంగా ఇంత అవసరం ఉండదు. ఒక పేజీతో ప్రారంభించండి. ఒకే వాక్యం ద్వారా నివారించగలిగే తప్పును agent చేసినప్పుడు మాత్రమే దాన్ని పెంచండి. పొడవు కొలమానం కాదు. ప్రతి పంక్తి లేకపోతే agent చేసే తప్పును వివరించాలి.