Modelith: доменная модель больше не пылится в документации

Давайте признаемся — почти каждый проект начинается с благих намерений. Кто-то рисует доменную модель на доске, все кивают, а потом... она тихо умирает в Confluence, где её уже никто не откроет.

Проблема не в самой идее доменного моделирования. Дело в том, что доменные модели обычно:

• Пишутся один раз и забываются
• Живут отдельно от кода
• Читаются только в специальных инструментах
• Практически не поддаются автоматической проверке

Modelith работает иначе. Здесь доменная модель — это не документация, которую сдали и забыли. Это живой артефакт, который живёт рядом с кодом, создаётся через диалог и автоматически проверяется в CI.

Что такое доменная модель?

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

Представьте это как общий словарь для всей команды. Когда все читают из одной модели, разговоры становятся точнее, онбординг быстрее, а добавление новых фич не превращается в археологические раскопки в legacy-коде.

Как работает Modelith: описываем, создаём, проверяем, генерируем

Самое интересное — вам не нужно писать YAML вручную. Вы вообще не думаете о YAML. Вы описываете свои доменные концепции обычным языком AI-агенту (конкретно — навыку для Claude Code), а тот уже формирует YAML-файл.

Весь процесс выглядит так:

1. Описываете — Рассказываете о домене на простом английском. «У нас есть клиенты, которые делают заказы. В заказе может быть несколько товаров. При этом у клиента не может быть больше трёх активных заказов одновременно.»

2. Создаёте — Плагин для Claude Code переводит ваше описание в файл modelith.yaml, параллельно проверяя корректность.

3. Проверяете — Запускаете modelith lint, чтобы убедиться в полноте и согласованности. Эта проверка становится гейтом в CI.

4. Генерируете — Выполняете modelith render для создания Markdown с Mermaid-диаграммами. Коммитите результат рядом с YAML.

Сгенерированный Markdown можно читать без каких-либо инструментов. YAML — это машиночитаемая основа. А CI гарантирует, что они никогда не разойдутся. По сути, это как проверка сгенерированного кода, только для доменной модели.

Почему этот подход работает

Простой язык снижает порог входа

Не каждый в команде комфортно читает JSON Schema или UML-диаграммы. Но понять простой английский могут все. Сделав обычный язык точкой входа, Modelith демократизирует доменное моделирование. Ваш продакт-менеджер может вносить вклад. QA-инженер — проверять. Джуниор-разработчик — реально видеть картину целиком.

AI берёт на себя рутину

Писать YAML руками — это и ошибки, и скука. Делегировав перевод описания в валидный YAML AI-агенту, вы снимаете когнитивную нагрузку, но сохраняете точность.

Проверки в CI не дают модели устареть

Это киллер-фича для команд. Доменная модель становится полноценной частью рабочего процесса. Каждый PR, который затрагивает домен, автоматически проверяется. Кто-то обновил YAML, но забыл перегенерировать документацию? CI это заметит.

Модель живёт рядом с кодом

Когда доменная модель лежит в том же репозитории, что и код, она остаётся актуальной. Её смотрят в пул-реквестах. Обновляют при изменении фич. Она не становится забытой документацией в какой-то другой системе.

С чего начать

Modelith задуман так, чтобы быть доступным. Не нужно сразу понимать всю схему. Действуйте постепенно:

• Установите плагин для Claude Code
• Опишите несколько ключевых понятий вашего домена
• Позвольте AI сгенерировать YAML
• Запустите modelith lint, чтобы увидеть, чего не хватает
• Повторяйте

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

Большая картина

Modelith отражает общий тренд в AI-assisted разработке: использовать естественный язык как слой взаимодействия, а под капотом держать машиночитаемые артефакты. Вы пишете то, что имеете в виду, а инструменты обеспечивают согласованность и валидацию.

Для команд, которые строят сложные системы — особенно в областях, где терминология критична (финтех, медицина, логистика, всё, где много бизнес-правил) — такой подход может быть трансформационным. Общая, проверенная, живая доменная модель означает меньше недопониманий, быстрый онбординг и более продуманную архитектуру.

Инструмент ещё развивается, но базовая идея крепкая. Ваша доменная модель не должна быть afterthought или артефактом со старта проекта. Она должна быть живым документом, который эволюционирует вместе с кодом, создаётся через диалог и проверяется автоматически.

Если вы сталкивались с проблемой устаревания доменных моделей в своих проектах, Modelith стоит попробовать. Иногда лучший инструмент — не самый мощный, а тот, который делает правильное поведение путём наименьшего сопротивления.

Загляните на modelith.sh, чтобы начать.