Как описать архитектуру программной системы
Нейросеть составит описание архитектуры программной системы по вашим схемам, коду и заметкам. Вы получите документ о компонентах, их связях и работе системы, а также список вопросов, которые нужно уточнить.
Что указать в промпте
- Из каких компонентов состоит система и как они связаны
Передайте схему, фрагменты кода или своими словами опишите основные части системы и их взаимодействие. Удалите из материалов пароли, токены и другие секреты.
Пример: «Веб-клиент обращается к API заказов, API использует сервис заказов и базу данных»
- Для чего нужна система и кто ею пользуется
Расскажите, какую задачу решает система и кто с ней работает. Например, сотрудники магазина используют приложение для обработки заказов.
Пример: «Сотрудники магазина обрабатывают заказы»
- Как проходят данные и какие правила нужно учесть
Опишите, как запрос проходит между компонентами, и добавьте известные ограничения. Например, укажите путь заказа от веб-приложения до сервиса, который его обрабатывает.
Пример: «Заказ проходит от веб-клиента через API к сервису заказов»
Что вы получите
- Описание компонентов, их обязанностей и связей
- Список вопросов о неизвестных частях системы
Новому разработчику будет проще разобраться, из каких частей состоит система и как между ними передаются данные. А список открытых вопросов покажет, какие связи и условия нужно уточнить у команды, прежде чем считать описание полным.
Как проверить и использовать описание архитектуры системы
Сначала сравните готовое описание архитектуры с имеющимися схемами и кодом. Проверьте, правильно ли названы компоненты, их обязанности и связи. Например, если в документе написано, что API напрямую сохраняет заказы в базу данных, а в коде этим занимается отдельный сервис заказов, исправьте описание. Затем передайте открытые вопросы разработчикам, которые отвечают за соответствующие части системы.
Если система обслуживает несколько организаций, опишите, какие компоненты работают с данными каждой компании и где проходят границы доступа сотрудников. Для понимания контекста корпоративных сервисов пригодятся данные о том, что 62,7% SaaS-компаний работают на рынке B2B. Этот показатель отражает долю SaaS-компаний, предлагающих услуги бизнесу, а не распространенность архитектуры с несколькими организациями. В документации вашего сервиса укажите подтвержденные правила разделения данных между организациями, а неизвестные условия вынесите в открытые вопросы.
Как описать архитектуру программной системы с помощью ИИ
Представьте, что в команду пришел новый разработчик. Ему нужно разобраться, как устроен сервис заказов, но сведения разбросаны по схемам, коду и заметкам коллег. Промпт для описания архитектуры программной системы поможет собрать их в один документ. Нейросеть опишет известные компоненты, связи и потоки данных, а неизвестные детали вынесет в отдельный список.
Начните с того, для чего нужна система и из каких частей она состоит. Допустим, сотрудники магазина обрабатывают заказы через веб-приложение. В схеме указаны веб-клиент, API, сервис заказов и база данных. Опишите обязанности каждого компонента, опираясь на исходные материалы. Читателю должно быть понятно, какая часть принимает действия сотрудника, какая обрабатывает заказы и как компоненты связаны между собой.
Затем разберите один важный поток данных. Например, сотрудник отправляет заказ из веб-приложения, запрос поступает в API, а оттуда передается сервису заказов. Если в материалах указано, что сервис сохраняет заказ в базе данных, включите этот шаг в описание. А вот неизвестный способ связи между API и сервисом лучше оставить открытым вопросом. Не нужно угадывать, используют ли компоненты HTTP, очередь сообщений или другой механизм.
Описывайте и внешние зависимости, если они известны. Например, система обращается к отдельному сервису с ИИ-моделью. В документации стоит указать, какой компонент отправляет запрос модели и куда поступает ответ. Если в вашем проекте используются открытые или локальные модели, дополнительный контекст даст статистика локальных и открытых ИИ-моделей. Она рассказывает об использовании таких моделей разработчиками, а устройство конкретной интеграции нужно описать по материалам вашего проекта.
Примеры разделов документа об архитектуре системы заказов
| Что описываем | Пример содержания |
|---|---|
| Назначение системы | Сотрудники магазина используют приложение для обработки заказов |
| Компоненты и связи | Веб-клиент обращается к API заказов, API передает запрос сервису заказов, а сервис работает с базой данных |
| Поток обработки заказа | Запрос проходит от веб-клиента через API к сервису заказов |
| Открытые вопросы о связях | Каким способом API передает запросы сервису заказов, если это не указано в материалах |
Когда описание архитектуры готово, его удобно использовать для следующих задач: проверки кода, подготовки тестов или разбора отдельных компонентов. Для работы над такими задачами пригодится библиотека промптов для программирования. Раздел постепенно пополняется материалами по разработке. Сохраните согласованную схему и описание системы, чтобы использовать их при дальнейшей работе.
Вопросы об описании архитектуры программной системы
Как подготовить описание архитектуры программной системы с помощью ИИ?
Передайте нейросети схему, фрагменты кода или заметки об устройстве проекта. Для описания архитектуры программной системы ИИ выделит известные компоненты, их обязанности и связи, а также покажет основные потоки данных. Например, объяснит, как запрос проходит от веб-приложения к сервису заказов. Неизвестные детали останутся в отдельном списке вопросов.
Как ИИ опишет архитектуру системы, если доступна только часть кода?
Нейросеть опишет компоненты и взаимодействия, которые удается определить по переданному коду. Например, если виден обработчик API и его обращение к сервису заказов, эти связи можно включить в документ. Но неизвестные части системы придется уточнить у команды. Отсутствие компонента в переданных файлах не означает, что его нет в проекте.
Какие ограничения системы нужно указать в промпте?
Укажите известные правила, которые важны для понимания архитектуры. Например, сотрудники разных магазинов должны работать только со своими заказами, а часть запросов проходит через внешний сервис. Если известно, какие компоненты отвечают за эти правила, назовите их. Не добавляйте предполагаемые ограничения только ради более подробного документа.
Как описать связь компонентов, если неизвестен способ передачи данных?
Опишите то взаимодействие, которое подтверждено материалами. Например, API передает запрос сервису заказов, но из схемы непонятно, как именно это происходит. Так и напишите в документе, а способ передачи данных вынесите в открытые вопросы. Не называйте HTTP или очередь сообщений только потому, что такой способ обычно используют в похожих проектах.
Как поддерживать документацию архитектуры системы в актуальном состоянии?
Обновляйте описание после изменений, которые затрагивают компоненты, их обязанности или взаимодействия. Например, если обработку заказов перенесли из API в отдельный сервис, исправьте схему и описание потока данных. Укажите, кто отвечает за документ, и фиксируйте дату последней проверки. Так новым разработчикам будет проще понять, насколько описание соответствует текущему устройству системы.
