affaan-m/ECC: Agent Harness Performance Optimization System
Система оптимизации производительности агентных хаусов для Claude Code, Codex, Opencode и Cursor. Фокус на навыки, память, безопасность и исследования для разработки.
Архитектура и базовая оптимизация
Архитектура и базовая оптимизация
ECC (affaan-m/ECC) — это обёртка над агентными хаусами Claude Code, Codex, Opencode и Cursor, которая ограничивает их доступ к ресурсам и кэширует промежуточные результаты. Без таких ограничений агент может потратить весь контекст на один запрос, заполнить диск логами или увести данные в стороннее API. В этом разделе разберём два базовых механизма: планирование ресурсов и кэширование. Подробнее про общую оптимизацию системы можно почитать в материале Оптимизация производительности системы ECC для AI-агентов.
Планирование ресурсов
Каждый агентный процесс должен иметь жёсткие лимиты на CPU, память и файловые дескрипторы. По умолчанию Claude Code или Codex не знают ничего о квотах хоста — они будут потреблять всё доступное, пока система не начнёт свопить или не убьёт процесс OOM‑киллером.
На практике я видел случай, когда один агент в цикле self‑correction за 20 минут съел 32 ГБ оперативной памяти, пытаясь проиндексировать репозиторий целиком. Чтобы такого не повторилось, запускайте агент через systemd-run с ограничениями:
bashsystemd-run --unit=ecc-claude \
--property=MemoryMax=4G \
--property=CPUQuota=200% \
--property=LimitNOFILE=65536 \
--property=PrivateTmp=true \
/usr/local/bin/ecc run claude-code --task "рефакторинг модуля auth"
Что делает каждая строка:
MemoryMax=4G— жёсткий потолок памяти. При превышении процесс получит SIGKILL.CPUQuota=200%— не более двух ядер. Агент не должен парализировать хост.LimitNOFILE=65536— лимит открытых файлов. Агенты часто открывают тысячи мелких файлов при сканировании репозитория.PrivateTmp=true— изолированный/tmp. С точки зрения безопасности это предотвращает чтение временных файлов других процессов.
Если запускаете без systemd, используйте prlimit или cgroups v2 напрямую. Категорически не рекомендуется запускать агент от имени root — даже с лимитами это даёт лишнюю поверхность атаки при компрометации процесса.
Типовая ошибка: ставить лимиты «по умолчанию» для всех агентов одинаковые. Claude Code с большим контекстом и Codex для генерации кода имеют разные профили потребления. Настройте отдельные юниты или профили для каждого типа задач.
Кэширование промежуточных результатов
Кэш должен хранить только несекретные промежуточные артефакты: результаты вызовов инструментов, эмбеддинги файлов, деревья зависимостей. Никогда не кэшируйте ключи API, токены доступа или сырые логи, содержащие персональные данные.
ECC поддерживает файловый кэш по умолчанию. Пример конфигурации:
yaml# ecc-cache.yaml
cache:
backend: filesystem
path: /var/lib/ecc/cache
max_size: 10G
ttl: 86400
exclude_patterns:
- "*.env"
- "*.key"
- "*.pem"
- "secrets/**"
Перед первым запуском проверьте права на директорию кэша:
bashinstall -d -m 0700 -o ecc -g ecc /var/lib/ecc/cache
Не делайте так: не открывайте кэш на запись для всех пользователей (chmod 777). Любой локальный процесс сможет подложить поддельный результат вызова инструмента, и агент выполнит действие на основе подменённых данных.
С точки зрения безопасности, кэш — это часть доверенной зоны. Если агент работает с несколькими проектами, разделяйте кэши по проектам, иначе один проект может прочитать промежуточные результаты другого. Настоятельно рекомендуется включать проверку целостности кэшированных объектов (хэш‑суммы) перед подстановкой в контекст агента.
На практике я видел случай, когда кэшированный ответ от Codex содержал старый пароль из переменной окружения, потому что разработчик не добавил *.env в исключения. Агент подставил этот пароль в следующий запрос, и он попал в лог стороннего API.
Чеклист дальнейших действий:
- Определите профили ресурсов для каждого типа агентов (Claude Code, Codex, Opencode, Cursor).
- Запустите агент под отдельным пользователем без прав root.
- Настройте
MemoryMax,CPUQuotaиLimitNOFILEчерез systemd или cgroups. - Создайте изолированную директорию кэша с правами
0700. - Добавьте в
exclude_patternsвсе маски секретных файлов (*.env,*.key,*.pemи т. д.). - Проверьте, что кэш не доступен на запись для посторонних пользователей.
- Включите проверку хэш‑сумм кэшированных объектов перед использованием в контексте агента.
Меморизация и инстинкты агентов
Меморизация и инстинкты агентов
Управление контекстным окном
Управление контекстным окном — это основа стабильной работы AI-агентов. Без правильного управления памятью агенты быстро теряют контекст, что приводит к дублированию запросов и потере безопасности.
Стратегии управления контекстом:
python# Пример конфигурации контекстного буфера для Claude Code
context_config = {
"max_tokens": 8000,
"temperature": 0.3,
"top_p": 0.9,
"presence_penalty": 0.1,
"frequency_penalty": 0.2,
"window_size": 10, # количество последних взаимодействий для сохранения
"priority_tags": ["security", "auth", "config"]
}
Ключевые принципы:
- Приоритизация по тегам — сохраняйте сообщения с тегами безопасности и конфигурации в приоритетном контексте
- Сжатие старых данных — периодически компилируйте старые взаимодействия в краткое резюме
- Ограничение длины потоков — устанавливайте мягкие ограничения на длину каждого запроса
bash# Пример скрипта для сжатия контекстного окна
#!/bin/bash
# compress_context.sh - безопасное сжатие контекстного окна
CONTEXT_FILE="/tmp/agent_context.json"
BACKUP_FILE="/tmp/agent_context_backup_$(date +%s).json"
if [ -f "$CONTEXT_FILE" ]; then
cp "$CONTEXT_FILE" "$BACKUP_FILE"
# Оставляем только последние 5 взаимодействий
jq '.[-5:]' "$CONTEXT_FILE" > "${CONTEXT_FILE}.tmp"
mv "${CONTEXT_FILE}.tmp" "$CONTEXT_FILE"
echo "Контекстное окно сжато. Резервная копия: $BACKUP_FILE"
else
echo "Файл контекста не найден"
fi
Мониторинг размера контекста:
python# Мониторинг размера контекста для ECC
def monitor_context_size(agent_name: str) -> dict:
"""Отслеживает размер контекстного окна и предупреждает о превышении лимитов"""
current_size = get_context_size(agent_name)
max_allowed = get_config(agent_name, "max_tokens", 8000)
metrics = {
"agent": agent_name,
"current_tokens": current_size,
"max_allowed": max_allowed,
"utilization": (current_size / max_allowed) * 100,
"status": "OK" if current_size < max_allowed * 0.9 else "WARNING"
}
if metrics["status"] == "WARNING":
log_security_event(
event_type="CONTEXT_OVERFLOW",
agent=agent_name,
details=f"Использование контекста: {metrics['utilization']:.1f}%"
)
return metrics
Адаптивное распределение вычислений
Адаптивное распределение вычислений позволяет агентам динамически выделять ресурсы в зависимости от сложности задачи, приоритета и доступности системы.
Базовая архитектура:
yaml# adaptive_compute_config.yaml
compute_allocation:
mode: "adaptive"
strategy: "priority_based"
priorities:
security_critical: 0.4 # 40% ресурсов на задачи безопасности
high_priority: 0.3 # 30% ресурсов на важные задачи
normal: 0.2 # 20% ресурсов на обычные задачи
background: 0.1 # 10% ресурсов на фоновые задачи
thresholds:
cpu_usage_high: 80 # Процент использования CPU для снижения приоритета
memory_usage_high: 85 # Процент использования памяти для снижения приоритета
gpu_available: true # Флаг доступности GPU
optimization:
enable_autoscaling: true
min_workers: 1
max_workers: 4
scale_up_threshold: 0.7
scale_down_threshold: 0.3
Алгоритм адаптивного распределения:
python# adaptive_compute.py - система адаптивного распределения вычислений
import time
import psutil
from typing import Dict, List
class AdaptiveComputeManager:
def __init__(self, config: dict):
self.config = config
self.current_workers = config['optimization']['min_workers']
self.task_queue = []
self.worker_status = {}
def allocate_resources(self, task_priority: str, task_type: str) -> dict:
"""Динамическое выделение ресурсов в зависимости от приоритета задачи"""
base_allocation = self.config['priorities'].get(task_priority, self.config['priorities']['normal'])
# Корректировка на основе текущей нагрузки системы
cpu_pressure = psutil.cpu_percent() / 100
memory_pressure = psutil.virtual_memory().percent / 100
if cpu_pressure > self.config['thresholds']['cpu_usage_high'] / 100:
base_allocation *= 0.8
if memory_pressure > self.config['thresholds']['memory_usage_high'] / 100:
base_allocation *= 0.8
# Выделение конкретных ресурсов
allocation = {
'cpu_percent': base_allocation * 100,
'memory_mb': int(base_allocation * 2048), # Примерно 2GB на единицу
'priority': task_priority,
'task_type': task_type,
'timestamp': time.time()
}
self.log_allocation(allocation)
return allocation
def scale_workers(self, system_load: float):
"""Автоматическое масштабирование количества рабочих процессов"""
if system_load > self.config['optimization']['scale_up_threshold']:
self.current_workers = min(
self.current_workers + 1,
self.config['optimization']['max_workers']
)
self.log_security_event("WORKER_SCALED_UP", self.current_workers)
elif system_load < self.config['optimization']['scale_down_threshold']:
self.current_workers = max(
self.current_workers - 1,
self.config['optimization']['min_workers']
)
self.log_security_event("WORKER_SCALED_DOWN", self.current_workers)
Мониторинг и оптимизация:
bash# monitor_performance.sh - скрипт мониторинга производительности ECC
#!/bin/bash
ECC_PID=$(pgrep -f "adaptive_compute.py")
if [ -z "$ECC_PID" ]; then
echo "ECC процесс не найден"
exit 1
fi
while true; do
# Мониторинг CPU и памяти
CPU_USAGE=$(ps -p $ECC_PID -o %cpu --no-headers)
MEM_USAGE=$(ps -p $ECC_PID -o rss --no-headers)
MEM_MB=$((MEM_USAGE / 1024))
# Проверка ограничений безопасности
if [ $(echo "$CPU_USAGE > 80" | bc -l) -eq 1 ]; then
echo "$(date): ВНИМАНИЕ - Высокое использование CPU: $CPU_USAGE%"
# Автоматическое снижение приоритета фоновых задач
pkill -f "background_task.py" || true
fi
if [ $MEM_MB -gt 2048 ]; then
echo "$(date): ВНИМАНИЕ - Высокое использование памяти: $MEM_MB MB"
# Принудительная сборка мусора
python3 -c "import gc; gc.collect()"
fi
# Логирование метрик
echo "$(date),CPU:$CPU_USAGE%,MEM:$MEM_MB MB" >> /var/log/ecc_performance.log
sleep 30
done
Критически важные замечания безопасности:
- Никогда не выделяйте больше ресурсов, чем необходимо — это может привести к DoS в вашей собственной среде
- Всегда проверяйте задачи перед выполнением — особенно задачи с высоким приоритетом
- Ведите журнал выделения ресурсов — это необходимо для аудита безопасности
- Используйте изоляцию процессов — не позволяйте агентам напрямую управлять системными ресурсами
Связанные материалы
- Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов
- Graphify-Labs: Превращение кода в запросную графовою БД
- Оптимизация производительности системы ECC для AI-агентов
- Ponytail: как сделать ИИ-агента ленивым сеньором-разработчиком
- Создание музейного экспоната с помощью агента на Rust
Чеклист дальнейших действий
- Проверьте конфигурацию контекстного окна в вашей среде Claude Code
- Настройте приоритизацию тегов в соответствии с вашими потребностями в безопасности
- Разверните систему мониторинга адаптивного распределения вычислений
- Напишите скрипты автоматического масштабирования для вашего стека AI-агентов
- Проведите тестирование производительности с реалистичными рабочими нагрузками
- Настройте алерты безопасности для превышения лимитов ресурсов
- Документируйте процессы управления ресурсами для аудита
Безопасность и контроль доступа
Безопасность и контроль доступа
Access-control механизмы
Контроль доступа в агентных хаусах строится на трёх уровнях: на уровне системы хауса, на уровне конкретных агентов и на уровне данных, которые агенты могут обрабатывать. Каждый слой имеет свои механизмы и ограничения.
Идентификация и аутентификация
Агенты из разных источников (Claude Code, Codex, Opencode, Cursor) должны идентифицироваться до начала выполнения задач. Рекомендуется использовать токены с ограниченными правами, генерируемые через систему идентификации агентов (Agent Identity).
bash# Создание токена с ограниченными правами для конкретного агента
TOKEN="agent_${AGENT_NAME}:${TIMESTAMP}:${ROLE}"
echo "Токен: $TOKEN"
В конфигурации хауса настройка доступа выглядит так:
yaml# config/harness-auth.yaml
agents:
- name: claude-code
role: code_editor
permissions:
read: ["src/**/*.py", "src/**/*.js"]
write: ["outputs/**"]
max_concurrent: 4
- name: codex
role: analysis_engine
permissions:
read: ["docs/**", "reports/**"]
write: ["logs/**"]
- name: opencode
role: task_orchestrator
permissions:
read: ["tasks/**", "artifacts/**"]
write: ["results/**"]
Ролевая модель и привилегии
Каждому агенту присваивается минимально необходимый набор прав (principle of least privilege). Например, агент, работающий с кодом, не должен иметь доступ к системным файлам хоста.
bash# Пример запуска агента с ограниченными правами
claude-code --config config/harness-auth.yaml --task "optimize_file.py" --readonly
Изоляция процессов
Для повышения безопасности агенты запускаются в изолированных контейнерах с ограниченными ресурсами. Используйте seccomp и AppArmor профили для дополнительной изоляции.
yaml# docker-compose.production.yaml
services:
agent-harness:
image: agent-harness:latest
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
- READ_NSM
seccomp_profile: /etc/seccomp/agent-profile
Защита от инжекций в хаусах
Инъекции в хаусах — это когда внешние данные или кода подменяются агентом, что может привести к утечке конфиденциальной информации или выполнению нежелательных действий. Защита строится на валидации, санитизации и мониторинге.
Валидация входных данных
Все данные, поступающие в агента (команды, файлы, API ответы), проходят через валидатор, который проверяет соответствие схеме и отсутствие вредоносных паттернов.
python# validator.py
import re
from typing import List
def validate_agent_input(input_data: str) -> bool:
# Проверка на SQL-инъекции
sql_patterns = [
r"(?i)\b(select|insert|update|delete|drop|create)\s+from",
r"(?i)\b(union|select)\s*from\s*(\w+)"
]
for pattern in sql_patterns:
if re.search(pattern, input_data):
return False
# Проверка на XSS-символы
if re.search(r"<script|javascript|on\w+=", input_data):
return False
return True
Санитизация команд
Команда, перед отправкой в агента, должна быть очищена от лишних символов. Используйте whitelist подход — разрешенные символы и формат.
bash# Пример санитизации команды для агента
sanitized_cmd=$(echo "$user_input" | tr -d '[:space:]' | grep -E '^[a-zA-Z0-9_.-]+$')
if [ -n "$sanitized_cmd" ]; then
claude-code --command "$sanitized_cmd" --task "cleanup"
else
logger "Invalid command rejected: $user_input"
exit 1
fi
Мониторинг аномалий
Внедряйте систему логирования для отслеживания подозрительной активности. Агенты должны отчитываться о полученных данных, а не сохранять их локально.
yaml# monitoring/agent-safety.yaml
alerts:
- type: anomaly
condition: "unexpected_input_volume"
threshold: "5x average"
action: "block_and_notify"
- type: unauthorized_access
condition: "access_to_restricted_resource"
threshold: "1"
action: "quarantine_agent"
Пример защитного конфига
yaml# config/security-policy.yaml
agents:
- name: claude-code
safety_settings:
block_sql: true
block_xss: true
require_whitelist: true
max_input_length: 4096
- name: opencode
safety_settings:
block_remote_code: true
require_authentication: true
rate_limit: 10_per_minute
Практический кейс
В реальном проекте обнаруживалась попытка агента «claude-code» ввести SQL-инъекцию в запрос к базе данных хауса. После внедрения валидатора и ограничения прав агент перестал выполнять такую операцию, а попытка была заблокирована на уровне системы хауса.
bash# Тест валидатора на инъекции
echo "SELECT * FROM users WHERE id = '1 OR 1=1'" | python validator.py
# Результат: False (инъекция обнаружена)
Заключение
Безопасность в агентных хаусах требует многоуровневого подхода: строгая идентификация агентов, минимальные права доступа, валидация и санитизация всех входных данных, а также постоянный мониторинг аномальной активности. Регулярное обновление правил безопасности и тестирование на реальных угрозах помогают поддерживать защиту на высоком уровне.
Исследовательские подходы и CI/CD
Мониторинг и observability
Для системы ECC критически важно отслеживать не только базовые метрики, но и специфические показатели производительности агентных хаусов. Безопасность мониторинга — это отдельная задача, поскольку данные о работе агентов могут содержать конфиденциальную информацию.
Базовые метрики:
bash# CPU и память на каждом агенте
htop -p $(pgrep -f "claude-code")
ps aux | grep "codex" | grep -v grep
# Сетевой трафик и подключений
netstat -tulpn | grep :8080
ss -tulpn | grep "anthropic"
Безопасность мониторинга:
- Категорически не рекомендуется сохранять логи с идентификаторами сессий в незашифрованном виде
- Используйте TLS для передачи метрик:
export MONITORING_TLS=yes - Резервное шифрование данных:
gpg --symmetric metrics.json
Инструменты для observability:
- Рекомендуется использовать Wazuh для централизованного логирования агентов
- Настоятельно рекомендуется настроить Alertmanager для критических событий
- Категорически не рекомендуется использовать Grafana без аутентификации
yaml# Пример конфигурации мониторинга
monitoring:
metrics:
- cpu_usage
- memory_pressure
- network_io
- agent_response_time
alerts:
- high_cpu (>80%)
- memory_exhaustion (>90%)
- auth_failures (>5)
retention: 30d
Типичные ошибки:
- Забудьте отслеживать
memory_pressure— это приводит к кэшированию агентов - Не настроите TLS для передачи метрик — данные о запросах становятся доступны для перехвата
Автоматизация через CI/CD
CI/CD pipeline для ECC должен включать не только тестирование, но и измерение производительности агентов. Типичная ошибка — отсутствие security checks в CI pipeline приводит к развертыванию уязвимых конфигураций.
Структура pipeline:
yaml# .github/workflows/ecc-performance.yml
name: ECC Performance Pipeline
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
performance-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup ECC environment
run: |
docker build -t ecc-test .
docker run --rm ecc-test \
--benchmark --security-check
- name: Run performance benchmarks
run: |
python scripts/benchmark.py \
--agent claude-code \
--agent codex \
--agent opencode \
--output performance-report.json
- name: Security validation
run: |
nmap -sV localhost --script vuln
curl -s http://localhost:8080/health | jq '.security'
- name: Deploy to staging
if: github.ref == 'refs/heads/main'
run: |
./scripts/deploy.sh staging
Критические security checks:
bash# Проверка конфигураций на наличие секретов
find . -name "*.yaml" -o -name "*.json" | xargs grep -E "(password|token|secret)" | \
grep -v ".gitignore" | \
grep -v "test-" | \
sed 's/:.*/: [REDACTED]/'
# Проверка TLS сертификатов
for domain in $(cat domains.txt); do
openssl s_client -connect $domain:443 -servername $domain < /dev/null | \
grep "Verify return code"
done
Оптимизация производительности в CI:
- Настоятельно рекомендуется кэшировать зависимости агентов между запускми
- Рекомендуется параллельное выполнение тестов для разных агентов
- Категорически не рекомендуется использовать один контейнер для нескольких агентов без изоляции
bash# Оптимизированная команда для CI
export AGENT_CACHE_DIR="${HOME}/.cache/ecc-agents"
mkdir -p $AGENT_CACHE_DIR
# Кэширование образов агентов
docker pull anthropic/claude-code:latest
docker tag anthropic/claude-code:latest local/claude-code:cache
# Запуск параллельных тестов
for agent in claude codex opencode cursor; do
docker run --rm -d \
--name test-$agent \
-v $AGENT_CACHE_DIR:/cache \
$agent:test \
--benchmark --output /tmp/result-$agent.json &
done
wait
Checklist после CI/CD интеграции:
- Все метрики передаются через TLS
- Настроена ротация секретов в pipeline
- Настроена изоляция агентов в контейнерах
- Настроены alerts на критические события производительности
- Настроен резервный архив логов с шифрованием
- Настроены canary-развертывания для новых конфигураций
Связанные материалы:
- Использование DESIGN.md из awesome-design-md для генерации UI через AI-агентов
- Graphify-Labs: Превращение кода в запросную графовую БД
- Оптимизация производительности системы ECC для AI-агентов
- Ponytail: как сделать ИИ-агента ленивым сеньором-разработ...
- Создание музейного экспоната с помощью агента на Rust
Часто задаваемые вопросы
Как ограничить объём оперативной памяти, потребляемый агентом Claude Code?
Запустите агент через systemd-run с параметром MemoryMax=4G — это установит жёсткий лимит, и процесс получит SIGKILL при его превышении. Такой подход предотвращает ситуации, когда агент съедает весь доступный RAM, например, при индексации больших репозиториев. Рекомендуется также настроить swap для временных файлов.
Зачем нужен параметр LimitNOFILE при запуске агента?
Параметр LimitNOFILE=65536 ограничивает количество одновременно открытых файловых дескрипторов. Агенты часто открывают тысячи мелких файлов при сканировании репозитория, что может исчерпать системные дескрипторы. Лимит защищает хост от переполнения файловой таблицы и обеспечивает стабильную работу агента. Используйте его вместе с PrivateTmp=true, чтобы изолировать временные файлы.
Как контролировать нагрузку агента на CPU?
Установите CPUQuota=200% в systemd-run — это ограничит агент не более чем двумя ядрами. Без такого ограничения процесс может парализовать хост, потребляя всё доступное CPU-время. Контроль нагрузки позволяет другим сервисам работать бесперебойно, особенно при параллельном выполнении нескольких задач. Проверяйте нагрузку через htop или systemd-cgtop после запуска.
Зачем нужен параметр PrivateTmp=true?
PrivateTmp=true создает для агента изолированную временную директорию, отделённую от системных /tmp и /var/tmp. Это предотвращает загрязнение общей временной области посторонними файлами и защищает хост от случайного удаления важных данных. Изолированные временные файлы также упрощают очистку после завершения работы агента.