DESIGN.md: Faili Baada ya AGENTS.md

DESIGN.md ni nini, na AGENTS.md haishughulikii nini

DESIGN.md ni faili la markdown lililo kwenye root ya repository yako. Linaeleza kwa nini code imeundwa kwa njia hiyo. AGENTS.md hujibu swali tofauti: jinsi ya kufanya kazi hapa. Hilo linajumuisha build command, test command, lint inayopaswa kufaulu, na paths ambazo hazipaswi kuguswa. DESIGN.md huhifadhi maamuzi ambayo tayari yamekubaliwa, pamoja na kinachoharibika mojawapo ya maamuzi hayo kinapobatilishwa.

Coding agent, yaani tool kama Claude Code au Cursor inayosoma na kuhariri repository yako yenyewe, huwa na uhakika kwa chaguo-msingi. Ikipata pattern ambayo haitambui, hujaribu kuiboresha. Cache iliyoandikwa kwa mkono inaweza kubadilishwa kuwa Redis (in-memory data store), kwa sababu hiyo ndiyo namna cache inavyoonekana kwenye code nyingi ambazo model imesoma. AGENTS.md haizuii hali hii, kwa sababu make test hupita katika hali zote mbili. Sheria iliyovunjwa haikuwa imeandikwa mahali ambapo agent angeweza kuisoma.

Ikiwa bado hujaandika faili la kwanza, anza hapo. AGENTS.md na HUMAN.md iliyo kando yake inaeleza format na mahali kila tool inapoitafuta. Kinachofuata ni sura inayofuata baada ya hiyo.

Kile kilicho ndani ya DESIGN.md iliyochapishwa

Njia ya haraka zaidi ya kujifunza muundo huu ni kusoma faili ambazo kampuni huchapisha kujihusu. Repository ya official-design-md hufuatilia faili hizo pekee. Kanuni yake ya kujumuisha faili ni mstari mmoja, na mstari huo ndio msingi wa mkusanyo huu:

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

Kufikia Agosti 2026, inaorodhesha saba: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel na VoltAgent. Kila faili iko kwenye URL ya umma isiyobadilika, kwa hiyo unaweza kuisoma kwenye terminal sasa hivi.

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

Hizo zote mbili ni nyaraka za design system. Zinaeleza jinsi bidhaa inavyopaswa kuonekana: rangi, aina ya herufi, nafasi na mwendo. Puuza mada yenyewe unapozisoma, kwa sababu sehemu muhimu ni muundo wa uandishi, si mada inayozungumziwa.

Faili ya Nuxt ina takriban maneno 2,100, na sehemu kubwa yake ni kanuni iliyoambatanishwa na sababu yake:

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

Faili ya Vercel ni ndefu zaidi, ikiwa na takriban maneno 6,500 mnamo Agosti 2026, na inaenda hatua moja zaidi. Mojawapo ya headings zake ni Reject generated-design reflexes. Chini yake kuna orodha ya vitu ambavyo generator yenye uwezo huchagua wakati hakuna mtu aliyeiambia isivitumie:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Sentensi hiyo inafafanua aina ya faili hii. Ni orodha iliyoandikwa ya defaults ambazo model yenye uhakika huzalisha, iliyochapishwa ili model iache kuzalisha. Kila DESIGN.md inayostahili ku-commit ni orodha hiyo kwa domain fulani.

Kwa nini kampuni huchapisha DESIGN.md zao?

Jumuiya ilitangulia. awesome-design-md ina faili 73 zilizofanyiwa reverse engineering kutoka kwenye tovuti za umma. Kila faili limeandikwa kwa muundo uleule wa sehemu tisa, ili agent iweze kupewa faili moja na kutoa kitu kinachokaribia mwonekano huo. Faili hizo ni muhimu, lakini bado ni makadirio. Hakuna mtu kutoka kampuni hizo aliyezihakiki.

Faili ya kampuni yenyewe ni tofauti kwa sababu ndiyo chanzo, si tafsiri ya matokeo. Vercel ikibadilisha type scale yake, vercel.com/design.md hubadilika pamoja nayo. Nakala iliyokusanywa kwa scraping mwezi wa Machi itaendelea kumfundisha agent type scale ya zamani. Hakuna kitu kwenye repository yako kitakachokuambia kuwa nakala hiyo imepitwa na wakati.

Wachapishaji saba ni idadi ndogo, na repository inasema hivyo: standard hii ni mpya na matumizi rasmi yanaongezeka. Makusanyo yote mawili yanatunzwa na VoltAgent, framework ya open source ya agent ambayo pia huchapisha faili yake. Kwa hiyo, isome orodha hiyo kama tracker, si kama census isiyoegemea upande wowote. Bado inafaa kuifuatilia kwa sababu ya kampuni hizo saba. Hizo ndizo kampuni ambazo developers wengine hunakili front-end code zao mara nyingi zaidi. Faili zao zinakuwa mfano unaotumika kuonyesha DESIGN.md ni nini. Linganisha njia iliyofuatwa na AGENTS.md: agents.md sasa ina zaidi ya miradi 60,000 ya open source inayotumia muundo huo. Usimamizi wake uko chini ya Agentic AI Foundation ndani ya Linux Foundation. Conventions za faili zinazoweza kusomeka na agent zinawekwa haraka, na zinawekwa kuanzia kampuni kubwa.

Nini huwekwa kwenye DESIGN.md wakati mradi hauna kiolesura cha mtumiaji

Programu nyingi zinazoendesha kwenye VPS hazina lugha ya mwonekano inayohitaji kubainishwa. Faili hii bado ina umuhimu, kwa sababu utaratibu hauhusiani na rangi. Inahusu kuandika vikwazo ambavyo mhariri mwenye uelewa angevuka bila kukusudia.

Masharti yasiyobadilika. Andika sentensi moja kwa kila sharti, ikieleza jambo ambalo lazima liendelee kuwa kweli baada ya mabadiliko yoyote. “Kila uandishi hupitia queue.enqueue(). Uandishi wa moja kwa moja kwenye database hupita audit log, na audit log ndiyo inayosomwa na compliance export.” Sharti lisilobadilika likiambatanishwa na sababu yake hudumu hata linapokabiliwa na task ambayo hukuitarajia. Sharti lililo peke yake huonekana kama upendeleo, na mapendeleo huondolewa wakati wa optimisation.

Njia mbadala zilizokataliwa. Taja chaguo lililoonekana wazi na sababu iliyofanya likataliwe. “Hatutumii Redis kwa caching. Service inaendesha kwenye VPS moja, kwa hiyo map ya ndani ya process ina kasi zaidi na ina daemon mmoja pungufu wa kuiweka ikiendelea. Tathmini tena hili kutakapokuwapo application server ya pili.” Bila aya hiyo, agent anayeombwa kuongeza kasi ya cache ataongeza Redis, na atakuwa amefanya jambo sahihi: hukumweleza kizuizi hicho. Hii ndiyo sehemu inayofanya faili zima liwe na thamani.

Mipaka. Hizi ni sehemu ambazo mabadiliko madogo yanaweza kusababisha madhara makubwa. Database schema. Public route prefix ambayo wateja tayari huitumia kwenye scripts. Config file ambayo deploy huisoma kabla application haijaanza. Cron entry inayodhani kuwa nakala moja tu ndiyo inaendesha. Zitaje, na eleza gharama ya kubadilisha kila moja.

Msamiati. Ikiwa code inasema tenant na timu inasema customer, andika uhusiano huo wazi. Agent anayekisia vibaya hapa hutengeneza code inayosomeka vizuri lakini inaeleza kitu kisicho sahihi, na hilo ndilo kosa gumu zaidi kugundua wakati wa review.

DESIGN.md unayoweza kunakili leo

# 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.

Jaza sehemu mbili unazoweza kuandika leo bila kurejelea nyaraka, yaani invariants na rejected alternatives, kisha acha sehemu nyingine zikiwa vichwa pekee. Faili yenye mistari minne ya kweli inatosha. Faili yenye mistari arobaini ya kubuni haifai.

Baadhi ya zana hupakia kila faili la markdown katika root ya repository, na nyingine hupakia faili pekee iliyoelekezwa kwao. Kwa hiyo, usikisie. Ongeza pointer ya AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

Muundo wa kuepuka: DESIGN.md unaorudia README

Toleo baya linalopatikana mara nyingi husomeka vizuri lakini halifundishi chochote. Linaanza kwa kueleza mradi hufanya nini, linaorodhesha vipengele, linaeleza jinsi ya kuusakinisha, kisha linaishia kwa leseni. Kila mstari wa maelezo hayo tayari upo kwenye README, na hakuna unaoeleza kwa nini mambo yamepangwa hivyo.

Hilo linakugharimu mara mbili. Gharama ya kwanza ni muktadha. Faili ambayo agent huisoma mwanzoni mwa kila kazi hulipiwa katika kila kazi, na sehemu ya usakinishaji iliyorudiwa ni mzigo usio na faida ndani ya muda maalum. Kupanga matumizi ya muda huo ni ujuzi wa pekee, unaoelezwa katika kusimamia context window katika Claude Code. Kwa kifupi: chochote kinachopakiwa kiotomatiki kinapaswa kuwa maandishi yenye thamani kubwa zaidi kwenye repository.

Gharama ya pili ni kubwa zaidi. Nakala mbili za kauli ileile huanza kutofautiana. README inasema huduma inasikiliza kwenye 8080, lakini DESIGN.md bado inasema 3000, na agent hana njia ya kuamua ipi ina uzito zaidi. Kwa hiyo huchagua moja na kuandika code kulingana nayo. Faili ambayo wakati mwingine huwa na makosa husomwa kwa kujiamini sawa na faili ambayo huwa sahihi kila mara.

Jaribio ni rahisi. Ikiwa aya inaweza kuwekwa bila tatizo kwenye README, iondoe kwenye DESIGN.md. Kinachobaki kinapaswa kuwa sehemu ambayo ungeisema wazi wakati wa code review, sehemu inayoanza kwa “tayari tulijaribu hilo”.

Unajuaje kama faili linafanya kazi?

Hakuna linter ya faili hili. Kuna ukaguzi unaoweza kuendesha ndani ya dakika moja.

Mpe agent kazi inayouelekeza moja kwa moja kwenye invariant. "Ongeza background job inayoweka rows zilizopitwa na wakati kuwa expired." Faili linalotekeleza kazi yake huonekana kwenye jibu kabla ya code yoyote: agent anapaswa kukuambia kuwa job inaandika kupitia queue.enqueue(), kwa sababu direct write ingeacha audit log. Ikiwa inafungua database connection na kuandika, basi moja kati ya mambo mawili ni kweli. Faili halisomwi kabisa, au invariant imeandikwa kwa ujumla kiasi cha kuruhusu mabishano.

Fuatilia token count pia, kwa sababu faili hili hupakiwa kwenye kila turn. Ikiwa matumizi ya context yanaongezeka baada ya kuongeza DESIGN.md na majibu hayawi bora, faili lina prose ambayo agent tayari alikuwa nayo. Kusoma token counters katika Claude Code kunaonyesha budget hiyo inatumika wapi.

Hili ni muhimu zaidi agent anapoishi kwenye server badala ya laptop yako. Agent anayefanya kazi kwenye session inayoendelea kwa muda mrefu, kama usanidi ulio katika Claude Code workspace kwenye VPS yenye tmux, hana kumbukumbu ya mazungumzo ya jana. Repository ndiyo kumbukumbu. Kila kitu ulichoeleza kwenye chat na hukuki-commit hupotea kwenye session inayofuata, na DESIGN.md ndiyo mahali pa kuhifadhi maelezo hayo ili yabaki.

Anza na maamuzi mnayobishania

Toleo la kwanza huchukua dakika ishirini. Fungua pull request kadhaa za mwisho ambapo reviewer aliandika “hapana, sisi hufanya hivi tofauti hapa”. Kila maoni hayo ni invariant ambayo haikuwahi kuandikwa, na kila moja ni eneo ambalo agent atafanya kosa hilohilo kwa kasi na mara nyingi zaidi kuliko mtu. Ongeza kwenye faili inapokufeli, si kwa ratiba maalum. Ikiwa bado unatafuta namna ya kuingiza agents katika workflow ya kawaida ya development, mwongozo wa 2026 wa kujifunza AI agents ni hatua inayofuata inayofaa.

FAQ

Je, DESIGN.md ni kiwango rasmi?

Si kwa namna ambayo AGENTS.md ilivyo. AGENTS.md ina ukurasa wake katika agents.md, inatumiwa na zaidi ya miradi 60,000 ya open source, na inasimamiwa chini ya Agentic AI Foundation, iliyo sehemu ya Linux Foundation. Kufikia August 2026, DESIGN.md haina chombo cha usimamizi wala specification iliyochapishwa. Kilicho nacho ni matumizi ya first-party: kampuni saba, zikiwemo Vercel, Nuxt, Atlassian na Resend, huchapisha faili hiyo kwenye URL ya umma, na mkusanyo wa jumuiya una faili nyingine 73 zilizoundwa upya kutokana na tovuti za umma. Ichukulie kama convention unayoweza kutumia sasa na kuipanua kwa uhuru, kwa sababu hakuna kinachothibitisha majina ya sections zako.

Je, DESIGN.md inapaswa kuwa section tu ya AGENTS.md?

Kwa repository ndogo, ndiyo. File moja ambayo agent huisoma kwa hakika ni bora kuliko files mbili ambazo moja inaweza kupuuzwa. Zitenge AGENTS.md inapoacha kuwa rahisi kuchanganua, au unapoona sehemu hizo mbili zikibadilika kwa kasi tofauti. AGENTS.md hubadilika build inapobadilika. DESIGN.md hubadilika uamuzi unapobadilika, jambo ambalo hutokea mara chache na huwa na uzito zaidi. Unapozitenganisha, ongeza line moja katika AGENTS.md inayomwambia agent asome DESIGN.md kabla ya kuhariri code, kwa sababu si kila tool hupakia kila markdown file iliyo kwenye root.

DESIGN.md inatofautianaje na architecture decision record?

ADR (architecture decision record) ni rekodi yenye tarehe ya uamuzi mmoja, na project yenye afya hujilimbikizia dazaini kadhaa katika folder. Hiyo ni history, na history ni ghali kupakia, kwa sababu agent angelazimika kuzisoma zote ili kubaini ni zipi bado ni za kweli. DESIGN.md ni hali ya sasa, iliyoandikwa ili isomwe yote katika kila task. Endelea kutumia zote mbili ikiwa tayari unaandika ADRs. ADR husema kilichoamuliwa na wakati kilipoamuliwa. DESIGN.md husema kilicho kweli leo, na hiyo ndiyo unayomwelekeza agent asome.

DESIGN.md inapaswa kuwa na urefu gani?

Iwe fupi kiasi cha kupakiwa katika kila turn bila kujuta. Examples zilizochapishwa ni ndefu kwa sababu zinaeleza visual language nzima: kufikia August 2026, file ya Nuxt ina takribani maneno 2,100 na file ya Vercel takribani 6,500. Backend service kwa kawaida huhitaji machache zaidi. Anza na ukurasa mmoja, kisha irefushe tu agent anapokosea jambo ambalo sentence moja ingezuia. Urefu si kipimo. Kila line inapaswa kuwa jambo ambalo agent angekosea vinginevyo.