Урок 4: 10 антипаттернов при работе с AI-агентами

Введение

Даже опытные разработчики допускают ошибки при работе с AI-кодом. Эти 10 антипаттернов уничтожают качество, создают tech debt и расстраивают команду. Обучение на чужих ошибках быстрее.

Антипаттерн 1: YOLO-промпт

Описание

Вы просто просите агента «написать всё» без контекста, требований, ограничений.

# [-] ПЛОХО
claude "напиши функцию для обработки данных"

# Результат:
# - Какие данные?
# - Какой формат?
# - Что делать с ошибками?
# - Где хранить логи?
# → Агент угадывает, выходит мусор

Пример: Реальная ошибка

# Неправильный запрос
claude "напиши парсер CSV"

# Что агент сгенерировал:
def parse_csv(file):
    import csv
    with open(file) as f:
        reader = csv.reader(f)
        return list(reader)  # Вот и всё. Где обработка ошибок?

Как исправить

# [+] ХОРОШО
claude """
Напиши функцию parse_csv_safe(file_path: str, encoding='utf-8') -> list[dict]:

Требования:
1. Читать CSV файл с заголовками
2. Вернуть список словарей (каждая строка = словарь)
3. Обработать ошибки:
   - Файл не существует → raise FileNotFoundError
   - Пустой файл → return []
   - Повреждённая кодировка → пробовать latin1
4. Логировать каждое прочитанное число строк

Пример использования:
data = parse_csv_safe('users.csv')
# [{'id': '1', 'name': 'Alice'}, {'id': '2', 'name': 'Bob'}]

Тесты будут в test_parser.py
"""

graph TB
    A["[-] Расплывчатый запрос<br/>Агент гадает"] -->|неопределённый результат| B["[!] Нужно переписывать"]
    C["[+] Подробный запрос<br/>Примеры, ошибки, API"] -->|целевой результат| D["[+] Заходит в код"]

Антипаттерн 2: Нет AGENTS.md

Описание

Агент не знает контекст проекта: архитектуру, зависимости, соглашения, историю.

# [-] ПЛОХО
claude "добавь endpoint для юзеров"

# Агент не знает:
# - Является ли это REST или GraphQL?
# - Какая используется БД? (PostgreSQL? MongoDB?)
# - Какой фреймворк? (FastAPI? Django? Express?)
# - Где хранятся модели?
# - Какие соглашения по именованию?

Как исправить

Создайте файл AGENTS.md:

# AGENTS.md - Краткая справка для AI-агентов

## Архитектура

### Tech Stack
- Backend: Python 3.11 + FastAPI
- DB: PostgreSQL 14
- Cache: Redis
- Frontend: React 18 + TypeScript
- DevOps: Docker, Kubernetes

### Структура проекта

backend/ ├── app/ │ ├── models/ # SQLAlchemy models │ ├── routes/ # API endpoints │ ├── services/ # Business logic │ └── schemas/ # Pydantic schemas ├── tests/ └── migrations/ # Alembic

frontend/ ├── src/ │ ├── components/ │ ├── hooks/ │ └── api/ # Axios clients └── tests/

## Соглашения кодирования

### Python
- Стиль: Black (line length 88)
- Тип: mypy strict
- Тесты: pytest
- Пример:
  ```python
  def get_user_by_id(user_id: int) -> User:
      """Получить пользователя по ID."""
      return db.query(User).filter(User.id == user_id).first()

JavaScript/TypeScript

• Стиль: ESLint + Prettier
• Компиляция: TypeScript strict
• Тесты: Vitest
• Пример:

  export async function getUserById(userId: number): Promise<User> {
    const response = await axios.get(`/api/users/${userId}`);
    return response.data;
  }

API соглашения

Endpoints

• Format: /api/v1/{resource}/{action}
• Методы: GET (list, detail), POST (create), PUT (update), DELETE (delete)
• Errors:
  • 400 Bad Request (validation)
  • 404 Not Found
  • 500 Internal Server Error
• Пример:

  GET    /api/v1/users         (список)
  POST   /api/v1/users         (создание)
  GET    /api/v1/users/{id}    (деталь)
  PUT    /api/v1/users/{id}    (обновление)
  DELETE /api/v1/users/{id}    (удаление)

Schemas (Pydantic)

from pydantic import BaseModel

class UserCreate(BaseModel):
    email: str
    name: str

class UserResponse(BaseModel):
    id: int
    email: str
    name: str
    created_at: datetime

    class Config:
        from_attributes = True  # SQLAlchemy compatibility

Бизнес-правила

• Пользователи удаляются логически (is_deleted флаг)
• Все даты в UTC
• Email должны быть lowercase

Инструменты и команды

• Запуск тестов: pytest
• Запуск linter: black . && mypy .
• Dev сервер: uvicorn app.main:app --reload
• DB migration: alembic upgrade head

Контакты

• Tech Lead: @alice (Slack)
• DevOps: @bob (Slack)
• Questions? спрашивайте в #development

### Использование в промпте

```python
# [+] ХОРОШО
claude """
Прочитай AGENTS.md для контекста.

Добавь endpoint для создания нового юзера:
- POST /api/v1/users
- Используй UserCreate schema
- Сохрани в PostgreSQL
- Вернёшь UserResponse
- Добавь тесты в tests/test_users.py
"""

Антипаттерн 3: Слишком большие задачи

Описание

Вы просите агента написать весь backend / весь frontend за раз. Результат: потеря контекста, низкое качество.

# [-] ПЛОХО
claude """
Напиши весь REST API для e-commerce:
- 20 endpoints
- 10 моделей
- Authentication
- Permissions
- Caching
- Logging

Сроки: сегодня вечером
"""

# Результат: контекст переполняется, качество падает на 70%

Как исправить: разбить на микротаски

# [+] ХОРОШО (День 1, утро)
claude """
Напиши модели:
- User (id, email, password_hash, created_at)
- Product (id, name, price, stock)
- Order (id, user_id, product_id, quantity, created_at)

С relationships, constraints, индексы.
Файл: backend/app/models.py
"""

# [+] ХОРОШО (День 1, день)
claude """
Напиши authentication endpoints:
- POST /auth/register
- POST /auth/login (return JWT)
- POST /auth/logout
- GET /auth/me (protected)

Используй модель User из models.py
"""

# [+] ХОРОШО (День 1, вечер)
claude """
Напиши endpoints для Products:
- GET /api/products (с paging)
- GET /api/products/{id}
- POST /api/products (admin only)
- PUT /api/products/{id} (admin only)

Используй auth middleware из authentication
"""

# Результат: каждая задача в одну сессию, качество 90%

graph TB
    A["[-] Одна большая задача<br/>Контекст: 5000 токенов"] -->|потеря контекста| B["[!] Качество падает"]
    C["[+] 3 маленькие задачи<br/>Контекст: 1500 токенов каждая"] -->|чистый контекст| D["[+] Качество 90%+"]

Антипаттерн 4: Blind Trust

Описание

Вы запустили код агента без проверки: нет тестирования, нет code review, прямо в продакшн.

# [-] ПЛОХО
claude "напиши SQL миграцию для удаления таблицы"

# Результат: агент генерирует код
# Вы запускаете DROP TABLE users; БЕЗ ПРОВЕРКИ
# → Потеря данных, 4 часа восстановления

Как исправить

# [+] ХОРОШО

# 1. Агент пишет код
claude "напиши SQL миграцию для удаления таблицы users"

# 2. Вы review-ите:
# - Нет DROP TABLE? [+]
# - Есть backup? [+]
# - Есть rollback? [+]

# 3. Вы запускаете на staging первым
pytest --no-header -v

# 4. Вы смотрите логи, проверяете data
# 5. Только потом в продакшн

# 6. Вы готовы к rollback
git checkout HEAD~1

Чек-лист перед merge

• Пройдены все unit-тесты
• Пройдены интеграционные тесты
• Нет SQL injection уязвимостей
• Нет утечек памяти (если критичный код)
• Нет hardcoded credentials
• Code review: человек прочитал весь код
• Staging тесты пройдены
• Есть rollback план

Антипаттерн 5: Copy-Paste без понимания

Описание

Агент пишет код, вы копируете его в проект БЕЗ ПОНИМАНИЯ. Через неделю возникает баг, вы не знаете что исправлять.

# [-] ПЛОХО
claude "напиши кэширование для getUserData"

# Агент пишет:
@lru_cache(maxsize=128)
def get_user_data(user_id):
    ...

# Вы скопировали, слово в слово
# Баг: кэш не инвалидируется при обновлении юзера
# Вы не понимаете, почему это произошло

Как исправить

# [+] ХОРОШО

# 1. Агент пишет код с комментариями
claude """
Напиши get_user_data с кэшированием.
Обязательно добавь комментарии, объясняющие:
- Почему именно эта стратегия кэша?
- Что такое maxsize=128?
- Какой срок жизни кэша?
- Как инвалидируется кэш?
"""

# 2. Результат с комментариями:
"""
# Используем LRU (Least Recently Used) кэш
# maxsize=128 - для типичной app где 100-200 активных юзеров
# TTL: нет встроенного TTL в lru_cache, используем redis для критичного кода
# Инвалидация: при update_user нужно вызвать get_user_data.cache_clear()
"""

# 3. Вы понимаете, ЗАЧЕМ это сделано
# 4. Вы можете поддерживать и менять код
# 5. Через 6 месяцев вы сами знаете, почему это работает

Антипаттерн 6: Игнорирование тестов

Описание

Агент пишет код без тестов. «Я проверил вручную, работает!»

# [-] ПЛОХО
claude "напиши функцию для валидации email"

# Результат: функция есть, но нет тестов
# Через 2 недели коллега меняет функцию
# 5 edge case'ов сломались, вы не узнали

Как исправить

# [+] ХОРОШО

# 1. Пишите тесты ПЕРЕД кодом (TDD)
claude """
Напиши функцию validate_email(email: str) -> bool

Требования:
- Тесты в test_email_validator.py (pytest)
- Минимум 8 тестов:
  - Валидный email
  - Email без @
  - Email без домена
  - Disposable domains
  - SQL injection попытка (если применимо)
  - И т.д.

Функция должна пройти ВСЕ тесты
"""

# 2. Вы запускаете
pytest test_email_validator.py -v

# 3. Все тесты зелёные = гарантия качества
# 4. Через 6 месяцев, если коллега сломает — тесты упадут

Антипаттерн 7: Контекстное загрязнение

Описание

Вы работаете в одной сессии Claude слишком долго (3+ часа). Контекст переполняется старой информацией, агент начинает ошибаться.

# [-] ПЛОХО
claude "сессия начала в 9:00"

# 09:00 - напиши User model (агент: ясный контекст, качество 95%)
# 10:00 - напиши Product model (качество 90%)
# 11:00 - напиши Order model (качество 85%)
# 12:00 - напиши API endpoints (качество 70%)
# 13:00 - напиши auth (качество 50%)

# Контекст переполнен, старая информация смешана с новой
# Агент забыл, что такое User, начал переписывать его

Как исправить

# [+] ХОРОШО

# Сессия 1 (09:00-10:00): Models
claude "напиши User, Product, Order models"

# Сессия 2 (10:00-11:00): Auth endpoints
# Новая сессия = чистый контекст
# Агент смотрит models.py, начинает с чистого листа

# Сессия 3 (11:00-12:00): API endpoints
# Ещё новая сессия = контекст не загрязнен

# Результат: качество 90%+ во всех сессиях

graph TB
    A["Сессия 1<br/>Контекст: модели<br/>Качество: 95%"] --> B["Сессия 2<br/>Контекст: auth<br/>Качество: 90%"]
    B --> C["Сессия 3<br/>Контекст: API<br/>Качество: 90%"]

    X["[-] Одна долгая сессия<br/>Контекст: всё подряд<br/>Качество: 50%"]

Антипаттерн 8: Микроменеджмент

Описание

Вы проверяете каждую строку кода, задаёте агенту 50 вопросов, теряется смысл автоматизации.

# [-] ПЛОХО
claude "напиши функцию"
# Агент пишет функцию

# Вы:
# "Почему ты использовал if вместо switch?"
# "Почему тут list вместо tuple?"
# "Почему 128 а не 256?"
# "Почему defaultdict а не обычный dict?"

# Результат: 50 итераций, потеря времени

Как исправить

# [+] ХОРОШО

# Даёте критерии успеха
claude """
Напиши функцию parse_config(file) с критериями:
- Читает JSON конфиги
- Валидирует против schema
- Обрабатывает ошибки
- Быстрая (под 10ms)
- Покрыта тестами

Как реализовать — твой выбор.
"""

# Агент выбирает лучший подход
# Вы проверяете результат: работает [+], быстро [+], протестировано [+]
# 2 итерации вместо 50

Антипаттерн 9: Один инструмент для всего

Описание

Вы используете Claude для ВСЕХ задач: код, docs, архитектуру, даже DevOps скрипты. Неправильный инструмент = плохой результат.

# [-] ПЛОХО
# Используем Claude для Kubernetes manifests
claude "напиши k8s deployment.yaml для production"

# Результат: базовый YAML, не оптимизирован для scale
# Лучше был бы Copilot (интегрирован в IDE) или даже человек

Как исправить: Выбирайте инструмент по задаче

Антипаттерн 10: Отсутствие итераций

Описание

Вы даёте один промпт и ожидаете идеального результата. Реальность: нужно 3-5 итераций.

# [-] ПЛОХО
claude "напиши функцию сортировки"

# Агент пишет bubble sort (медленный)
# Вы ожидали quick sort

# Вы: "Не то"
# Взаимное разочарование

Как исправить: Iterative development

# [+] ХОРОШО

# Итерация 1: базовая функциональность
claude "напиши функцию сортировки для 100 элементов"
# Результат: bubble sort

# Итерация 2: оптимизация
claude "сортировка работает, но медленная. Оптимизируй до O(n log n)"
# Результат: quick sort

# Итерация 3: edge cases
claude "добавь обработку пустого списка, None значений, дублей"
# Результат: готов к production

# Итерация 4: тесты
claude "добавь 10 тестов для edge cases"
# Результат: защита от регрессии

Чек-лист: Зрелая работа с AI-агентом

Перед началом

• Написан файл AGENTS.md с контекстом проекта
• Подготовлены примеры существующего кода (для стиля)
• Определены критерии успеха (качество, скорость, тесты)

Во время работы

• Задача разбита на микротаски (максимум 500 LOC за раз)
• Написаны тесты ДО кода (TDD)
• Используется новая сессия Claude для каждой крупной задачи
• Code review перед использованием в production
• Результат понятен (комментарии, документация)

После кода

• Все тесты проходят (unit, integration, staging)
• Code review: человек одобрил
• Нет hardcoded values, credentials
• Документация обновлена
• Есть rollback план

На следующем спринте

• Собрана метрика: сколько багов в коде от AI?
• Собрана обратная связь: что улучшить в промптах?
• Обновлена AGENTS.md с новыми learnings

Таблица: Было vs Стало

Попробуйте сами: Исправить плохой код

Задача: Вот 5 антипаттернов в одном промпте. Переделайте:

# [-] ПЛОХО (Все 5 антипаттернов вместе)

claude "напиши весь backend для социальной сети (100 endpoints):
- Юзеры, посты, комментарии, лайки, подписки, уведомления
- Нужны все feature сразу
- Сроки: сегодня вечером
- Я потом всё обновлю как нужно"

Задача: Переделайте правильно:

1. Создайте AGENTS.md
2. Разбейте на 5 микротаск (не более 200 LOC каждая)
3. Напишите TDD (тесты первыми)
4. Каждую задачу в новой сессии
5. Code review перед merge

Результат: Код, который 6 месяцев спустя вы сможете поддерживать (вместо “зачем это здесь?”)

Ключевые выводы

1. YOLO-кодирование убивает качество: дайте агенту контекст и примеры
2. AGENTS.md — инвестиция в качество: один раз написал, экономит часы
3. Разбивайте задачи: маленькие = лучший контекст = лучше код
4. Code review обязателен: слепое доверие = баги в production
5. Итерации нормальны: ожидайте 3-5 раундов уточнения
6. Одна сессия = 1-2 часа: потом новая для свежести контекста
7. Выбирайте инструмент: не все задачи для Claude
8. Тесты спасают: TDD с AI — лучшая комбинация
9. Микроменеджмент вредит: дайте агенту свободу в реализации
10. Понимание > copy-paste: убедитесь, что вы знаете, что пишет агент

Следующие шаги

Вы прошли модуль 2.9 полностью! Теперь вы знаете:

[+] TDD с агентом — как писать тесты для агента [+] Code Review — как использовать AI для pre-review [+] Мультиагенты — когда и как использовать несколько агентов [+] Антипаттерны — 10 ошибок, которых нужно избегать

Рекомендуемые следующие шаги:

• Модуль 2.10: Финальный проект — применить все навыки на практике
• Практика: Создайте AGENTS.md для вашего реального проекта
• Углубление: Изучите официальную документацию Claude Code по subagents

Домашнее задание

1. Создайте AGENTS.md для своего проекта
2. Переделайте один старый prompt в соответствии с best practices
3. Напишите 5 unit-тестов для следующей функции (перед кодом)
4. Дайте агенту эти тесты, попросите реализацию
5. Запустите, проверьте, дайте feedback

Результат: Код лучшего качества за МЕНЬШЕ времени.

Ресурсы

• Официальная документация Claude Code: https://code.claude.com/docs
• Best practices для prompt engineering: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering
• TDD цикл: https://en.wikipedia.org/wiki/Test-driven_development
• Git workflows: https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows