Продвинутый

affaan-m/ECC: Agent Harness Performance Optimization for...

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

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

affaan-m/ECC: Agent Harness Performance Optimization for Claude Code

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

Архитектура и ключевые компоненты

Общая схема

Агент‑ха́рнс (agent harness) состоит из нескольких взаимосвязанных слоёв, каждый из которых отвечает за конкретную задачу. Ниже — упрощённая схема, показывающая основные компоненты и их взаимодействие.

+-------------------+        +-------------------+        +-------------------+
|  UI / CLI         | <---> |  Orchestrator     | <---> |  Skill Manager    |
+-------------------+        +-------------------+        +-------------------+
          |                           |                         |
          v                           v                         v
+-------------------+        +-------------------+        +-------------------+
|  Memory Store     | <----> |  Security Layer   | <----> |  Instinct Engine  |
+-------------------+        +-------------------+        +-------------------+
          |                           |                         |
          v                           v                         v
+-------------------+        +-------------------+        +-------------------+
|  External APIs   | <----> |  sandbox / chroot | <----> |  Logging & Audits |
+-------------------+        +-------------------+        +-------------------+

Ключевые элементы

  • Orchestrator — центральный процесс, управляет жизненным циклом агента (запуск, остановка, перезапуск).
  • Skill Manager — загружает и выгружает навыки (skill modules) в зависимости от текущей задачи.
  • Memory Store — хранит контекст, историю и кеш; поддерживает сериализацию в JSON или protobuf.
  • Security Layer — изолирует агент, ограничивает сетевой доступ и права файловой системы.
  • Instinct Engine — реализует «инстинкты» (предустановленные поведенческие шаблоны) для быстрого реагирования.

Типичный конфиг (YAML) для загрузки агента:

yaml
# agent.yaml
name: claude-code-agent
version: "1.2.0"
skills:
  - skill/http_client
  - skill/sql_parser
memory:
  engine: sqlite
  path: /var/lib/agent_harness/memory.db
security:
  sandbox: true
  read_only_fs: true
  seccomp_profile: "default"
  network:
    allow:
      - 10.0.0.0/8
      - 127.0.0.1/32
    deny: "*"

На практике я видел случай, когда отсутствие read_only_fs привело к повреждению кэша в /tmp, что нарушило работу агента. Поэтому рекомендуется включить read_only_fs в продакшн‑деплое.

Ссылка: подробный разбор схемы и примеров кода – affaan-m/ECC: оптимизация производительности агент‑ха́рнс.


Модуль безопасного доступа

Модуль безопасного доступа (Secure Access Module, SAM) отвечает за изоляцию агента от внешних угроз и за контроль прав доступа. Он состоит из трёх подсистем: сеть, файловая система и процесс.

Сетевая изоляция

Для ограничения исходящего и входящего трафика используем nftables. Пример базового набора правил, которое рекомендуется для любого деплоя:

bash
# /etc/nftables/agent.nft
#!/usr/sbin/nft -f

flush ruleset

table inet filter {
    chain input {
        type filter hook input priority 0; policy drop;
        iif "lo" accept
        ct state established,related accept
        ip saddr 10.0.0.0/8 accept
        ip daddr 127.0.0.1/32 accept
    }

    chain forward {
        type filter hook forward priority 0; policy drop;
    }

    chain output {
        type filter hook output priority 0; policy accept;
        # запрещаем любые попытки доступа к внешним CDN без явного разрешения
        # (пример: блокировка доступа к известным malicious доменам)
        # ip daddr { 1.2.3.4, 5.6.7.8 } drop
    }
}

После загрузки правил проверяем их статус:

bash
sudo nft list ruleset

Ссылка: рекомендации по настройке nftables для изоляции контейнеров – Ponytail: оптимизация работы AI‑агентов.

Файловая система

Агент должен работать в ограниченной среде. В Docker‑контейнере это реализуется через параметры запуска:

bash
docker run -d \
  --name claude_harness \
  --read-only \
  --tmpfs /tmp:exec,size=64m \
  --security-opt no-new-privileges \
  --security-opt seccomp=default \
  -v /opt/agent/config:/etc/agent:ro \
  ghcr.io/anthropic/claude-code:latest
  • --read-only – делает корневую файловую систему только для чтения.
  • --tmpfs /tmp – создаёт временный образ в памяти, ограничивая размер.
  • --security-opt no-new-privileges – запрещает процессу получать новые привилегии через setuid/setgid.
  • --security-opt seccomp=default – применяет стандартный профиль seccomp, блокируя системные вызовы, не относящиеся к базовым операциям.

Процессная изоляция

Для дополнения SAM используем AppArmor профиль, который насторательно рекомендуется включить в любой продакшн‑деплой:

bash
# /etc/apparmor.d/local/usr.bin.docker
profile docker {
    #include <abstractions/base>
    #include <abstractions/namespaces>
    #include <abstractions/urandom>

    # Запрещаем сетевые соединения, кроме whitelist‑диапазонов
    network inet stream,
    network inet dgram,
    deny /etc/hosts r,
    deny /etc/resolv.conf r,
    deny /etc/hosts.windows etc,

    # Разрешаем только определённые пути
    /etc/agent/** r,
    /var/lib/agent_harness/** rw,
}

Перезагрузка профиля:

bash
sudo apparmor_parser -r /etc/apparmor.d/local/usr.bin.docker

Ссылка: примеры использования AppArmor в контейнерах – affaan-m/ECC: Agent Harness Performance Optimization.

Аудит и логирование

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

ini
[Unit]
Description=Journal Service

[Service]
# Включаем передачу логов в syslog для внешней агрегации
ForwardToSyslog=yes
SyslogIdentifier=agent_harness

[Install]
WantedBy=multi-user.target

Ссылка: best‑practice по аудиту контейнеров – Show HN: db-branch – ZFS DB branches in seconds for AI & CI.


Итого: модуль безопасного доступа объединяет network‑level filtering (nftables), filesystem hardening (Docker --read-only, tmpfs), процессную изоляцию (seccomp, no‑new‑privileges, AppArmor) и централизованный аудит. При правильной настройке SAM категорически не рекомендуется запускать агент без этих мер, так как это открывает путь к компрометации системы.

Оптимизация навыков и инстинктов

### Анализ контекстных запросов

Контекстные запросы – это «сырой материал», из которого агент формирует решение.
Если передать слишком много токенов, модель будет «запутываться», а качество ответа падает.

Типичная ошибка – отправлять весь репозиторий целиком. На практике я видел случай, когда git diff включил более 10 МБ текста, и Claude Code начал возвращать общие фразы без конкретики.

Как оптимизировать

  1. Отбирайте только нужные файлы – по сигнатуре функции, по импортам, по recent‑changes.
  2. Обрезайте контекст до ≈ 4 000 токенов (для Claude Code – максимум 8 К).
bash
# пример скрипта, который оставляет только файлы из списка
git ls-files | grep -E '(^src/|^tests/)' | xargs -I{} git show --stat {} \
  | awk '/^file/ {print $2}' | xargs -I{} sh -c 'git show {} | head -n 2000' \
  > context.txt
  1. Храните конфиг‑файл с параметром max_context_length и проверяйте его перед запуском агента.
yaml
# .env.example
MAX_CONTEXT_LENGTH=4000
PROMPT_TEMPLATE=prompts/agent_prompt.yaml
  1. Не забывайте о NBSP после предлогов в, к, с, о, у, и, а – это требование типографики, иначе текст будет выглядеть «машинно».

Ссылка на практический пример – подробный разбор в статье Ponytail: оптимизация работы AI‑агентов.


### Динамическая подсказка

Динамическая подсказка (dynamic prompting) – это когда система подставляет в промпт актуальную информацию justo‑in‑time.

Почему это важно
Если в контексте stale‑данные (например, старый API‑спецификаtion), агент будет предлагать устаревшие вызовы.

Пractical подход

  1. Шаблон‑промпт хранится в YAML/JSON, а значения подставляются через envsubst или jq.
yaml
# prompts/agent_prompt.yaml
system: |
  You are a senior DevSecOps engineer with 12+ years of experience.
  Your task is to review the provided code snippet and suggest security‑focused improvements.
  Never suggest actions that compromise production integrity.
  Use the following context:
  {{CONTEXT}}
  {{INSTRUCTION}}
bash
# пример подстановки переменных
export CONTEXT=$(cat context.txt | base64)
export INSTRUCTION="Review the Dockerfile for non‑root usage and seccomp profile."
envsubst < prompts/agent_prompt.yaml > prompt.txt
  1. Instinct‑check – перед тем как выполнить команду, проверяйте её последствия.
bash
# проверка перед запуском контейнера
if ! docker run --rm --security-opt seccomp=seccomp.json myimage; then
  echo "❗️  Проверка безопасности не прошла, отменяем действие"
  exit 1
fi
  1. Chain‑of‑thought – заставляйте модель «мысленно» пройти шаги.
text
# пример инструкции в prompt
"Подумайте шаг за шагом: 1) какая операционная система? 2) какие привилегии имеет процесс? 3) какие уязвимости известны в этой версии?"

Категорически не рекомендуется передавать в контекст полностью открытые репозитории без фильтрации – это открывает путь к утечке данных и усложняет анализ.

Связанный материал – подробный гайд по динамическому prompting в статье affaan-m/ECC: Agent Harness Performance Optimization.


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

  • Оцените размер контекста, оставьте только релевантные файлы.
  • Установите MAX_CONTEXT_LENGTH в .env.
  • Подготовьте шаблон‑промпт и скрипт подстановки.
  • Внедрите проверку docker run --security-opt перед выполнением критических команд.
  • Регулярно проверяйте актуальность используемых зависимостей (Nuclei, OpenVAS).

Если что‑то не работает – ищите причину в логах journald или auditd, а не в «пробных» командах.

Память и кэширование

Память и кэширование

### Внутренний кэш

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

Типичные параметры кеша

yaml
# ecc_config.yaml
cache:
  enabled: true
  directory: /var/lib/ecc/cache
  max_size_mb: 512      # ограничение по объёму
  ttl_hours: 12         # время жизни записей
  prune_interval: 6h    # частый фоновый запуск

Очистка кеша вручную

sh
# Очистить весь кеш (опасно, данные будут потеряны)
ecc cache purge --all

# Очистить только устаревшие записи старше 24 ч
ecc cache prune --age 24h

greyhat: «На практике я видел случай, когда кеш набрал 2 ГБ и система начала свопиться, хотя свободной RAM было менее 500 МБ». Поэтому настоятельно рекомендуется задавать max_size_mb и регулярно запускать prune_interval.

Связь с другими материалами
Оптимизация кеша описана в статье affaan-m/ECC: оптимизация производительности агент‑ха́рнс. Также полезен подход из Ponytail: оптимизация работы AI‑агентов, где кеш используется для «ленивого» старшего разработчика.

### Граничные условия памяти

Агент‑ха́рнс работает в контейнере или в виртуальном окружении, поэтому важно задавать ограничения на потребляемую память. Неправильные границы могут вызвать падение процесса (OOM) или нехватку памяти для контекста.

Задание лимита памяти при запуске

sh
# Запустить агент с лимитом 2 ГБ RAM
ecc run --memory 2g --max-context-length 8192

Проверка текущего потребления

sh
# Показать использование памяти контейнера (docker)
docker stats --no-stream --format "{{.MemUsage}} {{.Name}}" | grep ecc

# Или через cgroup (без docker)
cat /sys/fs/cgroup/memory/ecc/memory.usage_in_bytes

Ограничение контекстного окна

yaml
# ecc_config.yaml (добавить)
context:
  max_tokens: 8192   # максимальное количество токенов в контексте

greyhat: «Если max_context_length превышает доступную память, система будет падать с OOM‑ошибкой». Поэтому категорически не рекомендуется оставлять значение по умолчанию без проверки.

Связь с другими материалами
Для сравнения с другими системами хранения контекста смотрите в Show HN: db-branch – ZFS DB branches in seconds for AI & CI, где также обсуждаются ограничения памяти при работе с большими ветками данных.


Чек‑лист после настройки памяти и кеша

  • max_size_mb — задана и проверена (не более 70 % от доступной RAM)
  • ttl_hours — соответствует требованиям бизнес‑процесса
  • prune_interval — запланирован (не реже 6 ч)
  • --memory — задана при запуске, проверена через docker stats/cgroup
  • max_context_length — не превышает 80 % от max_memory (чтобы избежать OOM)

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

Безопасность и аудит

Безопасность и аудит

Когда мы говорим об использовании AI-агентов вроде Claude Code или Cursor, основная проблема смещается из плоскости «напишет ли он код» в плоскость «что этот код сделает с моей системой». Агент по сути получает доступ к терминалу, файловой системе и сети. С точки зрения безопасности, вы даёте LLM-модели неконтролируемый доступ к исполнению команд. Типовая ошибка — запускать такие инструменты в основной ОС под пользователем с правами sudo. Если агент получит неверную инструкцию или попадет под влияние Prompt Injection, последствия будут необратимыми.

Изоляция процессов

Никогда не запускайте агент-ха́рнс напрямую в вашей рабочей среде. Единственный разумный подход — полная изоляция. На практике я видел случаи, когда агенты, пытаясь «исправить» зависимости, удаляли критические системные пакеты или меняли конфигурацию сетевых интерфейсов.

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

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

yaml
services:
  ai-agent:
    image: agent-harness-env:latest
    # Запуск от не-root пользователя — это база
    user: "1000:1000"
    read_only: true # Делаем файловую систему только для чтения
    tmpfs:
      - /tmp # Разрешаем запись только в эфемерную память
      - /home/user/workspace/build # Только для рабочих директорий
    security_opt:
      - no-new-privileges:true # Запрещаем получение новых привилегий через setuid
    cap_drop:
      - ALL # Сбрасываем все возможности ядра
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
    networks:
      - isolated_net

networks:
  isolated_net:
    internal: true # Запрещаем агенту выход в интернет, если это не требуется для работы

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

Для более глубокой изоляции, особенно если вы работаете с проектами, требующими сложной настройки окружения, посмотрите в сторону ZFS DB branches, которые позволяют быстро создавать и откатывать состояния файловой системы. Это даст вам возможность «откатиться» после того, как агент решит, что удаление /etc — отличная идея.

Логирование и мониторинг

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

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

  1. Аудит системных вызовов. Используйте auditd. Это позволит вам видеть, какие файлы открывал агент и какие процессы запускал, даже если он попытается скрыть свои следы. Настройте правило для отслеживания выполнения команд в рабочей директории:

    bash
    # Следим за выполнением всех команд в папке проекта
    auditctl -w /home/user/project -p x -k agent_activity
    
  2. Анализ логов терминала. Если вы используете Docker, настройте экспорт логов контейнера в централизованную систему. Для домашнего сервера отлично подойдет связка с Wazuh или простым стеком Loki. Это позволит вам не только видеть, что произошло, но и настроить алерты на критические события (например, попытку обращения к /etc/shadow).

  3. Сетевой мониторинг. Если агент имеет доступ к сети, используйте tcpdump или специализированные инструменты для анализа трафика. Если вы видите, что агент пытается установить соединение с неизвестным IP-адресом, который не входит в список разрешенных, — это сигнал к немедленной остановке процесса.

Помните: безопасность — это не разовое действие, а непрерывный процесс. Изоляция и аудит — это фундамент, без которого использование AI-агентов в разработке превращается в игру в рулетку.

Для более глубокого понимания того, как оптимизировать работу таких систем без ущерба для производительности, изучите оптимизацию производительности агент‑ха́рнс.


Чеклист действий после настройки окружения:

  • Проверить, что агент запущен под не-root пользователем.
  • Убедиться, что no-new-privileges установлен в true.
  • Проверить, что auditd успешно фиксирует изменения в рабочей директории.
  • Протестировать откат состояния (например, через ZFS snapshot), если агент совершит деструктивное действие.
  • Убедиться, что сетевые правила ограничивают доступ агента только необходимыми ресурсами.

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

Как ECC влияет на безопасность при работе с кодом?

Security Layer в архитектуре ECC обеспечивает изоляцию агента через использование sandbox или chroot. Это ограничивает права агента на файловую систему и сетевой доступ, что критически важно при выполнении автоматизированных задач. С точки зрения безопасности, использование такого слоя предотвращает несанкционированный доступ к основной системе в случае ошибки или некорректного поведения модели.

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

Да, система спроектирована для интеграции с инструментами вроде Claude Code, Cursor и Codex. Благодаря компоненту Skill Manager, агент может подгружать специфические навыки для работы с вашим окружением. Однако настоятельно рекомендую запускать такие инструменты в изолированных средах, чтобы минимизировать риски при выполнении сгенерированного кода.

Зачем в системе нужен Instinct Engine?

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

Как ECC управляет контекстом и историей сессий?

За это отвечает Memory Store, который поддерживает сериализацию данных в форматах JSON или protobuf. Это позволяет сохранять состояние агента, его навыки и историю взаимодействий для последующего использования. При настройке системы важно учитывать, что хранение контекста требует контроля прав доступа к файлам памяти, чтобы избежать утечки чувствительных данных проекта.

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

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