DESIGN.md ఎందుకు అవసరం, AGENTS.md ఏం చెప్పదు

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

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

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

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

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

ఈ format నేర్చుకోవడానికి వేగవంతమైన మార్గం, కంపెనీలు తమ గురించి ప్రచురించిన files ను చదవడం. official-design-md repository అలాంటి files ను మాత్రమే track చేస్తుంది. దాని inclusion rule ఒకే line లో ఉంటుంది. ఆ line నే ఈ 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 ఎలా కనిపించాలో అవి వివరిస్తాయి: colour, type, spacing, motion. Subject matter ను దాటి చదవండి. ఉపయోగకరమైన భాగం topic కాదు, writing యొక్క structure.

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 సాధారణంగా ఎంచుకునే అంశాల 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.

ఈ sentence file type ను నిర్వచిస్తుంది. ధైర్యంగా పనిచేసే model ఉత్పత్తి చేసే defaults యొక్క written list ఇది. Model వాటిని ఉత్పత్తి చేయడం ఆపేలా ఈ list ను publish చేస్తారు. Commit చేయదగిన ప్రతి DESIGN.md ఏదో ఒక domain కోసం అలాంటి list అయి ఉంటుంది.

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

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

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 ను కూడా ప్రచురిస్తుంది. అందువల్ల ఈ list ను neutral census గా కాకుండా tracker గా చూడాలి. అయినప్పటికీ దీనిని గమనించడం విలువైనదే. కారణం ఆ ఏడుగురు ఎవరో అన్నది. ఇతర developers ఎక్కువగా copy చేసే front-end code ఉన్న companies అవే. DESIGN.md అంటే ఏమిటో చూపించే worked example గా వాటి files మారుతున్నాయి. AGENTS.md తీసుకున్న మార్గంతో దీన్ని పోల్చండి: agents.md format ను ఉపయోగిస్తున్న open source projects సంఖ్య ఇప్పుడు 60,000 దాటింది. దాని stewardship Linux Foundation కింద ఉన్న Agentic AI Foundation వద్ద ఉంది. Agent-readable files కోసం conventions వేగంగా స్థిరపడుతున్నాయి. అవి అగ్రస్థాయి projects నుంచి స్థిరపడుతున్నాయి.

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

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

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

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

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

పదజాలం. codeలో tenant అని, teamలో customer అని ఉపయోగిస్తే, ఆ రెండింటి అనుసంధానాన్ని రాయాలి. ఇక్కడ agent తప్పుగా అర్థం చేసుకుంటే చదవడానికి సరిగ్గా కనిపించే codeను తయారు చేస్తుంది, కానీ అది తప్పు విషయాన్ని model చేస్తుంది. 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

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

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

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

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

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

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

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

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

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

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

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

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 వద్ద ప్రచురిస్తున్నాయి. Community collectionలో public sites నుంచి reverse-engineer చేసిన మరో 73 ఫైళ్లు ఉన్నాయి. దీన్ని మీరు ఇప్పుడే స్వీకరించి స్వేచ్ఛగా విస్తరించగల conventionగా పరిగణించండి. ఎందుకంటే మీ section names ను validate చేసే వ్యవస్థ ఏదీ లేదు.

DESIGN.md కేవలం AGENTS.md లోని ఒక sectionగా ఉండాలా?

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

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

ADR (architecture decision record) అనేది ఒక నిర్ణయానికి సంబంధించిన తేదీతో కూడిన record. మంచి projectలో ఇలాంటి records ఒక folderలో డజన్ల కొద్దీ చేరతాయి. ఇది ఒక చరిత్ర. ఆ చరిత్రను load చేయడం ఖరీదైనది. ఏ records ఇప్పటికీ చెల్లుబాటులో ఉన్నాయో తెలుసుకోవడానికి agent వాటన్నింటినీ చదవాల్సి రావచ్చు. DESIGN.md ప్రస్తుత స్థితిని వివరిస్తుంది. ప్రతి taskలో పూర్తిగా చదివేలా ఇది రాయబడుతుంది. మీరు ఇప్పటికే ADRలను రాస్తుంటే రెండింటినీ ఉంచండి. 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 లేకపోతే తప్పుగా చేసే ఒక విషయంగా ఉంచండి.