ECC: оптимизация агентных оболочек для Claude Code и анал...

ECC: оптимизация агентных оболочек для Claude Code и аналогов

Разбираем архитектуру ECC — системы оптимизации AI-агентов. Skills, память, безопасность и исследовательский подход к разработке на примере Claude Code, Codex, Cursor.

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

ECC (Enhanced Claude Code) — это агентная оболочка, которая решает конкретную проблему: стандартные AI-ассистенты вроде Claude Code или Codex поставляются с универсальными настройками, не адаптированными под ваш проект, ваш стек и ваши стандарты разработки. ECC превращает универсального помощника в специализированный инструмент за счёт четырёх компонентов.

Skills — это набор инструкций, которые агент использует как чеклисты при выполнении типовых задач. Не путать с промптами: skill не просто говорит модели «делай хорошо», а описывает конкретную последовательность действий, допустимые инструменты и ограничения. Например, skill для работы с базой данных может запрещать DROP и TRUNCATE в production-среде, требовать бэкап перед миграцией и проверять план запроса перед выполнением.

Memory — долгосрочная память проекта. Агент записывает архитектурные решения, конвенции кода, историю изменений и контекст, который не помещается в одно окно контекста. Это не просто файл с заметками — это структурированная база, к которой агент обращается при каждом запросе. Без этого компонента Claude Code каждый раз «заново узнаёт» проект, что ведёт к непоследовательным решениям и ошибкам.

Security — встроенный слой безопасности, который работает на уровне агента. В плане безопасности это критически важный компонент: AI-агент имеет доступ к файловой системе, может выполнять команды, отправлять данные по сети. Без ограничений он становится вектором атаки. ECC реализует принцип минимальных привилегий: каждый набор действий проверяется против белого списка, опасные операции требуют подтверждения, а данные не утекают за пределы проекта.

Research-first development — подход, при котором агент перед написанием кода обязан провести исследование: изучить документацию, проверить существующие реализации, оценить совместимость зависимостей. Распространённая проблема — когда разработчик просит агента «напиши интеграцию с API X», и тот генерирует код на основе обучающих данных, без проверки актуальности. ECC заставляет агента сначала выполнить поиск, затем проанализировать результаты, и только потом писать код.

В одном из проектов команда из пяти разработчиков потеряла два дня из-за того, что Claude Code сгенерировал конфигурацию Docker Compose на основе устаревшей версии API. Система с research-first подходом исключает этот класс ошибок.

Отличие от стандартных промптов и конфигураций

Стандартный подход к настройке AI-агента — это написание большого промпта в файле CLAUDE.md или аналогичной конфигурации. Проблема в том, что промпт — это декларативное описание желаемого поведения. Модель может следовать ему, а может и нет, в зависимости от контекста, длины диалога и версии модели.

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

Вот пример типичной конфигурации ECC:

yaml
# ecc/config.yaml
skills:
  - path: skills/database.yaml
    enabled: true
  - path: skills/security-audit.yaml
    enabled: true
  - path: skills/deployment.yaml
    enabled: false  # Отключено в dev-среде

memory:
  backend: sqlite
  path: .ecc/memory.db
  auto_index: true
  max_entries: 10000

security:
  allow_shell: false
  allow_network: false
  max_file_size_mb: 10
  blocked_commands:
    - rm -rf
    - chmod 777
    - curl | sh

research:
  min_sources: 3
  check_documentation: true
  verify_dependencies: true

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

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

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

ECC совместим не только с Claude Code. Архитектура позволяет использовать его с Claudex, который переносит возможности Claude Code на другие модели, а также с Cursor и Codex. Принцип работы один и тот же: оболочка предоставляет структуру, а модель заполняет её конкретной реализацией.

Подробнее о настройке производительности агентного хранилища — в материале Оптимизация производительности агентного хранилища ECC.

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

Определить, какие типы задач AI-агент выполняет чаще всего, и создать для них отдельные skills
Настроить memory-компонент: указать путь к хранилищу и включить автоиндексацию
Задать ограничения безопасности — начать с блокировки shell-доступа и сетевых запросов
Включить research-first режим и задать минимальное количество источников для проверки
Протестировать конфигурацию на типовой задаче: попросить агента выполнить миграцию БД и убедиться, что он проверил бэкап перед выполнением

Архитектура системы: четыре ключевых компонента

Skills: структурирование навыков агента

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

Типовая структура skill выглядит так:

yaml
---
name: security-audit
description: Проведение аудита безопасности конфигурации сервера
triggers:
  - "проверь безопасность"
  - "аудит сервера"
context:
  - "/etc/nginx/nginx.conf"
  - "/etc/ssh/sshd_config"
  - "/etc/sysctl.conf"
constraints:
  - "read-only: true"
  - "no-network: true"
  - "max-commands: 50"
---

## Порядок действий

1. Проверить открытые порты через ss
2. Проверить настройки SSH (PermitRootLogin, PasswordAuthentication)
3. Проверить параметры sysctl (net.ipv4.conf.all.rp_filter и т. д.)
4. Сформировать отчёт

Типичный пример того, почему блок constraints обязателен: агент без ограничений попытался перезаписать iptables-правила во время аудита. Именно поэтому constraints — не рекомендация, а обязательный элемент.

Skills загружаются из директории .ecc/skills/ и применяются по триггерам. ECC поддерживает приоритизацию: если два skill сработали одновременно, выполняется тот, у которого выше приоритет.

Для проверки качества skill перед активацией используйте валидатор:

bash
ecc validate skill security-audit.yaml

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

Instincts и memory: контекстное поведение и долгосрочная память

Instincts — это поведенческие правила, которые агент применяет не к конкретной задаче, а глобально. Если skills отвечают на вопрос «что делать», то instincts отвечают на вопрос «как себя вести всегда».

Пример instinct для работы с чувствительными данными:

yaml
---
name: no-telemetry
scope: global
action: deny
conditions:
  - "outbound connection to *.analytics.*"
  - "outbound connection to *.telemetry.*"
  - "file write to ~/.local/share/telemetry"
message: "Блокировка телеметрии согласно политике no-telemetry"
---

Memory в ECC устроена в два слоя. Краткосрочная память — это контекст текущей сессии: файлы, которые агент уже читал, команды, которые выполнил. Долгосрочная память — это индексируемое хранилище решений, которые агент сохраняет между сессиями.

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

yaml
memory_filter:
  patterns:
    - type: regex
      pattern: 'password["\s:=]+[^\s]+'
      action: redact
    - type: regex
      pattern: 'sk-[a-zA-Z0-9]{48}'
      action: reject
      message: "Никогда не сохраняйте API-ключи Anthropic в память агента"
    - type: regex
      pattern: '\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b'
      action: redact

Настоятельно рекомендуется настроить memory_filter до первого использования долгосрочной памяти. По умолчанию ECC не фильтрует ничего — это осознанное решение, потому что пользователь должен сам определить, что считать чувствительным.

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

bash
ecc memory --backend sqlite --path ~/.ecc/memory.db

Обратите внимание: облачные бэкенды памяти отсутствуют принципиально. Всё хранится на вашем сервере.

Security: встроенные механизмы защиты агента

Безопасность в ECC реализована на нескольких уровнях. Первый уровень — это sandbox выполнения. Каждый skill по умолчанию работает в ограниченной среде: отдельное изолированное пространство идентификаторов процессов (PID namespace), ограниченный набор системных вызовов через seccomp, read-only файловая система для операций чтения.

Конфигурация seccomp-профиля для агента:

json
{
  "defaultAction": "SCMP_ACT_ERRNO",
  "architectures": ["SCMP_ARCH_X86_64"],
  "syscalls": [
    {
      "names": ["read", "write", "open", "close", "stat", "fstat", "lseek", "mmap", "mprotect", "munmap", "brk", "ioctl", "access", "pipe", "select", "sched_yield", "dup", "dup2", "nanosleep", "getpid", "getppid", "getuid", "getgid", "geteuid", "getegid", "uname", "fcntl", "flock", "fsync", "fdatasync", "truncate", "getcwd", "chdir", "rename", "mkdir", "rmdir", "unlink", "readlink", "symlink", "chmod", "chown", "lchown", "gettimeofday", "getrlimit", "getrusage", "sysinfo", "times", "getdents", "getdents64", "clock_gettime", "clock_getres", "exit_group", "exit"],
      "action": "SCMP_ACT_ALLOW"
    }
  ]
}

Это минимальный набор. Если ваш skill требует сетевых соединений, добавьте socket, connect, bind, listen, accept, sendto, recvfrom, sendmsg, recvmsg. Но каждый добавленный системный вызов расширяет поверхность атаки — добавляйте только необходимое.

Второй уровень — это контроль исходящих соединений. ECC ведёт лог всех сетевых запросов агента и блокирует соединения не из белого списка:

yaml
network_policy:
  default: deny
  allow:
    - host: "api.github.com"
      port: 443
      protocol: https
    - host: "registry.npmjs.org"
      port: 443
      protocol: https
  deny_log: true

Частая ловушка — оставить default: allow «для удобства». Не делайте так. Если агент скомпрометирован через вредоносный промпт, он сможет установить соединение с командным центром. Разрешать нужно только явно указанное.

Третий уровень — аудит действий. Каждое действие агента логируется с контекстом: какой skill сработал, какие команды выполнены, какие файлы изменены. Логи пишутся в формате, совместимом с auditd:

bash
# Просмотр лога действий агента
ecc audit --since "1 hour ago" --format json

Для интеграции с внешней SIEM-системой (Security Information and Event Management) можно настроить отправку через syslog:

yaml
audit:
  output:
    type: syslog
    facility: local0
    severity: info
    target: "192.168.1.100:514"

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

Подробнее о настройке производительности хранилища и профилей безопасности — в материале Оптимизация производительности агентного хранилища ECC.

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

Создать базовый набор skills для ваших типовых задач с обязательным блоком constraints
Настроить memory_filter с паттернами для вашей среды до первого использования долгосрочной памяти
Определить белый список сетевых соединений для каждого skill, который требует доступ в сеть
Включить аудит действий и настроить ротацию логов
Прогнать каждый новый skill через ecc validate перед активацией
Проверить seccomp-профиль на соответствие реальным потребностям агента — лишние системные вызовы должны быть удалены

Практическое применение с Claude Code и аналогами

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

ECC — это не отдельный инструмент, а слой оптимизации поверх существующих агентных оболочек. Архитектура спроектирована так, чтобы не завязываться на конкретного провайдера модели. На практике это означает: вы подключаете ECC к Claude Code, и он работает. Переключаетесь на Codex или Opencode — та же конфигурация остаётся валидной.

Claude Code — основной таргет для ECC. Интеграция происходит через системные промпты и структурированный контекст в директории .claude/. Ключевой файл — CLAUDE.md, который ECC генерирует автоматически на основе анализа проекта:

markdown
# CLAUDE.md — сгенерировано ECC

## Архитектура проекта
- Язык: Go 1.22
- Сборка: Makefile, цель `build`
- Тесты: `go test ./... -count=1`

## Ограничения
- Не изменять файлы в `vendor/` вручную
- Не коммитить без запуска `make lint`
- Не использовать `panic()` в production-коде

## Контекст безопасности
- Этот проект обрабатывает персональные данные (PII) — любые изменения в схеме БД требуют ревью

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

Codex (OpenAI) интегрируется через аналогичный механизм, но с поправкой на формат системных инструкций. ECC конвертирует свой внутренний формат в структуру, которую ожидает Codex:

json
{
  "instructions": {
    "project_context": "...",
    "constraints": ["..."],
    "security_rules": ["..."]
  }
}

Opencode — менее распространённый, но растущий игрок. Его преимущество в открытой архитектуре: ECC подключается через плагин-интерфейс без модификации ядра. Конфигурация плагина (версия указана для примера):

yaml
# .opencode/config.yaml
plugins:
  - name: ecc-optimizer
    source: github.com/ecc-tools/opencode-plugin
    version: 0.4.2  # номер версии приведён для иллюстрации
    config:
      memory_backend: sqlite
      research_mode: strict

Cursor — отдельный случай. Cursor использует собственный формат .cursorrules, и ECC генерирует его параллельно с CLAUDE.md. Содержимое дублируется, но адаптировано под синтаксис Cursor:

markdown
# .cursorrules — сгенерировано ECC

## Build & Test
- Build: `make build`
- Test: `make test`
- Lint: `make lint`

## Security Constraints
- No hardcoded secrets
- All DB migrations must be reversible
- Input validation required for all API endpoints

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

Важно: ECC не заменяет агентную оболочку. Он её дополняет. Claude Code остаётся основным интерфейсом взаимодействия с моделью. ECC работает на уровне подготовки контекста и пост-обработки действий агента.

Для тех, кто использует нестандартные модели через прокси, существует Claudex, который переносит возможности Claude Code на произвольные модели. ECC совместим с этой связкой, поскольку оптимизация происходит до обращения к модели.

Research-first подход: как агент проверяет гипотезы перед действием

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

Как это работает. Перед выполнением любого нетривиального действия (изменение архитектуры, добавление зависимости, модификация API) агент обязан сформулировать гипотезу и проверить её. ECC реализует это через структурированный протокол:

1. HYPOTHESIS: описание предполагаемого решения
2. ASSUMPTIONS: список допущений, на которых основана гипотеза
3. VERIFICATION: конкретные шаги для проверки допущений
4. EVIDENCE: результаты проверки
5. DECISION: подтверждение или отклонение гипотезы

На практике это выглядит так. Агент предлагает заменить database/sql на sqlx для упрощения сканирования результатов. Вместо немедленного выполнения ECC заставляет агента проверить:

bash
# Шаг верификации: проверить текущее использование database/sql
grep -r "database/sql" --include="*.go" . | wc -l

# Шаг верификации: оценить влияние на зависимости
go list -m all | grep sqlx

# Шаг верификации: проверить совместимость с текущей версией Go
go version

Если проверка показывает, что проект использует 50+ прямых вызовов database/sql и миграция затронет критический путь — агент должен пересмотреть гипотезу или предложить поэтапный план.

Режимы строгости. ECC поддерживает три уровня research-first:

Режим	Когда применять	Поведение
`suggestive`	Прототипы, эксперименты	Агент предлагает проверку, но может пропустить
`standard`	Обычная разработка	Проверка обязательна для действий с оценкой риска > 3
`strict`	Production-код, безопасность	Любое действие требует верификации

Конфигурация режима в ecc.yaml:

yaml
research:
  mode: strict
  risk_threshold: 3
  auto_verify:
    - dependency_changes
    - schema_migrations
    - api_breaking_changes
    - security_sensitive_paths

Интеграция с тестовым окружением. В strict-режиме ECC автоматически запускает тесты после каждого значимого изменения. Это не просто make test — агент анализирует, какие тесты релевантны для конкретного изменения:

bash
# ECC определяет затронутые пакеты и запускает только релевантные тесты
go test ./internal/auth/... ./internal/session/... -run "TestToken|TestSession" -v

Реальный случай: агент предложил «оптимизировать» функцию хеширования паролей, заменив bcrypt на sha256 «для производительности». В режиме strict агент был обязан проверить гипотезу — и обнаружил, что sha256 не предназначен для хеширования паролей. Гипотеза отклонена, инцидент предотвращён.

Связь с памятью. Research-first неразрывно связана с системой памяти ECC. Каждая проверенная гипотеза сохраняется и становится контекстом для будущих решений. Если агент уже проверял совместимость sqlx с текущей версией Go в этом проекте — он не будет проверять повторно. Подробнее об устройстве хранилища памяти — в материале Оптимизация производительности агентного хранилища ECC.

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

Установить ECC и сгенерировать начальную конфигурацию для вашего проекта
Настроить CLAUDE.md или .cursorrules через ECC, проверить, что агент учитывает ограничения
Выбрать режим research-first: suggestive для прототипов, strict для production
Определить список действий с автоматической верификацией в ecc.yaml
Протестировать переключение между Claude Code и Cursor — убедиться, что контекст сохраняется
Проверить, что агент не предлагает изменения без верификации в strict-режиме
Настроить интеграцию с CI: тесты должны запускаться автоматически после действий агента

Безопасность агентных систем: угрозы и защита

Типовые векторы атак на AI-агентов

Прежде чем защищать агентную систему, нужно понимать, что именно защищаем. AI-агенты вроде Claude Code или Cursor — это не просто чат-боты. Они читают файлы, выполняют команды, обращаются к API и пишут код. Каждое из этих действий — потенциальная точка входа.

Инъекция промптов через контекст. Самый распространённый вектор. Агент читает файл — а внутри инструкция, замаскированная под комментарий или документацию. Агент выполняет её как свою собственную команду. В одном из проектов злоумышленник разместил в README.md репозитория строку вида , и агент попытался её выполнить при анализе проекта.

Злоупотребление инструментами (tool abuse). Агенту доступны инструменты: чтение файлов, выполнение shell-команд, сетевые запросы. Если агент запущен с избыточными привилегиями, одна удачная инъекция даёт атакующему полный контроль над хостом. Частая ловушка — запуск агента от root в контейнере с примонтированным хостовым томом.

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

Атаки через MCP-серверы. Протокол MCP (Model Context Protocol) позволяет подключать к агенту внешние инструменты — базы данных, API, файловые системы. Каждый подключённый MCP-сервер расширяет поверхность атаки. Если сервер скомпрометирован или написан без должной проверки входных данных, агент становится вектором для атак на внутреннюю инфраструктуру.

Цепочки доверия между агентами. В сложных конфигурациях один агент может передавать задачи другому. Если промежуточный агент скомпрометирован, он подменит задание следующему в цепочке. Это аналог атаки через цепочку поставок (supply chain attack), только в мире AI.

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

Чем ECC отличается от обычного Claude Code с кастомным промптом?

ECC — это не один длинный системный промпт, а полноценная агентная оболочка с четырьмя независимыми компонентами: Skills, Memory, Security и Research-first. Кастомный промпт даёт модели инструкцию один раз, и она либо помещается в окно контекста, либо нет. ECC же структурирует знания проекта в отдельные слои, к которым агент обращается по запросу, а не держит всё в голове. С позиции безопасности промпт не может запретить модели выполнить опасную команду — он лишь просит. А слой Security в ECC работает как белый список на уровне действий, а не на уровне текста.

Можно ли использовать ECC с инструментами, отличными от Claude Code?

Да, ECC проектировался как универсальная оболочка. В документации заявлена поддержка Codex, Cursor, Opencode и других агентных платформ. Архитектура компонентов не привязана к конкретному провайдеру модели: Skills и Memory — это файлы проекта, Security — набор правил, которые интерпретируются агентом независимо от бэкенда. Типичный пример — команда перенесла конфигурацию ECC с Claude Code на Cursor за один вечер: потребовалось лишь адаптировать пути к файлам и формат вызова инструментов.

Как компонент Memory предотвращает утечку контекста между сессиями?

Memory в ECC — это структурированная база внутри проекта, а не внешняя облачная служба. Агент записывает архитектурные решения, конвенции и историю изменений в локальные файлы, которые читаются в начале каждой новой сессии. Данные не покидают файловую систему проекта, не отправляются на сторонние серверы и не смешиваются с контекстом других проектов. Это принципиальное отличие от решений, которые хранят память агента в облаке: в плане безопасности локальное хранение полностью исключает утечку через внешний API.

Что делает слой Security и можно ли его отключить для ускорения работы?

Слой Security реализует принцип минимальных привилегий: каждая операция агента проверяется против белого списка, потенциально опасные действия (удаление файлов, сетевые запросы, изменение production-конфигураций) требуют явного подтверждения. Формально его можно отключить — это настройка, а не аппаратная блокировка. Однако в production-среде или на проектах с чувствительными данными делать это категорически не рекомендуется. Реальный случай: разработчик отключил ограничения для «быстрого прототипирования», а агент случайно перезаписал конфигурацию базы данных. Если нужна скорость — лучше расширить белый список для конкретных безопасных операций, чем отключать защиту целиком.

Подходит ли ECC для небольших проектов или это избыточная сложность?

Для одноразовых скриптов и личных проектов из пары файлов ECC действительно избыточен. Система начинает приносить реальную пользу, когда в проекте появляется история: архитектурные решения, которые нужно помнить, конвенции, которые нужно соблюдать, и операции, которые нельзя выполнять бездумно. Порог я бы оценил так: если вы возвращаетесь к проекту через неделю и тратите больше 15 минут на вспоминание контекста — Memory уже окупает себя. Если в проекте есть база данных или внешние API — Security окупается с первого дня. Начинать можно с одного компонента и наращивать остальные по мере роста проекта.