AI ilə kod keyfiyyəti: Fabien Sanglardın agent.md qaydaları

Proqramçı Fabien Sanglard 2026-cı il avqustun 21-də "My agent.md to improve LLM-assisted code quality" yazısını dərc edərək kodlaşdırma alətlərinin sessiyanın əvvəlində avtomatik yüklədiyi agent.md faylını paylaşıb.

Uğursuz cəhddən işlək axına

Sanglard ilk cəhdini 2025-ci ilin ortasında etdi: Rust ilə yazılmış libadbmdns üzərində işləyirdi və yaradılan kod kompilyasiya olunmurdu. 2026-cı ilin yanvarında o, LLM-lərə yenidən qayıtdı: bu dəfə model mürəkkəb indekslənmiş ikili yığın sinfi yazdı və polling paketində Windows-un IOCP tətbiqindən qaynaqlanan gizli xətanı da tapdı.

Lakin kodun keyfiyyəti dəhşətli idi: şərhsiz və struktursuz spagetti kod. 2026-cı ilin martında o, Antigravity və VS Code-un Claude Code əlavəsi kimi agent əsaslı IDE-lərə keçdi; bu, kod üzərində təkrarlanan işləməyə imkan verdi. Keyfiyyət kəskin artdı və əl ilə yazdığına çox yaxınlaşdı, amma hər yeni sessiyada eyni təklifləri təkrarlamaq yorucu idi.

Faylın məzmunu

agent.md layihənin kök qovluğuna yerləşdirilir; gemini.md və ya claude.md ona simvolik keçidlə bağlanaraq qaydaların hər yerdə işləməsini təmin edə bilər. Sanglardın qaydaları arasında bunlar var: insan üçün nəzərdə tutulan mətndə mümkün qədər az söz işlətmək; tərifdən çəkinib "mənə soyuq həqiqəti söylə"; sehrli rəqəmlər yerinə izahedici sabitlər və ya enum işlətmək; girintini azaldıb erkən return ilə ox-antipatternindən qaçmaq; funksiya adlarını 30 simvoldan qısa saxlamaq; parametrlərdə boolean yerinə enum işlətmək; nə və niyə etdiyini izah edən qısa şərhlər yazmaq, lazım gəldikdə ASCII sxemlər əlavə etmək; görünürlük dəyişikliyini dizaynı pozan addım sayıb sahəni public etməzdən əvvəl icazə istəmək; abstraksiya səviyyələrinə uyğun proqramlaşdırmaq; əlaqəsiz bloklara toxunmamaq və dəyişdirilmiş sətirlərin sayını minimuma endirmək; qat iyerarxiyasına hörmət etmək.

Commit mesajları və testlər

Fayl həmçinin commit mesajları üçün yeddi qayda ehtiva edir: mövzu sətrini gövdədən boş sətirlə ayırmaq; mövzunu 50 simvolla məhdudlaşdırmaq (72 mütləq həddir); ilk hərfi böyük yazmaq; sonunda nöqtə qoymamaq; əmr formasından istifadə edib "If applied, this commit will..." cümləsini tamamladığını yoxlamaq; gövdəni 72 simvolda bükmək; gövdədə necə deyil, nə və niyə sualına cavab vermək. Xəta düzəltmələrində isə qayda budur: əvvəlcə testi yaz, onun uğursuz olduğunu gör, sonra düzəlişi et və testin keçdiyini izlə.

Məhdudiyyətlər: hallüsinasiya və kontekstin seyrəlməsi

Sanglard bunun sehrli çubuq olmadığını vurğulayır. Modellər daim hallüsinasiya edir və onlara etibar etmək olmaz; buna görə kodu yenə yoxlamaq və təkrarlamaq lazımdır — sadəcə indi o, kod üslubundan çox arxitektura və dizayna fokuslanır. İkinci problem Lost in the Middle məqaləsində təsvir olunan kontekst və ya diqqət seyrəlməsidir: kontekst böyüdükcə model ortadakı təlimatlara daha az, əvvəldə və sonda olanlara isə daha çox diqqət yetirir.

O, təsiri azaltmağın iki yolunu tapıb: hər funksiya üçün yeni sessiya açmaqla konteksti qısa saxlamaq və keyfiyyət düşdükdə alətdən açıq şəkildə agent.md-ni yenidən yükləməyi xahiş etmək — "Reload agent.md" ifadəsi kifayətdir. Yeni qayda əlavə etmək üçün redaktor açmağa ehtiyac yoxdur: o, agentdən agent.md-ni özünün yeniləməsini xahiş edir.