Якість коду з ШІ: правила agent.md Фаб'єна Санглара

Програміст Фаб'єн Санглар опублікував 21 серпня 2026 року допис "My agent.md to improve LLM-assisted code quality", у якому поділився своїм файлом agent.md — документом, який інструменти для кодування автоматично завантажують на початку сесії.

Від невдалої спроби до робочого процесу

Санглар згадує першу спробу в середині 2025 року: він працював над libadbmdns, реалізацією mDNS на Rust, і згенерований код не компілювався взагалі. У січні 2026 року він повернувся до LLM — модель написала складний клас індексованої двійкової купи й навіть знайшла малопомітну помилку в бібліотеці polling, спричинену реалізацією Windows IOCP.

Проте якість коду була жахливою: спагеті без коментарів і структури. У березні 2026 року він перейшов на агентні IDE, як-от Antigravity та плагін Claude Code для VS Code, що дозволило ітеративно переглядати код. Якість різко зросла — майже до рівня написаного вручну, — але повторювати ті самі підказки в кожній новій сесії було виснажливо.

Що містить файл

agent.md розміщують у корені проєкту; gemini.md або claude.md можна зробити символьним посиланням на нього, щоб правила діяли будь-де. Серед правил Санглара: вживати якнайменше слів у всьому, що призначене для людини; не хвалити й «давати холодну правду»; замінювати магічні числа описовими константами чи enum; зменшувати вкладеність і користуватися раннім return; тримати імена функцій коротшими за 30 символів; використовувати enum замість boolean у параметрах; додавати порожні рядки між логічними блоками; писати короткі коментарі про «що» і «чому», за потреби — ASCII-схеми; вважати зміну видимості члена класу зміною дизайну й питати дозволу перед оприлюдненням; програмувати на рівнях абстракції з окремим шаром драйвера; не чіпати не пов'язані блоки й мінімізувати кількість змінених рядків; поважати ієрархію шарів, не «пробиваючи» їх; завжди ставити фігурні дужки, навіть в однорядковому if.

Коміти й тести

Файл також містить сім правил для коміт-повідомлень: відокремлювати заголовок від тіла порожнім рядком; обмежувати заголовок 50 символами (72 — абсолютна межа); починати з великої літери; не ставити крапку в кінці; вживати наказовий спосіб, перевіряючи себе фразою "If applied, this commit will..."; переносити тіло на 72 символах; пояснювати в тілі «що» і «чому», а не «як». Для виправлення багів діє процедура: спершу написати тест, побачити його падіння, потім внести виправлення й переконатися, що тест проходить.

Обмеження: галюцинації та розмивання контексту

Санглар наголошує, що це не чарівна куля. LLM постійно галюцинують, і довіряти їм не можна, тому код усе одно доводиться перевіряти й доопрацьовувати — щоправда, тепер він зосереджується на архітектурі та дизайні, а не на стилі. Друга проблема — розмивання контексту чи уваги, описане в статті Lost in the Middle: зі зростанням контексту модель менше зважає на інструкції в середині й більше — на початок і кінець.

Він знайшов два способи пом'якшити ефект: тримати контекст коротким, починаючи нову сесію для кожної функції, та прямо просити інструмент перезавантажити agent.md, коли якість падає — фрази "Reload agent.md" достатньо. Щоб додати правило, редактор не потрібен: він просить агента оновити agent.md самостійно.