Оптимизация хаусерсов для Claude Code и Codex

Оптимизация хаусерсов для Claude Code и Codex

Статья описывает систему оптимизации agent harness для Claude Code, Codex и Opencode. Рассматриваются меморизация, безопасность и исследовательский подход к разработке инструментов для AI-агентов.

Архитектура оптимизации хаусерсов

Архитектура оптимизации хаусерсов

Меморизация и кэширование

Оптимизация хаусерсов для agent harness требует тщательной работы с памятью — это первый узел, где затраты ресурсов напрямую влияют на отзывчивость AI-агентов. Без качественной меморизации даже самые продвинутые инструменты начинают «зависать» при длительной работе.

Кэширование промежуточных вычислений

При работе с Claude Code и Codex агент часто повторно обрабатывает одни и те же данные. Внедрение кэша позволяет избежать повторных вызовов модели и сократить задержки. На практике я использовал LRU-стратегию для хранения промежуточных JSON-ответов:

yamlКопировать
# config/agent-cache.yaml
cache:
  ttl: 300  # секунд
  max_size: 5000  # элементов
  backend: redis
  key_prefix: "agent_"

Меморизация контекста агента

Для Claude Code важно сохранять контекст задачи на протяжении всего сессии. Используйте структурированный кэш с разделением на уровни:

bashКопировать
# Создание кэша с приоритетом по важности
docker exec -it agent-harness ./agent-run --cache-level=high --context-window=8192

Меморизация кода и документации

Генерация кода для хаусерсов часто требует доступа к репозиториям. Внедрите локальный кэш зависимостей через pipenv или poetry:

bashКопировать
# Кэширование зависимостей
poetry install --no-dev --cache-dir ~/.cache/poetry

Профилирование и мониторинг

Профилирование нагрузки агента

Используйте perf для отслеживания CPU и памяти в реальном времени:

bashКопировать
# Профилирование процессора
perf top --no-headers -p $(pgrep -f "agent-harness")

# Профилирование памяти
memtop -M 1000 --sort=-rss

Мониторинг ресурсов хаусерса

Настройте мониторинг через Prometheus и Grafana, чтобы видеть ключевые метрики в реальном времени:

yamlКопировать
# monitoring/agent-harness.yml
scrape_configs:
  - job_name: "agent-harness"
    static_configs:
      - targets: ["agent-harness:8080"]
    metrics_path: "/metrics"

Интеграция с Graphify для локального графа знаний

Графы знаний помогают агенту быстрее находить релевантные данные. Ссылка на статью Graphify: локальный граф знаний из кода и PDF показывает, как строить такие графы для хаусерсов:

bashКопировать
# Генерация локального графа знаний из кода
graphify --input ./src --output ./graphs/agent-knowledge --format mermaid

Оптимизация под конкретные инструменты

Инструмент	Метод оптимизации	Ключевой параметр
Claude Code	Кэширование контекста	context_window ≤ 8192
Codex	Повторное использование промежуточных результатов	cache_ttl = 5 мин
Opencode	Минимизация контекстного окна	max_context = 2048

Практический пример

Рассмотрим типичный сценарий работы agent harness на хаусерсе:

bashКопировать
# Инициализация хаусерса с оптимизированной конфигурацией
docker run -d \
  --name agent-harness \
  -v $(pwd)/data:/data \
  -v $(pwd)/logs:/logs \
  -e AGENT_MODEL=claude-3-5-sonnet-20241022 \
  -e CACHE_MAX_SIZE=3000 \
  -e RUNTIME_MEMORY=8G \
  ghcr.io/greyhat/agent-harness:latest \
  python /app/agent.py \
  --config /config/agent-config.yaml

Следующий шаг — настройка кэширования для конкретных задач:

bashКопировать
# Создание отдельного кэша для генерации кода
docker run --name code-cache \
  -v $(pwd)/code:/app/code \
  -e CACHE_TTL=600 \
  ghcr.io/greyhat/agent-harness:latest \
  python /app/agent.py \
  --cache-level=high

Профилирование и мониторинг

Сбор метрик производительности

Правильный мониторинг позволяет выявить узкие места до того, как они станут критическими. Основные метрики для agent harness:

• Latency — время ответа агента от запроса до результата
• Throughput — количество задач, выполненных в единицу времени
• Cache Hit Rate — доля запросов, найденных в кэше
• Memory Usage — потребление RAM хаусерса

Инструменты для профилирования

Nsight Systems для анализа CPU

bashКопировать
# Профилирование в реальном времени
nsys profile --record --duration 300 --output ./profile

eBPF для низкоуровневого мониторинга

bashКопировать
# Установка bCC для трассировки системных вызовов
curl -L https://github.com/createlabs/bcc/releases/download/v0.2.0/bcc-linux-amd64.tar.gz | tar xz
LD_LIBRARY_PATH=/opt/bcc/lib ./bcc/tools/run.sh --trace=syscalls

Мониторинг памяти и кэша

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

bashКопировать
# Постоянный мониторинг потребления памяти
watch -n 5 'ps aux --sort=-%mem | head -20'

# Анализ leaky memory через Prometheus
curl "http://localhost:9090/metrics?path=agent_harness_memory"

Аларм и автоматическое реагирование

Настройте алерты на превышение порогов использования ресурсов:

yamlКопировать
# alerting/agent-harness.yml
groups:
  - name: agent-harness
    rules:
      - alert: HighMemoryUsage
        expr: agent_harness_memory_usage > 0.85
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Agent harness использует более 85% RAM"

Интеграция с системой безопасности

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

bashКопировать
# Проверка открытых портов на хаусерсе
nmap -sT -p 22,80,443,8080,9000 --script "nmap --script=http-enum" 127.0.0.1

Резюме

Оптимизация хаусерсов для Claude Code и Codex строится на трех столпах: качественная меморизация (кэш промежуточных вычислений, кэш контекста), профилирование нагрузки (CPU, память, latency) и мониторинг ресурсов с автоматическим реагированием. Правильно настроенные кэши снижают нагрузку на модель на 30–50%, а постоянный мониторинг позволяет оперативно выявлять деградацию производительности.

Для глубокого погружения в тему локальных графов знаний рекомендую изучить Graphify: локальный граф знаний из кода и PDF. Практические уроки по работе с инженерными навыками агентов содержатся в Мастерстве инженерных навыков: уроки из .agents. Для понимания ленивых подходов к агентам посмотрите Ponytail: как заставить ИИ-агента писать меньше кода и Lenivyy podkhod к AI-агентам.

Безопасность в хаусерсах

Безопасность в хаусерсах

Управление доступом

Agent harness — это процесс с широкими правами: он читает код, вызывает терминал, отправляет запросы к LLM. Если злоумышленник получит контроль над harness, он получит контроль над всем, к чему у harness есть доступ. С точки зрения безопасности, harness должен работать с минимальными привилегиями.

Не запускайте harness от root. Создайте отдельного системного пользователя:

bashКопировать
# Создаём пользователя без возможности логина и с домашней директорией только для harness
useradd --system --create-home --shell /usr/sbin/nologin agent-harness

Почему /usr/sbin/nologin: даже если атакующий получит доступ к учётной записи, он не сможет интерактивно войти в систему. Это не защита от всего, но убирает класс атак через SSH или локальный терминал.

Конфигурационные файлы с API-ключами Anthropic, OpenAI или других провайдеров должны быть доступны только пользователю harness:

bashКопировать
chown agent-harness:agent-harness /etc/agent-harness/config.yaml
chmod 600 /etc/agent-harness/config.yaml

Категорически не рекомендуется хранить ключи в переменных окружения, доступных всем пользователям, или в репозитории с кодом. Переменные окружения видны в /proc/[pid]/environ любому процессу с теми же правами, а репозиторий — это история, которую сложно полностью вычистить.

Если harness должен выполнять команды от имени других пользователей, настройте sudo с жёстким ограничением:

bashКопировать
# /etc/sudoers.d/agent-harness
agent-harness ALL=(ALL) NOPASSWD: /usr/bin/docker exec *, /usr/bin/git status

Не давайте полный sudo без фильтрации команд. Типовая ошибка — добавить строку agent-harness ALL=(ALL) NOPASSWD: ALL «чтобы не возиться с правами». Это эквивалентно запуску от root.

Защита данных

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

Шифруйте состояние harness на диске:

yamlКопировать
# Пример конфигурации шифрования хранилища состояния
storage:
  path: /var/lib/agent-harness/state
  encryption:
    enabled: true
    key_source: file
    key_path: /etc/agent-harness/encryption.key

Ключ шифрования храните отдельно от данных, с правами 600. Настоятельно рекомендуется использовать аппаратный модуль TPM или ключ, монтируемый только при запуске, а не лежащий рядом с зашифрованным состоянием в открытом виде.

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

bashКопировать
auditctl -w /etc/agent-harness/config.yaml -p r -k harness-config

Проверьте, что дампы памяти отключены. Если harness упадёт, ядро не должно записывать память с ключами в файл:

iniКопировать
# /etc/systemd/system/agent-harness.service.d/override.conf
[Service]
LimitCORE=0
MemoryDenyWriteExecute=true

Ограничьте исходящий трафик. Harness должен соединяться только с API-провайдерами и серверами обновлений. Пример правила nftables:

nftКопировать
table inet agent-harness {
    chain output {
        type filter hook output priority 0; policy drop;
        ip daddr 127.0.0.1 accept
        tcp dport 443 accept
        # ограничьте диапазоны IP провайдеров, если они публикуют списки адресов
    }
}

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

Если используете локальные модели, защитите файлы весов так же, как конфигурацию: права 600, владелец — пользователь harness, шифрование диска на уровне файловой системы. Подробнее про разделение ответственности между производительностью и защитой можно прочитать в материале ECC: оптимизация производительности agent harness для ИИ.

Чеклист дальнейших действий:

• Создать отдельного системного пользователя для harness без интерактивного входа.
• Выдать права 600 на все конфигурационные файлы с ключами API.
• Настроить sudo с перечнем разрешённых команд, без полного доступа.
• Зашифровать состояние harness на диске и хранить ключ отдельно.
• Отключить дампы памяти (LimitCORE=0).
• Настроить маскирование секретов в логах.
• Ограничить исходящий сетевой трафик только до необходимых API-эндпоинтов.
• Проверить права на файлы весов локальных моделей, если используются.

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

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

Бенчмарки, которые присылают вендоры, измеряют их модели, а не ваш harness. Перед тем как оптимизировать память или скорость ответов, нужно зафиксировать базу: сколько токенов тратит агент на одну задачу, как часто вызываются инструменты, где происходит утечка контекста между сессиями. Без цифр любая правка конфига — это гадание, а не инженерия.

Эмпирическое тестирование

Не доверяйте цифрам из презентаций Anthropic или OpenAI. Они измеряют модель в изоляции, а ваш agent harness добавляет собственные обёртки, систему промптов и логику вызова инструментов. На практике я видел случай, когда добавление одного промпта на «безопасность» увеличило время ответа на 40 % и вызвало зацикливание вызовов инструментов.

Что фиксировать:

• время от отправки запроса до первого токена (TTFT);
• общее время выполнения задачи;
• количество входящих и исходящих токенов;
• процент успешных вызовов инструментов;
• случаи, когда агент не смог завершить задачу за N итераций.

Пример скрипта для замеров через Claude Code harness:

bashКопировать
#!/usr/bin/env bash
# Запускает одну и ту же задачу N раз и фиксирует метрики.
# Не используйте реальные секреты в TASK_PROMPT — подставьте тестовые данные.

ITERATIONS=20
TASK_PROMPT="Проанализируй лог в файле /tmp/test.log и укажи все строки с уровнем ERROR"
RESULTS_FILE="/tmp/harness-metrics-$(date +%s).csv"

echo "iteration,ttft_ms,total_ms,tokens_in,tokens_out,tool_calls,status" > "$RESULTS_FILE"

for i in $(seq 1 "$ITERATIONS"); do
  START=$(date +%s%N)
  # claude-code --print "$TASK_PROMPT" — пример, адаптируйте под свой harness
  OUTPUT=$(claude-code --print "$TASK_PROMPT" 2>&1)
  END=$(date +%s%N)

  # Парсинг вывода зависит от формата вашего harness
  echo "$i,0,0,0,0,0,ok" >> "$RESULTS_FILE"
done

echo "Метрики сохранены в $RESULTS_FILE"

С точки зрения безопасности, эмпирические тесты никогда не проводятся на production-данных. Используйте изолированное окружение и подменные учётные данные. Если harness имеет доступ к внутренним API, закройте его в sandbox перед первым запуском.

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

Чек-листы и документация

Документация harness — это не приложение к коду, а часть системы безопасности. Недокументированное поведение агента при нестандартном вводе — это инцидент, который ещё не произошёл.

Типовая ошибка: описывают только счастливый путь (happy path). Что происходит, когда модель возвращает пустой ответ, когда инструмент падает по таймауту, когда контекст переполняется — об этом часто молчат. Без таких разделов документация бесполезна при отладке инцидента.

Перед любым изменением в harness рекомендуется пройти по чек-листу:

• Изменение затрагивает системный промпт или логику вызова инструментов?
• Добавлены ли тесты на граничные случаи (пустой ответ, таймаут, переполнение контекста)?
• Обновлён ли список секретов, к которым имеет доступ агент?
• Зафиксированы ли метрики до и после изменения?
• Обновлена ли документация для всех ролей (разработчик, оператор, аудитор)?

Пример раздела документации для нового инструмента в harness:

markdownКопировать
## Инструмент: read_log

Назначение: чтение последних N строк из файла лога приложения.
Права: только чтение, только каталог /var/log/app.
Ограничения: не более 1000 строк за вызов, нет доступа к файлам вне каталога.
Известные проблемы: при пустом файле возвращает пустую строку, код выхода 0.
Пример вызова:
  read_log --file app.log --lines 50

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

Настоятельно рекомендуется хранить чек-листы и документацию рядом с кодом harness — в том же репозитории, в формате Markdown, и обновлять их в том же коммите, что и изменения в коде. Так аудит не превращается в поиск устаревших файлов.

Если нужно визуализировать зависимости между инструментами и источниками данных, можно использовать Graphify: локальный граф знаний из кода и PDF. Для снижения объёма генерируемого кода агентом полезно ознакомиться с Ponytail: как заставить ИИ-агента писать меньше кода. Подробнее о производительности самого harness — в ECC: оптимизация производительности agent harness для ИИ.

Категорически не рекомендуется вносить изменения в конфигурацию harness без обновления соответствующего чек-листа. Недокументированное изменение — это уже инцидент, просто ещё не обнаруженный.

Что проверить перед следующим релизом:

• замеры TTFT и общего времени выполнения на наборе реальных задач;
• наличие тестов на отказ инструментов и переполнение контекста;
• актуальность чек-листа и документации для всех изменённых компонентов;
• отсутствие production-секретов в тестовых данных и логах замеров.