DESIGN.md: File Pagkatapos ng AGENTS.md

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 ang aktuwal na nilalaman ng isang inilathalang DESIGN.md

Ang pinakamabilis na paraan para matutuhan ang format ay basahin ang mga file na inilalathala ng mga kumpanya tungkol sa kanilang sarili. Tanging ang mga iyon ang sinusubaybayan ng repository na official-design-md. Isang linya lamang ang tuntunin nito sa pagsama, at iyon ang pinakapunto ng koleksiyon:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

Noong August 2026, pitong file ang nakalista rito: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel, at VoltAgent. May stable public URL ang bawat file, kaya maaari mong basahin ang isa sa terminal ngayon.

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

Pareho silang mga document para sa design system. Inilalarawan ng mga ito kung ano ang dapat na hitsura ng isang produkto: kulay, typography, spacing, at motion. Huwag tumigil sa paksa, dahil ang kapaki-pakinabang na bahagi ay ang estruktura ng pagkakasulat, hindi ang topic.

Humigit-kumulang 2,100 salita ang Nuxt file, at karamihan dito ay rule na may kalakip na dahilan:

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

Mas mahaba ang Vercel file—humigit-kumulang 6,500 salita noong August 2026—at mas detalyado ito nang isang hakbang. Isa sa mga heading nito ay Reject generated-design reflexes. Sa ilalim nito ay may listahan ng mga karaniwang ginagamit ng isang mahusay na generator kapag walang nagsabi rito na huwag gamitin ang mga iyon:

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 inilalabas ng isang kumpiyansang model, na inilathala upang tumigil ang model sa paglalabas ng mga iyon. Ang bawat DESIGN.md na karapat-dapat i-commit ay listahang iyon para sa isang partikular na domain.

Bakit naglalabas ang mga kumpanya ng sarili nilang DESIGN.md?

Nauna ang komunidad. Naglalaman ang awesome-design-md ng 73 file na reverse-engineered mula sa mga public website. Pare-pareho ang gamit ng mga ito na nine-section format, kaya maaaring ituro ng agent ang isa sa mga ito at makagawa ng output na malapit sa ganoong itsura. Kapaki-pakinabang ang mga file na iyon, pero mga hula pa rin ang mga ito. Walang sinuman sa mga kumpanyang iyon ang nag-review 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 tungkol sa lumang scale, at walang anumang bagay sa repository mo ang magsasabi na luma na ang kopyang iyon.

Maliit na bilang ang pitong publisher, at sinasabi rin iyon ng repository: bago pa ang standard at lumalaki ang opisyal na adoption. Ang parehong collection ay mina-maintain ng VoltAgent, isang open source agent framework na naglalabas din ng sarili nitong file. Kaya ituring ang listahan bilang tracker, hindi bilang neutral na census. Gayunman, sulit pa rin itong subaybayan dahil sa kung sino ang pitong iyon. Sila ang mga kumpanyang pinakamadalas kopyahan ng ibang developer ng front-end code, at nagiging worked example ng DESIGN.md ang mga file nila. Ihambing ito sa naging landas ng AGENTS.md: mayroon na ngayong mahigit 60,000 open source project na gumagamit ng format sa agents.md, at nasa Agentic AI Foundation sa ilalim ng Linux Foundation ang pangangasiwa rito. Mabilis nang nabubuo ang mga convention para sa agent-readable file, at mula sa mga nangungunang organisasyon nagmumula ang direksyon ng pagbuo nito.

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 standard ang DESIGN.md?

Hindi sa paraang opisyal 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. Hanggang August 2026, walang namamahalang organisasyon o inilabas na specification ang DESIGN.md. Ang mayroon ito ay first-party adoption: pitong kumpanya, kabilang ang Vercel, Nuxt, Atlassian, at Resend, ang nagpa-publish nito sa isang public URL, at may community collection na naglalaman ng 73 pang reverse-engineered mula sa mga public site. Ituring itong convention na maaari mong gamitin ngayon at malayang palawakin, dahil walang nagva-validate sa mga pangalan ng section mo.

Dapat bang section lang ng AGENTS.md ang DESIGN.md?

Para sa maliit na repository, oo. Mas mabuti ang isang file na siguradong binabasa ng agent kaysa dalawang file na maaaring hindi mabasa ang isa. Paghiwalayin ang mga ito kapag hindi na madaling ma-scan ang AGENTS.md, o kapag napansin mong magkaiba ang bilis ng pagbabago ng dalawang bahagi. Nagbabago ang AGENTS.md kapag nagbabago ang build. Nagbabago ang DESIGN.md kapag may nagbabagong desisyon, 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 dated record ng isang desisyon, at ang maayos na project ay naiipon ang dose-dosenang ADR sa isang folder. Kasaysayan iyon, at magastos i-load ang kasaysayan dahil kailangang basahin ng agent ang lahat ng ito para matukoy kung alin pa ang valid. Ang DESIGN.md ang kasalukuyang estado, 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 kung kailan. Sinasabi ng DESIGN.md kung ano ang totoo ngayon, at ito ang itinuturo mo sa agent.

Gaano kahaba dapat ang isang DESIGN.md?

Dapat sapat na maikli para ma-load sa bawat turn nang hindi ito pinagsisisihan. Mahahaba ang mga inilabas na halimbawa dahil tinutukoy ng mga ito ang isang buong visual language: humigit-kumulang 2,100 salita ang Nuxt file at humigit-kumulang 6,500 salita ang Vercel file noong August 2026. Karaniwang mas kaunti ang kailangan ng backend service. Magsimula sa isang page at palawakin lamang ito kapag may nagawang mali ang agent na mapipigilan sana ng isang pangungusap. Hindi haba ang sukatan. Dapat bawat linya ay tumutukoy sa isang bagay na maaaring mali ang gawin ng agent kung wala ito.