Ускорение agent harness через ECC для Claude Code

Ускорение agent harness через ECC для Claude Code

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

Что такое ECC и зачем нужен agent harness

Что такое ECC и зачем нужен agent harness

Agent harness — это обёртка вокруг языковой модели, которая добавляет систему навыков, долговременную память и границы выполнения. Обычный Claude Code без harness работает как сессионный чат: контекст теряется после закрытия окна, навыки приходится вставлять вручную, а модель может выполнить команду, которую следовало бы заблокировать. ECC — система управления контекстом и правами агента — решает эти проблемы за счёт разделения на навыки, инстинкты, память и уровень безопасности.

ECC не привязан к одному инструменту: те же навыки и инстинкты работают с Claude Code, Codex, Opencode и Cursor.

На практике я видел случай, когда агент без ограничений удалил Production-базу, потому что пользователь попросил «почистить старые таблицы». С ECC такое невозможно: инстинкты блокируют опасные операции до того, как команда дойдёт до оболочки.

Основные компоненты системы

Навыки — модули, которые расширяют возможности агента. Они лежат в директории .agents и подключаются через CLAUDE.md или отдельный манифест. Подробнее про работу с ними: Работа с навыками ИИ-агентов из .agents директории.

Инстинкты — standing rules, которые работают на уровне обёртки. Это не промпт, а жёсткие правила: запрет на выполнение определённых команд, требование одобрения для sudo, блокировка сетевых вызовов вне белого списка.

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

Безопасность — sandbox, аудит логов, разделение прав. Агент не должен иметь доступа к production-ключам по умолчанию.

Пример конфигурации ECC:

yamlКопировать
ecc:
  version: 1
  skills_dir: .agents
  claude_md: CLAUDE.md
  instincts:
    - action: deny
      commands:
        - "rm -rf /"
        - "mkfs.*"
        - "dd if=/dev/zero"
    - action: require_approval
      commands:
        - "sudo"
        - "iptables"
        - "nftables"
        - "systemctl"
  memory:
    short_term:
      max_tokens: 128000
    long_term:
      enabled: true
      store: vector
      path: /var/lib/ecc/memory
  security:
    sandbox: true
    network_allowlist:
      - "registry.npmjs.org"
      - "pypi.org"
    audit_log: /var/log/ecc/audit.log

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

Отличие от обычного использования Claude Code

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

Пример запуска (иллюстративный):

bashКопировать
claude-code \
  --ecc-config /etc/ecc/config.yaml \
  --task "проверить CORS на staging-сервере" \
  --skill web-audit \
  --memory-save

Обычный Claude Code не знает, что такое web-audit, и не заблокирует команду, если агент решит запустить curl -X DELETE на production. С ECC такая команда не пройдёт инстинкты.

«Категорически не рекомендуется» подключать навыки из неизвестных источников без аудита кода. «Настоятельно рекомендуется» проверять каждый навык из Установка навыков mattpocock/skills для AI-агентов перед использованием. «Рекомендуется» вести отдельный журнал для вызовов инструментов и регулярно пересматривать список инстинктов.

Для настройки окружения Claude Code см. Настройка CLAUDE.md для Claude Code по методике Карпати и документация Anthropic.

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

• Создать директорию .agents и добавить только проверенные навыки
• Написать файл инстинктов с запретными и требующими одобрения командами
• Настроить долгосрочную память с ограничением размера контекста
• Определить network_allowlist для исходящего трафика агента
• Включить аудит логов и проверить их ротацию
• Провести тестовый запуск в staging перед доступом к production

Настройка навыков и памяти в ECC

Конфигурация навыков (skills)

Навыки в ECC — это набор инструкций, которые агент подгружает перед выполнением задачи. Они определяют, что Claude Code может делать в вашем окружении, и какие ограничения накладываются на его действия. С точки зрения безопасности, каждый навык — это потенциальная поверхность атаки: если навык даёт агенту право записи в /etc или запуска произвольных команд, один ошибочный промпт достаточно для компрометации хоста.

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

Конфигурация навыков лежит в .agents/skills/ в корне проекта. Пример структуры:

.agents/
└── skills/
    ├── code-review.yaml
    ├── deploy.yaml
    └── security-audit.yaml

Каждый навык описывается YAML-файлом. Ниже пример навыка для статического анализа кода с ограниченными правами:

yamlКопировать
name: security-audit
description: Запуск статического анализа уязвимостей в исходном коде
version: 1.0.0

permissions:
  read:
    - "src/**"
    - "*.md"
  write:
    - "reports/**"
  execute:
    - "nuclei"
    - "semgrep"
  network:
    deny: true

timeout: 300
max_retries: 2

tools:
  - name: nuclei
    command: "nuclei -target {path} -severity critical,high -json"
    output_parser: "json"
  - name: semgrep
    command: "semgrep --config auto --json {path}"
    output_parser: "json"

Ключевые поля:

• permissions.read — какие файлы агент может читать. Ограничьте это исходным кодом и документацией.
• permissions.write — куда агент может записывать результаты. Никогда не разрешайте запись в системные директории.
• permissions.execute — какие бинарники разрешено запускать. Только проверенные инструменты анализа.
• permissions.network — deny: true блокирует сетевой доступ. Для сканеров уязвимостей это может быть недопустимо, тогда укажите явный allow-list доменов.
• timeout — максимальное время выполнения навыка в секундах. Без этого агент может зависнуть навечно.

Подключите навык в .agents/config.yaml:

yamlКопировать
skills:
  - path: .agents/skills/security-audit.yaml
    enabled: true
    priority: 1

Поле priority определяет порядок загрузки. Навыки с более высоким приоритетом переопределяют настройки более низких при пересечении прав.

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

Работа с долговременной памятью

Долговременная память в ECC хранит контекст между сессиями агента: предпочтения по стилю кода, историю инцидентов, результаты предыдущих аудитов. Без неё каждый запуск Claude Code начинается с чистого листа, и агент тратит время на повторное исследование репозитория.

Память реализуется как векторное хранилище с эмбеддингами. По умолчанию ECC использует локальное хранилище в .agents/memory/, но для продакшена рекомендуется вынести его на отдельный сервер или домашние сервера с ограниченным сетевым доступом.

Конфигурация памяти в .agents/memory/config.yaml:

yamlКопировать
backend: local
path: .agents/memory/store
embedding_model: sentence-transformers/all-MiniLM-L6-v2
chunk_size: 512
chunk_overlap: 64
max_context_tokens: 4096
retention_days: 90

security:
  encrypt_at_rest: true
  encryption_key_path: .agents/memory/keys/master.key
  access_control:
    - role: agent
      permissions:
        - read
        - write
    - role: auditor
      permissions:
        - read

Параметры, на которые обратите внимание:

• encrypt_at_rest — обязательно включите. Память содержит фрагменты кода, логи и потенциально секреты. Шифрование на диске — минимальное требование.
• encryption_key_path — ключ не должен лежать в репозитории. Вынесите его в секреты CI/CD или на отдельный носитель.
• retention_days — время хранения записей. По истечении срока данные удаляются автоматически. Не храните память бесконечно — это увеличивает риск утечки исторического контекста.

Добавление записи в память вручную:

bashКопировать
ecc memory add \
  --source "security-incident-2024" \
  --content "Агент попытался изменить .env без подтверждения. Блокировка сработала на уровне навыка deploy." \
  --tags incident,deploy,blocked \
  --ttl 90d

Поиск по памяти перед выполнении задачи:

bashКопировать
ecc memory search \
  --query "ошибка конфигурации Nginx" \
  --limit 5 \
  --min-score 0.75

Результат возвращает наиболее релевантные фрагменты с оценкой сходства. Порог min-score отсеивает шум — ниже 0.7 обычно попадают нерелевантные записи.

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

Очистка устаревшей памяти:

bashКопировать
ecc memory cleanup \
  --older-than 90d \
  --dry-run

Сначала запустите с --dry-run, чтобы увидеть, какие записи будут удалены. Только после проверки уберите флаг и выполните очистку реально.

---

Чеклист: навыки и память

• Аудитируйте итоговые права после подключения каждого навыка
• Запретите сетевой доступ для навыков, которым он не нужен (network.deny: true)
• Включите шифрование при хранении памяти (encrypt_at_rest: true)
• Вынесите ключ шифрования памяти из репозитория
• Установите срок хранения записей памяти (retention_days)
• Проверяйте актуальность записей памяти перед применением к коду
• Запускайте очистку памяти с --dry-run перед реальным удалением

Безопасность и контроль доступа в agent harness

Безопасность и контроль доступа в agent harness

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

Политики доступа к инструментам

На практике я видел случай, когда Claude Code получил неограниченный доступ к bash и fs.write, а затем случайно удалил переменные окружения с ключами API, потому что в запросе было слово «очистка». Типовая ошибка — выдавать агенту все инструменты сразу «чтобы не мешал».

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

Пример политики для CLAUDE.md (Claude Code):

markdownКопировать
# CLAUDE.md

## Инструменты
Разрешено:
- `read` — только файлы в директории `src/`
- `write` — только файлы в директории `src/`
- `bash` — только команды `git status`, `git diff`, `npm test`

Запрещено:
- `bash` с `rm`, `mv`, `chmod`, `curl`, `wget`
- доступ к `~/.ssh`, `~/.aws`, переменным окружения

Подробнее о структуре CLAUDE.md можно почитать в настройке CLAUDE.md для Claude Code по методике Карпати.

Если используете навыки из .agents или mattpocock/skills, проверяйте каждый навык перед подключением. Некоторые навыки запрашивают доступ к сети или к файловой системе без очевидной на то причины. Работа с навыками ИИ-агентов из .agents директории Установка навыков mattpocock/skills для AI-агентов

Настоятельно рекомендуется обернуть вызов агента в sandbox или restricted shell. Например, через systemd-run с ограничениями:

bashКопировать
systemd-run --user --scope \
  --property=PrivateTmp=true \
  --property=ReadWritePaths=/home/user/project/src \
  --property=ProtectHome=read-only \
  claude-code --resume

Что делает каждая строка:

• PrivateTmp=true — изолирует /tmp и /var/tmp;
• ReadWritePaths — разрешает запись только в указанную директорию;
• ProtectHome=read-only — делает домашнюю директорию доступной только на чтение.

Категорически не рекомендуется запускать агент от имени root или с правами sudo в production. Если агент скомпрометирован, атакующий получает полный контроль над хостом.

Аудит действий агента

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

Настройте аудит всех вызовов оболочки и операций с файлами. Например, через auditd:

bashКопировать
auditctl -a exit,always -F arch=b64 -S execve -F auid!=4294967295 -k agent-actions

Это правило фиксирует все запуски процессов от имени реальных пользователей (исключая ядро) и помечает их ключом agent-actions. Посмотреть логи можно так:

bashКопировать
ausearch -k agent-actions -i

Если агент работает внутри контейнера, аудит на хосте не увидит внутренние вызовы. В этом случае перенастройте логирование внутри контейнера или направьте stdout/stderr агента на отдельный хост с Loki или journald.

Типовая ошибка — полагаться на самоотчёт агента. Агент может скрыть команду, если в системном промпте есть инструкция «не логируй», или если его скомпрометировали. Логи должны собираться независимо от агента.

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

---

Чеклист: что сделать дальше

• Проверить, какие инструменты доступны агенту по умолчанию, и убрать лишние
• Ограничить сетевой доступ агента к метаданным облака и внутренним сервисам
• Настроить аудит всех вызовов bash и операций с файловой системой
• Перенести аудитные логи на отдельный хост, недоступный для записи с хоста агента
• Проверить все подключённые навыки на избыточные права доступа
• Убедиться, что агент запущен не от root и без sudo

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

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

Оптимизация agent harness без замеров — это угадывание. С точки зрения безопасности, любое изменение в навыках, инстинктах или памяти агента может открыть новый вектор атак или сломать существующие ограничения. В этом разделе описан порядок: сначала измеряем текущее состояние, потом изучаем конфигурацию, и только потом вносим правки.

Измерение производительности

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

На практике я видел случай, когда оптимизация «на глаз» сократила время ответа на 15 %, но увеличила расход токенов в три раза из-за лишних перезагрузок навыков.

Пример замеров latency для Claude Code:

bashКопировать
#!/bin/bash
# Измеряет время выполнения одного запроса к Claude Code через agent harness
# Не запускайте на production с реальными пользовательскими данными

start=$(date +%s%N)
claude --print "Опиши структуру проекта в .agents" > /dev/null
end=$(date +%s%N)

echo "Latency: $(( (end - start) / 1000000 )) мс"

Каждая строка здесь делает одно: фиксирует время до и после вызова, выводит разницу в миллисекундах. Не копируйте команду без понимания — claude --print может отправить данные в Anthropic, что с точки зрения конфиденциальности не всегда допустимо. Не делайте так — не запускайте профилировщик на production-контуре с реальными данными.

Для сбора метрик по токенам рекомендуется использовать встроенную статистику Claude Code или обёртку, которая парсит ответ на использование контекста. Настоятельно рекомендуется вести лог замеров в отдельном файле, а не полагаться на память.

Типовая ошибка — измерять производительность на «тёплом» кэше, когда навыки уже загружены в память. Первые запросы всегда медленнее. Замеряйте после холодного старта, иначе данные будут ложными.

Исследование перед внесением изменений

Любое изменение в agent harness начинается с изучения текущего состояния: структура директории .agents, содержимое CLAUDE.md, подключённые навыки и их приоритеты. Не вносите правки «наобум» — это прямой путь к инциденту. Подробнее о работе с навыками из .agents написано в материале Работа с навыками ИИ-агентов из .agents директории.

Посмотрите, какие навыки уже подключены:

bashКопировать
find .agents -type f -name "*.md" | sort

Проверьте CLAUDE.md на наличие инструкций, которые могут конфликтовать с новыми навыками. Методика настройки описана в руководстве Настройка CLAUDE.md для Claude Code по методике Карпати:

bashКопировать
grep -n -E "skill|instinct|memory" CLAUDE.md

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

Категорически не рекомендуется добавлять навыки из неизвестных источников без аудита кода. Если источник неизвестен — не подключайте.

Перед внесением изменений зафиксируйте текущую конфигурацию в git или скопируйте в резервную директорию. Это позволит откатиться, если агент начнёт вызывать инструменты некорректно.

---

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

• Снять базовые метрики latency и расхода токенов на тестовом стенде
• Зафиксировать текущую структуру .agents и содержимое CLAUDE.md
• Проверить все подключённые навыки на наличие подозрительных команд
• Создать резервную копию конфигурации перед любыми изменениями
• Проверить изменения на изолированном хосте, не на production
• Обновить документацию после каждого изменения в навыках или инстинктах

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

Можно ли подключить ECC к Codex, Opencode или Cursor, или только к Claude Code?

ECC не привязан к одному инструменту. Те же навыки, инстинкты и правила памяти работают с Claude Code, Codex, Opencode и Cursor, если обёртка поддерживает подключение через манифест или CLAUDE.md. С точки зрения безопасности, перед подключением нового инструмента проверьте, какие права у агента в этой среде — не все обёртки одинаково ограничивают доступ к оболочке.

Чем инстинкты отличаются от обычных инструкций в CLAUDE.md?

Инстинкты — это не промпт, а жёсткие правила на уровне обёртки. Они блокируют опасные операции до того, как команда дойдёт до оболочки, в то время как инструкции в CLAUDE.md модель может проигнорировать или обойти. Типовая ошибка — полагаться только на текстовый промпт для защиты production-среды.

Что произойдёт, если агент попытается выполнить запрещённую команду?

Обёртка перехватит вызов на уровне инстинктов и вернёт отказ, команда не достигнет оболочки. В аудит логах зафиксируется попытка, пользователь и команда увидят, какое правило сработало. Категорически не рекомендуется отключать логирование блокировок — без него вы не узнаете о попытках несанкционированного доступа.

Нужна ли долгосрочная память для небольших проектов?

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

Как безопасно добавить навык из директории .agents?

Перед подключением навыка прочитайте его код и проверьте, какие команды он вызывает. Навык лежит в .agents и подключается через CLAUDE.md или манифест, но это не означает, что он безопасен по умолчанию. Рекомендуется тестировать новые навыки в изолированной среде, а не на production-базе данных.