AGENTS.md na HUMAN.md ni nini na jinsi ya kuvitumia

AGENTS.md ni nini

AGENTS.md ni faili la kawaida la markdown lililopo kwenye mzizi wa hazina (repository) ambalo humwelekeza wakala wa uandishi wa msimbo (coding agent) jinsi ya kufanya kazi kwenye mradi huo. Tovuti rasmi inalifafanua kama "README kwa ajili ya mawakala: mahali maalum na panapoweza kutabirika pa kutoa muktadha na maelekezo ili kusaidia mawakala wa AI wa uandishi wa msimbo kufanya kazi kwenye mradi wako." Umbizo hili linasimamiwa na Agentic AI Foundation chini ya Linux Foundation, na zaidi ya mawakala ishirini hulitambua, wakiwemo Codex, Cursor, Jules, Devin na GitHub Copilot (kufikia Julai 2026).

Sababu ya kuwepo kwa mkataba huu ni ya kiutendaji. Mtu mpya kwenye timu yako anasoma README, anakisia amri ya ujenzi (build command), na kumuuliza mtu mwingine pale akikosea. Wakala hawezi kuuliza. Hukisia, huendesha npm test kwenye mradi unaotumia pnpm test, husoma hitilafu, na kujaribu kitu kingine. Unalipia kila token kati ya hizo. Kuandika amri sahihi mara moja huondoa aina hiyo nzima ya hitilafu.

Hakuna sehemu za lazima. Tovuti iko wazi kuhusu hili: "AGENTS.md ni Markdown ya kawaida tu. Tumia vichwa vya habari vyovyote unavyopenda; wakala huchanganua tu maandishi unayotoa." Hiyo ndiyo maelezo yote ya kiufundi. Thamani haipo kwenye umbizo. Ipo kwenye faili hilo lililopo kwenye njia (path) ambayo kila zana tayari inaiangalia.

Mahali faili linapowekwa na ni faili lipi linaloshinda

Weka faili la kwanza kwenye mzizi (root) wa hazina. Katika monorepo unaweza kuongeza faili zaidi ndani ya kila mradi mdogo, na kanuni ni rahisi: "mawakala husoma kiotomatiki faili lililo karibu zaidi katika mti wa saraka, kwa hivyo lile lililo karibu zaidi ndilo linalopewa kipaumbele." Mgongano kati ya faili mbili hutatuliwa kwa kufuata faili linalohaririwa, na chochote unachoandika kwenye chat hupuuza yote mawili.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Uwekaji wa faili ndani ya nyingine (nesting) unafaa kutumika, kwa sababu ndiyo njia pekee ya kusema jambo ambalo ni kweli katika folda moja na si kweli katika folda inayofuata. Kanuni kama "kila endpoint inathibitisha data yake ya kuingiza" inapaswa kuwa kando ya endpoints husika. Katika faili la mzizi, kanuni hiyo hupakiwa kwenye kila kazi isiyohusika na haileti faida yoyote. Ikiwa faili lako la mzizi limekua na kuwa na sehemu moja kwa kila huduma, kuligawanya katika mpangilio wa ndani ndiyo suluhisho, na linafafanua ni kanuni zipi zinapaswa kushushwa chini na zipi zinapaswa kubaki juu.

Nini kinapaswa kuwemo kwenye AGENTS.md

Andika mambo ambayo wakala (agent) hawezi kuyabaini kwa kusoma msimbo (code). Amri kamili za ujenzi (build), majaribio (test), na uchanganuzi (lint) lazima zianze, katika mfumo ambao ungebandika kwenye terminal. Ongeza amri ya kuendesha jaribio moja, kwa sababu wakala anayejua kuendesha mkusanyiko mzima pekee atafanya hivyo mara arobaini. Taja miongozo inayotofautiana na ile ya kawaida ya zana husika, kwa kuwa wakala tayari anajua miongozo ya kawaida na anahitaji tu kujua mahali ulipopotea njia. Ongeza muundo wa ujumbe wa commit na kanuni za pull request ikiwa unazo.

Kuwa mahususi vya kutosha ili dai liweze kuthibitishwa. "Tumia nafasi 2 kwa indentation" ni maelekezo yanayotekelezeka kwa sababu yanaweza kuthibitika kama yamefanyika au la. "Pangilia msimbo vizuri" si maelekezo yanayotekelezeka, kwa sababu hakuna kinachoweza kuhakikiwa ndani yake. Vivyo hivyo kwa maeneo: "API handlers zipo kwenye src/api/handlers/" ni bora kuliko "weka faili zikiwa zimepangwa".

Kanuni za kuzuia (negative rules) pia ni muhimu. "Usihariri kamwe faili zilizo chini ya dist/, zinatengenezwa na npm run build" inazuia kosa mahususi, na kwa sababu inataja sababu, wakala anaweza kubaini kisa kingine kinachofanana ambacho hukukiandika. Kanuni kuhusu upeo (scope) pia inapaswa kuwemo hapa, kwa sababu wakala anayeachwa atumie uamuzi wake mwenyewe atafanya marekebisho mengi zaidi ya uliyoomba: ujuzi mmoja unaonakiliwa sana haufanyi kitu kingine isipokuwa kusisitiza mabadiliko madogo zaidi yanayofanya kazi.

Vitu visivyopaswa kuwemo

Usiweke kamwe siri yoyote kwenye faili hizi. Faili hii huwekwa kwenye git, hupakiwa kwenye muktadha mwanzoni mwa kila kikao, na hutumwa kwa mtoa huduma wa modeli katika kila ombi. API key iliyo ndani ya AGENTS.md ni API key iliyo kwenye historia ya hazina yako (repository) na kwenye kumbukumbu za wahusika wengine. Elekeza kwenye siri hiyo badala ya kuibandika: "nywila ya database iko kwenye .env, ambayo imewekwa kwenye gitignore; uliza kabla ya kuisoma." Nidhamu pana zaidi imeelezwa katika kuepusha vitambulisho (credentials) visifikiwe na wakala.

Ondoa chochote ambacho wakala anaweza kukipata kwa kukitazama. Orodha ya saraka (directory) iliyobandikwa, nakala ya orodha ya dependency zako, muhtasari wa usanifu unaorudia majina ya folda: yote haya hupitwa na wakati wiki moja baada ya kuyaandika, na hutumia nafasi ya muktadha katika kila kikao wakati huo. Weka mitego na sababu zake. Ondoa orodha ya vitu. Sababu zinastahili kutenganishwa, kwa sababu wakala asiyeona kwa nini umbo lisilo la kawaida lipo, atalirekebisha kimyakimya na kuliondoa, jambo ambalo ndilo sababu ya kuweka DESIGN.md karibu na faili hii.

CLAUDE.md ni mfano wa Claude Code wa wazo hilo hilo

Claude Code inasoma CLAUDE.md na haisomi AGENTS.md yenyewe. Faili la mradi linapatikana katika ./CLAUDE.md au ./.claude/CLAUDE.md, mapendeleo ya kibinafsi kwa kila mradi huwekwa katika ~/.claude/CLAUDE.md, na shirika linaweza kusukuma faili la mfumo mzima kwenye /etc/claude-code/CLAUDE.md katika Linux. Faili zilizogunduliwa huunganishwa kutoka mzizi wa mfumo wa faili hadi kwenye saraka yako ya kazi, kwa hivyo faili lililo karibu zaidi na mahali ulipoanzisha kipindi husomwa mwisho. Kila kipindi unachoanzisha katika saraka hiyo hupakia rundo lile lile, jambo ambalo hufanya iwezekane kuendesha vipindi viwili kando kando kwenye mashine moja, na vipindi hivyo vinaweza kupokezana kazi wakati vinafanya kazi.

Ikiwa hazina yako tayari ina AGENTS.md, usitunze nakala ya pili. Iingize, kisha ongeza yale tu ambayo ni mahususi kwa Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Symlink inafanya kazi wakati huna kitu kingine cha kuongeza:

ln -s AGENTS.md CLAUDE.md

Amri haichapishi chochote ikifanikiwa. Katika kipindi chako kijacho endesha /context na uthibitishe kuwa CLAUDE.md inaonekana chini ya Memory files. Ikiwa haipo kwenye orodha hiyo, faili halikupakiwa, kwa hivyo hakuna chochote ndani yake kilichotumika. Ili kutengeneza rasimu ya kwanza badala ya kuandika moja, endesha /init: inasoma codebase na kutengeneza faili la kuanzia, na wakati CLAUDE.md tayari ipo, inapendekeza maboresho badala ya kuandika juu yake.

Weka kila faili chini ya takriban mistari 200. Faili ndefu hutumia sehemu kubwa ya dirisha na utiifu hupungua. Ikiwa unataka kuona nini kingine kinashindania nafasi hiyo, nini kinachojaza dirisha la muktadha wa wakala kinafafanua hilo.

Jambo moja linastahili kusisitizwa. AGENTS.md ni mwongozo, si mfumo wa ruhusa. Maudhui hufika kama muktadha wa kawaida, kwa hivyo modeli huisoma na kwa kawaida hutii, lakini hakuna kinachozuia kitendo kinachopingana nayo. Wakati sheria uliyoandika inarukwa kimya kimya na huwezi kujua kwa nini, pitia sababu zinazofanya maelekezo kupotea kabla ya kuandika upya maneno hayo kwa mara ya tatu. Kwa sheria ambayo lazima izingatiwe kila wakati, kama vile "usipush kamwe kwenye main", tumia hook au mpangilio wa ruhusa, kwa sababu hizo huendeshwa kama msimbo na hazitegemei modeli kuamua kutii.

Zana zinazokuandikia faili hizi

Miradi miwili kwenye orodha ya GitHub trending mnamo tarehe 30 Julai 2026 inaonyesha mwelekeo wa kawaida huu.

agent0ai/dox (nyota 1,368 kufikia Julai 2026) ni mfumo wa kudumisha mti wa faili za AGENTS.md ukiwa wa kisasa. Haisambazi kifurushi chochote wala runtime. Unanakili maudhui ya AGENTS.md yake kwenye AGENTS.md yako ya mzizi (root), na huo ndio usakinishaji. Kwa mradi ambao tayari upo, unamwambia wakala wako:

Initialize DOX tree for this project now.

Wakala huyo kisha hutengeneza faili za AGENTS.md za watoto na faharasa zake, hupitia mti huo kabla ya kuhariri chochote, na kusasisha nyaraka zilizoathirika baada ya mabadiliko kutekelezwa. Dau lililopo nyuma yake ni kwamba nyaraka ambazo wakala anazidumisha kama matokeo ya kazi yake hubaki kuwa sahihi, wakati nyaraka ambazo mtu anazisasisha kwa mkono hazibaki hivyo.

HUMAN.md, mbinu hiyo hiyo inayokulenga wewe

Intuition-Lab/personal-model (nyota 1,260 kufikia Julai 2026) inatumia muundo huu kwa mtu badala ya hazina ya msimbo (repository). Mradi huu unachukulia HUMAN.md yako kama matokeo ya mfumo badala ya faili unayoandika: "mfano hai wa mambo muhimu sasa, jinsi unavyoamua, na mahali ambapo umakini wako unaelekea." Inafanya kazi ndani ya mashine kwenye macOS 13 au matoleo mapya zaidi, inakamata shughuli baada ya kutoa ruhusa ya macOS, na kuonyesha matokeo kwa mawakala kupitia MCP (model context protocol). Njia fupi ya usakinishaji:

uv tool install personal-model
persome onboard
persome model open --after 30

Hauhitaji yote hayo ili kupata manufaa mengi. HUMAN.md iliyoandikwa kwa mkono ina takriban mistari ishirini: jukumu lako, ukanda wako wa saa (timezone), teknolojia unayotumia kweli, maamuzi ambayo tayari umeshafanya na hutaki yajadiliwe tena, na kiasi gani cha maelezo unachotaka kurudishiwa. Inapunguza maelezo ya kurudiarudia kama faili ya mradi inavyofanya, lakini katika ngazi ya juu zaidi.

Tahadhari moja. HUMAN.md ni wasifu wa mtu, kwa hivyo ni nyeti kwa asili yake. Iweke nje ya hazina ya umma (public repository). Iweke kwenye ~/.claude/CLAUDE.md, au kwenye CLAUDE.local.md iliyoongezwa kwenye .gitignore kwenye mzizi wa mradi, ambayo hupakiwa pamoja na faili iliyowekwa kwenye git na hutendewa kwa njia ile ile.

Kiolezo cha kuanzia unachoweza kukinakili

Hii imefupishwa kwa makusudi. Futa sehemu zisizohusika, na epuka kuongeza zile ambazo huwezi kuzidumisha.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Iandike, kisha uisahihishe hapo hapo. Ishara ya kuongeza mstari ni pale unapochapa marekebisho yaleyale kwenye chat mara mbili. Kanuni hiyo moja huifanya faili kuwa muhimu, na huizuia faili hiyo kukua na kuwa hati ambayo hakuna mtu anayesoma, ikiwemo mashine. Pindi inapokuwa thabiti, husafiri pamoja na repository, jambo ambalo ni muhimu zaidi wakati wakala anapofanya kazi mahali pengine nje ya kompyuta yako: kuendesha wakala wa usimbaji kwenye seva yako mwenyewe inashughulikia usanidi huo.

FAQ

Je, AGENTS.md ni faili sawa na CLAUDE.md?

Hizi ni dhana sawa chini ya majina mawili tofauti ya faili. Claude Code husoma CLAUDE.md na kupuuza AGENTS.md isipokuwa kama utaziunganisha. Weka faili moja kama chanzo kikuu cha ukweli na uunganishe nyingine kwalo, ama kwa mstari unaosomeka @AGENTS.md juu ya CLAUDE.md yako au kwa kutumia ln -s AGENTS.md CLAUDE.md. Nakala mbili kamili zinazotunzwa kando zitapishana ndani ya mwezi mmoja.

Je, kuandika AGENTS.md kunahakikisha wakala anafuata maelekezo hayo?

Hapana. Maudhui huwasilishwa kama muktadha, kwa hivyo modeli huisoma na kwa ujumla hufuata, lakini hakuna kinachozuia kitendo kinachopingana nayo. Maelekezo yasiyo wazi hufuatwa kwa kiwango cha chini kabisa, na faili mbili zinazotoa mwongozo unaopingana humwacha wakala kuchagua moja kiholela. Kwa sheria inayopaswa kuzingatiwa kila wakati, tumia hook au sheria ya ruhusa, ambazo hutekelezwa na mteja bila kujali modeli imeamua nini.

Je, AGENTS.md inapaswa kuwekwa kwenye git?

Ndiyo, kwa chochote cha kweli kuhusu mradi: amri za build, mpangilio, na miongozo. Hilo ndilo kusudi la faili hiyo, kwa sababu mawakala wa wenzako wataanza na muktadha uleule unaotumia wewe. Chochote cha kibinafsi au maalum kwa mashine moja kinapaswa kuwa kwenye faili tofauti iliyowekwa kwenye gitignore, na vitambulisho (credentials) havipaswi kuwa kwenye mojawapo.

HUMAN.md ni nini na je, ninahitaji moja?

HUMAN.md ni wasifu unaoweza kusomwa na mashine wa mtu badala ya mradi. Huhifadhi jukumu lako, vikwazo vyako, na maamuzi ambayo tayari umeyafikia ili yasijadiliwe tena kila kikao. Huhitaji zana yoyote kuanza: mistari ishirini uliyoandika mwenyewe kwenye faili yako ya maelekezo ya kiwango cha mtumiaji inakupa thamani kubwa zaidi. Ichukulie kama data ya kibinafsi na uiweke nje ya hazina (repository) yoyote unayopush.