Общий язык важнее общей архитектуры
Глоссарий — это не скучная документация для онбординга. Это словарь, на котором говорят тикет, код и ревью. Без него в одном месте "авария", в другом "событие", в третьем "аларм" — и все считают, что имеют в виду одно и то же.
В DDD это единый язык. Пока «агент» у вас сразу FMA, MA и «просто сервис», путаница уже в разговоре. Кодинг-агент усугубляет ситуацию: он не уточняет, а выбирает самый правдоподобный синоним из обучения.
На практике это выглядит так. В ключ аварии положили текст примечания, а не прописали, что открытие и закрытие — одна сущность и текст должен быть одинаковым 🤯. В итоге закрытие не нашло исходную запись: она висит активной, рядом создается вторая. Дубли не из базы — из неопределённой идентичности.
Поэтому в репозитории лежит CONTEXT.md: только что есть что. Не README или ADR. Реализацию туда не пишем — она протухнет на следующем рефакторинге.
В глоссарии записываем, чем сущность является, а не как она устроена внутри. Рядом — какие слова нельзя. Авария, событие и нотификация у нас разные вещи. Источник — не интеграция. «Открытие» — действие, «активная авария» — состояние. Когда две аварии считаются одной — четко описанное правило, а не «совпали поля в JSON».
Файл обновляется в тот момент, когда термин наконец-то согласован. Если на созвоне термин поплыл, это не вкус, это дыра. Для людей ещё можно переспросить. Агент в новом контексте не видит предыдущую переписку: он прочитает CONTEXT.md или выдумает свой вариант.
