Оригинал: Heidenstedt — “How to effectively write quality code with AI”
Источник: https://heidenstedt.org/posts/2026/how-to-effectively-write-quality-code-with-ai/

Как эффективно писать качественный код с помощью ИИ

Ниже — перевод (с небольшими правками стиля для читаемости). Термины вроде property-based testing оставлены на английском с коротким пояснением.

1. Сформулируйте чёткое видение

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

Каждое важное решение в проекте, которое вы не приняли и не зафиксировали, ИИ «примет» за вас.

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

Вы должны знать, какие части кода нужно тщательно продумать и какие — агрессивно тестировать.

Продумайте и обсудите архитектуру, интерфейсы, структуры данных и алгоритмы, которые вы хотите использовать.

Продумайте, как тестировать и валидировать код относительно этих спецификаций.

2. Ведите точную документацию

Вам нужно подробно объяснять ИИ, чего вы хотите добиться — иначе он выдаст код, который не подходит вашей задаче.

Другим разработчикам тоже нужно передавать ИИ те же сведения. Поэтому выгодно писать столько документации, сколько практично, в стандартизированном формате, и хранить её прямо в репозитории.

Документируйте требования, спецификации, ограничения и архитектуру проекта в деталях.

Документируйте стандарты кодинга, best practices и паттерны проектирования.

Используйте блок‑схемы, UML‑диаграммы и другие визуальные материалы, чтобы объяснять сложные структуры и процессы.

Пишите псевдокод для сложных алгоритмов и логики — это помогает ИИ понять ваши намерения.

3. Стройте отладочные системы, которые помогают ИИ

Разрабатывайте эффективные системы отладки, которыми сможет пользоваться ИИ — чтобы уменьшить количество дорогих циклов «запусти CLI/браузер → проверь → попробуй снова».

Это экономит время и ресурсы и упрощает поиск и исправление проблем.

Пример: соберите систему, которая агрегирует логи со всех узлов распределённой системы и выдаёт абстрактные выводы вроде «Данные отправлены на все узлы» или «Данные X сохранены на узле 1, но не на узле 2».

4. Размечайте уровни ревью кода

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

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

Например, можно попросить ИИ добавлять комментарий //A к функциям, которые он написал, чтобы обозначать: «написано ИИ, человеком ещё не ревьюилось».

5. Пишите высокоуровневые спецификации и тестируйте сами

Рано или поздно ИИ начнёт «хитрить» и искать короткие пути.

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

Вы должны снижать вероятность такого поведения: пишите сами property-based и прочие высокоуровневые спецификационные тесты.

Стройте их так, чтобы ИИ было трудно «сжульничать», не добавив заметные большие куски кода.

Пример: property-based тестирование, перезапуск сервера между шагами, проверка, что база действительно содержит корректные значения.

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

6. Пишите интерфейсные тесты в отдельном контексте

Пусть ИИ пишет property-based интерфейсные тесты ожидаемого поведения, имея как можно меньше контекста о внутренностях остального кода.

Так вы получите тесты, на которые меньше влияет «ИИ‑имплементатор», и они с меньшей вероятностью будут подогнаны под реализацию так, что станут бесполезными или менее эффективными.

Разделяйте эти тесты так, чтобы ИИ не мог менять их без одобрения, и в промпте запрещайте их править.

7. Используйте строгие правила линтинга и форматирования

Строгий линтинг и форматирование помогают обеспечивать качество и единообразие. Это позволит вам и вашему ИИ находить проблемы раньше.

8. Используйте контекстно‑специфичные промпты для coding‑агентов

Экономьте время и деньги, используя path‑specific промпты для агентов — например файлы вроде CLAUDE.md (пример из Anthropic).

Их можно генерировать автоматически — так ИИ будет получать информацию, которую иначе ему пришлось бы каждый раз «изобретать заново».

Старайтесь давать как можно больше полезной высокоуровневой информации: стандарты кодинга, best practices, паттерны, специфические требования проекта. Это уменьшит количество уточнений и стоимость итераций.

9. Находите и помечайте функции с высоким риском безопасности

Идентифицируйте и помечайте функции повышенного риска: аутентификация, авторизация, обработка данных и т. п.

Такие функции нужно ревьюить и тестировать особенно тщательно — так, чтобы человек действительно понял логику во всех измерениях и был уверен в корректности и безопасности.

Сделайте это явным через комментарии вроде //HIGH-RISK-UNREVIEWED и //HIGH-RISK-REVIEWED, чтобы другие разработчики видели важность этих мест и относились к ним соответствующе.

Если ИИ меняет в такой функции хотя бы один символ, он обязан обновить статус ревью.

Разработчики должны следить, чтобы статус этих функций всегда был корректным.

10. Снижайте сложность кода, где это возможно

Старайтесь снижать сложность генерируемого кода. Каждая строка «съедает» контекстное окно и усложняет и ИИ, и вам удержание общей логики в голове.

Каждая лишняя строка — это стоимость в энергии, деньгах и вероятности будущих неудачных задач для ИИ.

11. Исследуйте проблемы через эксперименты и прототипы

Код, написанный ИИ, относительно дёшев — используйте это, чтобы исследовать разные решения через эксперименты и прототипы с минимальными спецификациями.

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

12. Не генерируйте «вслепую» и не делайте слишком сложное за раз

Разбивайте сложные задачи на меньшие управляемые подзадачи.

Вместо того чтобы просить ИИ сгенерировать весь проект/компонент целиком, просите по частям: отдельные функции, классы, модули.

Так вам проще сохранять контроль над кодом и его логикой.

Вы должны проверять каждый компонент или модуль на соответствие спецификациям и требованиям.

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