Почему Правила - Секретное Оружие
AI Код-Ревью

В diffray мы решили эту проблему с помощью структурированных правил. Давайте разберёмся, почему они являются ключом к эффективному AI код-ревью.

Проблема: Размывание Контекста Убивает Производительность ИИ

Когда вы загружаете весь PR в LLM с промптом типа «проверь этот код», происходит несколько проблем:

Решение: Структурированные Правила

Структурированное правило — это не просто промпт, а полная спецификация, которая говорит ИИ, что именно искать, где искать и как сообщать о результатах.

Вот как выглядит правило:

rules:
  - id: sec_sql_injection
    agent: security
    title: "SQL-инъекция через конкатенацию строк"
    description: "Пользовательский ввод, конкатенированный в SQL-запросы, позволяет злоумышленникам выполнять произвольный SQL"
    importance: 9

    match:
      file_glob:
        - "src/api/**/*.ts"
        - "src/routes/**/*.ts"
        - "!**/*.test.ts"
      content_regex:
        - "query.*\$\{|\+.*query"

    checklist:
      - "Найти все места, где пользовательский ввод используется в SQL-запросах"
      - "Проверить, используются ли параметризованные запросы или prepared statements"
      - "Убедиться, что конкатенация строк НЕ используется для построения запросов"

    examples:
      bad: |
        const query = `SELECT * FROM users WHERE id = ${userId}`;
        await db.execute(query);
      good: |
        const query = 'SELECT * FROM users WHERE id = ?';
        await db.execute(query, [userId]);

Эта структура обеспечивает три критические возможности, которые делают AI код-ревью по-настоящему работающим.

1. Детерминированные Результаты Благодаря Точному Таргетингу

Обратите внимание на секцию match? Это сопоставление паттернов, которое определяет когда правило срабатывает.

Без сопоставления паттернов проверка PR из 50 файлов означает анализ всех 50 файлов на каждую возможную проблему. С сопоставлением паттернов:

Если в PR есть 5 API-файлов с SQL-запросами, только эти 5 файлов отправляются на проверку SQL-инъекций. ИИ видит ровно то, что нужно оценить — ни больше, ни меньше.

Такая точность устраняет случайность, которая преследовала предыдущие попытки AI код-ревью. Один и тот же код + одни и те же правила = одни и те же результаты. Каждый раз.

2. Мультиагентная Архитектура: Правильный Эксперт для Каждой Задачи

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

Каждый агент имеет специализированный системный промпт с экспертизой в своей области. Агент безопасности знает OWASP Top 10. React-агент понимает правила хуков. Эта специализация кардинально улучшает качество обнаружения.

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

- id: react_useeffect_cleanup
  agent: react              # Обрабатывается специалистом по React
  match:
    file_glob: ["**/*.tsx"]
    content_regex: ["useEffect"]
  checklist:
    - "Проверить, возвращает ли useEffect функцию очистки"
    - "Убедиться, что event listeners и подписки очищаются"

Это правило отправляется только React-агенту, только для TSX-файлов, только когда присутствует useEffect. Агент получает сфокусированный контекст ровно на одну задачу — а не 50 разных задач, конкурирующих за внимание.

3. Курирование Контекста: Секрет Сохранения Внимания ИИ

Современные LLM могут обрабатывать 200k+ токенов. Но исследования показывают, что практическая производительность достигает предела около 25-30k токенов для сложных рассуждений. После этого порога вы платите за токены, которые модель не может эффективно использовать.

Система управления контекстом diffray гарантирует, что каждый агент получает именно ту информацию, которая ему нужна:

Каждый агент получает ровно то, что нужно для выполнения своей задачи. Не больше. Результат: сфокусированное внимание, лучшие результаты, меньше ложных срабатываний.

4. Гибкость: Правила для Проекта и Команды

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

Ваши внутренние библиотеки:

- id: use_internal_http_client
  agent: consistency
  title: "Использовать внутренний HTTP-клиент"
  match:
    file_glob: ["src/**/*.ts"]
    content_regex: ["\\bfetch\\(", "axios\\."]
  checklist:
    - "Найти прямые вызовы fetch() или axios"
    - "Проверить, должен ли код использовать httpClient из @/lib/http-client"
  examples:
    bad: |
      const response = await fetch('/api/users');
    good: |
      import { httpClient } from '@/lib/http-client';
      const data = await httpClient.get('/api/users');

Ваши доменно-специфичные паттерны:

- id: money_use_decimal
  agent: bugs
  title: "Использовать Decimal для денежных значений"
  match:
    content_regex: ["(price|amount|total)\\s*:\\s*(number|float)"]
  checklist:
    - "Найти денежные поля с типами float/number"
    - "Проверить, что хранение использует центы (integer) или тип Decimal"

Ваши требования соответствия:

- id: pii_logging_check
  agent: compliance
  title: "Никогда не логировать PII напрямую"
  tags: [compliance-gdpr, compliance-hipaa]
  match:
    content_regex: ["log.*(email|phone|ssn|password)"]

Положите их в .diffray/rules/, и они будут активны для следующего PR. Никаких изменений инфраструктуры, никаких обновлений инструментов — просто добавьте YAML, и ваш AI-ревьюер выучит ваши стандарты.

Почему YAML? Структура Обеспечивает Интеллект

Вы можете задаться вопросом, почему мы используем структурированный YAML вместо простых промптов. Структура обеспечивает возможности, которые произвольный текст дать не может:

Плоский промпт не может обеспечить такое разделение ответственности.

Результат: AI Код-Ревью, Которое Действительно Работает

Когда вы объединяете структурированные правила с мультиагентной архитектурой и интеллектуальным управлением контекстом, вы получаете:

Это то, что отличает «AI код-ревью» как демонстрацию от AI код-ревью как инфраструктуры, на которую ваша команда действительно может положиться.