dzentra_bot/docs/market_intelligence/decisions/decision-004-no-existing-code-assumptions.md

Decision 004 — No Existing Code Assumptions

Статус

Accepted

---

Дата принятия

Принято во время реализации первых Build подсистемы Market Intelligence.

---

Контекст

Во время разработки новых компонентов неоднократно возникала ситуация, когда для продолжения работы требовалось знать текущее состояние проекта.

Например:

• существующие модели;
• типы;
• контракты;
• Runtime State;
• Engine Contract;
• общие структуры данных.

Использование предположений о содержимом существующих файлов приводило бы к риску расхождения между проектируемым кодом и реальным состоянием проекта.

Для долгоживущей платформы подобный подход признан неприемлемым.

---

Проблема

Во время проектирования новых компонентов существует соблазн предположить, что существующий файл имеет ожидаемую структуру.

Например:

«Наверное, эта модель уже существует.»

или

«Скорее всего, поле называется именно так.»

Подобные предположения могут привести к следующим последствиям:

• дублирование уже существующих сущностей;
• несовместимые контракты;
• повторная реализация одинаковой логики;
• нарушение принципа единого источника истины;
• увеличение объёма последующего рефакторинга.

---

Рассмотренные варианты

Вариант 1

Использовать предположения о текущем состоянии проекта.

Преимущества

• быстрее писать код;
• меньше дополнительных запросов.

Недостатки

• высокий риск ошибок;
• потеря синхронизации с реальным проектом;
• появление дублирующих сущностей;
• снижение качества архитектуры.

---

Вариант 2

Использовать существующий код как единственный источник истины.

Если для реализации требуется информация о существующем компоненте, соответствующий файл предварительно запрашивается у пользователя.

После получения файла все архитектурные решения принимаются исключительно на основании его фактического содержимого.

Преимущества

• отсутствие ложных предположений;
• единый источник истины;
• отсутствие дублирования;
• минимизация архитектурных ошибок;
• синхронное развитие проекта и документации.

Недостатки

• требуется дополнительный шаг перед началом реализации.

---

Принятое решение

При реализации новых компонентов запрещается делать предположения о содержимом существующих файлов.

Если новый компонент зависит от уже существующей части проекта, соответствующий файл должен быть предварительно получен и использован как единственный источник истины.

---

Правило разработки

Перед началом реализации необходимо определить, зависит ли новый компонент от существующего кода.

Если зависимость существует, разработчик обязан запросить соответствующий файл до начала проектирования или написания кода.

После получения файла запрещается создавать альтернативные реализации уже существующих сущностей.

---

Причины принятия решения

Использование существующего кода как единственного источника истины позволяет:

• исключить дублирование;
• избежать несовместимых контрактов;
• сохранить целостность архитектуры;
• уменьшить объём последующего рефакторинга;
• обеспечить единое понимание структуры проекта.

---

Последствия

После принятия настоящего решения:

• архитектурные решения принимаются только на основании реального состояния проекта;
• существующие модели повторно используются вместо повторной реализации;
• новые сущности создаются только при их фактическом отсутствии;
• вероятность архитектурных расхождений существенно снижается.

---

Практическое применение

Перед созданием любого нового файла выполняется следующий вопрос:

Требуется ли для его реализации существующий код проекта?

Если ответ положительный, необходимые файлы запрашиваются до начала работы.

Данное правило распространяется на:

• модели;
• контракты;
• состояния Runtime;
• общие типы;
• перечисления;
• вспомогательные функции;
• архитектурные ограничения.

---

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

• architecture_principles.md
• development_process.md
• runtime_contract.md

---

История изменений

Версия	Изменение
1.0	Первое принятие архитектурного решения.