CLAUDE.md na AGENTS.md: ni nini, nini cha kuandika, na kwa nini wakala hupuuza kanuni

CLAUDE.md na AGENTS.md ni nini

Zote ni faili za kawaida za Markdown kwenye mzizi wa hazina, ambazo wakala huzipakia kiotomatiki kwenye muktadha mwanzoni mwa kikao. Kupitia faili hizi unamwambia wakala mambo ambayo hawezi kuyajua kutoka msimbo peke yake: jinsi ya kuwasha mazingira, amri gani za kukagua kazi, kanuni gani za mradi hazijadiliwi, na nyaraka za kina ziko wapi.

CLAUDE.md ni faili inayosomwa na Claude Code. AGENTS.md ni muundo wazi wenye wazo lilelile, unaoungwa mkono na mawakala wengi wa kuandika programu. Ikiwa timu inatumia mawakala tofauti, ni vyema kuweka yaliyomo kuu kwenye AGENTS.md na kuelekeza CLAUDE.md huko. Claude Code inaruhusu kuingiza faili nyingine kwa mstari unaoanza na @:

# CLAUDE.md
@AGENTS.md

Kwa njia hii kanuni zinaishi mahali pamoja na hazitofautiani kati ya faili mbili.

Wakala anazisoma vipi

Yaliyomo ya faili ya maelekezo huingia kwenye dirisha la muktadha la modeli pamoja na maelekezo ya mfumo, na hukaa humo kikao chote. Matokeo matatu muhimu yanafuata.

• Kila mstari unachukua nafasi kwenye muktadha. Faili husomwa yote kila mara, hata kama kazi ya sasa inahitaji sehemu moja tu kati ya kumi.
• Hizi ni maandishi, si kanuni zinazotekelezwa. Modeli inazizingatia pamoja na muktadha mwingine, na hakuna dhamana ya kutii asilimia mia moja. Makatazo makali yanahitaji kuungwa mkono na mifumo: ukaguzi, hooks na vikwazo vya ufikiaji.
• Faili zinaweza kuwekwa ndani ya nyingine. Claude Code hupakia CLAUDE.md kutoka mzizi wa mradi na kutoka folda ya mtumiaji ~/.claude/, na faili zilizo kwenye folda ndogo hupakiwa wakati wakala anafanya kazi na faili za folda hizo. Hii inaruhusu kuweka kanuni za moduli karibu na moduli yenyewe.

Nini cha kuandika kwenye CLAUDE.md na AGENTS.md

Faili nzuri ya maelekezo ni ramani, si kitabu cha kiada. Inajibu maswali ambayo wakala angemuuliza mwenzake mzoefu siku ya kwanza.

1. Jinsi ya kujenga na kuthibitisha mradi

Sehemu yenye thamani zaidi. Amri mahususi ambazo wakala lazima aziendeshe kabla ya kusema «imekamilika»: majaribio, linter, ukaguzi wa aina, kuwasha mazingira. Bila hizi, wakala anajikagua «kwa jicho».

2. Mipaka mikali

Orodha fupi ya mambo yasiyopaswa kuvunjwa chini ya hali yoyote: invariants za usalama na data. Ziandike kama invariants, si maelekezo ya utekelezaji: «maswali yote ya SQL yana vigezo», si «tumia kazi hii katika faili hili».

3. Ramani ya mradi

Kila kitu kiko wapi: mistari michache kuhusu muundo wa folda na mahali pa kutafuta maelezo zaidi. Kwa kila mada kuu kuna kiungo cha nyaraka tofauti ambazo wakala atazifungua tu anapokuwa akifanyia kazi mada hiyo.

4. Hali ya kazi iko wapi

Wapi kuangalia ili kuendelea pale kikao kilichopita kilipoishia: faili la mpango, kumbukumbu ya maendeleo au backlog. Hii inatibu «usahaulifu» wa wakala kati ya vikao.

Usichoandika

• Kile wakala anachoweza kukijua kutoka msimbo. Orodha ya utegemezi iko kwenye package.json au pyproject.toml, muundo wa madarasa uko kwenye msimbo wenyewe.
• Ushauri wa jumla. «Andika msimbo safi» au «kuwa makini» haibadilishi tabia na inachukua nafasi tu.
• Historia ya mradi na maelezo ya mara moja. «Mwezi wa Machi tulihamia kutoka MySQL 5.7» haisaidii kazi ya sasa.
• Maelekezo ya kina kwa kazi adimu. Utaratibu wa deploy au uhamishaji wa data unahitajika mara moja kwa wiki — uweke kwenye nyaraka tofauti au skill.
• Siri. Faili iko kwenye hazina na yote huingia kwenye modeli. Tokeni na nywila ziwe kwenye vigezo vya mazingira tu.

Kwa nini wakala hupuuza kanuni iliyoandikwa kwenye faili

Hadithi ya kawaida: wakala alikosea — kanuni iliongezwa kwenye faili. Alikosea tena — kanuni nyingine. Baada ya miezi kadhaa faili lina mistari mamia, na kanuni muhimu ya usalama wakala anaivunja kana kwamba haipo. Kwa kawaida kuna sababu nne zinazofanya kazi pamoja.

Faili lililovimba

Faili la mistari 600 ni takriban tokeni 10–20 elfu. Dirisha la muktadha linaonekana kubwa, lakini linagombewa na msimbo, matokeo ya amri na historia ya mazungumzo. Maelekezo yanapochukua nafasi zaidi, kila kanuni hupata umakini kidogo na nafasi ya kazi yenyewe inapungua.

Kanuni katikati

Modeli za lugha hutumia taarifa zilizo katikati ya maandishi marefu kwa udhaifu zaidi kuliko zile za mwanzo na mwisho. Kanuni ya mstari wa 300 kati ya 600 iko mahali penye udhaifu zaidi.

Hakuna vipaumbele

Katazo lisilojadiliwa na kidokezo cha mtindo wa kupita vimeandikwa kwa namna moja, kama mstari mmoja kwenye orodha. Wakala hana njia ya kujua lipi ni muhimu zaidi. Na kama kuna kanuni tatu za mtindo zinazopingana, tabia ya wakala inakuwa ya kubahatisha kutoka mara moja hadi nyingine.

Kuoza

Kuongeza kanuni ni bure, lakini kuiondoa kunatisha: «labda kuna kitu kinategemea hiyo». Kwa hiyo faili hukua bila kukoma na sehemu ya mistari yenye manufaa hupungua. Hii inaweza kupimwa kwa uwiano wa ishara na kelele: ni mistari mingapi inayohitajika kweli kwa kazi ya kawaida, na ngapi hazihitajiki.

Jinsi ya kurekebisha: rauta badala ya ukuta wa maandishi

Kurekebisha sababu moja pekee hakusaidii: ukipunguza faili lakini ukiacha bila muundo, kanuni bado zimechanganyika. Kinachofanya kazi ni mchanganyiko wa hatua.

1. Fanya faili la kuingilia kuwa rauta. Mistari 50–150: amri za uthibitishaji, mipaka mikali, ramani ya mradi na viungo vya nyaraka za mada.
2. Hamisha mada kwenye faili tofauti. Kwa mfano docs/agents/deploy.md na docs/agents/database.md. Wakala anazifungua inapohitajika. Katika Claude Code, skills zinafaa kwa taratibu zinazorudiwa kwa sababu zinapakiwa tu zinapohitajika.
3. Weka muhimu juu. Mipaka mikali iwe mwanzoni mwa faili, katika kizuizi kifupi tofauti chenye alama wazi ya MUST.
4. Ondoa migongano. Kwa kila mada kuwe na kanuni moja. Ikiwa kuna ubaguzi, uandike karibu na kanuni husika.
5. Ungisha kanuni kwa utaratibu. Ikiwa ukiukaji hauwezi kuruhusiwa, maandishi peke yake hayatoshi. Unahitaji ukaguzi unaonasa ukiukaji: linter, jaribio, pre-commit hook au hook ya wakala, au kizuizi cha ufikiaji.
6. Pitia mara kwa mara. Weka kikomo cha mistari na kila unapoongeza kitu, jiulize nini kinaweza kuondolewa au kuhamishwa.

Kanuni au ukaguzi?

Mfano wa AGENTS.md iliyofupishwa

# AGENTS.md — backend ya malipo (FastAPI, PostgreSQL)

## MUST — usivunje
- Kiasi cha fedha ni int kwa senti, kamwe float
- SQL yenye vigezo tu, bila f-string
- Usibadilishe migration iliyotumika; ongeza migration mpya tu
- Siri kutoka kwenye vigezo vya mazingira tu

## Uthibitishaji kabla ya kusema «imekamilika»
docker compose up -d     # mazingira
make lint                # ruff + mypy
make test                # pytest
make e2e                 # mchakato wa checkout
Majaribio ya kitengo pekee yakiwa ya kijani bila e2e, si «imekamilika».

## Ramani
- app/payments/   — hesabu za kiasi, punguzo, webhook ya mtoa huduma
- app/api/        — endpoints za HTTP
- tests/e2e/      — hali za mtumiaji
Maelezo zaidi: docs/agents/architecture.md, docs/agents/database.md

## Hali ya kazi
- PLAN.md      — lengo la sasa, vigezo vya ukamilifu, hatua inayofuata
- PROGRESS.md  — kilichofanyika na jinsi kilivyothibitishwa, njia zisizofaa
- BACKLOG.md   — mambo yanayoonekana njiani: andika hapa, usiyarekebishe sasa

Mwishoni mwa kikao, sasisha PROGRESS.md na hatua inayofuata kwenye PLAN.md.

Angalia kisichokuwepo: orodha ya maktaba, ushauri wa mtindo, historia ya mradi. Hivyo vyote vinaonekana kwenye msimbo, vimefungwa na ukaguzi, au viko kwenye nyaraka za mada.

Usahaulifu kati ya vikao: faili la maelekezo pamoja na faili la mpango

Faili la maelekezo linaeleza jinsi ya kufanya kazi katika mradi, lakini halielezi kinachoendelea sasa. Kwa hilo unahitaji faili tofauti la hali, ambalo wakala analisoma mwanzoni na kulisasisha mwishoni mwa kikao. Ndani yake kuna: lengo, yaliyokamilika pamoja na jinsi yalivyothibitishwa, maamuzi pamoja na sababu zake, chaguzi zilizokataliwa, na sentensi moja ya hatua inayofuata. Kipimo cha ubora ni rahisi: fungua kikao kipya, andika «endelea» na uone kama wakala anaanza kazi yenye manufaa bila kuuliza maswali.

Usichanganye faili mbili. Maelekezo hubadilika mara chache na yanahusu kazi zote. Mpango hubadilika kila kikao na unahusu kazi ya sasa. Zikichanganywa, faili la maelekezo linajaa haraka maelezo yaliyopitwa na wakati.

Jinsi ya kukagua kwamba faili linafanya kazi

Faili la maelekezo nalo linahitaji kukaguliwa. Chukua kazi kadhaa za kawaida — kurekebisha hitilafu, kipengele kidogo, urekebishaji wa muundo — na uone wakala anafanya nini bila vidokezo: je, anaendesha amri sahihi, anafungua nyaraka sahihi za mada, na anazingatia mipaka mikali. Kanuni ikivunjwa, jiulize kwanza kama inaonekana, kama kuna mgongano nayo, na kama inaweza kubadilishwa na ukaguzi wa kiotomatiki. Kuongeza mstari mpya ndiyo njia ya mwisho.

Hitimisho

CLAUDE.md na AGENTS.md ni mlango wa wakala kuingia kwenye mradi. Zinafanya kazi zikibaki ramani fupi: amri za uthibitishaji, mipaka mikali juu, viungo vya maelezo na faili la mpango. Kanuni ikipuuzwa, sababu karibu kila mara ni faili lililovimba na lisilo na muundo, na kanuni muhimu kweli zinahitaji kuungwa mkono na ukaguzi na hooks. Jinsi ya kupanga maelekezo na hali ya wakala inafundishwa kwa vitendo katika kozi ya harness engineering.