affaan-m/ECC: Agent Harness Performance Optimization

Agent harness оптимизирует Claude Code, Codex, Opencode, Cursor — навыки, инстинкты, память, безопасность, исследовательский подход.

Архитектура agent harness

Когда мы говорим об оптимизации работы AI-агентов вроде Claude Code или Cursor, главная проблема — это не вычислительная мощность, а контекстное загрязнение и неэффективный поиск данных. Типовая ошибка при работе с агентами — «скармливание» им всего репозитория целиком. Это приводит к галлюцинациям, раздуванию токенов и потере фокуса.

Архитектура Agent Harness построена на принципе минимизации шума. Вместо того чтобы заставлять модель гадать, где лежит нужная функция, harness предоставляет ей структурированный, проверенный инструментарий для извлечения конкретных фактов. С точки зрения безопасности и производительности, это переход от модели «черного ящика» к модели управляемого доступа к знаниям.

Модульная структура

Harness не является монолитным скриптом. Это набор независимых модулей, которые можно подключать к разным средам исполнения. Каждый модуль отвечает за свой слой работы с контекстом:

Memory Layer (Слой памяти): Управляет краткосрочным контекстом сессии и долгосрочными знаниями о проекте. Здесь важно не путать векторные базы данных с детерминированным парсингом. На практике я видел, как использование векторного поиска в сложных проектах приводило к тому, что агент находил «похожий» код, но не тот, который нужен для исправления бага.
Skill Layer (Слой навыков): Набор специализированных инструментов для выполнения конкретных задач (чтение файлов, выполнение тестов, поиск по AST). Рекомендуется использовать набор навыков для инженеров, чтобы агент не пытался «изобрести велосипед» при каждом запросе.
Abstraction Layer (Слой абстракции): Позволяет агенту взаимодействовать с кодом через высокоуровневые команды, не вникая в синтаксические мелочи на каждом шагу.

Для реализации глубокого понимания связей между компонентами системы, архитектура harness опирается на концепцию графов знаний. Вместо того чтобы просто индексировать текст, система строит дерево зависимостей. Это позволяет реализовать подход, описанный в материалах про Graphify, где каждый край графа объясним и детерминирован.

Интеграция с Claude Code

Интеграция с Claude Code происходит через расширение набора доступных инструментов (tools/functions). В Claude Code агент может вызывать внешние команды, и harness предоставляет ему эти команды в максимально безопасном и структурированном виде.

При настройке интеграции категорически не рекомендуется давать агенту прямой доступ к shell с правами root. Вместо этого используется прослойка, которая ограничивает область видимости (scope) агента текущим проектом.

Пример конфигурации модуля интеграции для Claude Code (в формате JSON-описания инструментов):

json
{
  "tool_name": "graph_query",
  "description": "Выполняет запрос к графу знаний проекта для получения точных связей между классами и методами.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Запрос на языке графовой навигации (например, 'find callers of function X')"
      }
    },
    "required": ["query"]
  },
  "security_policy": "read-only"
}

На практике наиболее эффективный сценарий использования — это связка Claude Code с инструментами построения графов. Если вы используете Graphify для создания графа знаний, агент получает возможность не просто «читать» код, а понимать его топологию.

Перед тем как развернуть harness в рабочей среде, обязательно проверьте права доступа к файловой системе. Типовая ошибка — оставить агенту возможность записи в директории .git или конфигурационные файлы среды.

Рекомендуемый порядок действий при интеграции:

Развернуть локальный экземпляр графа знаний через Graphify.
Настроить ограничения (sandbox) для выполнения команд через Claude Code.
Протестировать точность извлечения контекста на небольшом изолированном модуле.

Оптимизация производительности

Когда мы говорим об Agent Harness, мы не имеем в виду просто «ускорение ответа». В контексте работы с Claude Code или Cursor производительность — это минимизация лишних токенов и сокращение времени на раздумья агента. С точки зрения безопасности, чем меньше контекста мы скармливаем модели за один раз, тем меньше вероятность утечки чувствительных данных через неконтролируемые вызовы инструментов.

Типовая ошибка при работе с AI-агентами — попытка запихнуть в контекст всё дерево проекта. Это приводит к деградации логики и раздуванию стоимости запросов.

Кеширование инстинктов

Инстинкты агента — это его системные промпты и наборы инструментов (skills), которые определяют, как он реагирует на команды. Если агент каждый раз заново анализирует структуру проекта, чтобы понять, какой инструмент вызвать, вы теряете время и деньги.

На практике я видел случаи, когда агенты тратили до 30 % контекстного окна на повторное описание того, как работать с локальным окружением. Чтобы этого избежать, необходимо использовать механизмы кеширования высокоуровневых инструкций.

Вместо того чтобы передавать полный список навыков в каждом запросе, рекомендуется использовать предварительно сформированные графы знаний. Это позволяет агенту обращаться к структурированной информации, не перечитывая файлы конфигурации. Для этого эффективно подходит подход, описанный в материале Graphify: построение графа знаний из кода.

Если вы используете Claude Code, можно оптимизировать процесс, создав локальный индекс метаданных. Пример конфигурации для управления приоритетами навыков в вашем окружении:

yaml
# agent-harness-config.yaml
cache_settings:
  instincts:
    enabled: true
    ttl: 3600 # Время жизни кеша инструкций в секундах
    storage: local
  skills_optimization:
    use_graph: true # Использовать графовую структуру вместо векторного поиска
    deterministic_parsing: true

security:
  # Ограничиваем область видимости инструментов, чтобы агент не сканировал лишнее
  allowed_paths:
    - "./src"
    - "./tests"
  # Запрещаем агенту индексировать конфиги с секретами
  exclude_patterns:
    - "**/.env"
    - "**/secrets/*"

Использование Graphify позволяет превратить разрозненные файлы в queryable knowledge graph. Это превращает «инстинкт» поиска из метода перебора в метод точного запроса.

Управление памятью

Память агента делится на краткосрочную (текущий контекст диалога) и долгосрочную (база знаний, история прошлых сессий). Главная проблема здесь — «замусоривание» контекста. Когда история диалога становится слишком длинной, агент начинает галлюцинировать или игнорировать важные ограничения безопасности.

С точки зрения DevSecOps, управление памятью — это ещё и контроль над тем, какие данные остаются в истории. Категорически не рекомендуется хранить в долгосрочной памяти агента сырые логи или дампы БД.

Для эффективного управления памятью я рекомендую внедрять стратегию «ленивого» извлечения данных. Вместо того чтобы держать всё в памяти, агент должен уметь запрашивать только нужные фрагменты. Это концепция, которая лежит в основе подхода как сделать AI-агент «ленивым» senior dev.

При реализации управления памятью через Agent Harness, используйте следующие принципы:

Семантическая компрессия: вместо хранения всего лога выполнения команды, сохраняйте только результат (exit code и краткое описание ошибки).
Графовая память: используйте создание графа знаний из кода с помощью Graphify, чтобы агент мог восстанавливать связи между модулями, не держа их в активном контексте.
TTL для контекста: устанавливайте жесткие лимиты на количество итераций, после которых контекст должен быть очищен или сжат.

Пример команды для очистки текущего сессионного контекста в CLI-инструментах (если поддерживается):

bash
# Очистка контекста для предотвращения утечки данных из предыдущей сессии
agent-cli context clear --force

# Проверка текущего объема используемого контекста (в токенах)
agent-cli context status --verbose

Перед тем как позволить агенту записывать что-либо в долгосрочную память, проверьте, не содержит ли этот процесс автоматическую подгрузку чувствительных файлов из /etc/ или других системных директорий. Настройте exclude_patterns в конфигурации, как показано выше.

Безопасность и изоляция

Когда вы даёте AI-агенту вроде Claude Code или Cursor доступ к своей файловой системе, вы фактически передаёте управление ключами от квартиры. Типовая ошибка — запускать агент в той же среде, где крутятся ваши рабочие проекты, хранятся .env файлы с секретами или запущены базы данных. С точки зрения безопасности, агент — это непредсказуемый процесс. Он может ошибиться в интерпретации команды или стать вектором атаки, если в коде, который он анализирует, есть уязвимость, позволяющая выполнить произвольный код (RCE).

Я всегда настаиваю на принципе минимальных привилегий. Если агенту нужно только читать код, он не должен иметь прав на запись или выполнение системных команд.

Контроль доступа

Никогда не запускайте агентные среды под пользователем root. Это критическая ошибка, которая превращает любую галлюцинацию модели в полноценный захват системы.

Лучший способ ограничить возможности агента — использовать контейнеризацию. Я рекомендую изолировать рабочую среду в Docker-контейнере с ограниченным набором прав. Это позволяет агенту «видеть» только тот репозиторий, над которым он работает, и не иметь доступа к вашему домашнему каталогу или системным конфигам.

Пример конфигурации Dockerfile для безопасной песочницы:

dockerfile
# Используем минималистичный образ без лишних утилит
FROM debian:bookworm-slim

# Создаем непривилегированного пользователя
RUN groupadd -r agentuser && useradd -r -g agentuser agentuser

# Устанавливаем рабочую директорию
WORKDIR /workspace

# Ограничиваем права: агент может только читать/писать в /workspace
RUN chown agentuser:agentuser /workspace

# Переключаемся на пользователя
USER agentuser

# Запускаем агентную среду (пример для Claude Code)
ENTRYPOINT ["claude-code"]

При запуске контейнера обязательно используйте флаги, ограничивающие возможности системы:

bash
docker run --rm \
  --network none \
  --memory="2g" \
  --cpus="1.5" \
  -v $(pwd)/project:/workspace:ro \
  agent-harness-image

Обратите внимание на флаг --network none. Если агенту не требуется доступ в интернет для работы с API (в этом случае проксируется только трафик к Anthropic), отключайте сеть полностью. Это исключит возможность утечки ваших данных на сторонние серверы в случае компрометации агента. Если же доступ нужен, используйте --network с указанием конкретной изолированной подсети.

Если вы используете более сложные инструменты для построения контекста, например Graphify, помните, что создание графа знаний из кода требует глубокого анализа AST. Чтобы этот процесс не стал инструментом разведки (reconnaissance) для злоумышленника, создание графа знаний должно происходить строго внутри изолированного контура.

Аудит и мониторинг

В промышленной эксплуатации «черный ящик» — это приговор. Вы должны знать, что именно агент пытался сделать в системе. Мониторинг действий агента — это не паранойя, а необходимость.

На практике я видел случаи, когда агенты в попытках «исправить баг» начинали бесконечные циклы рекурсивного сканирования директорий или пытались прочитать /etc/passwd, просто потому что это было в их обучающей выборке как «полезный навык».

Для контроля за поведением агента в Linux-среде я рекомендую настроить auditd. Это позволит фиксировать все попытки доступа к чувствительным файлам.

Пример правила для auditd, чтобы отслеживать любые попытки чтения файлов конфигурации в /etc:

bash
# Добавляем правило в auditd
auditctl -w /etc/shadow -p r -k agent_access_attempt
auditctl -w /etc/passwd -p r -k agent_access_attempt

После выполнения операций агентом, всегда проверяйте логи. Если вы используете подход, описанный в материале как сделать AI-агент «ленивым» senior dev, где фокус смещен на качество кода, а не на объем написанного, аудит поможет убедиться, что «лень» агента не превратилась в игнорирование критических патчей безопасности.

Для комплексного анализа логов и отслеживания аномалий в поведении агента (например, резкий всплеск исходящего трафика или попытки обращения к системным вызовам) я рекомендую развернуть легковесный стек мониторинга. Если ваш домашний сервер позволяет, связка journald + Loki даст достаточно информации, чтобы понять, не начал ли ваш агент вести себя как вредоносное ПО.

Чеклист по безопасности перед запуском агента:

Агент запущен не под root?
Файловая система смонтирована в режиме read-only там, где это возможно?
Сетевой доступ ограничен (используется ли --network none или специфический bridge)?
Секреты (.env, ключи доступа) исключены из директории, к которой у агента есть доступ?
Настроены ли лимиты на ресурсы (CPU, RAM), чтобы агент не вызвал DoS вашей системы?
Включен ли аудит системных вызовов или доступа к файлам?

Исследовательский процесс разработки

Тестирование в изоляции

Когда вы доверяете AI-агенту вроде Claude Code или Cursor выполнение кода, вы фактически передаёте ему контроль над своей файловой системой. С точки зрения безопасности — это критическая точка отказа. Типовая ошибка новичка: запускать агентные инструменты прямо в основной рабочей директории или, что ещё хуже, на хостовой машине без ограничений.

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

Для оптимизации Agent Harness я рекомендую использовать контейнеризацию. Это не просто «хорошая практика», это единственный способ гарантировать, что действия агента не выйдут за пределы песочницы.

Пример конфигурации Dockerfile для создания изолированной среды разработки, где агент может безопасно экспериментировать с кодом:

dockerfile
# Используем минималистичный образ, чтобы уменьшить поверхность атаки
FROM debian:bookworm-slim

# Создаем непривилегированного пользователя
RUN groupadd -r devgroup && useradd -r -g devgroup agentuser

# Устанавливаем необходимые инструменты для работы агента
RUN apt-get update && apt-get install -y \
    curl \
    git \
    python3 \
    && rm -rf /var/lib/apt/lists/*

# Настраиваем рабочую директорию
WORKDIR /workspace
RUN chown agentuser:devgroup /workspace

# Переключаемся на пользователя, чтобы агент не работал под root
USER agentuser

# Ограничиваем возможности через запуск контейнера (команда для запуска)
# --read-only поможет предотвратить несанкционированные изменения в системных папках
# --tmpfs позволяет агенту писать временные файлы, не засоряя образ

Запуск такой среды должен выглядеть так:

bash
docker run -it --rm \
  --name agent-sandbox \
  --network none \
  --memory="2g" \
  --cpus="1.5" \
  -v $(pwd)/project:/workspace \
  agent-dev-image

Важно: Я настоятельно рекомендую использовать флаг --network none, если агенту не требуется доступ к внешним API для выполнения текущей задачи. Это полностью исключает риск утечки данных через сетевые запросы во время выполнения сгенерированного кода. Если доступ к сети необходим, используйте изолированную подсеть.

Для более глубокого понимания того, как агент может анализировать структуру проекта перед запуском тестов, изучите создание графа знаний из кода с помощью Graphify. Это позволит агенту «понимать» зависимости, не перебирая все файлы подряд.

Обратная связь и улучшения

Эффективность агента напрямую зависит от качества петли обратной связи (feedback loop). Если агент совершает ошибку, он должен не просто получить сообщение об ошибке от компилятора, а понять контекст этой ошибки.

В рамках оптимизации Agent Harness мы внедряем механизм многоуровневой проверки. Вместо того чтобы просто просить агента «исправить код», мы заставляем его проходить через этапы:

Анализ текущего состояния (через AST-парсинг).
Генерация гипотезы исправления.
Запуск изолированного теста.
Сравнение результата с ожидаемым.

Для того чтобы агент не превращался в «генератор мусорного кода», крайне полезно использовать инструменты, которые предоставляют ему структурированное представление о кодовой базе. Например, Graphify (в контексте нашего исследования) позволяет превратить документацию, SQL-схемы и конфиги в графовую структуру. Это дает агенту «инстинкт» — он видит связи между компонентами, а не просто текст.

Типовая ошибка при настройке обратной связи — игнорирование логов системы. Если вы используете Docker для изоляции, агент должен иметь доступ к journald или логам контейнера, чтобы понимать, почему процесс завершился с ошибкой.

Рекомендуемый подход к организации логов для агента:

yaml
# Пример части docker-compose.yml для сбора логов агента
services:
  agent-harness:
    image: agent-dev-image
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    # Проброс логов для анализа агентом
    volumes:
      - ./logs:/var/log/agent_feedback

Чтобы агент работал как «ленивый senior dev», который сначала думает, а потом пишет, необходимо внедрять ограничения на количество итераций. Не позволяйте агенту зацикливаться на одной и той же ошибке. Если после трёх попыток исправления ошибка повторяется, процесс должен прерываться с требованием вмешательства человека. Подробнее о том, как настроить такие паттерны поведения, можно прочитать в материале как сделать AI-агент «ленивым» senior dev.

Чеклист для проверки процесса разработки:

Агент запускается в контейнере с ограниченными правами (non-root).
Сетевой доступ ограничен или полностью отключен.
Ресурсы (CPU/RAM) ограничены на уровне рантайма.
Настроена передача результатов тестов обратно в контекст агента.
Имеется лимит на количество попыток исправления ошибки.

Часто задаваемые вопросы

Как Agent Harness влияет на расход токенов?

Оптимизация расхода токенов достигается за счёт минимизации контекстного шума. Вместо передачи всего репозитория, система поставляет агенту только релевантные фрагменты кода через специализированные слои. С точки зрения экономики проекта, это позволяет избежать раздувания контекстного окна и снижает вероятность галлюцинаций модели.

Можно ли использовать векторный поиск вместо детерминированного парсинга?

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

Безопасно ли предоставлять агенту доступ к файловой системе через Skill Layer?

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

В чем преимущество модульной структуры перед монолитными решениями?

Модульность позволяет гибко настраивать среду под конкретные задачи, не перегружая систему лишними процессами. Вы можете подключать только необходимые слои — например, только Memory Layer для простых задач или полный набор модулей для глубокого аудита. Это упрощает отладку и позволяет контролировать каждый этап взаимодействия агента с данными.

affaan-m/ECC: Agent Harness Performance Optimization