Перейти к основному содержимому

Удержание контекста связанных документов

Версия: 1.0 Дата: 25.04.2026 Статус: Утверждён

Главный архитектор vitiana-api-platform постоянно держит в активном контексте текущую цепочку связанных документов, их пересечения, открытые развилки и принятые решения. При работе над любым документом — обязательная предварительная сверка соседних документов и обратных ссылок (backlinks).

Зафиксировано 25.04.2026 как закон работы.

Главный тезис​

Архитектурная документация — это граф решений, а не набор изолированных документов. Любое изменение в одной точке распространяется по графу.

Без удержания связей в активном контексте появляются скрытые противоречия между соседними документами. Архитектор без активного контекста становится редактором отдельных файлов — это разрушает целостность системы.

Что это означает практически​

1. Перед каждой архитектурной правкой — обязательная сверка соседей​

Не правлю документ изолированно. Перед изменением commercial-model.md обязательно открываю и держу в активном контексте:

  • offer-pricing-booking-semantics.md (зависимость по Quote).
  • partner-finance-and-clearing.md (зависимость по settlement).
  • tenancy-and-identity.md (зависимость по actor scope).
  • api-contracts.md (зависимость по price view contract).
  • clients.md (зависимость по visibility).

Перед правкой domain-model.md — открываю все 12 reference-документов, использующих сущности (Property, Offer, Quote, Booking, TourDraft, Tenant, ApiClient и так далее).

2. Backlinks через docs_links — обязательная процедура​

Перед любым изменением документа:

docs_links(section_id, direction="from")

Возвращает все документы, ссылающиеся на правимую секцию. Это даёт полный список зависимых документов.

После любого изменения:

docs_links(section_id, direction="both")

Для проверки целостности обратных ссылок и обнаружения unresolved.

3. Текущая цепочка решений — фиксируется​

Все принятые стратегические решения держу в project memory:

  • Бизнес-модель: anchor (B2B API marketplace primary, vitrip.store demo, agency platform fast-follower), география (UA/CZ/PL/KZ + EU), гибридная merchant-of-record модель.
  • Реализация: связь с home-to-go-api как первой реализацией слоя приёма данных.
  • Data infrastructure: events / DWH / ETL / ML / A-B testing закладывать с нулевого дня.
  • Tour Builder: положение как core, гибкий конструктор с raw API по модулям, partner-grade surface.

При появлении нового стратегического решения — обновляю соответствующую запись сразу, не откладываю.

4. Открытые развилки и противоречия — отдельный лог​

В каждом архитектурном документе при обнаружении расхождения с другим документом или с реализацией home-to-go-api — фиксирую как открытую развилку в специальном разделе документа («Открытые вопросы» или «Развилки требующие решения»). Не выбираю самостоятельно — эскалирую владельцу платформы.

5. После каждой фазы — карта пересечений​

По завершении фазы (см. CLAUDE.md §8 «Порядок работы») — даю отчёт владельцу платформы с явной картой:

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

6. При длинной сессии — периодическое восстановление контекста​

Если сессия длится долго и контекст автокомпрессируется системой — восстанавливаю активный набор документов через docs_search и docs_get_section для текущей задачи. Не работаю с обрывочной памятью.

Алгоритм для каждой архитектурной задачи​

  1. Идентифицирую правимый документ или новый документ для создания.
  2. docs_search(тема, project="vitiana-api-platform") — найти все соседние документы по теме.
  3. docs_links(section_id, direction="both") — для существующих документов получить forward-links и backlinks.
  4. docs_get_section для каждого соседа — прочитать релевантные секции и держать в активном контексте.
  5. Сверка с реализацией home-to-go-api (см. перечень обязательных к чтению документов в CLAUDE.md §2).
  6. Сверка с принятыми стратегическими решениями.
  7. MDX-safe self-check перед записью: проверяю, что в тексте нет голых <digit или >digit (используется &lt; / &gt;). См. MDX-безопасное написание.
  8. Только после полного контекста и MDX-safe проверки — выполняю правку через docs_patch_section или docs_create_file.
  9. После правки — docs_links для проверки целостности.
  10. После записи — повторный grep для уверенности: grep -nE '<[0-9]' file.md и grep -nE '>[0-9]' file.md должны быть пусты (или совпадения только внутри backtick-инлайна или fenced code blocks).
  11. Обновление backlinks в соседних документах при необходимости.
  12. Отчёт в конце фазы с картой пересечений.

Запрещённые паттерны​

  • ❌ Работа над одним документом, «забыв» про соседние.
  • ❌ Оптимизация через «позже свяжу» — связи строятся в момент создания или изменения.
  • ❌ Принятие решения без явных backlinks к зависимым документам.
  • ❌ Архивация документа без проверки backlinks и обновления ссылок в зависимых документах.
  • ❌ Создание нового документа без ссылок на верхнеуровневые документы (overview/*) и связанные reference-документы.

Почему это закон​

Зафиксировано владельцем платформы 25.04.2026. Причины:

  1. Архитектурная документация — это граф решений. Любое изменение распространяется по графу. Без активного контекста архитектор разрушает связи.
  2. Скрытые противоречия — главная проблема существующего пакета. Слабая увязка между vertical-доменами уже зафиксирована как одна из дыр первичного слоя в критическом анализе. Удержание контекста — единственный способ её закрыть.
  3. Без удержания связей нельзя построить зрелую платформу. Surface-aware, truth-aware, tenant-aware решения требуют постоянной сверки между десятками документов.

Связанная документация​