DESIGN.md: File Pagkatapos ng AGENTS.md

Ano ang DESIGN.md, at ano ang hindi saklaw ng AGENTS.md

Ang DESIGN.md ay isang markdown file sa root ng iyong repository na nagpapaliwanag sa isang AI coding agent kung bakit ganoon ang pagkakabuo ng code. Ibang tanong ang sinasagot ng AGENTS.md: kung paano magtrabaho rito. Kabilang dito 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 kung ano ang masisira kapag binago ang mga ito.

Ang coding agent, gaya ng tool na Claude Code o Cursor na kusang nagbabasa at nag-e-edit ng iyong repository, ay karaniwang kumpiyansa sa mga ginagawa nito. Kapag nakakita ito ng pattern na hindi nito nakikilala, inaayos nito ang pattern na iyon. Ang manu-manong ginawang cache ay maaaring gawing Redis (in-memory data store), 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. Ang nilabag na rule ay hindi kailanman naisulat sa lugar na mababasa ng agent.

Kung hindi mo pa naisusulat ang unang file, magsimula roon. Sinasaklaw ng AGENTS.md at HUMAN.md na nasa tabi nito ang format at kung saan ito hinahanap ng bawat tool. Ang sumusunod ay kabanata pagkatapos nito.

Ano talaga ang laman ng isang na-publish na 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 mga ganitong file ang sinusubaybayan ng repository na official-design-md. Isang linya lamang ang inclusion rule nito, at iyon ang pangunahing layunin 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 August 2026, may pitong nakalista rito: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel, at VoltAgent. Nasa 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

Parehong design system document ang dalawang iyon. Inilalarawan ng mga ito kung ano dapat ang itsura ng isang produkto: kulay, typography, spacing, at motion. Huwag tumigil sa paksa ng mga ito, dahil ang kapaki-pakinabang na bahagi ay ang anyo ng pagkakasulat, hindi ang paksa.

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, na humigit-kumulang 6,500 salita noong August 2026, at may idinagdag 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 capable 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 ginagawa ng isang confident model, na inilalathala upang itigil ng model ang paggawa ng 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 nang nabuo ito ng komunidad. May 73 file ang awesome-design-md na ni-reverse-engineer mula sa mga public website. Pare-pareho ang gamit nilang nine-section format, kaya maaaring ituro ng isang agent ang alinman sa mga ito upang makagawa ng output na malapit sa ganoong visual style. 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 source ito, 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 anumang nasa repository mo ang magsasabi na stale na ang kopya.

Maliit na bilang ang pitong publisher, at sinasabi rin ito ng repository: bago pa ang standard at lumalaki ang official adoption. Ang dalawang collection ay mina-maintain ng VoltAgent, isang open source agent framework na naglalabas din ng sarili nitong file. Kaya basahin ang listahan bilang tracker, hindi bilang neutral na census. Gayunman, sulit pa rin itong bantayan dahil sa kung sinu-sino ang pitong iyon. Sila ang mga kumpanyang pinakamadalas kopyahan ng front-end code ng ibang developer, at nagiging worked example ang mga file nila kung ano ang isang DESIGN.md. Ikumpara ang naging landas ng AGENTS.md: mayroon nang mahigit 60,000 open source project na gumagamit ng format ang agents.md, at ang stewardship nito ay nasa Agentic AI Foundation sa ilalim ng Linux Foundation. Mabilis nang nabubuo ang mga convention para sa mga file na nababasa ng agent, at mula sa mga nangungunang kumpanya nanggagaling ang direksiyon ng mga ito.

Ano ang nilalaman ng DESIGN.md kapag walang user interface ang proyekto

Karamihan sa software na tumatakbo sa VPS ay walang visual language na kailangang tukuyin. May silbi pa rin ang file dahil walang kinalaman ang mekanismo sa kulay. Ang layunin nito ay itala ang mga constraint na maaaring malabag ng isang kumpiyansang editor nang hindi namamalayan.

Mga invariant. Tig-isang pangungusap na nagsasaad ng bagay na dapat manatiling totoo pagkatapos ng anumang edit. "Dapat dumaan sa queue.enqueue() ang bawat write. Nilalaktawan 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 sa task na hindi mo inasahan. Kapag nag-iisa ang invariant, nagmumukha 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. Iisang VPS lang ang pinapatakbo ng service, kaya mas mabilis ang in-process map at isa itong daemon na hindi na kailangang panatilihing tumatakbo. Balikan ito kapag may ikalawang application server na." Kung wala ang talatang iyon, magdadagdag ng Redis ang agent na inutusang pabilisin ang cache, at tama itong gawin dahil hindi mo sinabi ang constraint. Ito ang seksyong bumabawi sa buong file.

Mga boundary. Ito ang mga lugar kung saan maaaring malaki ang epekto ng maliit na edit. Kasama rito ang database schema, ang public route prefix na ginagamit na sa mga script ng mga customer, ang config file na binabasa ng deploy bago magsimula ang application, at ang cron entry na nag-aakalang iisang kopya lang nito ang tumatakbo. Pangalanan ang mga ito at sabihin kung ano ang magiging halaga ng pagbabago sa bawat isa.

Talasalitaan. Kung tenant ang nasa code at customer ang tawag dito ng team, itala ang mapping. Kapag mali ang hula ng agent dito, makagagawa ito ng code na maayos basahin ngunit maling konsepto ang mino-model. Ito ang pinakamahirap mapansin na uri ng pagkakamali sa 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.

Punan ang dalawang seksyong kaya mong isulat mula sa memorya ngayon: mga invariant at mga alternatibong tinanggihan. Iwan ang iba bilang mga heading. Gumagana ang file na may apat na tapat na linya. Hindi gumagana ang file na may apatnapung hula lamang.

May ilang tool na naglo-load ng bawat markdown file sa root ng repository, at may ilan namang naglo-load lamang ng file na itinuro sa mga ito. Kaya huwag magpalagay. Magdagdag ng pointer papunta 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: isang 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 kang nagbabayad para rito. Ang unang gastos ay context. Ang file na binabasa ng agent sa simula ng bawat task ay binabayaran sa bawat task, at purong overhead ang duplicate na installation section laban sa limitadong window. Kasanayan mismo ang pagba-budget sa window na iyon; tinalakay ito sa pag-manage ng context window sa Claude Code. Ang maikling bersyon: anumang awtomatikong nilo-load ay dapat ang text na may pinakamataas na halaga sa repository.

Mas malala ang ikalawang gastos. Nagkakahiwalay ang dalawang kopya ng parehong pahayag. Sinasabi ng README na nakikinig ang service sa 8080, habang 3000 pa rin ang nasa DESIGN.md, at walang paraan ang agent para malaman kung alin ang dapat unahin. Kaya pumipili ito ng isa at nagsusulat ng code batay rito. Ang file na minsan ay mali ay kinokonsulta nang may kaparehong kumpiyansa sa file na laging tama.

Mabilis ang test. Kung komportableng mailalagay ang isang paragraph sa README, alisin ito sa DESIGN.md. Ang matitira ay dapat iyong sasabihin mo nang malakas sa isang code review—iyong bahaging nagsisimula sa “nasubukan 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 nagsusulat ang job sa pamamagitan ng queue.enqueue(), dahil malalaktawan ng direct write ang audit log. Kung nagbukas ito ng database connection at direktang nagsulat, isa sa dalawang bagay ang totoo. Hindi talaga binabasa ang file, o sapat na maluwag ang pagkakasulat sa invariant para pagtalunan ito.

Bantayan din ang token count, dahil nilo-load ang file sa bawat turn. Kung 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 gumagana sa long-running session, gaya ng setup sa Claude Code workspace sa VPS gamit ang tmux, ay walang memorya ng pag-uusap ninyo kahapon. Ang repository ang 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 pinagtatalunan ninyo

Dalawampung minuto ang kailangan para sa unang bersyon. Buksan ang mga pinakahuling pull request kung saan may reviewer na sumulat ng “hindi, iba ang paraan natin dito.” Bawat isa sa mga komentong iyon ay invariant na hindi naisulat, at bawat isa ay posibleng pagkunan ng parehong pagkakamali ng agent—mas mabilis at mas madalas kaysa sa isang tao. Idagdag ito sa file kapag nabigo ka nito, hindi ayon sa isang takdang iskedyul. Kung tinutukoy mo pa rin kung saan dapat gamitin 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 ito ang AGENTS.md. May home ang AGENTS.md sa agents.md, ginagamit ito ng mahigit 60,000 open source project, at pinangangasiwaan ito ng Agentic AI Foundation bilang bahagi ng Linux Foundation. Noong August 2026, walang governing body at walang published 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 public URL, at may community collection na naglalaman ng 73 pa na reverse-engineered mula sa mga public site. Ituring itong convention na maaari mong gamitin at malayang palawakin ngayon, dahil walang nagva-validate sa mga pangalan ng iyong section.

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

Para sa maliit na repository, oo. Mas mabuti ang isang file na tiyak na mababasa ng agent kaysa dalawang file kung saan 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 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 dated record ng isang decision, at ang maayos na project ay karaniwang nag-iipon ng dose-dosenang ADR sa isang folder. History iyon, at mahal mag-load ng history dahil kailangang basahin ng agent ang lahat ng ito para malaman kung alin pa ang kasalukuyang valid. Ang DESIGN.md ay naglalaman ng kasalukuyang state at isinulat para basahin nang buo sa bawat task. Panatilihin ang dalawa kung nagsusulat 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 ang ikli nito para ma-load sa bawat turn nang walang pagsisisi. Mahahaba ang published examples dahil tinutukoy ng mga ito ang buong visual language: humigit-kumulang 2,100 words ang file ng Nuxt at humigit-kumulang 6,500 naman ang file ng Vercel noong August 2026. Karaniwang mas maikli ang kailangan ng isang backend service. Magsimula sa isang page at dagdagan lamang ito kapag may maling ginawa ang agent na mapipigilan sana ng isang pangungusap. Hindi haba ang sukatan. Dapat bawat linya ay tumutukoy sa isang bagay na maaaring magawa nang mali ng agent kung wala ito.