Диаграммы умирают по скучной причине: у них только одна форма, и она не подходит как минимум для половины задач. Рисунок отлично подходит читателю и бесполезен в пул-реквесте. Блок кода диаграммы прекрасно проходит ревью и ничего не сообщает стейкхолдеру. Поэтому команды выбирают что-то одно, а вторая потребность остаётся неудовлетворённой, пока диаграмма не отстанет и все не перестанут ей доверять.
Решение не в выборе. Оно в том, чтобы хранить обе формы и свободно переходить между ними. Код становится диаграммой, когда вы хотите его увидеть; диаграмма становится кодом, когда вы хотите её проверить или сохранить. ИИ сглаживает переход в обе стороны, а сам обмен туда и обратно делает диаграмму долговечной.
Направление первое: генерация диаграммы из кода
У вас уже есть текст, описывающий структуру, будь то Mermaid, D2 или артефакт вроде файла Compose или SQL-схемы. Импортируйте его, и он станет настоящими редактируемыми фигурами, разложенными за вас. Теперь можно делать то, чего не умеет текст: выделить рискованный путь, сгруппировать ограниченный контекст, оставить заметку там, где спрятана хитрая часть.
graph LR
client --> api
api --> cache
api --> db
worker --> queue
Вставьте это, и вы получите не отрендеренную картинку, а набор блоков и стрелок, которые можно взять и передвинуть. Структуру вам бесплатно дал код. Смысл добавляют ваши правки.
Направление второе: код из диаграммы
Теперь наоборот. Вы довели диаграмму на холсте и хотите положить её в репозиторий рядом с кодом, который она описывает, где её можно проверять и версионировать. Экспортируйте её обратно в Mermaid или D2 и закоммитьте текст. Когда кто-то в следующий раз откроет пул-реквест, меняющий систему, код диаграммы изменится в том же ревью, под теми же глазами.
Где ИИ помогает в обмене туда и обратно
С моделью в цикле оба направления становятся проще, но не так, как обещает хайп. ИИ здесь не для того, чтобы заменить код или рисунок. Он нужен, чтобы закрыть неудобные разрывы:
- От свободного описания к чистому коду. Опишите поток одним предложением и получите первую версию кода диаграммы, которую можно отрендерить и доработать.
- От беспорядочной диаграммы к аккуратному коду. Попросите упростить экспортированный текст или переименовать подписи, чтобы закоммиченная версия хорошо читалась.
- От расхождения к свежему черновику. Когда система ушла вперёд, сгенерируйте диаграмму заново из текущего источника и сверьте, вместо того чтобы латать старую картинку вручную.
Две формы одной истины. Код делает её проверяемой; картинка делает её читаемой.
Почему это лучше, чем выбирать сторону
Диаграмма в одной форме навязывает плохой компромисс. Только диаграмма как код даёт проверяемость и картинку, которую никто не любит читать. Только рисунок даёт дружелюбную картинку, которая тихо расходится с кодом. Если хранить обе формы и легко переходить между ними, вы получаете проверяемость текста и ясность визуала из одного источника. Ни одна из форм не становится второсортной.
Привычка, которую стоит выработать: синхронизация диаграмм с кодом
Относитесь к двум формам как к одному артефакту с двумя представлениями. Делайте черновик в той, что быстрее в данный момент (набросайте визуально или напишите структуру текстом), а затем сделайте обмен и получите вторую форму бесплатно. Делайте так постоянно, и вечная проблема устаревшей диаграммы в основном исчезнет, потому что всегда есть дешёвый путь обратно к правильной версии.
Вставьте код диаграммы и доработайте его или нарисуйте что-нибудь и экспортируйте код. Когда вы однажды почувствуете этот обмен туда и обратно, поддержание диаграммы в актуальном виде перестанет быть повинностью, которую вы пропускаете.