Средний

affaan-m/ECC: Agent Harness Performance Optimization

greyhat
greyhat
Специалист по безопасности16 ноября 2026 г.13 мин чтения

The agent harness performance optimization system for Claude Code, Codex, Opencode, emphasizing skills, instincts, memory, security, research‑first dev.

affaan-m/ECC: Agent Harness Performance Optimization

The agent harness performance optimization system for Claude Code, Codex, Opencode, emphasizing skills, instincts, memory, security, research‑first dev.

Core Architecture and Key Modules

Core Architecture and Key Modules

Архитектура ECC (Agent Harness Performance Optimization) строится на принципе минимизации когнитивной нагрузки на модель при сохранении высокой скорости выполнения задач. Если рассматривать систему как конвейер, то основная цель здесь — не просто передать промпт, а подготовить окружение так, чтобы агент не тратил токены на избыточные рассуждения или поиск контекста.

С точки зрения безопасности, такая архитектура требует строгого разделения между средой исполнения (execution environment) и средой хранения данных. Любая оптимизация производительности не должна приводить к утечке контекста между сессиями или к возможности агента выйти за пределы разрешённого окружения.

Agent Skill Execution

В ECC выполнение навыков (skills) отделено от основного цикла рассуждений. Вместо того чтобы просить модель «напиши скрипт и запусти его», система использует предварительно определённые инструменты с жестко заданными интерфейсами. Это снижает вероятность галлюцинаций при вызове функций.

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

Для управления навыками рекомендуется использовать декларативный подход. Вместо передачи размытых инструкций, мы передаём четкие спецификации. Это перекликается с подходом, описанным в анализе DESIGN.md, где структура документа определяет логику работы системы.

Пример конфигурации навыка для выполнения исследовательских задач (research-first dev):

yaml
# Конфигурация навыка исследования
skill:
  name: research_tool
  description: "Анализ локальной кодовой базы и поиск уязвимостей"
  parameters:
    path: "string" # Путь к директории (строго внутри рабочей области)
    depth: "integer" # Глубина рекурсии
  constraints:
    allow_network: false # Категорически запрещаем сетевую активность без явного запроса
    max_tokens: 4000 # Лимит на ответ, чтобы избежать перегрузки контекста

Перед тем как внедрять новые навыки в production-окружение, настоятельно рекомендуется протестировать их в изолированном контейнере. Никогда не запускайте агента с правами root в среде, где есть доступ к важным данным.

Memory Management and Persistence

Управление памятью в ECC — это не просто сохранение истории чата. Это многоуровневая система, которая разделяет краткосрочную рабочую память (context window) и долгосрочную память (persistence layer).

  1. Short-term memory: Текущий контекст сессии. Здесь важно уметь эффективно «сжимать» историю, удаляя промежуточные шаги рассуждений, которые уже не влияют на текущую задачу.
  2. Long-term memory: Векторная база данных или структурированные файлы (например, CLAUDE.md), которые позволяют агенту извлекать знания о проекте.

Использование файлов типа CLAUDE.md — эффективный способ управления поведением модели, что подтверждается опытом использования набора навыков Andrej Karpathy. Это позволяет внедрить «инстинкты» и правила разработки прямо в контекст, не раздувая каждый промпт.

С точки зрения безопасности, работа с памятью — это критическая точка. Если агент сохраняет в долгосрочную память чувствительные данные (API-ключи, пароли, персональные данные), они станут доступны при следующей сессии.

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

bash
# Пример структуры директории для хранения контекста проекта
# Используйте только зашифрованные разделы для хранения векторов
mkdir -p /opt/agent_memory/project_alpha/vector_store
mkdir -p /opt/agent_memory/project_alpha/logs

# Установка прав доступа: доступ только для пользователя, под которым запущен агент
chmod 700 /opt/agent_memory/project_alpha

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

Для более глубокого понимания того, как оптимизация этих модулей влияет на общую производительность системы, изучите основной материал: [ECC: Agent Harness Performance Optimization](/articles/affaan-m/ECC: Agent Harness Performance Optimization).

Performance Tuning Strategies

Performance Tuning Strategies

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

На практике я видел случаи, когда неоптимизированные циклы рассуждений (reasoning loops) приводили к неконтролируемому росту нагрузки на CPU и переполнению памяти, что фактически превращало инструмент разработки в инструмент для DoS-атаки на собственный сервер.

Instruction-Level Optimization

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

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

При работе с Claude Code крайне важно ограничивать область видимости (context window). Не позволяйте агенту сканировать весь репозиторий без необходимости. Настройте .claudecodeignore или аналогичные механизмы, чтобы исключить бинарные файлы, логи и директории с зависимостями.

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

Рекомендуется использовать подход, описанный в CLAUDE.md для улучшения поведения, где правила поведения жестко зашиты в конфигурационный файл проекта. Это снижает вероятность того, что агент уйдет в бесконечный цикл попыток исправить ошибку, которую он не может разрешить.

Resource Allocation and Concurrency

Если вы запускаете агентов в рамках автономной разработки, управление ресурсами становится критическим фактором. Агент — это процесс, который может порождать множество дочерних процессов: запуск тестов, линтеров, сканеров уязвимостей.

Чтобы предотвратить деградацию системы, необходимо ограничивать ресурсы на уровне контейнера или cgroups. Если вы используете Docker для изоляции среды агента, обязательно задавайте лимиты.

Пример конфигурации docker-compose.yml для запуска агента с жесткими ограничениями:

yaml
services:
  agent-harness:
    image: agent-executor:latest
    deploy:
      resources:
        limits:
          cpus: '2.0'        # Ограничение на 2 ядра
          memory: 4G         # Лимит оперативной памяти
        reservations:
          memory: 1G         # Гарантированный минимум
    security_opt:
      - no-new-privileges:true # Запрет на получение новых привилегий
    cap_drop:
      - ALL                  # Сброс всех возможностей ядра

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

При настройке параллелизма (concurrency) важно соблюдать баланс. Слишком высокая степень параллелизма при выполнении задач исследования (research-first dev) может привести к исчерпанию лимитов API (rate limits) или к перегрузке локальной файловой системы.

На практике я рекомендую внедрять механизм семафоров для управления количеством одновременно выполняемых задач. Это позволяет поддерживать стабильный поток работы, не превращая систему в хаос. Подробнее о комплексном подходе к оптимизации читайте в основной статье [ECC: Agent Harness Performance Optimization](/articles/affaan-m/ECC: Agent Harness Performance Optimization).

Security Hardening and Access Control

Security Hardening and Access Control

Когда мы говорим об оптимизации производительности агентских систем, таких как ECC: Agent Harness Performance Optimization, легко уйти в погоню за скоростью отклика и объёмом контекста. Но с точки зрения безопасности, каждый агент — это потенциальная точка входа. Если агент получает доступ к вашей файловой системе или сетевым ресурсам, он становится полноценным пользователем с набором привилегий. Типовая ошибка — запускать такие инструменты с правами текущего пользователя или, что ещё хуже, от root.

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

Authentication and Permission Scoping

Принцип наименьших привилегий (PoLP) здесь должен соблюдаться неукоснительно. Если агент работает в рамках проекта, он не должен иметь доступа к /etc/, домашним директориям других пользователей или SSH-ключам.

Для изоляции среды я настоятельно рекомендую использовать контейнеризацию с жестко ограниченными правами. Не делайте так, чтобы агент имел доступ к Docker socket (/var/run/docker.sock) внутри контейнера — это фактически даёт ему полный контроль над хостом.

При настройке окружения для агента (например, при использовании подходов, описанных в проекте Claw-Code на Rust), используйте не-root пользователя и монтируйте только необходимые директории с флагом read-only, где это возможно.

Пример конфигурации Docker Compose для запуска агента в изолированном окружении:

yaml
services:
  agent-harness:
    image: agent-runtime:latest
    user: "1001:1001" # Запуск от конкретного UID/GID, а не от root
    read_only: true   # Файловая система доступна только для чтения
    volumes:
      - ./project_files:/app/workspace:ro # Рабочая директория только на чтение
      - ./agent_logs:/app/logs:rw        # Только для логов
      - /tmp/agent_cache:/tmp/cache:rw   # Ограниченное место для временных файлов
    security_opt:
      - no-new-privileges:true # Запрещает получение новых привилегий через setuid бинарники
    cap_drop:
      - ALL # Сбрасываем все возможности ядра
    cap_add:
      - CHOWN # Добавляем только то, что критически необходимо для работы

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

Audit Logging and Anomaly Detection

Логирование в агентских системах — это не просто сбор ошибок. Это ваш единственный способ понять, что именно «решил» сделать ИИ в обход ваших ожиданий. Если вы используете методы из CLAUDE.md для улучшения поведения, помните: инструкции в файле конфигурации — это лишь мягкое ограничение. Настоящая защита — это аудит действий.

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

На практике я использую связку auditd на хосте и сборщик логов для отслеживания подозрительной активности. Если агент внезапно начинает сканировать порты или пытаться прочитать /etc/shadow, система должна немедленно прервать его сессию.

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

bash
# Отслеживаем доступ к файлу passwd
-w /etc/passwd -p wa -k agent_access_attempt

# Отслеживаем выполнение команд в директории проекта, если агент работает через shell
-a always,exit -F arch=b64 -S execve -F dir=/app/workspace -k agent_exec

Для автоматизации обнаружения аномалий можно настроить простой скрипт, который анализирует частоту выполнения команд. Если количество вызовов curl или wget резко возрастает, это повод для немедленной остановки процесса.

Чеклист по безопасности агента:

  • Агент запущен от пользователя с ограниченными правами (non-root).
  • Файловая система агента ограничена (используется read-only там, где это возможно).
  • Все системные вызовы ограничены через seccomp или AppArmor.
  • Логи действий агента вынесены на отдельный ресурс.
  • Настроен мониторинг подозрительных системных вызовов (через auditd или аналоги).
  • У агента нет доступа к Docker socket или другим интерфейсам управления инфраструктурой.

Research‑Driven Development Workflow

Iterative Testing with Real‑World Scenarios

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

С точки зрения безопасности и стабильности, я рекомендую внедрять подход Research-Driven Development (RDD). Это значит, что каждый цикл итерации начинается не с написания кода, а с создания сценария, максимально приближенного к боевым условиям. Если вы оптимизируете Agent Harness, ваши тесты должны имитировать не только успешные кейсы, но и деградацию окружения.

На практике я видел случаи, когда агент идеально справлялся с рефакторингом, но полностью «ломался» при попытке прочитать конфиг с ограниченными правами доступа. Поэтому тестирование должно включать проверку ограничений (constraints).

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

yaml
services:
  agent-sandbox:
    image: debian:bookworm-slim
    container_name: fsociety-sandbox
    volumes:
      - ./workspace:/app/workspace:ro # Монтируем рабочую директорию только для чтения
      - ./logs:/app/logs
    cap_drop:
      - ALL # Сбрасываем все привилегии ядра
    security_opt:
      - no-new-privileges:true # Запрещаем повышение привилегий
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

В этом конфиге я намеренно использую no-new-privileges и cap_drop: - ALL. Это критически важно: если ваш агент имеет доступ к инструментам разработки, он должен уметь работать в максимально урезанном окружении. Если агент не может выполнить задачу из-за нехватки прав или ресурсов в таком контейнере — значит, его алгоритмы планирования (planning) требуют доработки.

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

Documentation and Knowledge Sharing

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

Категорически не рекомендуется полагаться на то, что агент «сам разберется» в коде. Для эффективной работы необходимо внедрять структурированные файлы контекста. Одним из лучших примеров является использование специализированных файлов типа CLAUDE.md, которые задают правила поведения и архитектурные паттерны. Подробнее об этом можно почитать в гайде по использованию CLAUDE.md для улучшения поведения Claude Code.

Чтобы процесс обмена знаниями внутри команды (и между человеком и агентом) был эффективным, я придерживаюсь следующих правил:

  1. Единый источник истины (Single Source of Truth): Все архитектурные решения, описанные в DESIGN.md, должны быть доступны агенту. Это позволяет избежать ситуации, когда агент предлагает решение, противоречащее общей логике системы (см. анализ DESIGN.md).
  2. Логирование «инстинктов»: Если вы оптимизируете Agent Harness, документируйте не только результат, но и процесс принятия решения. Почему агент выбрал именно этот инструмент? Какие ошибки он совершил в процессе исследования?
  3. Аудит контекста: Регулярно проверяйте, не перегружено ли контекстное окно агента лишней информацией. Избыточный контекст — это не только потеря производительности, но и риск безопасности, так как агент может начать использовать нерелевантные или устаревшие данные.

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

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

  • Сценарии тестирования включают кейсы с нехваткой ресурсов (CPU/RAM).
  • Окружение для тестов максимально изолировано (используются no-new-privileges).
  • В проекте присутствует актуальный CLAUDE.md или аналогичный файл инструкций.
  • Архитектурные решения зафиксированы в документации, доступной агенту.
  • Все изменения в Agent Harness прошли через цикл «исследование — тест — фиксация».

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

Как ECC уменьшает когнитивную нагрузку модели?

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

Почему необходимо строго разделять среду исполнения и хранения данных?

Разделение гарантирует, что данные, сохраняемые в хранилище, не будут случайно переданы в новый сеанс и не приведут к утечке контекста между запросами. Такая изоляция также предотвращает возможность агента выйти за пределы разрешённого окружения, что критично с точки зрения безопасности. При строгом разделении любые изменения в хранилище не влияют на выполнение текущего запроса, что снижает риск неожиданного поведения. Это соответствует принципам безопасного дизайна, описанным в разделе Core Architecture.

Какие риски возникают, если предоставить агенту слишком широкий набор инструментов без ограничений?

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

Как правильно настроить декларативные спецификации навыков, чтобы избежать рекурсивных вызовов?

В конфигурации навыка указываются точные команды, их параметры и ожидаемый результат, а не общие инструкции «выполнить задачу». Пример: в yaml‑файле задаётся skill_id: run_script, command: ["bash", "-c", "script.sh"], timeout: 30s. Такой подход гарантирует, что модель не сможет инициировать повторный вызов того же инструмента, потому что интерфейс фиксирован. Кроме того, рекомендуется использовать max_calls: 1 в описании навыка, чтобы явно запретить множественные запросы. Это согласуется с рекомендациями из DESIGN.md, где структура документа определяет логику работы системы.

Поделиться:TelegramX / TwitterVK

Читайте также