affaan-m/ECC: Agent Harness Performance Optimization

affaan-m/ECC: Agent Harness Performance Optimization

Agent harness for Claude Code, Codex, Opencode, Cursor and beyond, focusing on skills, instincts, memory, security, research‑first development.

Архитектура и Основные Компоненты

Структура Agent Harness

Agent Harness представляет собой набор модулей, отвечающих за управление агентами, их память, безопасность и процесс исследований.

Главные компоненты

• Core Engine – ядро, которое инициализирует агентов, загружает конфиги и управляет жизненным циклом.
• Agent Manager – отвечает за регистрацию, отписку и мониторинг состояния агентов.
• Memory Store – хранит контекстные данные, историю диалогов и кеширует результаты исследований.
• Security Layer – проверяет запросы на выполнение опасных команд, ограничивает привилегии и логирует события.
• Research Pipeline – последовательность шагов: поиск уязвимостей → анализ → рекомендации → применение исправлений.

Пример структуры проекта

bashКопировать
agent-harness/
├── core/
│   ├── engine.py
│   └── config.yaml
├── managers/
│   └── agent_manager.py
├── storage/
│   └── memory_store.py
├── security/
│   └── security_policy.json
└── pipelines/
    └── research_pipeline.py

Конфиг‑пример (config.yaml)

yamlКопировать
# config.yaml – базовые настройки harness
log_level: INFO
max_concurrent_agents: 5
security:
  sandbox: true
  allowed_commands:
    - git
    - curl
    - docker
    - npm
  blocked_commands:
    - rm -rf /
    - chmod 777
    - sudo
memory:
  engine: sqlite
  cache_ttl_seconds: 3600

Важно: с точки зрения безопасности не делайте запуск harness в режиме sandbox: false на production‑серверах – это отключает изоляцию и может привести к компрометации системы.

Запуск harness

bashКопировать
# Запуск в режиме отладки
python -m agent_harness.core.engine --config config.yaml --debug

---

Интеграция с Claude Code и Cursor

Интеграция происходит через переменные окружения, CLI‑интерфейс и файловую систему. Claude Code и Cursor могут вызывать функции harness, передавая им задачи в виде JSON‑payload.

Подключение через Claude Code

1. Установите переменную окружения AGENT_HARNESS_PATH – путь к корню проекта harness.
2. В файле claude.cfg укажите команду для запуска агента:

iniКопировать
[agent]
command = python -m agent_harness.core.engine --config /path/to/config.yaml
env:
  AGENT_HARNESS_PATH = /home/user/agent-harness

Пример вызова из Claude Code

bashКопировать
# Внутри Claude Code (CLI)
agent_run --task "сканировать порт 22 на наличие устаревших SSH‑ключей" \
          --config /home/user/agent-harness/config.yaml

Интеграция с Cursor

Cursor использует механизм «watch‑folder». Чтобы подключить harness:

• Создайте директорию cursor_hooks/ в проекте.
• Поместите в неё скрипт run_harness.sh, который будет вызываться при изменении файлов.

Скрипт run_harness.sh

bashКопировать
#!/usr/bin/env bash
# cursor_hooks/run_harness.sh – вызывается Cursor при сохранении файла

set -euo pipefail

CONFIG="/home/user/agent-harness/config.yaml"
TASK="${1:-}"   # задача передаётся как первый аргумент

python -m agent_harness.core.engine --config "$CONFIG" --task "$TASK"

Ссылка на подробную настройку – см. Настройка Claude Code через CLAUDE.md и Настройка CLAUDE.md для Claude Code.

Рекомендации

• рекомендуется проверять список allowed_commands перед запуском любого агента.
• настоятельно рекомендуется включать sandbox: true в production‑конфиге.
• категорически не рекомендуется передавать в payload команды, требующие привилегий sudo или rm -rf /.

Практический пример

на практике я видел случай, когда агент, не ограниченный sandbox‑ом, выполнил rm -rf /tmp/backup и удалил критические логи, что привело к потере данных. Поэтому всегда проверяйте security_policy.json перед включением агента в продакшн.

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

• Установить AGENT_HARNESS_PATH в окружении Claude Code и Cursor.
• Проверить allowed_commands в config.yaml.
• Запустить harness в режиме --debug и убедиться в отсутствии небезопасных команд.
• Включить sandbox: true для production‑развёртывания.
• Регулярно аудировать security_policy.json на наличие новых блокированных команд.

Стратегии Оптимизации Производительности

Управление памятью и кеширование

Когда мы говорим об использовании AI-агентов вроде Claude Code или Cursor в рамках ECC: Agent Harness Performance Optimization, основной проблемой становится не вычислительная мощность, а «раздувание» контекстного окна. Типовая ошибка — позволять агенту считывать весь репозиторий при каждом запросе. Это не только раздувает счета за токены, но и увеличивает задержку (latency), превращая работу в ожидание ответа.

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

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

1. L1 (Context Cache): Текущий активный контекст (последние N сообщений и измененные файлы).
2. L2 (Semantic Memory): Векторная база данных с эмбеддингами ключевых функций и документации.
3. L3 (File System Index): Быстрый индекс структуры проекта (tree-sitter или аналоги).

Для оптимизации работы с локальными файлами при использовании агентов, настоятельно рекомендуется ограничивать области видимости через .gitignore и специализированные файлы конфигурации. Если вы настраиваете среду, обязательно изучите настройку CLAUDE.md для Claude Code, чтобы задать агенту четкие границы работы с памятью.

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

yamlКопировать
# Пример логики фильтрации контекста для агента
context_management:
  exclude_patterns:
    - "**/node_modules/**"
    - "**/dist/**"
    - "**/.git/**"
    - "**/build/**"
    - "**/*.log" # Категорически не рекомендую давать агенту доступ к сырым логам без предварительной фильтрации
  cache_strategy:
    semantic_search: true
    max_context_tokens: 20000 # Жесткий лимит для предотвращения runaway-затрат

Настройка на уровне инструкций

Оптимизация производительности — это не только про кэш, но и про то, как вы формулируете системные инструкции. В ECC акцент сделан на «research-first development». Это значит, что агент сначала должен сформировать план исследования, а не сразу бросаться писать код.

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

Настройка инструкций должна следовать иерархии:

1. Анализ (Observation): Сбор данных о структуре и зависимостях.
2. Гипотеза (Reasoning): Формирование плана изменений.
3. Исполнение (Action): Применение изменений в изолированной среде.

Чтобы агент работал эффективно и не тратил токены на лишние рассуждения, необходимо использовать технику «Chain-of-Thought» (цепочка мыслей), но в ограниченном виде. Вместо того чтобы просить агента «думать вслух» бесконечно, мы задаем ему жесткий формат ответа.

Если вы используете Claude Code, крайне рекомендую прописать в CLAUDE.md правила, запрещающие агенту выполнять действия без предварительного подтверждения плана.

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

markdownКопировать
# Инструкция по выполнению задач (Agent Protocol)

1. ПЕРЕД любым изменением кода:
   - Проведи поиск по символам (grep/ripgrep) для определения зависимостей.
   - Сформулируй краткий план (max 3 пункта).
   - Ожидай подтверждения.

2. ПРАВИЛА КОДА:
   - Не используй устаревшие библиотеки.
   - Всегда проверяй наличие обработки ошибок.
   - При обнаружении потенциальной уязвимости (например, отсутствие валидации входных данных) — немедленно останови выполнение и сообщи.

3. ОГРАНИЧЕНИЯ:
   - Запрещено изменять конфигурационные файлы системы (systemd, iptables и т.д.) без явного указания.

Не делайте так: не давайте агенту полный доступ к терминалу с правами root. Это классическая ошибка при развертывании инструментов автоматизации. Агент должен работать в ограниченном окружении, где его возможности по манипуляции системой строго регламентированы. Для более глубокого понимания архитектуры подобных инструментов, можно изучить проект Claw-Code, где реализован более строгий контроль над поведением агента.

Безопасность и Управление Доступом

Безопасность и Управление Доступом

Когда мы говорим об использовании ИИ-агентов вроде Claude Code или Cursor, основная ошибка — воспринимать их как обычные IDE. С точки зрения безопасности, агент — это высокопривилегированный пользователь с потенциально непредсказуемым поведением. Он может генерировать код, выполнять команды в терминале и обращаться к файловой системе. Если вы даёте агенту полный доступ к своей рабочей директории без ограничений, вы фактически предоставляете ему право на выполнение произвольного кода (RCE) в вашем окружении.

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

Аутентификация и Ограничение Разрешений

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

На практике я видел случаи, когда агенты, пытаясь «исправить» права доступа к файлам, случайно выставляли 777 на важные директории или конфигурационные файлы.

Рекомендуется использовать принцип наименьших привилегий (PoLP). Агент должен работать в изолированном окружении под отдельным пользователем с ограниченным набором прав.

При настройке окружения через CLAUDE.md обязательно прописывайте ограничения на выполнение команд. Если вы используете Docker для запуска агента, используйте флаг --user, чтобы агент не работал под root.

Пример запуска контейнера с агентом под ограниченным пользователем:

bashКопировать
# Создаем системного пользователя без возможности входа в shell
sudo useradd -r -s /usr/sbin/nologin agent_user

# Запускаем контейнер, ограничивая права пользователя и файловую систему
docker run -it \
  --user agent_user:agent_user \
  --read-only \
  --tmpfs /tmp \
  -v $(pwd):/app:ro \
  claude-code-image

Обратите внимание: флаг -v $(pwd):/app:ro монтирует вашу рабочую директорию только в режиме «чтения». Это категорически рекомендуется, если агент занимается только анализом кода или поиском уязвимостей, а не написанием фиксов. Если же агенту нужно писать код, используйте отдельные поддиректории, доступные только ему.

Изоляция сети и Zero-Trust

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

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

Для этого лучше всего использовать nftables или специализированные прокси-серверы. Если вы запускаете агента на домашнем сервере, настройте правила так, чтобы он мог обращаться только к API Anthropic или GitHub.

Пример базового правила nftables для ограничения исходящего трафика (предварительно настройте разрешенные IP/домены):

bashКопировать
# Создаем таблицу для управления трафиком агента
table inet agent_isolation {
    chain output {
        type filter hook output priority 0; policy drop;

        # Разрешаем локальный loopback
        oifname "lo" accept

        # Разрешаем доступ к API Anthropic (пример для конкретного IP)
        ip daddr 142.250.0.0/15 accept

        # Разрешаем DNS запросы к вашему доверенному DNS-серверу
        udp dport 53 accept
    }
}

Перед применением таких правил обязательно проверьте текущую конфигурацию через nft list ruleset.

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

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

• Агент запущен под отдельным пользователем с ограниченными правами.
• Файловая система агента смонтирована в режиме read-only там, где это возможно.
• Доступ к секретам (API keys, SSH keys) ограничен через переменные окружения или защищенные хранилища, а не через файлы в рабочей директории.
• Исходящий сетевой трафик ограничен списком разрешенных доменов.
• Все действия агента логируются (используйте auditd для мониторинга системных вызовов).

Рабочий Поток Разработки Сначала Исследований

Рабочий поток: сначала исследования

Когда вы работаете с AI-агентами вроде Claude Code или Cursor, возникает соблазн сразу броситься писать код. Это типовая ошибка. В контексте использования ECC (Agent Harness) подход должен быть обратным: сначала исследовательская фаза, затем генерация. Если агент начнет писать код на основе неполных данных, вы получите не решение, а набор галлюцинаций, которые потом придётся вычищать вручную.

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

Итеративное тестирование и валидация

В рамках ECC: Agent Harness Performance Optimization основной упор сделан на то, чтобы агент не просто выдавал результат, а проверял его на каждом этапе. Это называется исследовательским подходом (research-first).

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

Каждый шаг должен сопровождаться автоматической проверкой. Если вы используете Claude Code, крайне важно правильно настроить контекст через CLAUDE.md, чтобы агент знал, какие тесты считать успешными.

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

bashКопировать
# 1. Создаем изолированную среду для теста (рекомендуется использовать контейнеры)
docker run --rm -v $(pwd):/app -w /app python:3.11-slim bash

# 2. Агент должен сначала выполнить сканирование зависимостей
pip install safety && safety check

# 3. Запуск итеративного теста
# Вместо простого запуска кода, агент выполняет:
python -m pytest tests/test_new_feature.py --verbose

Никогда не позволяйте агенту выполнять команды изменения состояния (например, rm -rf или apt upgrade) без предварительного вывода dry-run или проверки текущего состояния системы. Перед выполнением любой команды, которая может изменить конфигурацию, агент обязан предоставить отчет о том, что именно он собирается сделать.

Документация и обмен знаниями

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

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

Типовой рабочий процесс документирования выглядит так:

1. Агент находит уязвимость или несоответствие в архитектуре.
2. Агент записывает это в ARCHITECTURE.md или обновляет CLAUDE.md.
3. Агент предлагает исправление, основываясь на обновленных данных.

Пример структуры блока в CLAUDE.md для фиксации исследовательских выводов:

markdownКопировать
## Research Findings: Module X
- **Status**: Validated
- **Discovery**: Dependency 'libfoo' version 2.0 introduces a breaking change in API.
- **Mitigation**: Switched to version 1.8.5 to maintain compatibility with legacy modules.
- **Security Note**: Ensure that the fallback mechanism is tested in CI/CD.

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

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

• Агент всегда начинает с анализа существующего кода и документации, а не с написания нового.
• Все изменения в зависимостях проходят через проверку безопасности (например, safety или npm audit).
• Результаты исследований агента фиксируются в файлах проекта (.md), а не остаются только в истории чата.
• Тесты запускаются автоматически после каждой итерации изменения кода.

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

Как обеспечить безопасность при использовании Agent Harness?

С точки зрения безопасности, критически важно держать параметр sandbox в значении true даже при разработке. Настоятельно рекомендуется использовать изолированные среды, такие как Docker-контейнеры, для запуска агентов, чтобы минимизировать риски при выполнении команд. Типовая ошибка — расширение списка allowed_commands до включения инструментов с широкими привилегиями без дополнительного контроля.

Можно ли использовать Agent Harness на критически важных серверах?

Категорически не рекомендуется запускать harness напрямую на production-серверах, где находятся важные данные или инфраструктура. Любой агент, имеющий доступ к файловой системе или сетевым запросам, потенциально может стать вектором атаки. На практике я видел случаи, когда ошибки в логике агента приводили к непредсказуемым изменениям в конфигурационных файлах системы.

Как ограничить права агентов при выполнении команд?

Для контроля действий агентов необходимо правильно настроить security_policy.json и список allowed_commands в config.yaml. Не делайте список разрешенных команд слишком обширным: включайте только те инструменты, которые необходимы для конкретной задачи. Перед внедрением новых команд в белый список обязательно проверьте, не позволяют ли они обойти ограничения через инъекции аргументов.

Как работает механизм памяти в этой архитектуре?

Компонент Memory Store отвечает за хранение контекста и истории взаимодействий, используя SQLite или другие движки для кеширования результатов. С точки зрения защиты данных, важно следить за тем, чтобы в Memory Store не попадали чувствительные секреты, такие как API-ключи или пароли. Рекомендуется проводить регулярную очистку кеша и проверять содержимое хранилища на предмет утечки конфиденциальной информации.