AI-ის დახმარებით კოდის წერის ხარისხი: ფაბიენ სანგლარის agent.md წესები

პროგრამისტმა ფაბიენ სანგლარმა 2026 წლის 21 აგვისტოს გამოაქვეყნა ჩანაწერი „My agent.md to improve LLM-assisted code quality“, სადაც საკუთარ agent.md ფაილს აზიარებს — დოკუმენტს, რომელსაც კოდის აგენტები სესიის დასაწყისში ავტომატურად კითხულობენ.

პირველი მცდელობიდან სამუშაო პროცესამდე

სანგლარი იხსენებს, რომ LLM-ები პირველად 2025 წლის შუაში სცადა და არ მოეწონა: Rust-ზე დაწერილი mDNS ბიბლიოთეკის, libadbmdns-ის, მიერ გენერირებული კოდი კომპილაციასაც ვერ გადიოდა. 2026 წლის იანვარში მან ხელახლა სცადა — მოდელმა რთული ინდექსირებული ორობითი ჰიპის კლასი დაწერა და polling crate-ში Windows-ის IOCP-ის გამო არსებული ბუნდოვანი შეცდომაც იპოვა.

თუმცა კოდის ხარისხი, მისი შეფასებით, საშინელი იყო: სპაგეტი კომენტარებისა და სტრუქტურის გარეშე. 2026 წლის მარტში მან აგენტური IDE-ები (Antigravity და VS Code-ის Claude Code დამატება) გამოიყენა — კოდის გამეორებითი გადახედვა შესაძლებელი გახდა და ხარისხი მკვეთრად გაუმჯობესდა, თუმცა ყოველ ახალ სესიაზე ერთი და იმავე შენიშვნების გამეორება დამღლელი იყო.

რას შეიცავს agent.md

agent.md პროექტის ძირეულ დირექტორიაში იდება; gemini.md ან claude.md შეიძლება მასზე სიმბოლური ბმულით იყოს მიბმული, რომ ფაილი ყველგან მოქმედებდეს. სანგლარის წესები: ადამიანისთვის განკუთვნილ ტექსტში (კომენტარი, კომიტ-შეტყობინება, პასუხი) რაც შეიძლება ცოტა სიტყვა; ქება არ სჭირდება — „მითხარი ცივი სიმართლე“; მაგიური რიცხვების ნაცვლად მუდმივები და enum-ები; ჩადგმულობის შემცირება და ადრეული return; ფუნქციის სახელი 30 სიმბოლოზე ნაკლები; პარამეტრებში boolean-ის ნაცვლად enum; ლოგიკურ ბლოკებს შორის ცარიელი ხაზი; მოკლე კომენტარი, რომელიც ხსნის „რას“ და „რატომ“, საჭიროებისას ASCII სქემები; წვდომის მოდიფიკატორის შეცვლა private-იდან public-ზე მკითხველის თანხმობის გარეშე აკრძალულია; აბსტრაქციის დონეებისა და ფენების იერარქიის დაცვა (ინტერფეისი არასოდეს მიმართავს უშუალოდ ბაზას ან დრაივერს); სხვა ბლოკებში ცვლილებები მინიმალური; ხვეული ფრჩხილები ყოველთვის, ერთხაზიანი if-ის შემთხვევაშიც.

კომიტ-შეტყობინებები და ტესტები

ფაილი ასევე მოიცავს შვიდ წესს კომიტ-შეტყობინებისთვის: სათაური და ტექსტი ცარიელი ხაზით გამოიყოფა; სათაური არაუმეტეს 50 სიმბოლოა (72 — აბსოლუტური ზღვარი); პირველი ასო დიდია; ბოლოში წერტილი არ ისმება; სათაური ბრძანებითი კილოთი იწერება და უნდა ერგებოდეს წინადადებას „If applied, this commit will…“; ტექსტი 72 სიმბოლოზე იკეცება; ტექსტი ხსნის „რას“ და „რატომ“, არა „როგორ“. შეცდომის გასწორებისას წესია: ჯერ დაწერე ტესტი, ნახე, რომ ვარდება, შემდეგ გამოასწორე და ნახე, რომ გადის.

შეზღუდვები: ჰალუცინაცია და კონტექსტის გაზავება

ავტორი ხაზგასმით აღნიშნავს, რომ ეს „ჯადოსნური ტყვია“ არ არის: მოდელები ხშირად ჰალუცინირებენ, ამიტომ კოდის წაკითხვა და შემოწმება მაინც აუცილებელია — ახლა ის უფრო არქიტექტურასა და დიზაინზე კონცენტრირდება, ვიდრე კოდის სტილზე. მეორე პრობლემაა „კონტექსტის გაზავება“, რომელიც Lost in the Middle-ის ნაშრომშია აღწერილი: კონტექსტის ზრდასთან ერთად მოდელი შუაში მოთავსებულ ინსტრუქციებს ნაკლებად აქცევს ყურადღებას.

გადაწყვეტაც ორია: თითო ფუნქციაზე ახალი სესია და პირდაპირი მოთხოვნა „Reload agent.md“, როცა ხარისხი ეცემა. ახალი წესის დამატებისას რედაქტორის გახსნა არ სჭირდება — საკმარისია აგენტს სთხოვოთ, რომ თავად განაახლოს agent.md.