Как построить эффективный харнесс для кодящего AI-агента: реальный опыт на продакшене

Проблема: агент без обвязки - это как программист без рук

Три месяца назад я запустил в продакшен кодящего AI-агента. Наивно думал: дам ему доступ к репе, пропишу пару правил в промпте - и он будет сам фиксить баги, писать тесты, рефакторить. Спойлер: получил не that. Агент переписывал весь код, удалял нужные файлы, вызывал API по 500 раз за задачу, а потом отвечал: "Я сделал всё, проверяй" - и в рантайме всё падало.

Оказалось, что сам LLM - это только ядро. Если не обернуть его в жесткий харнесс (обвязку), получите дорогой генератор шума. В этой статье - мой опыт, кровью и токенами заработанный. Без воды, только схемы, код и грабли.

Что такое харнесс и почему без него - караул

Харнесс - это прослойка между LLM и средой. Она включает:

• Правила (Rules) - явные границы: что можно, что нельзя, как писать код, куда коммитить.
• Память - краткосрочная (история диалога) и долгосрочная (что агент уже узнал о проекте).
• Инструменты - MCP-серверы, которые ограничивают доступ к API, БД, файлам.
• Карта проекта - структура кода, зависимости, конфиги, чтобы агент не блуждал.
• Мониторинг и троттлинг - считаем токены, лимитируем вызовы, ретраим ошибки.

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

Архитектура, которая выжила в продакшене

После трёх месяцев итераций родилась схема:

# harness_config.yaml
core_model: claude-4-sonnet-20260609
memory:
  short_term: sliding_window (last 20 turns)
  long_term: sqlite + embeddings (chromadb)
rules:
  path: .ai/rules/*.md
  strict: true
tools:
  mcp_servers:
    - filesystem (read + appends only)
    - git (only branch: feature/*)
    - pytest (only tests/)
monitoring:
  log_level: debug
  cost_limit: 0.05 USD per task

Ключевое - разделение ответственности. Правила не в промпте, а в отдельных файлах, которые загружаются при старте сессии. Память не в контексте, а в SQLite + эмбеддинги. Инструменты - не прямой доступ, а через MCP с белыми списками.

Шаг 1: Правила - заповеди, а не пожелания

Первая версия правил была в промпте: "Ты - опытный Python-разработчик, следуй PEP8". Агент игнорировал. Пришлось делать жестко.

Формат: *.rules.md в папке .ai/. Пример:

# Rule: Formatting
- All Python files must pass `black --check` before commit
- Type hints required for all public functions
- Docstrings in Google style

# Rule: Scope
- You may modify files only in `src/` and `tests/`
- Changes to `config/`, `deploy/` require human approval
- NEVER delete files without confirmation

Агент загружает эти правила при старте и перечитывает каждые 10 шагов. Да, это съедает контекст, но дешевле, чем потерять production-базу.

Шаг 2: Память - чтобы не переспрашивать одно и то же

Агент забывает архитектуру после каждого перезапуска. Решение - долгосрочная память. Я использовал SQLite + ChromaDB. Каждый значимый факт ("Модуль auth использует JWT", "База данных PostgreSQL с пулом на 50 коннектов") сохраняется в векторную БД. При старте агент получает топ-5 релевантных фактов.

# memory_manager.py
import chromadb
import sqlite3

class LongTermMemory:
    def __init__(self, db_path="memory.db"):
        self.client = chromadb.PersistentClient(path="vectors/")
        self.collection = self.client.get_or_create_collection("project_facts")
        self.sql = sqlite3.connect(db_path)
        self._init_tables()

    def remember(self, fact: str, metadata: dict):
        embedding = self._embed(fact)
        self.collection.add(
            documents=[fact],
            metadatas=[metadata],
            ids=[hash(fact)]
        )
        self.sql.execute("INSERT INTO facts (text) VALUES (?)", (fact,))

    def recall(self, query: str, top_k=5):
        results = self.collection.query(query_texts=[query], n_results=top_k)
        return results['documents'][0]

Важно: память не должна захламляться. Я ограничил максимум 100 фактов на проект, самые старые удаляются. И агент сам решает, что запомнить - иначе он пишет всё подряд.

Шаг 3: Инструменты - через MCP с белыми списками

Прямой доступ к shell или файловой системе - зло. Только через MCP-сервера. Я настроил три сервера:

Такая конфигурация удешевила ошибки в 20 раз. Агент больше не может случайно затереть конфиг или запушить в мастер.

Шаг 4: Мониторинг и троттлинг - чтобы не обанкротиться

Средний вызов Claude 4 Sonnet стоит около $0.015. За час работы агент может сделать 300 вызовов - это $4.5. В месяц $100-150. Но если агент зациклится (а он зацикливается) - может накрутить $50 за час.

Решение: лимит на стоимость задачи и детектор циклов. Если агент повторяет одно и то же действие (например, читает файл снова и снова) - прерываем и просим переформулировать.

class BudgetTracker:
    def __init__(self, max_cost: float = 0.05):
        self.cost = 0.0
        self.max_cost = max_cost

    def charge(self, amount: float):
        self.cost += amount
        if self.cost > self.max_cost:
            raise BudgetExceeded(f"Cost {self.cost:.3f} > {self.max_cost:.3f}")

Что НЕ работает - мой чёрный список

1. Длинные промпты с архитектурой проекта. Агент читает 10 страниц документации, забывает первые пять. Лучше давать ссылки на файлы и учить его читать нужные.
2. Слишком мягкие правила. "Старайся не удалять файлы" - агент удалит. "Удаление только после подтверждения" - работает.
3. Отсутствие контекстного окна. Историю нужно сжимать. Использовал алгоритм summa: после каждых 20 шагов агент пишет краткое резюме, которое заменяет старые сообщения.
4. Доверие к ответам. Агент уверенно говорит "Я обновил конфиг", а на самом деле - нет. Обязательно проверять через diff.

Особый случай - галлюцинации файловой системы. Агент придумывает пути к файлам, которых нет. Решил тем, что все операции с файлами идут через MCP-сервер, который возвращает ошибку "File not found" - и агент учится проверять существование.

Сравнение инструментов для харнесса (2026)

Я пробовал три основных:

• Claude Code (Anthropic) - лучший для Python/TS. Встроенный MCP, правила в .clinerules. Но только для Claude, не поддерживает другие модели.
• Cursor (v0.50+) - отличный UI, поддержка кастомных правил, но меньше контроля над MCP. Подходит для веб-разработки.
• Copilot Workspace (GitHub) - хорош для простых задач, но слабая память и дорогие вызовы. Для продакшена - нет.

Я остановился на Claude Code + самописном харнессе на Python. Он даёт полный контроль и лёгкую кастомизацию.

Пошаговый план внедрения харнесса в ваш проект

1 Аудит: что делает агент сейчас

Пробегитесь по логам. Сколько вызовов, какие токены, сколько ошибок. Определите самые частые проблемы: потеря контекста? высокая стоимость? неверные действия?

2 Настройте MCP-сервера

Закройте прямой доступ к shell и файловой системе. Опубликуйте свои MCP-сервера или используйте готовые (filesystem, git, docker). Поставьте белые списки.

3 Создайте файл правил

В папке .ai/ создайте rules.md. Пропишите минимум 5 конкретных правил. Например: "Все коммиты должны содержать issue-номер в заголовке".

4 Внедрите долгосрочную память

Поставьте ChromaDB или FAISS. Настройте сохранение фактов. Протестируйте: спросите агента через день, помнит ли он архитектуру.

5 Добавьте мониторинг

Считайте стоимость, количество шагов, ошибки. Поставьте алерты, если стоимость задачи превышает лимит. Используйте LangFuse или OpenTelemetry.

6 Запустите пилот

Выберите одну задачу (например, написание тестов) и дайте агенту поработать в ограниченном окружении. Проверяйте каждый результат.

Типичные ошибки и как их избежать

Если вы чувствуете, что вам не хватает системных знаний - рекомендую курс AI-креатор: создаём контент с помощью нейросетей от Skillbox. Там есть модули по практической разработке AI-агентов. Но помните: ни один курс не заменит собственных граблей.

FAQ по харнессу для кодящих агентов

Завершу неочевидным советом: не пытайтесь сделать агента полностью автономным. Лучшая стратегия - human-in-the-loop для всех критических действий. Агент пишет код, человек ревьюит. Агент предлагает рефакторинг, человек утверждает. Это в 10 раз снижает риски и делает работу с агентами комфортной. Помните: агент - это инструмент, а не замена инженеру. Как писалось в статье AI-агенты как сотрудники, управляйте ими как стажёрами: давайте четкие задачи, проверяйте результат, не оставляйте без присмотра.

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