Ponytail: Kanuni ya Wakala Mvivu wa Msimbo

Ponytail ni nini

Ponytail ni seti ya kanuni inayomfanya wakala wa AI wa kuandika msimbo aandike msimbo mchache. Mradi huu unajieleza kwa sentensi moja: "Humfanya wakala wako wa AI afikiri kama msanidi mkuu mvivu zaidi katika chumba. Msimbo bora ni ule ambao hukuuandika kamwe." Umepewa leseni ya MIT. Hauna mfumo wake wa uendeshaji, na hakuna kitu ndani yake kinachotekelezwa. Ni maandishi yanayoingizwa katika maagizo ya wakala, yakiwa yamefungashwa kama skill kwa wapangishaji wanaopakia skills, na kama faili za kawaida za kanuni kwa wapangishaji wasiopakia skills.

Hifadhi yake ni DietrichGebert/ponytail. Iliundwa tarehe 12 Juni 2026 na ikafikisha nyota 90,000 kufikia 1 Agosti 2026. Toleo la hivi karibuni lenye tagi tarehe 1 Agosti 2026 ni v4.8.4, lililochapishwa tarehe 29 Juni 2026, na ukurasa wa matoleo unaorodhesha tagi kumi kati ya tarehe 14 na 29 Juni pekee. Mradi unaoendelea kwa kasi hiyo utakuwa umebadilika wakati utakapousoma, kwa hiyo weka tagi maalum kabla ya kujenga chochote juu yake.

Wazo kabla ya zana: simama kwenye ngazi ya kwanza inayotosheleza

Msingi wa Ponytail ni ngazi ya maamuzi. Wakala hupitia ngazi hii kabla ya kuandika chochote na husimama kwenye ngazi ya kwanza inayotosheleza.

1. Je, hili linahitaji kuwepo kabisa? Hii ni YAGNI (hutalihitaji). Ikiwa jibu ni hapana, liruke.
2. Je, tayari lipo kwenye codebase hii? Tumia tena helper au muundo uliopo.
3. Je, standard library inaweza kufanya hivyo? Itumie.
4. Je, kipengele cha native cha jukwaa kinaweza kushughulikia hilo? Kitumie.
5. Je, dependency iliyosakinishwa tayari inaweza kutatua hilo? Itumie.
6. Je, linaweza kuwa mstari mmoja? Lifanye kuwa mstari mmoja.
7. Ni baada ya hapo tu uandike code ya chini kabisa inayofanya kazi.

Mpangilio huu ndio unaofanya kazi, si ngazi yoyote moja pekee. Wakala akiombwa date picker ataandika date picker, kwa sababu hilo ndilo aliloagizwa kufanya. Ngazi hii inamlazimisha kuangalia ngazi ya 4 kwanza, na ngazi ya 4 inasema browser tayari ina <input type="date">. Maelezo ya benchmark ya mradi yanaonyesha hali hii hasa: date picker iliyokuwa na mistari 404 bila kanuni hiyo ilipungua hadi mistari 23 pamoja nayo, kwa sababu wakala alitumia input ya native badala ya kujenga component. Colour picker ilipungua kutoka mistari 287 hadi 23 kwa sababu hiyo hiyo.

Uvivu hapa haumaanishi uzembe, na ruleset inasema hivyo moja kwa moja. Orodha yake ya mambo ambayo haipaswi kuwa mvivu kuyashughulikia inajumuisha kuelewa tatizo kabla ya kuamua, kuthibitisha input kwenye mipaka ya uaminifu, kushughulikia makosa ili kuzuia upotevu wa data, usalama, accessibility, na kila kitu ulichoomba waziwazi. Pia inaomba ukaguzi mmoja mdogo unaoweza kuendeshwa kwa kila sehemu ya logic isiyo ya kawaida. Kanuni hii inapunguza uvumbuzi usio wa lazima. Haipunguzi usahihi.

Kile ambacho hazina hutoa kwa hakika

• AGENTS.md, seti ya kanuni inayotumika kila wakati. Hili ndilo wazo lote katika faili moja unayoweza kusoma ndani ya dakika tano.
• skills/ponytail/SKILL.md, ufafanuzi wa skill, wenye kidokezo cha hoja cha lite, full au ultra.
• Faili za kanuni zilizo katika saraka mahususi za editor, kama vile .cursor/rules/ na .windsurf/rules/, kwa hosts zinazosoma kanuni lakini hazipakii skills.
• hooks/, benchmarks/, examples/ na scripts/.

Hoja ya intensity hubadilisha nguvu ya msukumo wa kanuni. lite huunda ulichoomba na hutaja chaguo lisilo na msukumo mkubwa katika mstari mmoja. full ndiyo chaguo-msingi na hulazimisha mpangilio huo. ultra ni mpangilio mkali wa YAGNI: hupendelea kufuta badala ya kuongeza, na huhoji hitaji lenyewe.

Hosts zinazoweza kutumia skills pia hupata slash commands. /ponytail huweka kiwango, /ponytail-review hukagua diff ili kubaini uhandisi uliopitiliza, /ponytail-audit hukagua hazina nzima, /ponytail-debt hukusanya njia za mkato ulizoahirisha, na /ponytail-gain huchapisha scorecard ya benchmark. Hosts zinazosoma faili za kanuni pekee hupata seti ya kanuni bila commands.

Ili usome chanzo kabla ya kukiamini, clone tag badala ya branch:

git clone --depth 1 --branch v4.8.4 https://github.com/DietrichGebert/ponytail.git

Kwenye Claude Code, mradi unaandika kuhusu usakinishaji wa plugin badala yake, na mistari hii miwili imeandikwa kama ilivyo kwenye nyaraka tarehe 1 August 2026:

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Njia ya plugin hufuata default branch badala ya tag. Kwa hiyo, maelekezo yanayomwongoza agent wako yanaweza kubadilika bila wewe kutarajia kati ya sessions. Hiyo ndiyo gharama unayokubali kwa urahisi wa update command.

Kwa nini agent mvivu ni nafuu kwenye VPS

Mabadiliko ambayo agent huandika hayauondoki kwenye mazungumzo. Katika zamu inayofuata, modeli huyasoma tena kama muktadha, pamoja na kila faili iliyoifungua ili kuyatengeneza. Kwa hiyo, mabadiliko ya mistari 500 huongeza gharama katika kila zamu inayofuata ya kikao, si katika zamu iliyoyatengeneza pekee. Hii ndiyo sababu refactor isiyodhibitiwa humfanya agent aonekane polepole na asiye na uwezo kadiri kikao kinavyoendelea: dirisha hujaa matokeo ya agent mwenyewe, hivyo nafasi inayobaki kwa msimbo wako halisi hupungua. Kudhibiti hali hii ndilo lengo kuu la kusimamia dirisha la muktadha la agent wa uandishi wa msimbo.

Tokeni hutozwa wakati wa kuingizwa na wakati wa kutolewa, kwa hiyo diff yenye nusu ya ukubwa hugharimu nafuu mara mbili: mara moja inapoandikwa, na tena katika kila zamu inaposomwa upya. Ikiwa unafuatilia bili kwenye usanidi unaojipangia mwenyewe, faili la maagizo ni kichocheo ambacho hakigharimu chochote kukitumia. Kudhibiti gharama ya agent wa AI kwako huanza na kiasi cha matokeo, na jinsi agent wa uandishi wa msimbo anavyotumia tokeni zake hufafanua kwa nini kusoma tena kuna umuhimu mkubwa kuliko watu wanavyotarajia.

Mwanadamu bado husoma diff. Mabadiliko ya mistari 400 ambayo yangefaa kuwa mistari 20 hutumia umakini wa mkaguzi, na umakini ndiyo rasilimali inayoisha kwanza. Hakuna anayekagua diff ndefu ya nne ya siku kwa uangalifu alioutumia kwenye ya kwanza, kwa hiyo kujenga kupita kiasi hakupotezi muda pekee. Pia hupunguza kimya kimya ubora wa ukaguzi unaopaswa kugundua makosa.

Kwenye seva, hatari huwa kubwa zaidi kwa sababu agent mara nyingi huendesha bila mtu anayemfuatilia. Agent anayefanya kazi katika kikao cha tmux au kwa ratiba anaweza kutumia saa kadhaa kuendeleza uamuzi mbaya kabla hujauona. Hiyo ndiyo hatari ya kiutendaji katika kuendesha agent wa uandishi wa msimbo kwenye VPS, na ndiyo sababu watu wanaofanya uhandisi wa mizunguko hutumia uangalifu mwingi kwenye maagizo ya kudumu badala ya vidokezo binafsi. Kanuni iliyo katika faili linalowashwa kila wakati hutumika katika zamu ya 200. Kanuni uliyoandika kwenye mazungumzo hutumika katika zamu ya 3.

Mategemezi mapya ni gharama nyingine isiyoonekana kwa urahisi. Kanuni ya 5 inasema utumie vilivyosakinishwa. Kila kifurushi ambacho agent huongeza kwa hiari yake ni kitu utakachopaswa kukipatia viraka baadaye, na kitu kitakachoishia katika kila picha ya kontena utakayounda kutoka kwenye hazina hiyo.

Namba za majaribio ya utendaji zilizochapishwa na Ponytail yenyewe

Mradi unachapisha seti mbili za matokeo, na zinatofautiana kwa kiasi kikubwa. Zote ni takwimu zilizochapishwa na mradi wenyewe. Hakuna hata moja iliyotokana na jaribio huru.

[
  {
    "label": "Lines of code",
    "single_shot_pct": 93,
    "agentic_pct": 54
  },
  {
    "label": "Cost per run",
    "single_shot_pct": 63,
    "agentic_pct": 20
  },
  {
    "label": "Wall clock time",
    "single_shot_pct": 74,
    "agentic_pct": 27
  }
]

Safu ya jibu moja inatokana na modeli tupu inayojibu seti ndogo ya maelekezo ikiwa na sheria na bila sheria hiyo. Takwimu hizo ni mediani za majaribio yaliyorudiwa yaliyofanywa tarehe 13 na 17 Juni 2026. Safu ya wakala inatokana na kipindi cha Claude Code kisicho na kiolesura kinachohariri full-stack-fastapi-template ya tiangolo, yaani hazina halisi ya FastAPI na React, kwa tiketi kumi na mbili za vipengele, kila moja ikiwa na majaribio manne kwenye Haiku 4.5. Tathmini ilifanywa kwa kutumia tofauti ya git iliyoachwa.

Soma safu ya pili. Matokeo ya wakala yana mistari ya msimbo 54 asilimia chache, gharama 20 asilimia chini, na muda wa ukuta 27 asilimia mfupi, ikilinganishwa na 93 asilimia na 74 asilimia kwa vipimo hivyo katika usanidi wa jibu moja. README inaeleza kwa uwazi sababu: msingi wa jibu moja ni modeli tupu inayojibu kwa “chaguo kadhaa pamoja na maelezo”, jambo ambalo ni rahisi kulishinda. Ukilinganisha na wakala halisi anayefanya kazi halisi, faida hupungua. Hata hivyo, matokeo hayo bado ni halisi, na huo ndio ukweli unaofaa zaidi.

Kuna tahadhari moja kutoka kwa mradi wenyewe, nayo ndiyo huamua kama hii itakusaidia. Akiba huwa kubwa zaidi pale ambapo kuna hatari halisi ya kujenga zaidi ya inavyohitajika, na huwa karibu sifuri kwenye msimbo ambao tayari ulikuwa mdogo. Tiketi kumi na mbili katika hazina moja ya Python na TypeScript haziwakilishi hazina yako. Ikiwa namba hiyo ni muhimu kwako, fanya ulinganisho kwenye tiketi zako mwenyewe, ukiwa na sheria hiyo na bila sheria hiyo, kisha uhesabu mistari mwenyewe.

Muundo unaoweza kunakili leo bila kusakinisha chochote

Ngazi hiyo ni maandishi, kwa hiyo huhitaji plugin ili kutumia wazo hilo. Bandika kizuizi kama hiki kwenye faili ya maagizo ambayo agent yako tayari huisoma, iwe ni AGENTS.md, CLAUDE.md au faili ya kanuni za kihariri chako.

## Before you write code

Climb this list in order. Stop at the first line that applies.

1. Does this need to exist? If not, say so and stop.
2. Does this repo already have it? Reuse the helper.
3. Does the standard library do it? Use it.
4. Does the platform do it natively? Use it.
5. Does an installed dependency do it? Use it.
6. Can it be one line? Write one line.
7. Otherwise write the minimum that works.

Never take the shortcut on: reading the code before changing it, validating
input that crosses a trust boundary, error handling that would otherwise lose
data, security, accessibility, or anything I asked for by name.

Do not add an abstraction I did not ask for. Do not add a dependency without
saying why in one line. Prefer deleting code to adding it.

Mark a deliberate simplification with a comment naming its ceiling and the
upgrade path.

Kanuni hiyo ya mwisho inastahili kuzingatiwa pekee. Mkataba wa Ponytail ni maoni yenye jina la zana:

# ponytail: global lock, per-account locks if throughput matters

Maoni hayo yana mistari miwili ya kazi na hutatua swali ambalo vinginevyo lingetumia mzunguko wa ukaguzi. Humwambia msomaji anayefuata kwamba toleo rahisi lilikuwa uamuzi, na hutaja sharti ambalo uamuzi huo utaacha kutumika. Bila maoni hayo, mkaguzi hawezi kutofautisha njia fupi iliyozingatiwa na kitu ambacho agent alisahau, kwa hiyo lazima aulize.

Mahali unapoweka kizuizi ni muhimu sawa na maudhui yake. Faili ambayo agent hupakia katika kila uendeshaji huongoza kila uendeshaji, kutia ndani ile usiyoifuatilia. Tofauti hiyo ndiyo mada ya kuandika AGENTS.md ambayo agent yako hufuata kwa kweli, na ndiyo sababu muundo huu unapaswa kuwa katika faili iliyowekwa kwenye hifadhi ya msimbo badala ya historia ya shell yako.

Mahali ambapo kanuni hii haifai tena

Ngazi hii imeundwa kwa kazi ya kuongeza vipengele katika codebase iliyopo, ambapo kutumia tena msimbo kwa kawaida kunawezekana na huwa sahihi. Haifai vizuri kwa mradi mpya, kwa sababu ngazi ya 2 haina kitu cha kutumia tena na ngazi ya 5 haina chochote kilichosakinishwa. Kwa hiyo, kila mara agent huishia kwenye ngazi ya 7. Pia haifai wakati ambapo kwa kweli unataka abstraction hiyo. Ikiwa unakaribia kuongeza mtumiaji wa nne wa block ileile iliyonakiliwa, “diff fupi zaidi” itakupa nakala ya tano.

Ngazi ya ultra itapinga mahitaji yako. Hilo ndilo lengo la ngazi hiyo, na ni gharama halisi ikiwa tayari umefanya uamuzi na unataka kazi ikamilishwe. Tumia full kwa kazi za kawaida, na tumia ultra unaposhuku kuwa ombi la kipengele ndilo tatizo.

Hakuna block ya maagizo inayoweza kukuokoa kutokana na kuelewa tatizo kwa njia isiyo sahihi. Kipengele cha kwanza cha ruleset yenyewe ni kuelewa code kabla ya kuamua, na hiyo ndiyo sehemu inayohitaji muda zaidi na ambayo maandishi haya hayawezi kukufanyia. Diff ndogo katika function isiyo sahihi bado ni marekebisho yasiyo sahihi, na sasa ni marekebisho madogo yasiyo sahihi ambayo ni rahisi kuidhinisha.

Muhtasari wa kweli ni kwamba Ponytail ni prompt iliyoandikwa kwa uangalifu, iliyosambazwa vizuri, na yenye nambari zilizoambatanishwa. Hakuna chochote ndani yake kinachohitaji plugin. Kile ambacho mradi huu unakupa ni kwamba mtu aliandika orodha hiyo ipasavyo, akaijaribu dhidi ya repository halisi, na kuchapisha mbinu hiyo pamoja na matokeo.

FAQ

Je, Ponytail inafanya kazi na mawakala wengine isipokuwa Claude Code?

Ndiyo. Husambazwa kama skill kwa hosts zinazopakia skills. Orodha hiyo inajumuisha Claude Code, Codex, OpenCode, Gemini na nyingine kadhaa zilizotajwa kwenye README. Editors zinazosomeka rule files lakini hazipakii skills, kama vile Cursor, Windsurf, Cline na Copilot, hutumia always-on ruleset kutoka kwenye rules directory inayolingana na hazipati slash commands. Maandishi ni yaleyale katika hali zote mbili. Tofauti ya msingi ni kama host yako huweka maandishi hayo kwenye context kila turn au huyaweka tu skill inapowashwa.

Je, agent mvivu ataruka tests, validation au usalama?

Hapana, na ruleset inaeleza hili moja kwa moja. Orodha yake ya mambo ambayo haipaswi kuwa mvivu kuyashughulikia inataja input validation kwenye trust boundaries, error handling inayozuia upotezaji wa data, usalama na accessibility. Pia inahitaji check moja ndogo inayoweza kuendeshwa kwa kila sehemu ya logic isiyo ya kawaida. Rule hiyo huondoa muundo uliobuniwa bila sababu: abstractions ambazo hakuna aliyeomba na dependencies ambazo hakuna aliyehitaji. Ikiwa agent yako inaanza kuacha tests baada ya kuisakinisha, sababu ni instruction nyingine katika config yako yenye kipaumbele cha juu kuliko hii. Kwa hiyo, soma file ambayo agent hupakia mwisho.

Je, nambari zilizochapishwa za kasi na gharama zinaaminika?

Hizo ni vipimo vya mradi wenyewe, vilivyochapishwa pamoja na mbinu iliyotumika, na zinapaswa kusomwa kwa mtazamo huo. Takwimu za single shot zinalinganisha na model tupu inayojibu kwa options na maelezo ya ziada. README yenyewe inaonyesha kuwa huo ni msingi dhaifu wa kulinganisha. Takwimu za agentic zilitokana na session ya headless Claude Code kwenye repository moja ya FastAPI na React, tickets kumi na mbili, na runs nne kwa kila ticket, kwa kutumia Haiku 4.5. Hizo ni nambari halali kwa setup hiyo. Si utabiri wa codebase yako, kwa sababu mradi pia unasema kuwa uokoaji hupungua hadi karibu sifuri kwenye code ambayo tayari ilikuwa minimal.

Je, ninahitaji kusakinisha kitu ili nipate manufaa?

Hapana. Ladder ni maandishi, na kubandika block inayolingana kwenye instruction file ambayo agent yako tayari husoma hukupa sehemu kubwa ya manufaa. Plugin hukupa wording inayodumishwa, intensity levels, review commands na njia ya kupata updates. Kujaribu block iliyonakiliwa kwanza ni jibu la rung 1 kwa swali la kama install inahitaji kuwepo kabisa.

Ninawezaje kumzuia agent asiyeangaliwa asijenge kupita kiasi usiku kucha?

Weka rule kwenye always-on instruction file badala ya kuiweka kwenye ujumbe wa chat. Hivyo itatumika kwenye turn 200 ya run ndefu, wala si kwenye turn 3 pekee. Kisha punguza madhara kando: mpe agent checkout ambayo inaruhusiwa kuiharibu badala ya copy yako pekee, na hitaji human diff review kabla ya kitu chochote kuunganishwa. Rule ya minimal diff hupunguza kiasi unachopaswa kusoma. Haiamui kitakachoingia, wala haipaswi kufanya hivyo.