Стандарты кода и Definition of Done
Проверено: 20 июля 2026 года.
Общий стандарт не заменяет правила конкретного проекта. Приоритет имеют его версии языка, архитектура, formatter, линтеры, тестовый стек и принятые idioms.
Принципы реализации
- Решать заявленную задачу минимальным связным изменением.
- Сохранять существующие публичные контракты, если их изменение не согласовано.
- Предпочитать простой код с очевидным потоком данных и ошибок.
- Не создавать абстракцию ради одного гипотетического будущего случая.
- Не подавлять исключения без обработки, логирования или обоснованного fallback.
- Валидировать вход на границе системы; внутри опираться на явные типы и инварианты.
- Не добавлять зависимость, если задача надёжно решается средствами проекта.
- Комментарии должны объяснять причину или ограничение, а не пересказывать код.
Перед написанием типового механизма с нуля выполнить library scout по REUSE.md. Предпочтение готовому package не отменяет проверки его лицензии, maintenance, безопасности и совместимости.
Изменение существующего кода
До правки найти аналогичную реализацию и связанные тесты. При исправлении дефекта сначала получить воспроизводимый сценарий или regression-тест. Не переименовывать и не форматировать несвязанные участки: узкий diff легче проверить и откатить.
Совместимость оценивать явно:
- API, CLI и форматы данных;
- схема БД и порядок развёртывания;
- конфигурация и переменные окружения;
- очереди, события, кэш и фоновые задания;
- поддерживаемые версии рантайма и зависимостей.
Пирамида проверки
Выбирать проверки по реальному стеку проекта, обычно от быстрых к дорогим:
- Formatter и синтаксис.
- Целевой unit/feature/integration-тест.
- Static analysis и type checking.
- Связанный набор тестов.
- Сборка, миграционный или контейнерный smoke-check.
- Ручная проверка критического пользовательского сценария.
Нельзя утверждать, что вся система исправна, если запускался только отдельный тест. Если полный набор недоступен или слишком дорог, назвать точный охват.
Базовый Definition of Done
- Реализован согласованный результат без случайного расширения scope.
- Добавлены или обновлены тесты для нового поведения и значимых границ.
- Пройдены штатные formatter, lint, analysis, tests и build, применимые к diff.
- Проверены ошибки, авторизация, валидация и конкурентность, если они затронуты.
- Просмотрен итоговый diff; нет секретов, debug-кода, временных файлов и дампов.
- Документация, примеры конфигурации, миграции и changelog обновлены по правилам проекта.
- Для опасного изменения описаны развёртывание, наблюдение и откат.
- В финальном отчёте приведены фактически выполненные команды и ограничения.
Ревью AI-сгенерированного кода
Человек или независимый review-проход должен проверить не только стиль, но и:
- соответствует ли код исходной задаче;
- не придуманы ли несуществующие API, флаги или версии;
- не ослаблены ли auth, permissions, validation и обработка ошибок;
- нет ли N+1, неограниченных выборок, гонок и неидемпотентных повторов;
- действительно ли тест способен упасть при регрессии;
- не скрывает ли snapshot или mock неправильный production-контракт.
Для нового AI-сгенерированного regression-теста применить принцип «test the test»: временно вернуть дефект или точечно использовать mutation testing и убедиться, что проверка краснеет. Подробный цикл — в DEBUGGING.md.
Механические требования закреплять инструментами. Для ревью небольших изменений полезны Google Engineering Practices, а security-критерии выбирать из применимого уровня OWASP ASVS.