affaan-m/ECC: Agent Harness Performance Optimization
Разбор системы ECC от affaan-m: навыки, инстинкты, память, безопасность и исследовательский подход для Claude Code, Codex, Opencode, Cursor и др.
Архитектура и ключевые компоненты ECC
Архитектура и ключевые компоненты ECC
Модульная структура и взаимодействие сервисов
ECC построен как набор независимых сервисов, каждый из которых отвечает за чётко определённую задачу.
Главный процесс — ecc-agent, который оркестрирует работу остальных модулей через локальный RPC‑канал (gRPC).
Типичная иерархия:
ecc/
├─ agent/ # ядро агента, управление задачами
├─ config/ # загрузчик конфигураций (YAML/JSON)
├─ adapters/ # плагины для Claude Code, Codex, Opencode, Cursor
├─ telemetry/ # сбор метрик (Prometheus)
└─ utils/ # вспомогательные функции (логирование, проверка прав)
Запуск сервисов (пример для локального теста):
bash# собрать образ и запустить все сервисы
docker compose up -d
# проверить статус
docker compose ps
# логи агентов
docker logs -f ecc-agent
Типовая ошибка – запуск ecc-agent до того, как config-loader завершит инициализацию, приводит к nil‑значениям в конфиге и падению процесса.
Решение: добавить зависимость requires: config-loader в docker‑compose.yml и использовать healthcheck:
yamlservices:
config-loader:
image: ecc/config-loader:latest
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/ready"]
interval: 10s
timeout: 5s
retries: 3
ecc-agent:
image: ecc/agent:latest
depends_on:
config-loader:
condition: service_healthy
С точки зрения безопасности рекомендуется запускать ecc-agent в привилегированном контейнере только в тестовой среде; в продакшене используйте user: 1000:1000 и ограничьтеCapabilities (--cap-drop ALL).
Интеграция с Claude Code, Codex, Opencode, Cursor
ECC предоставляет адаптеры, которые позволяют «подключить» любой из перечисленных IDE‑инструментов через их CLI‑интерфейсы.
Общий принцип:
- Установить адаптер (
ecc adapter install <name>). - Добавить токен/ключ в переменную окружения.
- Указать в конфиге путь к проекту, где будет работать агент.
Пример интеграции с Claude Code:
bash# установить адаптер
ecc adapter install claude
# задать токен (пример)
export CLAUDE_API_KEY="sk-XXXXXXXXXXXXXXXXXXXX"
# конфигурация (config/adapters/claude.yaml)
cat <<EOF > config/adapters/claude.yaml
project_path: "/home/user/projects/my-app"
default_model: "claude-3-sonnet"
prompt_template: "ecc://prompt/optimize"
EOF
Проверка соединения (рекомендуется выполнить перед запуском в прод):
bashecc adapter test claude --project /home/user/projects/my-app
Если тест возвращает OK, можно переходить к реальному использованию.
Интеграция с Codex (пример):
yaml# config/adapters/codex.yaml
project_path: "/home/user/projects/my-app"
api_endpoint: "https://api.codex.example.com/v1"
token: "${CODEX_TOKEN}"
На практике я видел случай, когда токен Codex был скомпрометирован из‑за хранения в открытом репозитории; после инцидента был введён обязательный чек‑лист:
- токен хранится в Vault/Secrets Manager, а не в файле конфигурации;
- переменная окружения помечена как
readonly; - проверка наличия токена перед запуском
ecc agent start.
Opencode и Cursor работают аналогично – требуется лишь указать URL API и токен. В их адаптерах добавлена опция --dry-run, позволяющая проверить запросы без изменения кода.
Чек‑лист интеграции:
- версия адаптера совместима с текущей версией IDE (см. changelog);
- токен защищён (не в репозитории);
- проверен health‑check адаптера (
ecc adapter test <name>); - в
docker‑compose.ymlуказана зависимостьrequires: adapters/<name>.
Оптимизация ИИ-агентов с помощью системы ECC — подробный разбор того, как модульная архитектура повышает отзывчивость агентов.
Ponytail: как научить AI‑агента писать меньше кода — примеры использования адаптеров для снижения объёма генерируемого кода.
Оптимизация навыков и инстинктов
Клавиатурные и контекстные подсказки
Клавиатурные сочетания — быстрый способ передать агентu Harness (ECC) указание без лишних токенов. В конфиге редактора задаём привязку к команде eccPlan:
json{
"keybindings": [
{
"command": "eccPlan",
"sequence": "ctrl+alt+p",
"when": "editorTextFocus"
}
]
}
Контекстные подсказки должны быть лаконичными и содержать только нужную информацию. Пример подсказки для рефакторинга функции:
text// context: refactor processData to use async I/O, keep signature unchanged function processData(data) { // sync processing }
Краткая подсказка уменьшает количество токенов и ускоряет планирование.
Ponytail: как научить AI‑агента писать меньше кода — показывает, как сократить объём контекста за счёт чётких указаний.
Автоматическое планирование задач
ECC умеет генерировать план действий на основе описания задачи. CLI‑утилита ecc plan создаёт файл .plan.json, который можно inspect‑ить перед выполнением:
bashecc plan --task "Implement rate limiting for API endpoint" --project myapp
План сохраняется в виде структурированного JSON‑файла, например:
yamlplanner:
mode: "tree"
max_steps: 5
timeout_sec: 30
steps:
- "analyze current rate‑limiting middleware"
- "draft middleware implementation using token bucket"
- "add unit tests for edge cases"
- "integrate middleware into request pipeline"
- "review and merge"
Рекомендуется проверять план вручную, особенно если в нём присутствует более 3 шагов — это типичная ошибка, когда агент переоценивает сложность задачи.
Оптимизация ИИ‑агентов с помощью системы ECC — детали работы планировщика.
StarSling: AI‑driven CI for agent‑volume GitHub Actions — пример автоматического применения плана в CI.
На практике я видел случай, когда агент без ограничения max_steps зациклился на генерации тестовых данных, что привело к превышению таймаута. Поэтому всегда задавайте max_steps и проверяйте timeout_sec.
Не делайте так: оставляйте план без проверки — это типичная ошибка, снижающая надёжность автоматизации.
Настоятельно рекомендуется добавить в конфиг ограничение на количество шагов и время выполнения, чтобы избежать зацикливания и перерасхода ресурсов.
Память, кэш и безопасность
Управление контекстной памятью
Контекстная память – это основной ресурс, который расходуется на хранение токенов диалога и промежуточных вычислений. Слишком большие контексты приводят к переполнению ОЗУ, а слишком маленькие – к потере информации и ухудшению качества ответа. На практике я обычно задаю лимит через переменную окружения и проверяю её значение перед запуском агента.
bash# Ограничиваем контекст до 8 К токенов (пример для системы с 16 ГБ RAM)
export ECC_MAX_CONTEXT=8192
# Проверяем значение
echo $ECC_MAX_CONTEXT
В конфигурационном файле ecc.yaml можно задать параметр max_context_tokens. Это удобно, если нужно менять лимит без перезапуска оболочки.
yaml# ecc.yaml
model:
name: claude-3-sonnet
max_context_tokens: 8192 # ← лимит контекста
На практике я видел случай, когда агент, работающий с 32 К токенов, падал с OOM‑ошибкой на сервере с 8 ГБ RAM. После снижения max_context_tokens до 12 К всё стабилизировалось.
Если требуется динамически уменьшать контекст, используйте утилиту ecc trim. Она обрезает историю диалога, оставляя только последние N токенов.
bash# Оставляем только последние 4 К токенов
ecc trim --max-tokens 4096
Рекомендации
- Определяйте лимит на основе объёма RAM и типовых размеров контекста ваших задач.
- Тестируйте в staging‑среде перед применением в production.
- Не забывайте про NBSP после предлогов:
в контекст,на памяти.
Изоляция и контроль доступа
Агент‑харнесс часто запускается в контейнере, поэтому важно ограничить его доступ к ресурсам хоста. Ниже перечислены типичные меры, которые я применяю в продакшене.
bash# Запуск контейнера с ограниченными правами
docker run -d \
--name ecc-agent \
--security-opt seccomp=profile/seccomp.json \
--read-only \
-v /srv/ecc/logs:/app/logs:ro \
-e ECC_MAX_CONTEXT=8192 \
affaan-m/ecc:latest
--security-opt seccomp=...– применяет профиль seccomp, запрещающий системные вызовы, не указанные в файле.--read-only– делает корневую файловую систему только для чтения, исключая возможность изменения файлов хоста.-v …:ro– монтирует только нужные директории в режиме read‑only.
В Docker‑Compose можно задать те же ограничения в файле docker-compose.yml.
yaml# docker-compose.yml
version: "3.8"
services:
ecc-agent:
image: affaan-m/ecc:latest
security_opt:
- seccomp=profile/seccomp.json
read_only: true
volumes:
- /srv/ecc/logs:/app/logs:ro
environment:
- ECC_MAX_CONTEXT=8192
Для управления доступом к файлам внутри самого агента используйте ACL (Access Control Lists). Пример:
bash# Даем права только пользователю agent, запрещая всем остальным доступ к /app/data
setfacl -m u:agent:rwx /app/data
setfacl -m d:u:agent:rwx /app/data
Ponytail: как научить AI‑агента писать меньше кода – в этой статье описаны приёмы сокращения контекста, что напрямую влияет на безопасность памяти.
Рекомендации по изоляции
- Запускайте агента в отдельном контейнере с
--read-onlyи минимальными монтированиями. - Применяйте seccomp‑профиль, соответствующий минимальному набору системных вызовов.
- Ограничивайте файловую систему через bind‑монтирования с
ro‑флагом. - Проверяйте журнал доступа (
auditd) и логи контейнера после каждого изменения.
Чек‑лист дальнейших действий
- Установить
ECC_MAX_CONTEXTвecc.yamlи в переменной окружения. - Провести тестовый запуск с ограниченным контекстом (например, 4 K токенов).
- Запустить контейнер с
--security-opt seccomp=...и--read-only. - Ограничить файловую систему через bind‑монтирования в
:ro. - Настроить ACL для критических каталогов (
/app/data). - Включить аудит (
auditd) и мониторинг журналов (journalctl -u ecc-agent).
Следуя этим рекомендациям, вы снизите риск переполнения памяти и несанкционированного доступа, а также улучшите стабильность работы вашего AI‑агента.
Исследовательский подход и дальнейшее развитие
Тестирование в изолированных средах
Тестировать агента в полностью изолированном контейнере гарантирует, что результаты не искажаются внешними сервисами, нагрузкой или политиками безопасности хоста.
Почему изоляция важна
- Исключает влияние сторонних процессов и сетевых правил.
- Позволяет воспроизводить тесты на любой машине без «магических» настроек.
- Упрощает отладку: если агент падает – визуализируем лог в контейнере, а не в системе хоста.
Практический пример
bash# Создаём контейнер с ограниченными ресурсами и без внешних сетей
docker run -d \
--name ecc-test \
--cpus="2" \
--memory="4g" \
--restart=no \
--network=none \
-v "$(pwd)/tests:/tests" \
affaan-m/ecc:latest \
./run_tests.sh
docker run— базовый образ, запущенный в фоне (-d).--cpusи--memory— ограничиваем потребление, чтобы не «перегрузить» хост.--network=none— полностью отключаем сеть; при необходимости добавляем отдельные правила nftables.
Дополнительная проверка через firejail
bashfirejail --net=none --private=~/ecc_test affaan-m/ecc:latest ./run_tests.sh
firejail— дополнительно ограничивает доступ к файловой системе и процессам.
Что проверять
- Время выполнения теста (CPU usage, memory pressure).
- Наличие утечек памяти или «зависаний» процессов.
- Соответствие ограничениям, заданным в
docker-compose.ymlилиpodman‑конфигурации.
рекомендуется запускать каждый тест в отдельном контейнере, а не переиспользовать один и тот же образ.
Оптимизация ИИ-агентов с помощью системы ECC
Ponytail: как научить AI‑агента писать меньше кода
Постоянный аудит и улучшение
После того как базовый образ прошёл тесты, необходимо внедрить непрерывный аудит: мониторинг ресурсов, контроль поведения процессов и автоматическое обнаружение отклонений.
Инструменты аудита
- auditd — системный аудит вызовов ядра.
- falco — rules‑based обнаружение аномального поведения.
- Wazuh — сбор метрик и оповещения о отклонениях.
Пример правила auditd
bash# Записываем все вызовы execve, связанные с агентом
auditctl -a always,exit -F arch=b64 -S execve -k agent_exec
auditctl -a always,exit -F arch=b32 -S execve -k agent_exec
- Правила фиксируются в
/etc/audit/rules.d/agent.rulesи загружаются при старте службыauditd.
Falco rule для подозрительного запуска
yaml- rule: Suspicious agent exec
command: /usr/bin/agent* # шаблон имени процесса
condition: exit = 0 and proc.name != "agent_known"
output: "Agent started (user=%user.name pid=%proc.id)"
priority: WARNING
Автоматизация через CI
В GitHub Actions (или аналогичном) можно добавить шаг, который запускает falco в режиме dry‑run и проверяет, что количество тревог = 0.
yaml- name: Run Falco audit
uses: docker://falcoorg/falco:latest
with:
args: -c /etc/falco/rules.d/audit.yaml --output json
# Далее — проверка кода возврата и количества сообщений
настоятельно рекомендуется включать в пайплайн проверку метрик CPU > 80 % и памяти > 70 % за последние 5 минут.
Чек‑лист дальнейших действий
- Запустить тестовый контейнер с ограниченными ресурсами (docker/firejail).
- Настроить auditd‑правила для отслеживания execve‑вызовов агента.
- Добавить Falco‑правила, покрывающие аномальный запуск процессов.
- Интегрировать аудит в CI/CD (GitHub Actions, GitLab CI).
- Регулярноreview‑ить логи Wazuh/OSSEC и корректировать пороги тревог.
- Проводить периодический benchmark‑тест (например, 1000 запросов/сек) и сравнивать с базой.
affaan-m/ECC: Agent Harness Performance Optimization
StarSling: Self-Improving CI for Agent-Volume Repos
StarSling: AI‑driven CI for agent‑volume GitHub Actions
Часто задаваемые вопросы
Зачем нужен ECC, если Claude Code уже работает без него?
ECC не заменяет агент, а добавляет к нему единый слой управления: навыки, память и телеметрия выносятся в отдельные сервисы. Это заметно на длинных сессиях, где встроенный контекст агента заканчивается быстрее, чем нужно. На практике я видел случай, когда команда отказывалась от ECC после первого дня — потом возвращалась, когда задачи выросли. Рекомендуется начинать с тестовой среды и мерить, а не переносить сразу всё.
Почему ecc-agent падает сразу после запуска?
Типовая ошибка — запуск агента до готовности config-loader: конфиг остаётся nil, процесс падает без внятного стека. Проверьте в docker-compose.yml зависимость condition: service_healthy и наличие healthcheck у config-loader. Если healthcheck есть, а падение повторяется — смотрите логи docker logs ecc-agent и порядок старта сервисов. Не делайте так: не отключайте healthcheck ради скорости запуска.
Можно ли запускать ECC в production?
Можно, но не так, как в примере из статьи. Привилегированный контейнер допустим только в тестовой среде; в production используйте user: 1000:1000 и --cap-drop ALL. Настоятельно рекомендуется ограничить сеть агента только теми портами, которые нужны для gRPC и телеметрии. С точки зрения безопасности каждый открытый порт должен быть обоснован.
Какие инструменты поддерживает ECC?
В статье указаны адаптеры для Claude Code, Codex, Opencode и Cursor. Работает это через отдельный модуль adapters, так что добавление нового клиента — вопрос конфигурации, а не переписывания ядра. Рекомендуется проверять актуальный список адаптеров в репозитории, прежде чем строить план миграции.
Безопасно ли давать ECC доступ к коду и токенам?
Нет ничего безопасного по умолчанию — проверяйте, что именно агент читает и куда отправляет. Настоятельно рекомендуется запускать ECC в изолированной сети, без доступа к переменным окружения с прод-токенами. Категорически не рекомендуется монтировать в контейнер директории с ключами и .env файлами. С точки зрения безопасности минимальный набор прав — единственный рабочий вариант.