ADR

ADR-003: Core-first change protocol

ADR-003: Core-first change protocol

Статус: ✅ Accepted
Дата: 2026-06-11
Автор: openclaw-architect

Контекст

В constitution-driven development документация — единственный источник истины. Без формального протокола возникает риск:

  • Изменения в коде без обновления документации
  • Расхождение между архитектурой и реализацией
  • Потеря контекста решений
  • Невозможность трассировки

Рассматривались подходы:

  1. Без протокола — "команда ответственная, сама запомнит" (ненадёжно)
  2. ADR-only — ADR для архитектуры, но нет протокола для всех изменений
  3. Полный 10-шаговый протокол — каждое изменение от запроса до ревью

Решение

Выбираем полный 10-шаговый протокол изменений (core-first):

  1. Change Request — описать что меняем и почему
  2. Classification — тип (core/feature/bug/docs/refactor) и impact (H/M/L)
  3. Impact Analysis — какие документы и модули затронуты
  4. Core Docs Update — обновить конституцию до кода
  5. ADR — если нужно архитектурное решение
  6. Task Card — детальная задача с acceptance criteria
  7. Code — реализация
  8. Tests — покрытие
  9. Changelog & Timeline — запись в историю
  10. Review — проверка по чеклисту

Исключения

  • Bug fix (critical): Hotfix без протокола, ADR post-factum
  • Docs-only: Шаги 6-8 пропускаются
  • Refactor (no model change): Шаги 1-5 пропускаются

Последствия

Положительные (+)

  • Целостность: Документация всегда соответствует коду
  • Прозрачность: Любое решение можно проследить от запроса до реализации
  • Онбординг: Новые участники видят историю и контекст решений
  • Трассировка: Каждый элемент имеет trace id

Отрицательные (-)

  • Замедление: Даже маленькое изменение требует документации
  • Дисциплина: Протокол работает только если команда его соблюдает
  • Overhead: Для bug fix'ов протокол избыточен

Стратегия смягчения

  1. Шаблоны (TASK_TEMPLATE, CHANGE_REQUEST_TEMPLATE) ускоряют процесс
  2. Чёткие критерии — когда протокол обязателен, а когда нет
  3. Исключения для hotfix'ов
  4. Автоматическая проверка (CI: проверка changelog при изменении core docs)

Связанные документы

  • CHANGE_PROTOCOL.md (полное описание)
  • PROJECT_CONSTITUTION.md (цикл разработки)
  • TRACEABILITY_POLICY.md
  • REVIEW_CHECKLIST.md