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

---

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

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

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`
```markdown
# 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 на старте? (да — замкнутый круг: агенты без контроля = хаос)