Debugging AI-Generated Diagrams
Великолепный текст Why Your AI-Generated C4 Diagrams Look Terrible (And How to Fix Them) опубликовал пару дней назад David R Oliver. Добрую половину занятия про Diagram as Code из моего нового курса Проектирование ИТ-решений с использованием Cursor AI можно было бы сделать на основе этого материала. Выводы автора абсолютно созвучны моим наблюдениям о том, когда использовать Mermaid, а когда PlantUML, с чем большие языковые модели справятся, а когда им надо немного помочь. И список ссылок в статье потрясающий.
А еще автор не поленился сделать несколько agent skills для генерации diagram as code и выложил их сюда: github.com/DavidROliverBA/Daves-Claude-Code-Skills
Для тех, кто поленится читать оригинальный текст, соберу конспект из основных рекомендаций. Они подходят для любой модели (ну, для тех, что я посмотрел, по крайней мере) и могут быть полезны как при использовании сред (IDE) так и в чатах
Сначала набор антипаттернов рисования архитектурных диаграмм посредством ИИ:
- Antipattern 1: Random Element Order. Самая частая проблема. В псевдокоде модель напишет элементы в том порядке, в которым вы их укажите. Получится некрасиво. Сначала придумай как отсортировать элементы, а затем напишите это в промпт.
- Antipattern 2: Vague Refinement Requests. Править результат работы модели отдельная черная магия и запрос «попробуй нарисовать еще раз» вряд ли приведет к желаемому результату
- Antipattern 3: Relationships Before Elements. Если сначала задать несколько элементов и связей между ними, а после дописать еще несколько элементов и еще немножко связей, а затем еще элементов – получится так себе. Сначала задаем все элементы (и группирующие их контейнеры), а потом отношения между ними
- Antipattern 4: No Crossing Target. Просто скажите модели, что следует минимизировать количество пересечений линий на диаграмме. Она же не знает, что вы хотите. Может ваша цель – поразить руководство витиеватом узором пересечений стрелок в spaghetti-like architecture.
Рекомендации
- Specify Elements in Tier Order. Именно так. Я очень надеюсь, что в ближайшие годы в инструменты Diagram as Code придут тривиальные, но крайне полезные механизмы современной веб-верстки, ну а пока мы будет группировать элементы вручную и явно рассказывать модели что и где рисовать
- Declare Relationships in Flow Order. Чтоб раз и навсегда этому научиться следует просто понять, что скорее всего любая ваша диаграмм это ацикличный ориентированный граф, именуемый в народе DAG (Directed Acyclic Graph). И в нем можно выделить (и вытянуть в прямую линию) самый длинный путь А множество остальных ветвлений представить в качестве расширений основного сценарий. Вспомните про use cases от ivar jacobsonс и Alistair Cockburn
- Specify Styling. Возможно, что это лучше сделать уже потом, по готовой диаграмме. Ну или если не хочется вспоминать синтаксис задания стилей и самому подбирать палитру, то озадачим этим моделей, а потом подправим.
- Set Constraints. За исключением LR(for left-to-right), TB(top-to-bottom) работает только для PlantUML, да и то не всегда.
Интересуетесь темой? Непременно прочитайте статью. И, конечно, делитесь своим мнением в комментариях.