DESIGN.md: File Pagkatapos ng AGENTS.md
Alamin kung bakit kailangan ang DESIGN.md bukod sa AGENTS.md, at paano nito pinipigilan ang coding agent na baligtarin ang mahahalagang desisyon sa code.
Ano ang DESIGN.md, at ang hindi saklaw ng AGENTS.md
Ang DESIGN.md ay isang markdown file sa root ng repository na nagsasabi sa AI coding agent kung bakit ganoon ang pagkakabuo ng code. Ibang tanong ang sinasagot ng AGENTS.md: kung paano magtrabaho sa repository na ito, kabilang ang build command, test command, lint na kailangang pumasa, at mga path na hindi dapat baguhin. Itinatala ng DESIGN.md ang mga desisyong napagkasunduan na at ang mga masisirang bahagi kapag binaligtad ang isa sa mga ito.
Ang coding agent, gaya ng tool na Claude Code o Cursor na kusang bumabasa at nag-e-edit ng repository, ay likas na kumpiyansa sa mga desisyon nito. Kapag nakakita ito ng pattern na hindi nito nakikilala, inaayos nito ang pattern. Nagiging Redis (in-memory data store) ang isang cache na isinulat nang mano-mano, dahil iyon ang karaniwang anyo ng cache sa karamihan ng code na nabasa ng model. Hindi ito napipigilan ng AGENTS.md, dahil make test ay pumapasa sa alinmang paraan. Hindi kailanman naisulat ang nilabag na rule sa lugar na mababasa ito ng agent.
Kung hindi mo pa naisusulat ang unang file, magsimula roon. Saklaw ng AGENTS.md at HUMAN.md na nasa tabi nito ang format at kung saan ito hinahanap ng bawat tool. Ang kasunod ay ang chapter pagkatapos nito.
Ano talaga ang laman ng isang published na DESIGN.md
Ang pinakamabilis na paraan para matutuhan ang format ay basahin ang mga file na inilalathala ng mga kumpanya tungkol sa sarili nila. Tanging ang mga iyon ang sinusubaybayan ng repository na official-design-md. Isang linya lamang ang inclusion rule nito, at iyon ang mismong punto ng collection:
Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.Noong October 2026, labing-isa ang nakalista rito: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel, at VoltAgent. Nasa public URL ang bawat file. Karamihan ay nasa sariling domain ng publisher, at ang iba naman ay nasa public GitHub repository. Kaya maaari kang magbasa ng isa sa terminal ngayon.
curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -wParehong design system document ang dalawang iyon. Inilalarawan nila kung ano dapat ang hitsura ng isang produkto: kulay, typography, spacing, at motion. Huwag magpokus lamang sa paksa. Mas mahalaga ang anyo ng pagkakasulat kaysa sa topic.
Humigit-kumulang 2,000 salita ang Nuxt file noong October 27, 2026, at karamihan dito ay rule na may kalakip na dahilan. Nagsisimula ito sa pahayag na dark mode ang default theme. Inililista nito ang brand green na #00DC82, kasama ang paalala na ang brand colours ay "Para sa mga logo, social image, at print. Huwag gamitin ang mga ito bilang raw value sa UI code." Malapit sa hulihan, may section na may heading na Reject these at naglalaman ng:
Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.Mas mahaba ang Vercel file, humigit-kumulang 6,000 salita noong October 2026, at may idinadagdag pa itong isang hakbang. Isa sa mga heading nito ay Reject generated-design reflexes. Sa ilalim nito ay may listahan ng mga karaniwang pinipili ng isang mahusay na generator kapag walang nagsabing huwag itong gamitin:
Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.Tinutukoy ng pangungusap na iyon ang uri ng file. Isa itong nakasulat na listahan ng mga default na awtomatikong ginagawa ng isang kumpiyansang model, na inilalathala upang hindi na gawin ng model ang mga iyon. Ang bawat DESIGN.md na karapat-dapat i-commit ay ganoong listahan para sa isang partikular na domain.
Bakit naglalabas ang mga kumpanya ng sarili nilang DESIGN.md?
Nauna rito ang komunidad. Naglalaman ang awesome-design-md ng 84 file na kinuha mula sa mga pampublikong website, batay sa bilang sa README nito noong October 27, 2026. Pare-pareho ang gamit nilang siyam na seksyon, kaya maaaring ituro ng isang agent ang isa sa mga ito upang makagawa ng output na kahawig ng itsura nito. Kapaki-pakinabang ang mga file na iyon, pero mga pagtatantiya pa rin ang mga ito. Walang sinuman sa mga kumpanyang iyon ang sumuri sa mga ito.
Iba ang first-party file dahil ito ang source, hindi interpretasyon ng output. Kapag binago ng Vercel ang type scale nito, nagbabago rin ang vercel.com/design.md. Ang kopyang na-scrape noong March ay patuloy na nagtuturo sa agent mo ng lumang scale, at walang anuman sa repository mo ang magsasabi na luma na ang kopya.
Maliit pa rin ang bilang na 11 publisher, at sinasabi rin ito ng repository: bago pa ang standard at lumalawak ang opisyal na adoption. Parehong pinapanatili ng VoltAgent ang dalawang collection. Ang VoltAgent ay isang open source agent framework na naglalabas din ng sarili nitong file. Kaya ituring ang listahan bilang tracker, hindi bilang neutral na census. Mahalaga pa rin itong subaybayan dahil sa mga kumpanyang kasama rito. Ilan sa mga ito ang kumpanyang pinakamadalas kopyahan ng ibang developer ng front-end code. Ang mga mas bagong entry—Ant Design, Microsoft FAST, Juspay, at Oxide Computer—ay mga design system na ginagamit na pundasyon ng ibang team. Nagiging aktuwal na halimbawa na ang mga file nila kung ano ang isang DESIGN.md. Ihambing ito sa naging takbo ng AGENTS.md: mahigit 60,000 open source project na ngayon ang gumagamit ng format ayon sa bilang sa agents.md, at nasa ilalim na ng Agentic AI Foundation sa ilalim ng Linux Foundation ang pangangasiwa rito. Nagsimula na rin ang DESIGN.md sa parehong landas. Noong April 21, 2026, naglabas ang Google ng draft specification para sa format bilang open source. Inilathala ito bilang google-labs-code/design.md, kasama ang token schema at isang CLI sa ilalim ng Apache-2.0 licence. Noong October 2026, nasa alpha version pa ang format at aktibo pa ring dine-develop. Google Labs, hindi isang neutral na foundation, ang nagpapanatili rito. Inilalarawan nito ang visual identity, kaya wala itong sinasabi tungkol sa mga invariant na kailangan ng backend file. Mabilis na nabubuo ang mga convention para sa mga file na mababasa ng agent, at mula sa mga nangungunang organisasyon nanggagaling ang direksiyong ito.
Ano ang nilalaman ng DESIGN.md kapag walang user interface ang proyekto
Karamihan ng software na tumatakbo sa isang VPS ay walang visual language na kailangang tukuyin. May saysay pa rin ang file, dahil walang kinalaman sa kulay ang mekanismo. Tungkol ito sa pagtatala ng mga constraint na maaaring malabag ng isang kumpiyansang editor nang hindi namamalayan.
Mga invariant. Isang pangungusap bawat isa na nagsasaad ng isang bagay na dapat manatiling totoo pagkatapos ng anumang edit. "Dumaan ang bawat write sa queue.enqueue(). Nilalampasan ng direktang database write ang audit log, at ang audit log ang binabasa ng compliance export." Kapag kasama ang dahilan, nananatiling kapaki-pakinabang ang invariant kahit may task na hindi mo inaasahan. Kapag nag-iisa ang invariant, para lamang itong preference, at karaniwang inaalis sa optimization ang mga preference.
Mga tinanggihang alternatibo. Ilahad ang halatang opsyon at kung bakit hindi ito pinili. "Hindi kami gumagamit ng Redis para sa caching. Tumatakbo ang service sa iisang VPS, kaya mas mabilis ang in-process map at isa itong daemon na hindi na kailangang panatilihing gumagana. Muling suriin ito kapag may ikalawang application server na." Kung wala ang talatang iyon, kapag inutusan ang isang agent na pabilisin ang cache, magdaragdag ito ng Redis, at tama itong gawin: hindi mo kailanman sinabi ang constraint. Ito ang seksyong nagbibigay-katwiran sa buong file.
Mga hangganan. Ito ang mga lugar kung saan maaaring magkaroon ng malaking epekto ang isang maliit na edit. Kasama rito ang database schema. Ang public route prefix na ginagamit na sa mga script ng customer. Ang config file na binabasa ng deployment bago magsimula ang application. Ang cron entry na nag-aakalang isang kopya lamang nito ang tumatakbo. Pangalanan ang mga ito at sabihin kung ano ang magiging kapalit ng pagbabago sa bawat isa. Kung maaabot din ng agent ang open web sa pamamagitan ng isang self-hosted na SearXNG instance na naka-configure bilang search backend nito, isa rin itong hangganang dapat itala, dahil dapat tukuyin ng file kung aling fetched text ang pinapayagang makaapekto sa code at alin ang maaari lamang i-quote pabalik sa iyo.
Talasalitaan. Kung tenant ang tawag ng code at customer ang tawag ng team, itala ang mapping. Kapag mali ang hula ng agent dito, makagagawa ito ng code na maayos basahin ngunit maling bagay ang mina-modelo. Ito ang pinakamahirap mapansin sa code review.
Isang DESIGN.md na maaari mong kopyahin ngayon
# 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.Isulat ang dalawang seksyong kaya mong buuin mula sa alaala ngayon: mga invariant at mga alternatibong tinanggihan. Iwan ang iba bilang mga heading. Ayos lang ang file na may apat na tapat na linya. Hindi ayos ang file na may apatnapung hula lamang. Kung maraming package ang repository, hindi kasya ang isang root file sa lahat ng ito. Gamitin dito ang parehong per-directory split na gumagana para sa mga nested AGENTS.md file sa isang monorepo: isang maikling root file para sa mga desisyong pare-parehong ginagamit ng lahat, at isang mas maliit na file sa tabi ng bawat package na may sarili nitong mga desisyon.
May ilang tool na nilo-load ang bawat markdown file sa repository root, habang ang iba ay nilo-load lamang ang file na itinuro sa kanila. Kaya huwag mag-assume. Magdagdag ng pointer sa AGENTS.md:
Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.Ang anti-pattern: DESIGN.md na inuulit ang README
Ang pinakakaraniwang maling bersyon ay maayos basahin pero walang itinuturo. Nagsisimula ito sa paglalarawan ng ginagawa ng project, inililista ang mga feature, ipinapaliwanag kung paano ito i-install, at nagtatapos sa license. Nasa README na ang bawat linyang iyon, at wala sa mga ito ang nagpapaliwanag kung bakit ganoon ang disenyo.
Dalawang beses ang kapalit nito. Una, nababawasan ang context. Binabasa ang file sa simula ng bawat task, kaya kasama ang halaga nito sa bawat task. Ang inuulit na seksyon ng installation ay puro overhead sa limitadong window. Ang pagba-budget sa window na iyon ay hiwalay na kasanayan, na tinalakay sa pamamahala ng context window sa Claude Code. Sa madaling sabi: ang anumang awtomatikong nilo-load ay dapat pinakamahalagang text sa repository.
Mas masama ang ikalawang kapalit. Nagkakaroon ng pagkakaiba ang dalawang kopya ng parehong pahayag. Sinasabi ng README na nakikinig ang service sa 8080, pero 3000 pa rin ang nasa DESIGN.md. Walang paraan ang agent para matukoy kung alin ang dapat unahin, kaya pipili ito ng isa at bubuo ng code batay rito. Ang file na paminsan-minsang mali ay kinokonsulta nang may parehong kumpiyansa tulad ng file na palaging tama.
Mabilis ang pagsusuri. Kung ang isang paragraph ay maayos ilagay sa README, alisin ito sa DESIGN.md. Ang matitira ay dapat iyong sasabihin mo nang direkta sa code review, iyong nagsisimula sa “sinubukan na natin iyan.”
Paano mo malalaman kung gumagana ang file?
Walang linter para rito. May check na maaari mong patakbuhin sa loob ng isang minuto.
Bigyan ang agent ng task na direktang tumatama sa isang invariant. “Magdagdag ng background job na nagmamarka sa mga stale row bilang expired.” Makikita sa sagot bago pa ang anumang code kung ginagawa ng file ang tungkulin nito: dapat sabihin ng agent na sumusulat ang job sa pamamagitan ng queue.enqueue(), dahil malalampasan ng direktang pagsulat ang audit log. Kung nagbukas ito ng database connection at sumulat, isa sa dalawang bagay ang totoo. Hindi binabasa ang file, o maluwag ang pagkakasulat sa invariant kaya maaari itong pagtalunan.
Subaybayan din ang token count, dahil nilo-load ang file sa bawat turn. Kung biglang tumataas ang context usage matapos mong idagdag ang DESIGN.md at hindi gumaganda ang mga sagot, naglalaman ang file ng prose na alam na ng agent. Ipinapakita ng Pagbasa sa mga token counter sa Claude Code kung saan napupunta ang budget na iyon.
Pinakamahalaga ito kapag nasa server ang agent at hindi sa laptop mo. Ang agent na nagtatrabaho sa isang long-running session, gaya ng setup sa Claude Code workspace sa isang VPS na may tmux, ay walang memorya ng pag-uusap ninyo kahapon. Ang repository ang nagsisilbing memorya. Lahat ng ipinaliwanag mo sa chat at hindi mo na-commit ay mawawala sa susunod na session, at ang DESIGN.md ang paglalagyan ng paliwanag na iyon para manatili ito.
Magsimula sa mga desisyong madalas pagtalunan
Dalawampung minuto ang kailangan para sa unang bersyon. Buksan ang pinakahuling ilang pull request kung saan may reviewer na sumulat ng “hindi, iba ang paraan natin dito.” Ang bawat komento ay isang invariant na hindi naisulat, at bawat isa ay sitwasyon kung saan gagawa ang agent ng parehong pagkakamali—mas mabilis at mas madalas kaysa sa tao. Idagdag sa file kapag nagdudulot ito ng pagkakamali, hindi ayon sa isang iskedyul. Kung inaalam mo pa kung paano isasama ang mga agent sa karaniwang development workflow, makatuwirang susunod na basahin ang gabay sa pag-aaral ng AI agents para sa 2026.
FAQ
Opisyal bang pamantayan ang DESIGN.md?
Hindi sa paraang opisyal na pamantayan ang AGENTS.md. May tahanan ang AGENTS.md sa agents.md, ginagamit ito ng mahigit 60,000 open source project, at pinangangasiwaan ito ng Agentic AI Foundation, na bahagi ng Linux Foundation. May inilathalang specification ang DESIGN.md, pero wala itong neutral na tagapangasiwa. Nag-open source ang Google ng draft specification noong April 21, 2026, at nasa google-labs-code/design.md repository ito sa ilalim ng Apache-2.0 licence. Noong October 2026, nasa alpha version pa ito at aktibong binubuo pa. Inilalarawan nito ang visual identity: mga kulay, typography, layout, at component. May first-party adoption din ang DESIGN.md: labing-isang kumpanya at project, kabilang ang Vercel, Nuxt, Atlassian, at Resend, ang naglalathala nito. May community collection din na naglalaman ng 84 pang file na kinuha mula sa mga pampublikong site noong October 27, 2026. Para sa backend file na naglalaman ng mga invariant at tinanggihang alternatibo, ituring ito bilang convention na maaari mong gamitin ngayon at malayang palawakin, dahil walang specification na sumasaklaw sa mga pangalan ng seksyong iyon.
Dapat bang maging seksyon lang ng AGENTS.md ang DESIGN.md?
Para sa maliit na repository, oo. Mas mabisa ang isang file na tiyak na binabasa ng agent kaysa dalawang file na maaaring hindi mabasa ang isa. Hatiin ang mga ito kapag hindi na madaling ma-scan ang AGENTS.md, o kapag napansin mong magkaiba na ang bilis ng pagbabago ng dalawang bahagi. Nagbabago ang AGENTS.md kapag nagbabago ang build. Nagbabago ang DESIGN.md kapag nagbabago ang isang decision, na mas bihira at mas mahalaga. Kapag pinaghiwalay mo ang mga ito, magdagdag ng isang linya sa AGENTS.md na nagsasabing basahin ng agent ang DESIGN.md bago mag-edit ng code, dahil hindi lahat ng tool ay naglo-load ng bawat markdown file sa root.
Paano naiiba ang DESIGN.md sa isang architecture decision record?
Ang ADR (architecture decision record) ay may petsang tala ng isang decision. Ang maayos na project ay nag-iipon ng dose-dosenang ADR sa isang folder. Kasaysayan iyon, at magastos i-load ang kasaysayan dahil kailangang basahin ng agent ang lahat ng ito upang malaman kung alin pa ang totoo. Ang DESIGN.md ang kasalukuyang state, at isinulat ito para basahin nang buo sa bawat task. Panatilihin ang dalawa kung gumagamit ka na ng ADR. Sinasabi ng ADR kung ano ang napagdesisyunan at kailan ito napagdesisyunan. Sinasabi ng DESIGN.md kung ano ang totoo ngayon, at ito ang itinuturo mo sa agent.
Gaano kahaba dapat ang DESIGN.md?
Dapat sapat itong maikli para ma-load sa bawat turn nang walang pagsisisi. Mahahaba ang mga inilathalang halimbawa dahil tinutukoy ng mga ito ang isang buong visual language: humigit-kumulang 2,000 salita ang Nuxt file at humigit-kumulang 6,000 salita ang Vercel file noong October 2026. Karaniwang mas kaunti ang kailangan ng backend service. Magsimula sa isang pahina at pahabain lamang ito kapag may maling ginawa ang agent na mapipigilan sana ng isang pangungusap. Hindi haba ang sukatan. Bawat linya ay dapat tumukoy sa isang bagay na maaari sanang magawa nang mali ng agent.