Как оптимизировать код для AI-агентов: трёхуровневая документация вместо бесполезных grep-запросов

Ваш AI-агент тупит не потому что глупый, а потому что вы его кормите мусором

Вы загружаете в GPT-5 или Claude 4 всю кодовую базу. Надеетесь, что он найдет нужную функцию. Он возвращает вам код из середины проекта, который давно устарел. Вы ругаете модель. Проблема не в модели. Проблема в том, как вы подаете информацию.

За последний год я видел десятки команд, которые сжигают тысячи долларов на API-вызовы, получая при этом хрупкий, неконсистентный код. Все потому, что они пытаются заставить LLM работать как grep.

Почему grep-запросы не работают в 2026 году

Потому что современные LLM (я говорю про GPT-5, Claude 4.5 Sonnet, Gemini 2.0 Ultra, Llama 4 405B) страдают от "Lost in the Middle" эффекта. Исследования 2025 года подтвердили: информация в начале и конце контекста запоминается хорошо, а в середине – теряется.

Ваш AI-агент – не база данных. Это не поисковик, который выдает точные совпадения. Это собеседник с ограниченной оперативной памятью. И если вы даете ему 100 страниц текста, он запомнит только введение и заключение.

Трёхуровневая документация: как кормить агентов правильно

Вместо того чтобы скармливать сырые исходники, нужно готовить специальное "питание" – иерархическую документацию. Три уровня, каждый решает свою задачу.

1 Уровень 1: Архитектурная карта (500 токенов максимум)

Это как оглавление книги. Одна страница Markdown, которая объясняет: какие модули есть в проекте, как они связаны, кто за что отвечает.

# Архитектура проекта PaymentService

## Основные компоненты

1. **API Gateway** (папка `gateway/`)
   - Входная точка всех запросов
   - Валидация JWT-токенов
   - Маршрутизация к сервисам

2. **Payment Processor** (папка `processor/`)
   - Обработка платежей через Stripe и PayPal
   - Асинхронные задачи через Celery
   - Хранение транзакций в PostgreSQL

3. **Notification Service** (папка `notifications/`)
   - Отправка email и push-уведомлений
   - Шаблонизация через Jinja2
   - Очередь сообщений в RabbitMQ

## Важные детали
- Все сервисы общаются через gRPC, кроме Gateway (REST)
- Конфиги хранятся в HashiCorp Vault
- Логи пишутся в структурированном JSON в ELK

Этот файл всегда идет ПЕРВЫМ в контекст. AI-агент видит его первым, запоминает структуру. Теперь он понимает, где что искать.

2 Уровень 2: Спецификации модулей (1000-1500 токенов)

Для каждого крупного модуля создаем отдельный документ. Не код, а описание: какие функции выполняет, какие интерфейсы предоставляет, какие зависимости имеет.

# Модуль: Payment Processor

## Назначение
Обрабатывает платежи, создает транзакции, обновляет балансы пользователей.

## Ключевые функции

### `process_payment(user_id, amount, currency, provider)`
- Проверяет лимиты пользователя
- Вызывает API Stripe/PayPal
- Создает запись в таблице `transactions`
- Запускает Celery-задачу для нотификаций

### `get_transaction_history(user_id, limit=50)`
- Возвращает последние транзакции
- Поддерживает пагинацию через курсоры
- Кэширует результат на 5 минут в Redis

## Зависимости
- PostgreSQL (таблицы `transactions`, `user_balances`)
- Redis для кэша и Celery broker
- Stripe API v2 (2026)
- Внутренний сервис `user-service` по gRPC

3 Уровень 3: Критичные участки кода с пояснениями

Только теперь даем сам код. Но не весь, а ключевые функции с инлайн-комментариями, написанными специально для LLM.

# payment_processor/core.py

def process_payment(user_id: str, amount: float, 
                    currency: str = "USD",
                    provider: str = "stripe") -> PaymentResult:
    """
    ОСНОВНАЯ ФУНКЦИЯ ОБРАБОТКИ ПЛАТЕЖА
    
    Последовательность действий:
    1. Проверяем, не превышены ли суточные лимиты пользователя
    2. Резервируем сумму в бухгалтерском журнале
    3. Вызываем внешний API платежной системы
    4. Если успешно - фиксируем транзакцию, иначе откатываем
    
    ВАЖНО: эта функция должна быть идемпотентной.
    При повторном вызове с тем же payment_id возвращает существующий результат.
    """
    
    # 1. Проверка лимитов (вызывается внутренний метод)
    if not _check_user_limits(user_id, amount):
        raise LimitExceededError(f"User {user_id} exceeded daily limit")
    
    # 2. Резервирование средств в журнале
    # Используем SELECT FOR UPDATE для избежания race condition
    with db.transaction():
        journal_entry = create_journal_entry(user_id, amount, "reserve")
        
        # 3. Вызов Stripe API (актуальная версия 2026)
        # Документация: https://stripe.com/docs/api/2026-03-11
        stripe_charge = stripe.Charge.create(
            amount=int(amount * 100),  # центы
            currency=currency,
            customer=user.stripe_id,
            idempotency_key=payment_id  # ключ для идемпотентности
        )
        
        # 4. Фиксация результата
        if stripe_charge.status == "succeeded":
            _commit_transaction(journal_entry, stripe_charge.id)
            return PaymentResult.success(charge_id=stripe_charge.id)
        else:
            _rollback_journal_entry(journal_entry)
            return PaymentResult.failed(reason=stripe_charge.failure_message)

Обратите внимание на комментарии. Они не для людей, а для AI-агента. Объясняют не "что делает эта строка", а "какую роль играет этот блок в бизнес-логике".

Как внедрить трёхуровневую документацию за неделю

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

Шаг 1: Создайте архитектурную карту силами AI

Возьмите Llama 4 70B (она бесплатная для самоделок) или GPT-5 через API. Дайте ей все ваши README, основной __init__.py файлы, и попросите создать карту.

# Используем Claude 4.5 для анализа структуры
cat docs/*.md src/main.py | \
  claude-api --model claude-4.5-sonnet \
  --prompt "Создай архитектурную карту проекта. Перечисли модули и их связи." \
  > docs/architecture_map.md

Шаг 2: Напишите спецификации для критичных модулей

Возьмите 3-4 самых важных модуля. Для каждого создайте файл module_spec.md. Формат: что делает, основные функции, зависимости, ограничения.

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

Шаг 3: Добавьте AI-ориентированные комментарии в ключевые функции

Прогоните самые сложные функции через инструмент вроде Cursor или GitHub Copilot с промптом: "Добавь комментарии, объясняющие бизнес-логику этой функции для другого AI-агента".

Что изменится после внедрения

• AI-агенты будут делать в 2-3 раза меньше ошибок в архитектурных решениях
• Сократится количество токенов в контексте (не нужно грузить весь код)
• Новые разработчики смогут быстрее вникать в проект
• Ваш собственный RAG (если он есть) станет точнее, как в DeepResearch от Яндекса

Типичные ошибки (как не надо делать)

Ответы на вопросы, которые вы боялись задать

Это не слишком много работы?

Да, первые 20-30 часов придется потратить. Но потом вы экономите сотни часов на исправлении багов, которые наделал AI-агент из-за непонимания контекста. Плюс, ваша команда начинает работать быстрее.

А если у нас микросервисы? Там же десятки репозиториев

Создайте отдельный репозиторий company-architecture. В нем храните карту всех сервисов, их взаимодействия, SLA, контракты. Каждый сервис по-прежнему имеет свою трёхуровневую документацию внутри, но глобальная карта – в одном месте.

Какие инструменты использовать в 2026 году?

• Для анализа кода: SonarQube с AI-плагинами, Semgrep с кастомными правилами
• Для генерации документации: Mintlify, Docusaurus с AI-ассистентом
• Для поддержания актуальности: собственные скрипты на Python, которые сравнивают сигнатуры функций и документацию
• Для работы с AI: автономные агенты, обученные на вашей кодовой базе

Финал. Что будет через год

Компании, которые уже внедрили AI-ориентированную документацию (по данным Q4 2025), сократили время onboarding новых разработчиков с 3 месяцев до 3 недель. Количество инцидентов, вызванных непониманием кодовой базы, упало на 40%. AI-агенты стали генерировать более стабильный код – как в статье про технический долг.

Но главное – вы перестаете бороться с инструментами. Вместо того чтобы ругать GPT-5 за глупые ответы, вы даете ему информацию в том формате, в котором он может ее переварить. Это как кормить ребенка: не дадите целый стейк, а порежете на мелкие кусочки – он съест и скажет спасибо.

Начните с одного модуля. Просто возьмите самый проблемный, создайте для него три документа. И посмотрите, как изменится качество ответов вашего AI-ассистента. Это работает. Проверено на продакшене.

Подписаться на канал