voidea/template/docs/agents/02-agent-versioning.md

Версионирование агентов

---

Принцип

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

---

Правила бампа

Компонент	Когда	Кто
A (major)	Breaking change в публичном интерфейсе (сигнатура run(), публичные методы)	EvolutionAgent
B (minor)	Новая capability (новый метод, новый prompt, новая роль)	EvolutionAgent
C (patch)	Внутренние правки без изменения поведения	Сам агент (авто)

---

Механика

Каждый Agent.run()
  → compute_checksum() — SHA256 от __file__ агента
  → сравнивает с AgentConfig.checksum в БД
  → не совпал → bump_version("patch") → запись в changelog → обновление БД
  → совпал → ничего

EvolutionAgent
  → анализирует код агента
  → нашёл новую capability → bump_version("minor")
  → нашёл breaking change → bump_version("major")

---

Хранение checksum

Checksum хранится в двух местах:

1. В БД (AgentConfig.checksum) — для быстрого сравнения
2. В changelog файле (<!-- checksum: ... -->) — для git history

---

Changelog

Файл: CHANGELOG/agents/<agent_name>.md

# audit_agent Changelog
<!-- checksum: a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890 -->

## 1.0.2 (2026-05-10)
- Fixed: ruff output parsing for Windows paths

## 1.0.1 (2026-05-09)
- Fixed: missing error handling in health_check

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

---

Разделение ответственности

Аспект	Владелец	Где хранится
Версия проекта	SpecAgent / человек	project.yaml, CHANGELOG/v*.md
Версия агента	EvolutionAgent	AgentConfig.version (БД)
Changelog проекта	SpecAgent / человек	CHANGELOG/v*.md
Changelog агента	EvolutionAgent	CHANGELOG/agents/<name>.md

---

[ASK] Вопросы по версионированию

• Версионировать агентов с первого коммита? (да — привычка, потом не внедрить)
• Допустим ли ручной бамп версии? (да, EvolutionAgent — автоматизация, но человек может и вручную)
• Нужна ли блокировка бампа (если checksum не совпал — не запускать)? (нет, только предупреждение)