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.

Nini hasa kilichomo ndani ya DESIGN.md iliyochapishwa

Njia ya haraka zaidi ya kujifunza muundo huu ni kusoma faili ambazo makampuni huchapisha kuyahusu wenyewe. 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 Oktoba 2026, inaorodhesha kumi na moja: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel na VoltAgent. Kila faili inapatikana kwenye URL ya umma, nyingi zikiwa kwenye domain ya mchapishaji na nyingine zikiwa kwenye hazina ya umma ya GitHub, 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

Hizo zote mbili ni nyaraka za mfumo wa usanifu (design system). Zinaelezea jinsi bidhaa inavyopaswa kuonekana: rangi, chapa ya maandishi, nafasi, na mwendo. Soma zaidi ya mada husika, kwa sababu sehemu yenye manufaa ni umbo la uandishi badala ya mada yenyewe.

Faili ya Nuxt ina takriban maneno 2,000 kufikia Oktoba 27, 2026, na sehemu kubwa yake ni kanuni iliyoambatana na sababu yake. Inaanza kwa kueleza kuwa dark mode ndiyo theme chaguo-msingi. Inaorodhesha rangi ya chapa (brand green) #00DC82 ikiwa na dokezo kwamba rangi za chapa ni "Kwa ajili ya nembo, picha za mitandao ya kijamii, na machapisho. Usizitumie kama thamani ghafi (raw values) kwenye msimbo wa UI." Karibu na mwisho, sehemu yenye kichwa Reject these inajumuisha:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Faili ya Vercel ni ndefu zaidi, takriban maneno 6,000 kufikia Oktoba 2026, na inakwenda hatua moja zaidi. Moja ya vichwa vyake ni Reject generated-design reflexes. Chini yake kuna orodha ya kile ambacho jenereta yenye uwezo hufikia 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 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 huchapisha DESIGN.md yao wenyewe?

Jumuiya ilianza kufanya hivyo kwanza. awesome-design-md ina faili 84 zilizotolewa kutoka kwenye tovuti za umma, kulingana na hesabu iliyo kwenye README yake kufikia Oktoba 27, 2026. Kila moja imeandikwa kwa muundo uleule wa sehemu tisa, ili wakala (agent) aweze kuelekezwa kwenye faili moja na kutoa kitu kinachokaribiana na mwonekano huo. Faili hizo ni muhimu lakini bado ni makisio tu. Hakuna mtu yeyote 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 chapa (type scale), vercel.com/design.md hubadilika pamoja nayo. Nakala iliyokusanywa (scraped) mwezi Machi inaendelea kumfundisha wakala wako kiwango cha zamani, na hakuna kitu katika hazina (repository) yako kitakachokuambia kuwa nakala hiyo imepitwa na wakati.

Wachapishaji kumi na mmoja bado ni idadi ndogo, na hazina hiyo inasema hivyo: kiwango hiki ni kipya na upokeaji rasmi unakua. Makusanyo yote mawili yanatunzwa na VoltAgent, mfumo wa wakala wa chanzo huria (open source agent framework) ambao huchapisha faili yake pia, kwa hivyo soma orodha hiyo kama kifuatiliaji na si kama sensa isiyo na upendeleo. Bado inafaa kufuatiliwa, kwa sababu ya nani yupo kwenye orodha hiyo. Kadhaa ni makampuni ambayo nambari zao za front-end hunakiliwa zaidi na watengenezaji wengine, na viingilio vipya, Ant Design, Microsoft FAST, Juspay na Oxide Computer, ni mifumo ya usanifu (design systems) ambayo timu nyingine hujenga juu yake. Faili zao zinakuwa mfano halisi wa kile ambacho DESIGN.md inapaswa kuwa. Linganisha njia ambayo AGENTS.md ilifuata: agents.md sasa inahesabu zaidi ya miradi 60,000 ya chanzo huria inayotumia muundo huo, na usimamizi uko chini ya Agentic AI Foundation chini ya Linux Foundation. DESIGN.md imeanza kufuata njia hiyo hiyo. Mnamo Aprili 21, 2026, Google ilitoa kama chanzo huria rasimu ya vipimo kwa ajili ya muundo huo, iliyochapishwa kama google-labs-code/design.md ikiwa na token schema na CLI chini ya leseni ya Apache-2.0. Kufikia Oktoba 2026 muundo huo uko kwenye toleo la alpha na bado uko chini ya maendeleo endelevu, unatunzwa na Google Labs badala ya taasisi isiyo na upendeleo, na unaelezea utambulisho wa kuona (visual identity), kwa hivyo hausemi chochote kuhusu viambajengo (invariants) ambavyo faili ya backend inahitaji. Kanuni za faili zinazoweza kusomeka na wakala zinatulia haraka, na zinatulia kutoka 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. DESIGN.md ina vipimo vilivyochapishwa lakini haina msimamizi asiyeegemea upande wowote. Google ilitoa rasimu ya vipimo hivyo kama open source mnamo Aprili 21, 2026, na inapatikana katika hazina ya google-labs-code/design.md chini ya leseni ya Apache-2.0. Kufikia Oktoba 2026, iko katika toleo la alpha na bado inaendelezwa kikamilifu, na inaelezea utambulisho wa kuona: rangi, uchapaji, mpangilio na vipengele. DESIGN.md pia ina watumiaji wa kwanza: makampuni na miradi kumi na moja, ikiwemo Vercel, Nuxt, Atlassian na Resend, huchapisha faili moja, na mkusanyiko wa jamii ulikuwa na faili nyingine 84 zilizotolewa kutoka kwenye tovuti za umma kufikia Oktoba 27, 2026. Kwa faili ya backend ya viashiria na njia mbadala zilizokataliwa, ichukulie kama mkataba unaoweza kuufuata sasa na kuupanua kwa uhuru, kwa sababu hakuna vipimo vinavyoshughulikia majina hayo ya sehemu.

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

Kwa hazina ndogo, ndiyo. Faili moja ambayo wakala (agent) anaisoma hakika ni bora kuliko faili mbili ambapo moja hupuuzwa. Zigawanye wakati AGENTS.md inapoacha kusomeka kwa urahisi, au unapoona sehemu hizo mbili zinabadilika kwa viwango tofauti. AGENTS.md hubadilika wakati ujenzi (build) unapobadilika. 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 msimbo, kwa sababu si kila zana hupakia kila faili ya markdown iliyo kwenye mzizi (root).

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

ADR (architecture decision record) ni rekodi ya 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 kusoma zote ili kubaini ni zipi bado ni kweli. DESIGN.md ni hali ya sasa, iliyoandikwa ili kusomwa 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 kuitumia.

DESIGN.md inapaswa kuwa na urefu gani?

Iwe fupi kiasi cha kupakia katika kila zamu bila majuto. Mifano iliyochapishwa ni mirefu kwa sababu inabainisha lugha nzima ya kuona: faili ya Nuxt ina takriban maneno 2,000 na faili ya Vercel takriban 6,000 kufikia Oktoba 2026. Huduma ya backend kwa kawaida inahitaji kidogo sana. Anza na ukurasa mmoja na uikuze tu wakati wakala anapokosea jambo ambalo sentensi moja ingezuia. Urefu si kipimo. Kila mstari unapaswa kuwa jambo ambalo wakala angekosea vinginevyo.