Средний

ECC: Agent Harness Optimization for Claude Code & Beyond

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

Deep dive into ECC, the agent harness that optimizes performance, security, and research‑first development for Claude Code, Codex, Opencode, Cursor and beyond.

ECC: Agent Harness Optimization for Claude Code & Beyond

Deep dive into ECC, the agent harness that optimizes performance, security, and research‑first development for Claude Code, Codex, Opencode, Cursor and beyond.

Core Architecture of ECC

Core Architecture of ECC

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

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

Modular Agent Pipeline

Вместо монолитного процесса ECC использует модульный конвейер. Каждый этап — от получения запроса до выполнения команды — это отдельный модуль, который можно аудировать и ограничивать.

Конвейер состоит из трёх ключевых фаз:

  1. Intent Analysis (Анализ намерений): Модуль разбирает план агента. Если агент хочет выполнить rm -rf /, модуль блокирует запрос ещё до того, как он попадет в шелл.
  2. Context Injection (Инъекция контекста): Вместо того чтобы скармливать агенту весь репозиторий, ECC подаёт только необходимые фрагменты. Здесь полезно использовать подходы, описанные в материалах про построение графа знаний из кода, чтобы агент видел только релевантные связи, не перегружая контекстное окно и не выходя за рамки дозволенного.
  3. Execution Sandbox (Песочница исполнения): Команды выполняются в изолированных контейнерах.

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

yaml
# ecc-policy.yaml
pipeline:
  execution:
    mode: containerized
    runtime: runc
    constraints:
      # Категорически не рекомендую оставлять доступ к /etc или /home
      readonly_paths:
        - /etc
        - /home
        - /var/log
      writable_paths:
        - /workspace/project_alpha
      network_access:
        allow_external: false # Запрещаем агенту стучаться на внешние IP без явного разрешения
        allowed_domains:
          - github.com
          - pypi.org

Перед тем как внедрять подобные политики в production, я настоятельно рекомендую прогнать их через режим dry-run. Это позволит увидеть, какие команды агент пытается выполнить, не ломая при этом рабочий процесс.

Resource‑Aware Scheduling

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

ECC внедряет планировщик, который учитывает текущую нагрузку системы и лимиты конкретного агента. Мы используем подход, схожий с тем, как можно сделать AI-агента «ленивым» senior dev, ограничивая его вычислительную жадность.

Планировщик контролирует три параметра:

  • CPU/RAM Quotas: Жесткие лимиты через cgroups.
  • Token Budget: Ограничение количества токенов на одну итерацию задачи.
  • Time-to-Live (TTL): Максимальное время жизни сессии агента.

Пример настройки лимитов для агента, выполняющего рефакторинг (в файле конфигурации среды):

bash
# Ограничиваем ресурсы для процесса агента через systemd-run
# Это гарантирует, что даже при утечке памяти агент не уронит весь сервер
systemd-run --scope -p CPUQuota=20% -p MemoryMax=2G \
  --property=TasksMax=50 \
  ecc-agent --task "refactor-auth-module"

С точки зрения безопасности, Resource-Aware Scheduling — это не только про экономию ресурсов, но и про защиту от DoS-атак со стороны самого агента. Если модель «сойдет с ума» и начнет генерировать бесконечные циклы вычислений, планировщик просто прибьёт процесс по истечении TTL.

Чеклист для проверки архитектуры ECC перед запуском:

  • Проверено, что все writable_paths ограничены только рабочей директорией.
  • Установлены лимиты MemoryMax и CPUQuota для контейнеров агента.
  • Включен режим логирования всех попыток выполнения команд (auditd/journald).
  • Сетевой доступ агента ограничен списком разрешённых доменов.

Performance Optimization Techniques

Memory‑Bound Tuning

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

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

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

yaml
services:
  agent-harness:
    image: ecc-agent-runtime:latest
    deploy:
      resources:
        limits:
          memory: 8G # Жесткий лимит, чтобы избежать OOM Killer на хосте
          cpus: '4'
        reservations:
          memory: 4G # Гарантированный объем для стабильной работы контекста
    # Настройка параметров ядра для управления кэшем
    sysctls:
      net.core.somaxconn: 1024

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

Если вы настраиваете окружение вручную, проверьте текущее использование памяти и наличие swap:

bash
# Проверка использования памяти и активности подкачки
free -h

# Проверка, не упирается ли агент в лимиты cgroups
cat /sys/fs/cgroup/memory/memory.usage_in_bytes

Категорически не рекомендуется запускать тяжелые агенты на системах, где swappiness установлен в значение по умолчанию (обычно 60). Для высоконагруженных сред разработки я рекомендую снижать этот параметр, чтобы система до последнего держала данные в RAM.

bash
# Временное снижение агрессивности использования swap
sudo sysctl vm.swappiness=10

Instruction‑Level Parallelism

Параллелизм на уровне инструкций (ILP) в контексте ECC — это не про многопоточность в привычном понимании, а про то, как эффективно агент планирует цепочки рассуждений (reasoning chains) и запросов к LLM. Вместо того чтобы ждать завершения одного шага (например, чтения файла), ECC пытается перекрывать операции ввода-вывода и вычисления.

Типовая ошибка при разработке кастомных инструментов для агентов — последовательный (синхронный) вызов функций. Если агент сначала читает файл, потом анализирует его, а потом только запрашивает у Claude уточнение, вы теряете до 70% потенциальной скорости.

В ECC реализован механизм префетчинга контекста. Пока модель генерирует ответ на текущий запрос, harness уже подготавливает следующие блоки данных, основываясь на предсказании следующего шага. Это напоминает подход, описанный в материале Как сделать AI‑агент «ленивым» senior dev, где акцент смещается с написания кода на правильное управление контекстом.

Для оптимизации этого процесса рекомендуется использовать асинхронные интерфейсы для всех внешних инструментов. Пример структуры вызова инструментов на Python:

python
import asyncio

async def execute_agent_step(tool_name, params):
    """
    Асинхронное выполнение инструмента. 
    Не делайте вызовы синхронными, это блокирует event loop агента.
    """
    try:
        # Имитация вызова инструмента (например, поиск по коду)
        result = await asyncio.wait_for(call_tool(tool_name, params), timeout=10.0)
        return result
    except asyncio.TimeoutError:
        # Важно: всегда обрабатывайте таймауты, чтобы агент не "завис"
        return {"error": "tool_timeout"}

async def main():
    # Параллельный запуск нескольких задач (например, сбор метаданных)
    tasks = [
        execute_agent_step("read_file", {"path": "main.py"}),
        execute_agent_step("list_dir", {"path": "./src"}),
        execute_agent_step("get_git_status", {})
    ]
    results = await asyncio.gather(*tasks)
    print(results)

if __name__ == "__main__":
    asyncio.run(main())

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

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

Security and Access Control

Security and Access Control

Когда вы даёте AI-агенту доступ к терминалу или файловой системе, вы фактически передаёте ключи от своего дома незнакомцу, который может случайно (или под влиянием инъекции) сжечь здание. В контексте ECC мы не рассматриваем агента как «помощника», мы рассматриваем его как потенциально скомпрометированный процесс. С точки зрения безопасности, агент — это ненадежный исполнитель.

Zero-Trust Execution

Типовая ошибка при работе с Claude Code или Cursor — запуск агента в той же сессии, где у вас есть права root или доступ к важным переменным окружения. Если агент получит вредоносный промпт через контекст кода (Prompt Injection), он сможет выполнить rm -rf / или украсть ваши AWS_ACCESS_KEY_ID.

В ECC мы внедряем принцип Zero-Trust. Агент должен работать в изолированном окружении с минимально необходимыми привилегиями. На практике я рекомендую использовать контейнеризацию с ограничением ресурсов и файловой системы.

Никогда не запускайте агентов напрямую на хостовой машине. Используйте Docker с флагом --read-only для системных директорий и монтируйте только конкретный рабочий каталог.

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

bash
docker run -it --rm \
  --name ecc-agent-executor \
  --network none \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  -v $(pwd)/project:/workspace:ro \
  -v $(pwd)/output:/workspace/output:rw \
  claude-code-ecc-image

Разберем, что здесь происходит:

  • --network none: агент не имеет доступа к сети. Если его попытаются заставить отправить ваши секреты на внешний сервер, это не удастся. Если агенту нужен доступ к API Anthropic, используйте прокси с белым списком доменов.
  • --cap-drop ALL: мы сбрасываем все возможности ядра (capabilities). Агенту не нужно менять время в системе или управлять сетевыми интерфейсами.
  • --security-opt no-new-privileges: запрещает процессам внутри контейнера получать новые привилегии через setuid биты.
  • -v ...:ro: основной код монтируется только для чтения. Агент может его анализировать, но не может незаметно изменить логику работы приложения.

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

Audit Logging and Monitoring

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

Каждое действие агента (чтение файла, выполнение команды, запрос к LLM) должно логироваться. Типовая ошибка — полагаться на логи самого приложения. Если агент скомпрометирован, он просто очистит stdout или удалит файл лога.

Рекомендуется использовать auditd на хосте для отслеживания системных вызовов, которые делает контейнер с агентом.

Пример настройки правила для отслеживания попыток записи в директорию /etc из контейнера:

bash
# Добавляем правило в auditd для мониторинга записи в критические директории
auditctl -w /etc/ -p wa -k agent_unauthorized_access

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

  1. Исходный промпт пользователя.
  2. Сгенерированную команду агента.
  3. Результат выполнения (stdout/stderr).
  4. Время выполнения и затраченные токены.

Это позволяет проводить ретроспективный анализ. Например, если вы заметили, что агент начал вести себя странно, вы сможете понять, был ли это результат ошибки в логике или целенаправленная атака через контекст. Для более глубокого понимания того, как правильно выстраивать процессы контроля, рекомендую изучить Набор навыков для инженеров: разбор репозитория skills.

Помните: мониторинг бесполезен, если вы не реагируете на алерты. Если агент пытается выполнить команду, не входящую в его разрешенный профиль (например, curl или nmap), процесс должен немедленно завершаться.

Integration with Claude Ecosystem

Integration with Claude Ecosystem

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

ECC выступает в роли прослойки (harness), которая не просто передаёт промпты, а структурирует среду исполнения. Это позволяет интегрировать Claude в существующие пайплайны, сохраняя контроль над тем, что именно агент может изменять в вашем проекте.

Claude Code Plugin Development

Разработка плагинов для Claude Code через ECC строится на принципе минимальных привилегий. Вместо того чтобы давать агенту доступ ко всему репозиторию, мы создаём изолированные инструменты (tools), которые предоставляют доступ только к конкретным абстракциям.

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

Пример реализации базового инструмента для чтения структуры проекта, который не позволяет агенту «уйти» в системные директории:

python
# Пример логики плагина для ECC (псевдокод)
import os
from ecc.security import validate_path

class ProjectStructureTool:
    def __init__(self, root_dir):
        # Ограничиваем корень проекта, чтобы агент не гулял по /etc или /home
        self.root_dir = os.path.abspath(root_dir)

    def execute(self, relative_path):
        # Настаиваю на проверке пути перед любым чтением
        target_path = validate_path(self.root_dir, relative_path)
        
        if not target_path:
            return "Error: Access denied. Path is outside project scope."
            
        return self._get_tree(target_path)

    def _get_tree(self, path):
        # Логика построения дерева файлов
        ...

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

Cross‑Tool Workflow Automation

Автоматизация рабочих процессов между разными инструментами (например, переход от Claude Code к Cursor или локальному терминалу) требует единого протокола передачи контекста. ECC обеспечивает этот протокол, позволяя сохранять состояние сессии.

Типовой сценарий: Claude находит уязвимость, создаёт план исправления, а затем передаёт этот план в другой инструмент для автоматизированного тестирования. Чтобы этот процесс не превратился в бесконечный цикл саморазрушения, необходимо внедрять промежуточные проверки (human-in-the-loop).

Конфигурация автоматизации в ECC может выглядеть так:

yaml
# config/workflows/security-audit.yaml
workflow:
  name: "Vulnerability Patching"
  steps:
    - tool: "claude-code"
      action: "scan_vulnerabilities"
      output: "vuln_report.json"
    
    - tool: "ecc-validator"
      action: "verify_context"
      input: "vuln_report.json"
      # Категорически не рекомендую пропускать этап валидации контекста
      strict_mode: true 

    - tool: "custom-patcher"
      action: "apply_fix"
      input: "vuln_report.json"
      requires_approval: true # Обязательная ручная проверка перед записью в файлы

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

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

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

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

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

Чем ECC отличается от стандартного использования Docker в качестве песочницы?

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

Как ECC помогает экономить токены при работе с большими репозиториями?

Проблема перегрузки контекстного окна решается через модуль Context Injection. Вместо передачи всего содержимого проекта ECC использует графовые структуры для подачи только тех фрагментов кода, которые необходимы для решения текущей задачи. Это не только снижает затраты на API, но и повышает точность ответов, так как модель не отвлекается на нерелевантный шум.

Нужно ли настраивать дополнительные правила доступа для каждого нового агента?

ECC спроектирован как модульный конвейер, поэтому базовые политики безопасности применяются ко всем подключенным инструментам, будь то Claude Code или Cursor. Однако для специфических задач рекомендуется создавать отдельные профили ограничений. Перед внедрением нового агента в рабочий процесс проверьте, какие права ему требуются по умолчанию, и максимально сузьте их в конфигурации ECC.

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

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