voidea/template/docs/17-self-development.md

Саморазвитие и эволюция проекта

---

Зачем проекту саморазвитие

Проект, который не развивается, умирает. Но развитие требует ресурсов, которых у команды может не быть. Решение: агенты автоматизируют развитие.

1. Проект живёт дольше команды — агенты продолжают работу независимо
2. Автоматизация рутины — тесты, документация, ревью
3. Адаптация — проект сам подстраивается под новые требования

---

Три уровня саморазвития

Level 1: Reactive (базовый)

Агенты реагируют на события:

• Pre-commit: AuditAgent проверяет правила
• Push: SecurityAgent проверяет зависимости
• Cron: DocAgent обновляет документацию

Начинаем с этого уровня.

Level 2: Proactive (целевой)

Агенты предлагают улучшения:

• EvolutionAgent анализирует код и предлагает рефакторинг
• ObserverAgent собирает метрики и предлагает оптимизацию
• FixAgent анализирует ошибки и предлагает исправления

Достигаем к Stage 3 (см. migration-path.md).

Level 3: Autonomous (будущее)

Агенты принимают решения:

• Self-healing: авто-откат при росте ошибок
• Auto-versioning: автоматический бамп версий
• Auto-scaling: масштабирование под нагрузку

---

Ядро агентов (создаются с первого коммита)

4 агента, которые должны жить в проекте всегда:

Агент	Роль	Триггеры	Без него
DocAgent	Пишет документацию	pre-commit, manual	Документация пишется "потом" → никогда
AuditAgent	Проверяет правила	pre-commit, push, cron	Правила не применяются
EvolutionAgent	Версионирует агентов	cron, event, manual	Агенты не эволюционируют
SupervisorAgent	Следит за всеми агентами	cron, event, manual	Экосистема не контролируется

Подробнее о каждом

DocAgent:

• При каждом коммите проверяет, что документация соответствует коду
• Если находит недокументированный публичный метод — добавляет docstring
• Обновляет ADR при архитектурных изменениях

AuditAgent:

• Проверяет каждый коммит на соответствие docs/00-rules.md
• Проверяет: стиль кода, наличие тестов, docstrings, .env.example
• Пишет отчёт о нарушениях

EvolutionAgent:

• Отслеживает версии всех агентов
• При изменении checksum агента — бампит версию
• При добавлении новой capability — бампит minor
• При breaking change — бампит major

SupervisorAgent:

• Регулярно проверяет health всех агентов
• Собирает метрики выполнения (длительность, успешность)
• При падении агента — перезапускает или шлёт алерт
• Формирует сводный отчёт о состоянии экосистемы

---

Расширение агентов

По мере роста проекта добавляются:

Агент	Когда	Зачем
QATesterAgent	Появились тесты	Поддерживать качество тестов
FixAgent	Пойман первый баг	Анализировать и исправлять
BacklogAgent	Появился техдолг	Управлять задачами
SecurityAgent	Перед production	Проверять безопасность
SpecAgent	Перед релизом	Управлять версией
RolloutAgent	Перед деплоем	Постепенный rollout
ObserverAgent	После запуска	Собирать метрики
UITestAgent	Есть UI	Визуальное тестирование

---

Agent Versioning

Каждый агент версионируется независимо по A.B.C.

Почему независимо: агенты изменяются с разной скоростью. DocAgent может меняться каждый день, а SecurityAgent — раз в месяц.

Как работает:

1. Агент запускается → вычисляет SHA256 своего файла (compute_checksum())
2. Сравнивает с хранимым checksum
3. Если не совпал → авто-бамп patch + запись в changelog
4. EvolutionAgent анализирует изменения и решает: это minor (новая capability) или major (breaking change)?

Хранение: CHANGELOG/agents/<name>.md

# doc_agent Changelog
<!-- checksum: a1b2c3d4e5f6... -->

## 1.2.0 (2026-05-10)
- Added: поддержка YAML-формата для промптов

## 1.1.3 (2026-05-09)
- Fixed: обработка пустых docstrings

## 1.0.0 (2026-05-01)
- Initial version

---

Триггеры запуска агентов

Триггер	Когда	Какие агенты
pre_commit	Перед каждым коммитом	AuditAgent, DocAgent
push	При пуше в remote	SecurityAgent, BacklogAgent, SpecAgent
tag_creation	При создании git-тега	RolloutAgent, SpecAgent
cron	По расписанию (daily)	EvolutionAgent, SupervisorAgent, ObserverAgent
manual	Вручную из админки	Любой
api	Через API	Любой
event	При событии (ошибка, деплой)	FixAgent, RolloutAgent

---

[ASK] Вопросы по саморазвитию

• Сколько агентов нужно на старте? (рекомендация: 4 ядерных, остальные по необходимости)
• Как часто запускать EvolutionAgent? (рекомендация: ежедневно по cron)
• Кто пишет агентов? (рекомендация: команда, начиная с самого простого — DocAgent)
• Нужен ли SupervisorAgent на старте? (да — замкнутый круг: агенты без контроля = хаос)