Quality Gates и Anti-Mirage
Автоматические проверки качества, правило трёх попыток и защита от галлюцинаций AI. Матрица: что, чем, когда.
Простым языком
AI иногда ошибается. Выдумывает функции которых нет. Пишет код который не работает. Quality Gates — это встроенные проверки, которые ловят такие ошибки до того как ты потратишь время на отладку.
Представь контрольный пункт на дороге. Прежде чем код попадёт в продакшн — он проходит проверку. Сначала план, потом код, потом деплой. Каждый этап защищает от следующего.
Quality Gates — зачем нужна система
AI пишет код быстро, но ошибается. Без системы проверок ошибки накапливаются и обнаруживаются поздно — когда исправление стоит дорого. Quality Gates — набор барьеров, через которые код проходит автоматически.
- Gate 1 — после создания плана (для фич M и L)
- Gate 2 — после написания кода (>10 строк)
- Gate 3 — перед деплоем (для фич M и L)
Проблема на Gate 1 обходится в 10 раз дешевле, чем на Gate 3.
Gate 2: Ревью кода (самый важный)
Триггер: написан код >10 строк. Всегда включает Anti-Mirage check.
Автоматические проверки через хуки
- security-scan.sh — SQLi, XSS, OS-инъекции при каждом Write/Edit
- protect-secrets.sh — блокирует запись API-ключей, токенов, паролей в код
- destructive-guard.sh — блокирует
rm -rf /,DROP TABLE, форс-пуш в main - prettier / ruff — автоформатирование JS/TS и Python после каждого файла
Severity — уровни серьёзности
- Critical — обязательно исправить до продолжения. Ре-верификация после исправления
- Major — исправить в этой же сессии. Не блокирует, но нужно
- Minor — исправить если займёт <2 минуты. Иначе → записать в техдолг
# Примеры по severity
Critical:
- SQL инъекция в публичном эндпоинте
- Хардкод пароля или токена в коде
- Эндпоинт без проверки авторизации
Major:
- Функция 80 строк (должна быть <50)
- Дублирование бизнес-логики в двух местах
- Отсутствие тестов для критичной функции
Minor:
- Комментарий на английском (нужен русский)
- Переменная с нечётким именем
- Неоптимальный запрос (но работает)Правило трёх попыток
Попытка 1: проверка → findings → исправление
Попытка 2: ре-проверка → findings → исправление
Попытка 3: финальная → если issues есть → эскалация
Эскалация = сообщить пользователю + прекратить цикл.
Нельзя крутиться бесконечно — это сжигает токены впустую.Anti-Mirage — проверка реальности
Claude любит «галлюцинировать» — ссылаться на несуществующие файлы, функции, API, пакеты. Это самая частая причина ошибок при AI-разработке. Anti-Mirage — правила и проверки, которые это предотвращают.
Типичные миражи и как их поймать
# Мираж 1: Несуществующий файл
# Claude: "Добавь логику в src/utils/payment-helpers.ts"
# Реальность: файла нет
ls src/utils/ # проверяем что есть
# Мираж 2: Несуществующая функция
# Claude: "Вызови UserService.getByTelegramId()"
# Реальность: метод называется findByTgId()
grep -n "getByTelegramId|findByTgId" src/services/user.ts
# Мираж 3: Устаревший API библиотеки
# Claude: "requests.get_async(url)" ← такого метода нет
# Проверка: context7 → актуальная документация requests
# Мираж 4: Фантомный пакет
# Claude: "npm install react-query-v4-compat"
npm info react-query-v4-compat 2>&1 || echo "Пакет не найден"
# Мираж 5: Несуществующее поле БД
# Claude: "WHERE user.role = 'admin'" ← поля role нет в схеме
grep "role" prisma/schema.prismaЧеклист Anti-Mirage
- Импорты — каждый
import/require/fromссылается на существующий файл - Функции — каждая вызываемая функция существует в импортируемом модуле
- Env vars — каждый
process.env.Xописан в.env.example - Пакеты — каждый внешний пакет указан в
package.json/requirements.txt - API endpoints — URL и метод внешнего API актуальны (проверь через context7)
Скрипт автоматической проверки импортов
#!/bin/bash
# .claude/hooks/check-imports.sh
# Запускается PostToolUse:Write|Edit для .ts/.tsx файлов
FILEPATH="$1"
[[ "$FILEPATH" != *.ts && "$FILEPATH" != *.tsx ]] && exit 0
echo "Anti-Mirage: проверяю импорты в $FILEPATH..."
DIR=$(dirname "$FILEPATH")
ERRORS=0
# Извлечь и проверить локальные импорты
while IFS= read -r imp; do
found=0
for ext in "" ".ts" ".tsx" "/index.ts" "/index.tsx"; do
[ -f "$DIR/$imp$ext" ] && found=1 && break
done
[ $found -eq 0 ] && echo "WARN: Импорт не найден: $imp" && ERRORS=$((ERRORS+1))
done < <(grep -oP "from ['"]\K\.{1,2}/[^'"]*" "$FILEPATH")
[ $ERRORS -gt 0 ] && exit 1
echo "Anti-Mirage: OK"Anti-Mirage — единственная проверка, которую никогда нельзя пропускать. Она дешёвая (минуты) и ценная (спасает часы отладки).
> Пока нет комментариев