AGENTS.md na HUMAN.md: Ufafanuzi wa Faili Hizi

AGENTS.md ni nini

AGENTS.md ni faili la kawaida la markdown lililo kwenye mzizi wa hazina, linalomwelekeza wakala wa uandishi wa msimbo jinsi ya kufanya kazi kwenye mradi huo. Tovuti rasmi inalieleza kama "README ya mawakala: mahali maalumu na panapotabirika pa kutoa muktadha na maelekezo ya kusaidia mawakala wa AI wa uandishi wa msimbo kufanya kazi kwenye mradi wako." Muundo huu unasimamiwa na Agentic AI Foundation chini ya Linux Foundation, na zaidi ya mawakala ishirini hulisoma, wakiwemo Codex, Cursor, Jules, Devin na GitHub Copilot (hadi Julai 2026).

Sababu ya kuwepo kwa utaratibu huu ni ya kiutendaji. Mtu mpya kwenye timu yako husoma README, anakisia amri ya kujenga, kisha humuuliza mtu mwingine anapogundua kuwa makisio hayo si sahihi. Wakala hawezi kuuliza. Hukisia, huendesha npm test kwenye mradi unaotumia pnpm test, husoma hitilafu, kisha hujaribu kitu kingine. Unalipia kila tokeni kati ya hizo. Kuandika amri halisi mara moja huondoa aina hiyo yote ya hitilafu.

Hakuna sehemu zinazohitajika. Tovuti inaeleza wazi: "AGENTS.md ni Markdown ya kawaida tu. Tumia vichwa vyovyote unavyotaka; wakala huchanganua tu maandishi unayotoa." Huo ndio ufafanuzi wote. Thamani haipo kwenye muundo. Ipo kwenye faili lililoko kwenye njia ambayo kila zana tayari huiangalia.

Mahali faili linawekwa na ni faili gani hutumika

Weka faili la kwanza kwenye mzizi wa repository. Katika monorepo, unaweza kuongeza faili zaidi ndani ya kila subproject. Kanuni ni rahisi: "agents husoma kiotomatiki faili lililo karibu zaidi katika mti wa saraka, kwa hiyo faili lililo karibu zaidi hutangulia." Mgongano kati ya faili mbili hutatuliwa kwa kupendelea faili linalohaririwa, na chochote unachoandika kwenye mazungumzo hubatilisha faili zote mbili.

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

Inafaa kutumia mpangilio wa viwango, kwa sababu ndiyo njia pekee ya kueleza jambo linalokuwa kweli katika folda moja na si kweli katika folda inayofuata. Kanuni kama "kila endpoint huthibitisha ingizo lake" inapaswa kuwekwa karibu na endpoints. Ikiwa itawekwa kwenye faili ya mzizi, itapakiwa katika kila kazi isiyohusiana na haitakuwa na manufaa.

Kinachopaswa kuwekwa kwenye AGENTS.md

Andika mambo ambayo agent hawezi kuyatambua kwa kusoma msimbo. Amri kamili za build, test na lint ziwekwe kwanza, katika muundo ambao ungebandika kwenye terminal. Ongeza amri ya kuendesha test moja, kwa sababu agent anayejua tu jinsi ya kuendesha suite nzima ataendesha suite nzima mara arobaini. Taja kanuni zinazotofautiana na mipangilio chaguomsingi ya zana, kwa kuwa agent tayari anajua mipangilio hiyo na anahitaji tu kujua tofauti zenu. Ongeza muundo wa ujumbe wa commit na kanuni za pull request ikiwa mnazo.

Toa maelezo mahususi kiasi kwamba dai linaweza kuthibitishwa. "Tumia indentation ya nafasi 2" ni agizo linaloweza kutumika kwa sababu linaweza kuthibitishwa kuwa limetekelezwa au halijatekelezwa. "Pangilia msimbo ipasavyo" si agizo linaloweza kutumika, kwa sababu hakuna jambo ndani yake linaloweza kuthibitishwa. Hali ni hiyo hiyo kwa maeneo: "Wahudumu wa API wako kwenye src/api/handlers/" ni bora kuliko "panga faili vizuri".

Kanuni hasi pia zinafaa kuwekwa. "Usiwahi kuhariri faili zilizo chini ya dist/; zinatengenezwa na npm run build" huzuia kosa moja mahususi. Kwa kuwa inataja chanzo cha kosa, agent anaweza kubaini hali inayolingana ambayo hukuandika.

Kile ambacho hakipaswi kamwe kuwekwa humo

Usiweke kamwe siri katika mojawapo ya faili hizi. Faili huwasilishwa kwenye git, hupakiwa katika muktadha mwanzoni mwa kila kipindi, na hutumwa kwa mtoa huduma wa modeli katika kila ombi. API key iliyo katika AGENTS.md huwa katika historia ya hazina yako na katika kumbukumbu za mtu mwingine. Rejelea siri badala ya kuibandika: "nenosiri la hifadhidata liko katika .env, ambayo imewekewa gitignore; uliza kabla ya kuisoma." Nidhamu pana zaidi imeelezwa katika kuweka vitambulisho nje ya ufikiaji wa wakala.

Acha chochote ambacho wakala anaweza kupata kwa kukitazama. Orodha ya saraka iliyonakiliwa, nakala ya orodha ya vitegemezi vyako, au muhtasari wa usanifu unaorudia majina ya folda: yote hupitwa na wakati wiki moja baada ya kuiandika, na wakati huo huo hutumia muktadha katika kila kipindi. Hifadhi mitego na sababu zake. Ondoa orodha ya yaliyomo.

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

Claude Code husoma CLAUDE.md na haisomi AGENTS.md yenyewe. Faili ya mradi huwekwa katika ./CLAUDE.md au ./.claude/CLAUDE.md, mapendeleo ya kibinafsi kwa kila mradi huwekwa katika ~/.claude/CLAUDE.md, na shirika linaweza kuweka faili ya mfumo mzima katika /etc/claude-code/CLAUDE.md kwenye Linux. Faili zilizogunduliwa huunganishwa kutoka kwenye mzizi wa mfumo wa faili hadi kwenye saraka yako ya kazi, kwa hiyo faili iliyo karibu zaidi na mahali ulipoanzisha kipindi husomwa mwisho.

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

@AGENTS.md

## Claude Code

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

Kiungo cha ishara hufanya kazi wakati huna chochote cha ziada cha kuongeza:

ln -s AGENTS.md CLAUDE.md

Amri hiyo haichapishi chochote ikifanikiwa. Katika kipindi chako kinachofuata, endesha /context na uthibitishe kuwa CLAUDE.md inaonekana chini ya Faili za kumbukumbu. Ikiwa haipo kwenye orodha hiyo, faili haikupakiwa, kwa hiyo hakuna maudhui yake yaliyotumika. Ili kutengeneza rasimu ya kwanza badala ya kuandika moja, endesha /init: husoma codebase na kuzalisha faili ya kuanzia, na ikiwa CLAUDE.md tayari ipo, hupendekeza maboresho badala ya kuandika juu yake.

Weka kila faili chini ya takriban mistari 200. Faili ndefu hutumia sehemu kubwa zaidi ya dirisha la muktadha, na uzingatiaji hupungua. Ikiwa unataka kuona ni nini kingine kinachoshindania nafasi hiyo, kinachojaza kwa hakika dirisha la muktadha la wakala kinaeleza kwa muhtasari.

Jambo moja linahitaji kusisitizwa. AGENTS.md ni mwongozo, si mfumo wa ruhusa. Maudhui yake huwasili kama muktadha wa kawaida, kwa hiyo modeli huyasoma na kwa kawaida huyafuata, lakini hakuna kinachozuia kitendo kinachokiuka mwongozo huo. Kwa sheria ambayo lazima itekelezwe kila mara, kama vile "usiwahi kusukuma mabadiliko kwenye main", tumia hook au mpangilio wa ruhusa, kwa sababu hizo hutekelezwa kama code na hazitegemei modeli kuamua kuitii.

Zana zinazokuandikia faili hizi

Miradi miwili kwenye orodha ya miradi inayovuma ya GitHub tarehe 30 July 2026 inaonyesha mwelekeo wa kanuni hii.

agent0ai/dox (ikiwa na nyota 1,368 kufikia July 2026) ni mfumo wa kuweka mti wa faili za AGENTS.md katika hali ya sasa. Haitoi package wala runtime. Unakili maudhui ya AGENTS.md yake kwenye AGENTS.md ya mzizi wako, na huo ndio usakinishaji. Kwa mradi ambao tayari upo, unaambia agent yako:

Initialize DOX tree for this project now.

Kisha agent huunda faili za AGENTS.md za matawi na faharasa zake, hupitia mti huo kabla ya kuhariri chochote, na husasisha nyaraka zilizoathiriwa baada ya mabadiliko kutekelezwa. Msingi wa dhana hii ni kwamba nyaraka ambazo agent hudumisha kama sehemu ya ziada ya kazi yake hubaki sahihi, ilhali nyaraka ambazo mtu husasisha kwa mkono hazibaki hivyo.

HUMAN.md, mbinu hiyo hiyo ikikulenga

Intuition-Lab/personal-model (nyota 1,260 kufikia Julai 2026) hutumia muundo huo kwa mtu badala ya hazina ya msimbo. Mradi huu huchukulia HUMAN.md yako kuwa matokeo ya mfumo, si faili unayoandika wewe: “muundo hai wa mambo muhimu kwa sasa, jinsi unavyofanya maamuzi kwa kawaida, na mwelekeo wa umakini wako.” Hufanya kazi ndani ya kompyuta kwenye macOS 13 au matoleo ya baadaye, hukusanya shughuli baada ya kutoa ruhusa ya macOS, na huwasilisha matokeo kwa mawakala kupitia MCP (model context protocol). Hatua fupi za usakinishaji ni hizi:

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

Huhitaji hayo yote ili kupata sehemu kubwa ya manufaa. HUMAN.md iliyoandikwa kwa mkono huwa na takribani mistari 20: jukumu lako, saa za eneo lako, stack unayotumia kwa kweli, maamuzi ambayo tayari umefanya na hutaki yazungumzwe tena, na kiwango cha maelezo unachotaka kupokea. Huokoa maelezo yale yale ya kurudiwa ambayo faili ya mradi huokoa, lakini katika ngazi ya juu zaidi.

Kuna tahadhari moja. HUMAN.md ni wasifu wa mtu, kwa hiyo ni taarifa nyeti kiasili. Iweke nje ya hazina ya umma. Iweke katika ~/.claude/CLAUDE.md, au katika CLAUDE.local.md iliyo kwenye orodha ya gitignore katika mzizi wa mradi; faili hiyo hupakiwa pamoja na faili iliyowekwa kwenye hazina na hushughulikiwa kwa njia hiyo hiyo.

Kiolezo cha kuanzia unachoweza kunakili

Hiki ni kifupi kwa makusudi. Futa sehemu ambazo hazitumiki, na epuka kuongeza sehemu ambazo huwezi kuzisasisha.

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

Kiandike, kisha kirekebishe mahali pake. Ishara ya kuongeza mstari ni pale unapoandika marekebisho hayo hayo kwenye gumzo mara mbili. Kanuni hiyo moja huifanya faili ibaki muhimu, na huzuia faili kukua kuwa hati ambayo hakuna mtu anayeisoma, hata mashine. Ikiwa imetulia, husafiri pamoja na hifadhi ya msimbo, jambo muhimu hasa wakala anapoendeshwa mahali pengine badala ya kompyuta yako mpakato: kuendesha wakala wa uandishi wa msimbo kwenye seva yako mwenyewe inaeleza usanidi huo.

FAQ

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

Ni wazo lilelile lenye majina mawili ya faili. Claude Code husoma CLAUDE.md na hupuuza AGENTS.md isipokuwa uyaunganishe. Weka faili moja liwe chanzo cha ukweli, kisha unganisha jingine nalo, ama kwa kuweka mstari unaosomeka @AGENTS.md juu ya CLAUDE.md yako au kwa kutumia ln -s AGENTS.md CLAUDE.md. Nakala mbili kamili zikidumishwa tofauti zitatofautiana ndani ya mwezi mmoja.

Je, kuandika AGENTS.md kunahakikisha kuwa wakala atafuata?

Hapana. Maudhui huwasilishwa kama muktadha, hivyo modeli huyasoma na kwa kawaida huyafuata, lakini hakuna kinachozuia kitendo kinachokiuka maudhui hayo. Maagizo yasiyo wazi hufuatwa kwa kutotegemewa zaidi, na faili mbili zenye mwongozo unaopingana humwacha wakala achague moja bila utaratibu maalumu. Kwa kanuni inayopaswa kutumika kila mara, tumia hook au kanuni ya ruhusa; mteja huzitekeleza bila kujali uamuzi wa modeli.

Je, AGENTS.md inapaswa kuingizwa kwenye git?

Ndiyo, kwa kila kitu ambacho ni kweli kuhusu mradi: amri za ujenzi, mpangilio na kanuni. Hilo ndilo kusudi la faili hilo, kwa sababu mawakala wa wenzako huanza wakiwa na muktadha uleule ambao wako unao. Kitu chochote cha kibinafsi au mahususi kwa mashine moja kiwekwe kwenye faili tofauti inayopuuzwa na git, na vitambulisho vya siri visiwekwe katika faili yoyote kati ya hizo.

HUMAN.md ni nini, na je, ninaihitaji?

HUMAN.md ni wasifu unaoweza kusomwa na mashine wa mtu, si wa mradi. Huwa na jukumu lako, vikwazo vyako na maamuzi ambayo tayari umefanya, ili yasijadiliwe upya katika kila kipindi. Huhitaji zana yoyote kuanza: mistari ishirini iliyoandikwa mwenyewe kwenye faili lako la maagizo ya kiwango cha mtumiaji hukupa sehemu kubwa ya manufaa. Ichukulie kama data ya kibinafsi na usiiweke kwenye hazina yoyote unayopakia.