Как правильно работать с AI агентами

Почему AI иногда генерирует откровенный мусор

Если вы уже пробовали писать код с AI-ассистентами, то почти наверняка прошли через классическую цепочку эмоций:

Сначала — вау-эффект 🤯
Потом — модель начинает писать странный код
Затем приходит понимание: «кажется, проблема не только в модели…»

И это не субъективное ощущение. Свежие данные исследований подтверждают проблему: по данным Carnegie Mellon, CodeRabbit и MIT, AI-код содержит в 1.7 раза больше дефектов, в 8 раз больше проблем с производительностью, а рост сложности кодовой базы на 41% — необратим. Но проблема не в самих моделях, а в процессе вокруг них.

Главная ошибка разработчиков — использовать AI как поиск или магический компилятор. На самом деле LLM — это вероятностная модель генерации текста. Она не компилирует код, не проверяет архитектуру и не понимает бизнес-логику проекта. Формально её работа выглядит так:

P(next_token | context)

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

Главная проблема: AI не знает ваш проект

Когда разработчик пишет:

Напиши сервис заказов

модель не знает:

архитектуру проекта
правила кодирования
бизнес-логику
ограничения
используемые паттерны

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

Ограничения контекстного окна LLM

Даже современные модели имеют ограничение на размер контекста — от 200k до 1M токенов. Звучит много, но реальный проект обычно содержит сотни файлов, десятки тысяч строк кода, документацию и архитектурные правила. LLM физически не может увидеть всю систему целиком. Поэтому без дополнительной структуры она начинает терять контекст.

Контекстная инженерия (Context Engineering)

Решение этой проблемы — контекстная инженерия. Это подход к работе с AI, при котором разработчик структурирует информацию, которую получает модель.

Качество ответа LLM напрямую зависит от качества контекста.

Output = LLM(Task + Context)

Если контекст плохой — получаем мусор. Если структурированный — получаем результат. Именно поэтому в современных AI-инструментах появляются: project memory, правила проекта, системные инструкции, файлы контекста.

Правильный pipeline разработки с AI

Ключевой insight видео: AI должен писать код только на одном этапе из четырёх, а не заменять весь процесс разработки. Структурированный pipeline выглядит так:

Research → Design → Plan → Implement

Research — исследование задачи, сбор требований, анализ существующего кода
Design — архитектура (DFD, Sequence-диаграммы), выбор паттернов
Plan — декомпозиция на фазы реализации, оценка рисков
Implement — непосредственная генерация кода

На каждом этапе AI участвует по-разному, и только на последнем пишет код. Это принципиально отличается от «вайбкодинга», где всё сводится к одному запросу.

Команда агентов: лид, кодер, ревьюер

Эффективная модель работы с AI-агентами — это команда специализированных агентов, а не один универсальный ассистент:

Лид-агент — управляет процессом, декомпозирует задачи, следит за архитектурой
Кодер-агент — непосредственно пишет код по чёткому заданию от лида
Ревьюер-агент — проверяет результат, ищет проблемы, предлагает улучшения

Такое разделение ролей резко снижает вероятность ошибок и дрейфа архитектуры.

Quality Gates

Между этапами pipeline необходимо ввести Quality Gates — явные критерии проверки перед переходом к следующему шагу. Например, перед этапом Implement должно быть подтверждено, что архитектура согласована, план декомпозирован на независимые фазы и каждая фаза имеет чёткий критерий готовности. Это предотвращает накопление технического долга и позволяет поймать проблему раньше, когда она дешевле всего исправить.

Почему «вайбкодинг» не работает

Популярная сегодня модель работы выглядит так:

Напиши сервис
Напиши API
Исправь ошибку

Это хаотичный процесс. В результате AI начинает переписывать код, нарушать архитектуру, дублировать логику и создавать лишние абстракции. Через несколько итераций проект превращается в хаос. Ещё важнее: копировать чужие промпты бесполезно — промпт работает только в контексте конкретного проекта, стека и архитектуры.

Итерационная разработка с LLM

Большая ошибка — просить модель написать сразу всю систему. Гораздо эффективнее разбивать работу на этапы.

Шаг 1 — анализ задачи

Explain architecture for order system

Шаг 2 — план реализации

Create implementation plan

Шаг 3 — генерация кода

Implement OrderService

Шаг 4 — ревью

Review this code and suggest improvements

Шаг 5 — тестирование

Write unit tests

Такой процесс намного стабильнее.

Как организовать контекст проекта для AI

Ключевой принцип: контекст проекта должен жить в репозитории, а не в голове разработчика. Ниже — несколько оптимальных вариантов организации.

Вариант 1: Минимальный (для небольших проектов)

Один файл в корне проекта, который читают большинство AI-инструментов автоматически:

CLAUDE.md  # или AGENTS.md, COPILOT.md — зависит от инструмента

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

Вариант 2: Стандартный (папка /ai или /.context)

project/
└── .context/
    ├── architecture.md   # общая архитектура, паттерны
    ├── tech-stack.md     # стек, версии, зависимости
    ├── coding-rules.md   # соглашения по коду
    ├── constraints.md    # ограничения и запреты
    └── examples.md       # примеры правильного кода

Файлы подключаются вручную или через настройки инструмента (Cursor Rules, Claude Project Knowledge).

Вариант 3: Полный (для крупных проектов / команд)

project/
├── src/
├── tests/
├── docs/
└── ai/
    ├── architecture.md    # C4-модель или DFD
    ├── design/
    │   ├── sequence/      # sequence-диаграммы ключевых флоу
    │   └── decisions/     # ADR (Architecture Decision Records)
    ├── coding-rules.md    # линтер-правила в читаемом виде
    ├── constraints.md     # что нельзя менять и почему
    ├── patterns.md        # используемые паттерны с примерами
    └── phases/            # декомпозиция на фазы реализации
        ├── phase-1.md
        └── phase-2.md

Вариант 4: Через нативные механизмы инструментов

Современные AI-инструменты имеют встроенные механизмы контекста:

Cursor — файл .cursorrules или папка .cursor/rules/
Claude Code — файл CLAUDE.md в корне проекта (читается автоматически)
GitHub Copilot — файл .github/copilot-instructions.md
Windsurf — файл .windsurfrules

Это самый «нативный» способ: инструмент подхватывает контекст без дополнительных действий.

По сути все эти варианты — это Single Source of Truth для AI: один источник правды о вашем проекте, который делает генерацию кода предсказуемой.

Практический пример запроса (Laravel)

Плохой запрос:

Напиши сервис заказов

Хороший запрос:

Project: Laravel API
Architecture:
  - Controller → Service → Repository
  - DTO for input
  - Eloquent only in repository

Rules:
  - Services contain business logic
  - Controllers must stay thin
  - Use dependency injection

Task: Implement OrderService with methods:
  createOrder()
  cancelOrder()
  calculateTotal()

Разница в качестве ответа будет огромной.

Главный вывод

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

AI ≠ разработчик
AI = ускоритель мышления программиста

Поэтому правильный подход — не вайбкодинг, а AI-assisted engineering: структурированный pipeline, команда агентов, качественный контекст и Quality Gates между этапами. Именно этот подход постепенно становится стандартом современной разработки.

Статья по мотивам видео «Почему AI генерит мусор — и как заставить его писать нормальный код» (Дмитрий Березницкий, YouTube).