Как я улучшил качество кода, генерируемого LLM, с помощью agent.md

Был бы какой-то недостаток в том, чтобы просто держать все правила стиля кода в файле CONTRIBUTING.md, а «как общаться со мной» — в AGENTS.md, поскольку правила стиля кода также применимы к человеческим контрибуциям? Аналогично, разве «как общаться со мной» не является личным и, следовательно, не должно находиться в репозитории?

> - Держите имена функций короткими. Меньше 30 символов.

Недавно я попросил GPT портировать браузерную игру на Rust. Он выдал такой перл:

draw_image_with_html_image_element_and_sw_and_sh_and_dx_and_dy_and_dw_and_dh(...)

Я подумал, что он курит что-то хорошее, но оказалось, что это на самом деле имя функции!

https://docs.rs/web-sys/latest/web_sys/struct.CanvasRenderin...

Раз уж мы делимся своими AGENTS.md, я решил поделиться своим, потому что в большинстве случаев этого почти достаточно, чтобы LLM писали хороший код, всё остальное можно добавлять под конкретный проект:

----

*Правило сходимости*

Каждая существенная задача должна заканчиваться ровно одним из трёх состояний:

A. Успех

Задуманная возможность работает в реальном сценарии, и реальный мотивирующий случай существенно улучшается.

B. Значимое продвижение

Возможность не завершена, но устранён один настоящий блокер, и следующий блокер изолирован с доказательствами.

C. Честная остановка

Дальнейшая работа потребовала бы чрезмерного расширения области, чрезмерного долга, хрупких патчей или запутанной логики. Остановитесь и сообщите причину с конкретными доказательствами.

Не продолжайте создавать патчи, как только работа перестаёт сходиться.

Не путайте активность с прогрессом. Неудачная попытка приемлема только в том случае, если она оставляет после себя более узкую проблему, более сильные доказательства или обоснованную остановку.

Любая частичная работа должна оставлять кодовую базу в более чистом, более читаемом и более диагностируемом состоянии, чем раньше.

----

Многие из AGENTS.md из статьи просто говорят агентам LLM либо то, что они уже знают (например, в большинстве случаев они знают, что нужно использовать исчерпывающие switch/match вместо «анти-паттерна со стрелками»), либо то, что кажется активно вредным («держите имена функций короткими» кажется произвольным и может заставить LLM писать странные сокращения для функций, которые труднее читать и ревьюить.

Это много контекста для небольшого содержания. Я обычно начинаю с чего-то вроде:

- Предпочитайте документацию как код

- Комментируйте «почему», а не «что»

- Документируйте публичные API

- Читаемость превыше всего

Обычно это даёт мне 80% результата; остальное покрывает линтер.

В основном мне не хватает того, чтобы он слишком много объяснял предыдущее состояние, особенно при внесении правок в планы, но я пока не нашёл хорошей формулировки для этого.

«Когда пишете что-то, предназначенное для потребления человеком (комментарий, сообщение коммита, ответ на промпт), используйте как можно меньше слов. Тщательно подбирайте каждое слово, чтобы сократить объём до строгого минимума. Будьте по делу. Меньше — значит больше».

Ирония в том, что этот первый абзац использует много слов и много способов передать одно и то же сообщение о краткости. Но этот файл не для потребления человеком, поэтому к нему должны (всё ещё?) применяться другие правила.

Я замечаю, что делаю так в промптах, думаю, это способ придать больше веса частям контекста, которые мы считаем нужным подчеркнуть, и это показывает недоверие к способностям LLM понять сообщение, если оно упомянуто один раз.

Интересно читать такие вещи.

Я бы описал это как 13 правил написания кода (интерпретируемых как минимум как 16 — начиная с уменьшения отступов кода) плюс набор инструкций для сообщений коммитов, которые я решил игнорировать — потому что это специфично для стиля и мне неинтересно.

8 или 9 из этих правил не нужны. Базовую информатику мне не приходилось просить соблюдать агентов, которых я использую. Например, объяснять, что нужны явные интерфейсы, — не обязательная инструкция, как и использование раннего выхода.

Неясные инструкции имеют ограниченную полезность. Что означает «дайте читателю кода дышать» или «уменьшите отступы кода» — субъективно и редко будет эффективно. Возможно, в обучении используемого языка есть пробелы, которых нет у других. Если хотите измерить, попросите выводить строку, когда применяется правило. Вы быстро поймёте, что работает, что нет и как часто.

Здесь есть 3 или 4 выбора стиля.

Остальное я бы не использовал, но всех нас обжигают разные вещи, так что я понимаю.

Отличный материал. Однако AGENTS.md — не идеальное место для большинства этого. Большая часть того, что показано в статье, может быть помещена в CODING_STANDARDS.md. Навыки, которые я использую, находят этот документ, когда он нужен (при написании и ревью кода), так что он не засоряет контекст при чтении кода.

У меня также есть ревью от субагентов (как фазы планирования, так и созданного кода), которые могут выявить некоторые из этих проблем и потребовать исправлений. [1]

> - Если промпт указывает, что исправляется баг, не пишите исправление сразу. Сначала напишите тест. Убедитесь, что он падает. Затем напишите исправление. И убедитесь, что тест проходит.

Я всегда использую /tdd [2]. Иногда это приводит к глупым тестам, но это даёт гораздо меньше дефектного кода. Это не только для багов.

[1] https://github.com/gregwebs/skills-sdlc/

[2] https://github.com/mattpocock/skills/blob/main/skills/engine...