Jinsi ya kutumia DESIGN.md kuzuia AI kubadilisha msimbo

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

DESIGN.md ni faili la markdown lililopo kwenye mzizi wa hazina (repository) yako ambalo humweleza wakala wa uandishi wa msimbo (AI coding agent) sababu za muundo wa msimbo huo. AGENTS.md hujibu swali tofauti: jinsi ya kufanya kazi hapa, likijumuisha amri ya ujenzi (build command), amri ya majaribio (test command), lint inayopaswa kupita, na njia (paths) za kutoguswa. DESIGN.md hurekodi maamuzi yaliyokwisha kubaliwa, na kile kinachoharibika pale mojawapo ya maamuzi hayo yanapobatilishwa.

Wakala wa uandishi wa msimbo, yaani zana kama Claude Code au Cursor inayosoma na kuhariri hazina yako yenyewe, huwa na ujasiri kwa chaguo-msingi. Inapokuta muundo (pattern) isiyoifahamu, huiboresha muundo huo. Cache iliyoandikwa kwa mkono inageuzwa kuwa Redis (hifadhi ya data ya ndani ya kumbukumbu), kwa sababu ndivyo cache inavyoonekana katika sehemu kubwa ya msimbo ambao modeli imesoma. AGENTS.md haizuii hili, kwa sababu make test hupita kwa vyovyote vile. Kanuni iliyovunjwa haikuwahi kuandikwa popote ambapo wakala angeweza kuisoma.

Ikiwa bado hujaandika faili la kwanza, anzia hapo. AGENTS.md na HUMAN.md iliyo kando yake inashughulikia umbizo na mahali ambapo kila zana inapotafuta faili hilo. Kinachofuata ni sura inayokuja baada ya hiyo.

Ni nini hasa kilichomo ndani ya DESIGN.md iliyochapishwa

Njia ya haraka zaidi ya kujifunza muundo huu ni kusoma faili ambazo makampuni huchapisha kuyahusu. Hazina ya official-design-md hufuatilia faili hizo pekee. Kanuni yake ya ujumuishaji ni mstari mmoja, na mstari huo ndio kiini cha mkusanyiko 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 inapatikana katika URL ya umma iliyo thabiti, kwa hivyo unaweza kusoma moja kwenye terminal hivi sasa.

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

Zote mbili ni nyaraka za mfumo wa usanifu (design system). Zinaelezea jinsi bidhaa inavyopaswa kuonekana: rangi, chapa ya maandishi, nafasi, na miondoko. Soma zaidi ya mada husika, kwa sababu sehemu muhimu ni mtindo wa uandishi badala ya mada yenyewe.

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

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, ina takriban maneno 6,500 kufikia Agosti 2026, na inakwenda hatua moja zaidi. Mojawapo ya vichwa vyake vya habari ni Reject generated-design reflexes. Chini yake kuna orodha ya vitu ambavyo jenereta yenye uwezo huchagua wakati hakuna mtu aliyoiambia isifanye hivyo:

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 chaguo-msingi (defaults) ambazo modeli yenye ujasiri huzalisha, iliyochapishwa ili modeli hiyo iache kuzizalisha. Kila DESIGN.md inayostahili kuhifadhiwa ni orodha hiyo kwa kikoa fulani.

Kwa nini makampuni yanachapisha DESIGN.md yao wenyewe?

Jumuiya ilianza kufanya hivyo mapema. awesome-design-md ina faili 73 zilizotengenezwa kwa njia ya reverse-engineering kutoka kwenye tovuti za umma, kila moja ikiwa imeandikwa kwa muundo uleule wa sehemu tisa, ili wakala (agent) aweze kuelekezwa kwenye faili moja na kutoa matokeo yanayokaribiana na muonekano huo. Faili hizo ni muhimu lakini bado ni makisio tu. Hakuna mtu katika makampuni hayo aliyeyapitia.

Faili ya kwanza (first-party) ni tofauti kwa sababu ndiyo chanzo badala ya kuwa tafsiri ya matokeo. Vercel inapobadilisha kiwango chake cha fonti (type scale), vercel.com/design.md inabadilika pamoja nayo. Nakala iliyokusanywa mwezi Machi itaendelea kumfundisha wakala wako kiwango cha zamani, na hakuna kitu katika hazina (repository) yako kitakachokuambia kuwa nakala hiyo imepitwa na wakati.

Wachapishaji saba ni idadi ndogo, na hazina yenyewe inasema hivyo: kiwango hiki ni kipya na upokeaji rasmi unazidi kukua. Makusanyo yote mawili yanatunzwa na VoltAgent, mfumo wa wakala wa chanzo huria (open source agent framework) ambao nao huchapisha faili yake pia, kwa hivyo soma orodha hiyo kama kifuatiliaji na si kama sensa isiyo na upendeleo. Bado inafaa kufuatiliwa, kwa sababu ya utambulisho wa hao saba. Hawa ni makampuni ambayo kanuni zao za front-end hunakiliwa zaidi na watengenezaji wengine, na faili zao zinakuwa mfano wa kuigwa wa kile ambacho DESIGN.md inapaswa kuwa. Linganisha njia iliyochukuliwa na AGENTS.md: agents.md sasa inahesabu zaidi ya miradi 60,000 ya chanzo huria inayotumia muundo huo, na usimamizi uko chini ya Agentic AI Foundation iliyo chini ya Linux Foundation. Kanuni za faili zinazoweza kusomwa na wakala zinatulia haraka, na zinatulia kuanzia ngazi ya juu.

Nini kinapaswa kuwemo kwenye DESIGN.md wakati mradi hauna kiolesura cha mtumiaji

Programu nyingi zinazoendeshwa kwenye VPS hazina lugha ya kuona ya kubainisha. Faili hii bado inastahili kuwepo, kwa sababu utaratibu huu hauhusiani na rangi. Inahusu kuandika vikwazo ambavyo mhariri anayejiamini angevikiuka bila kutambua.

Invariants. Sentensi moja kila moja, ikieleza jambo ambalo lazima libaki kuwa kweli baada ya marekebisho yoyote. "Kila uandishi hupitia queue.enqueue(). Uandishi wa moja kwa moja kwenye database unaruka logi ya ukaguzi, na logi ya ukaguzi ndiyo inayosomwa na export ya utiifu." Invariant iliyoambatishwa na sababu yake hustahimili kazi ambayo hukuwahi kutarajia. Invariant iliyo peke yake husomeka kama upendeleo, na mapendeleo huboreshwa na kuondolewa.

Njia mbadala zilizokataliwa. Chaguo dhahiri, na kwa nini lilishindwa. "Hatutumii Redis kwa ajili ya caching. Huduma inaendeshwa kwenye VPS moja, kwa hivyo ramani ya ndani ya mchakato (in-process map) ni ya haraka zaidi na ni daemon moja pungufu ya kuhifadhiwa ikiwa hai. Rejea hili wakati seva ya pili ya programu itakapokuwepo." Bila aya hiyo, wakala aliyeulizwa kuharakisha cache ataongeza Redis, na yuko sahihi kufanya hivyo: hukuwahi kumwambia kuhusu kizuizi hicho. Hii ndiyo sehemu inayolipa gharama ya faili nzima.

Mipaka. Maeneo ambapo marekebisho madogo yana athari kubwa. Schema ya database. Kiambishi awali cha njia ya umma (public route prefix) ambacho wateja tayari wanakiandikia hati (script). Faili ya usanidi ambayo deploy inaisoma kabla ya programu kuanza. Ingizo la cron linalodhani kuwa nakala moja tu ndiyo inayofanya kazi. Yataje, na useme gharama ya mabadiliko kwa kila moja. Ikiwa wakala anaweza pia kufikia mtandao wa wazi, sema kupitia instance ya SearXNG inayojiendesha yenyewe iliyounganishwa kama backend yake ya utafutaji, huo ni mpaka unaostahili kuandikwa pia, kwa sababu faili inapaswa kueleza ni maandishi yapi yaliyochotwa yanayoruhusiwa kuathiri msimbo na yapi yanayopaswa kunukuliwa tu kwako.

Msamiati. Ikiwa msimbo unasema tenant na timu inasema customer, andika ramani hiyo. Wakala anayekisia vibaya hapa hutoa msimbo unaosomeka vizuri lakini unaoiga kitu kisicho sahihi, ambayo ndiyo aina ngumu zaidi ya kosa kugundulika wakati wa uhakiki.

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 kutoka kumbukumbu leo, yaani invariants na njia mbadala zilizokataliwa, na acha sehemu nyingine kama vichwa vya habari. Faili yenye mistari minne ya kweli inatosha. Faili yenye mistari arobaini ya kubahatisha haifai. Ikiwa hazina (repository) ina vifurushi kadhaa, faili moja ya mzizi haitatosheleza vyote, na mgawanyo uleule wa kila saraka unaofanya kazi kwa faili za AGENTS.md zilizowekwa ndani ya monorepo unatumika hapa: faili fupi ya mzizi kwa ajili ya maamuzi yanayoshirikiwa na kila kitu, na faili ndogo zaidi kando ya kila kifurushi chenye maamuzi yake.

Baadhi ya zana hupakia kila faili ya markdown iliyo kwenye mzizi wa hazina na nyingine hupakia ile tu iliyoagizwa, kwa hivyo usidhani. Ongeza kiashiria kuelekea AGENTS.md:

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

Anti-pattern: faili la DESIGN.md linalorudia yaliyomo kwenye README

Toleo baya la kawaida husomeka vizuri lakini halifundishi chochote. Hufunguka kwa kueleza kazi ya mradi, kuorodhesha vipengele, kuelezea jinsi ya kuinstall, na kuhitimisha kwa leseni. Kila mstari wa hayo tayari upo kwenye README, na hakuna hata mmoja unaoeleza kwa nini mambo yamepangwa kwa namna hiyo.

Hili linakugharimu mara mbili. Gharama ya kwanza ni muktadha (context). Faili ambalo wakala (agent) hulisoma mwanzoni mwa kila kazi hulipiwa kwa kila kazi, na sehemu ya install iliyorudiwa ni mzigo usio na faida ndani ya nafasi finyu ya kumbukumbu. Kupangilia nafasi hiyo ni ujuzi wa kipekee, unaoelezewa katika usimamizi wa context window katika Claude Code. Kwa ufupi: chochote kinachopakiwa kiotomatiki kinapaswa kuwa maandishi yenye thamani ya juu zaidi kwenye hazina (repository).

Gharama ya pili ni mbaya zaidi. Nakala mbili za maelezo sawa hupishana. README inasema huduma inasikiliza kwenye 8080, DESIGN.md bado inasema 3000, na wakala hana njia ya kujua ipi ni sahihi, hivyo huchagua moja na kuandika msimbo (code) kulingana na hiyo. Faili ambalo wakati mwingine huwa na makosa hurejelewa kwa imani sawa na faili ambalo huwa sahihi kila wakati.

Jaribio ni rahisi. Ikiwa aya inaweza kukaa vizuri kwenye README, iondoe kwenye DESIGN.md. Kilichobaki kinapaswa kuwa sehemu ambayo ungesema kwa sauti wakati wa ukaguzi wa msimbo (code review), sehemu inayoanza na "tulishajaribu hilo tayari".

Unajuaje kama faili hili linafanya kazi?

Hakuna linter kwa ajili ya hili. Kuna ukaguzi unaoweza kuufanya ndani ya dakika moja.

Ipe agent kazi inayokiuka kanuni fulani moja kwa moja. "Ongeza background job inayoweka alama kwenye safu (rows) zilizopitwa na wakati kama zilizokwisha muda wake." Faili linalofanya kazi yake litaonekana kwenye jibu kabla ya msimbo wowote: agent anapaswa kukuambia kuwa job hiyo inaandika kupitia queue.enqueue(), kwa sababu uandishi wa moja kwa moja ungeepuka audit log. Ikiwa inafungua muunganisho wa database na kuandika, mojawapo ya mambo haya ni kweli. Faili hilo halisomwi kabisa, au kanuni hiyo imeandikwa kwa njia isiyo na msisitizo kiasi cha kuweza kubishaniwa.

Fuatilia pia idadi ya token, kwa sababu faili hili hupakiwa katika kila hatua. Ikiwa matumizi ya muktadha (context) yanaongezeka baada ya kuongeza DESIGN.md na majibu hayaboreki, faili hilo linabeba maelezo ambayo agent alikuwa nayo tayari. Kusoma vihesabio vya token katika Claude Code inaonyesha mahali ambapo bajeti hiyo huenda.

Hili ni muhimu zaidi wakati agent anapokuwa kwenye seva badala ya kompyuta yako ya mkononi. Agent anayefanya kazi katika kipindi cha muda mrefu (long-running session), kama usanidi uliopo katika workspace ya Claude Code kwenye VPS yenye tmux, hana kumbukumbu ya mazungumzo ya jana. Hazina (repository) ndiyo kumbukumbu. Kila kitu ulichoelezea kwenye chat na ambacho hukukiweka kwenye commit kinapotea katika kipindi kijacho, na DESIGN.md ndipo maelezo hayo yanapohifadhiwa ili yaweze kudumu.

Anza na maamuzi unayojadili

Toleo la kwanza huchukua dakika 20. Fungua maombi kadhaa ya mwisho ya pull requests ambapo mkaguzi aliandika "hapana, tunafanya hivi kwa njia tofauti hapa". Kila moja ya maoni hayo ni kigezo kisichobadilika ambacho hakikuwahi kuandikwa, na kila moja ni mahali ambapo wakala atafanya kosa lilelile, kwa haraka na mara nyingi zaidi kuliko binadamu. Ongeza kwenye faili pale linapokushinda, si kwa kufuata ratiba. Ikiwa bado unatafuta mahali ambapo mawakala wanafaa katika mtiririko wa kawaida wa maendeleo, mwongozo wa 2026 wa kujifunza mawakala wa AI ni hatua inayofuata inayofaa.

FAQ

Je, DESIGN.md ni kiwango rasmi?

Si kwa namna ile ile kama AGENTS.md. AGENTS.md ina makazi yake katika agents.md, inatumiwa na zaidi ya miradi 60,000 ya open source, na inasimamiwa na Agentic AI Foundation, ambayo ni sehemu ya Linux Foundation. Kufikia Agosti 2026, DESIGN.md haina chombo cha usimamizi wala vipimo vilivyochapishwa. Inachonacho ni utekelezaji wa kwanza: kampuni saba, zikiwemo Vercel, Nuxt, Atlassian na Resend, huchapisha faili hiyo kwenye URL ya umma, na mkusanyiko wa jamii una faili nyingine 73 zilizotengenezwa kwa njia ya reverse-engineering kutoka kwenye tovuti za umma. Ichukulie kama mwongozo unaoweza kuufuata sasa na kuupanua kwa uhuru, kwa sababu hakuna kinachothibitisha majina ya sehemu zako.

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

Kwa hazina (repository) ndogo, ndiyo. Faili moja ambayo wakala (agent) anaisoma hakika ni bora kuliko faili mbili ambapo moja inaweza kupuuzwa. Zigawanye wakati AGENTS.md inapoacha kusomeka kwa urahisi, au unapoona sehemu hizo mbili zinabadilika kwa viwango tofauti. AGENTS.md hubadilika wakati build inapobadilika. DESIGN.md hubadilika wakati uamuzi unapobadilika, jambo ambalo ni nadra na lina uzito zaidi. Unapozigawanya, ongeza mstari mmoja kwenye AGENTS.md ukimwelekeza wakala kusoma DESIGN.md kabla ya kuhariri code, kwa sababu si kila zana hupakia kila faili ya markdown iliyo kwenye root.

DESIGN.md inatofautianaje na rekodi ya uamuzi wa usanifu (architecture decision record)?

ADR (architecture decision record) ni rekodi yenye tarehe ya uamuzi mmoja, na mradi mzuri hukusanya makumi ya rekodi hizo kwenye folda. Hiyo ni historia, na historia ni ghali kupakia, kwa sababu wakala angehitaji kuzisoma zote ili kubaini ni zipi bado ni za kweli. DESIGN.md ni hali ya sasa, iliyoandikwa ili isomwe kikamilifu katika kila kazi. Hifadhi zote mbili ikiwa tayari unaandika ADRs. ADR inasema nini kiliamuliwa na lini. DESIGN.md inasema nini ni kweli leo, na ndiyo unayomwelekeza wakala kuisoma.

DESIGN.md inapaswa kuwa na urefu gani?

Iwe fupi kiasi cha kupakia katika kila hatua bila majuto. Mifano iliyochapishwa ni mirefu kwa sababu inabainisha lugha nzima ya muonekano: faili ya Nuxt ina takriban maneno 2,100 na faili ya Vercel ina takriban 6,500 kufikia Agosti 2026. Huduma ya backend kwa kawaida huhitaji kidogo sana. Anza na ukurasa mmoja na uipanue tu wakati wakala anapokosea jambo ambalo sentensi moja ingeweza kulizuia. Urefu si kipimo. Kila mstari unapaswa kuwa jambo ambalo wakala angekosea vinginevyo.