Артефакты аналитической деятельности
ERD — Entity Relationship; SQL — SQL для аналитики, SQL; миграции — Пакетная работа. Полная таблица — о разделе.
Play ITЗагрузка интерактивного демо…
Диаграмма классов — мост к коду: проектирование сущности, ООП — о разделе. OpenAPI и контракты — технический дизайн.
Артефакт — это любой документ, схема, модель или запись, которая фиксирует знания, решения или требования в процессе разработки продукта/системы.
Что такое артефакт?
Артефакт (от лат. artefactum — "искусственно созданное") — это любой осязаемый или формализованный продукт интеллектуальной деятельности, создаваемый в ходе жизненного цикла разработки программного обеспечения или информационной системы. Артефакт может существовать в материальной форме (например, печатный документ) или в цифровой (файл спецификации, диаграмма, код, тест-кейс), но в любом случае он фиксирует решение, знание, требование или результат на определённом этапе проекта.
Происхождение термина
Термин "артефакт" был заимствован из гуманитарных и естественных наук, где он обозначает объект, созданный человеком, в отличие от природного явления. В археологии, например, артефактом считается любой предмет, изготовленный или изменённый людьми (орудие труда, украшение, черепок). В медицине и технике термин приобрёл значение побочного эффекта, возникающего в результате вмешательства (например, шум на МРТ-снимке — артефакт сканирования).
В инженерии программного обеспечения термин закрепился в конце XX века в рамках формализации процессов разработки. Он был популяризован методологиями, такими как RUP (Rational Unified Process) и позднее — Agile/Scrum, где под артефактом понимали любой выходной продукт спринта или фазы: от пользовательской истории до исполняемого модуля.
В ИТ-контексте артефакт является целевым результатом интеллектуального труда. Это — след мышления, зафиксированный в структурированной форме.
Почему артефакты важны?
Артефакты выполняют несколько ключевых функций:
- Фиксация знаний — предотвращают "потерю в головах" при смене команды или отсутствии участника.
- Коммуникация — служат общим языком между заказчиком, аналитиком, разработчиком, тестировщиком и администратором.
- Прослеживаемость — позволяют отследить путь от бизнес-цели до реализации и проверки.
- Контроль качества — предоставляют основу для ревью, верификации и валидации.
- Юридическая и нормативная защита — подтверждают выполнение договорных обязательств и соответствие стандартам.
Отсутствие артефактов ведёт к росту когнитивной нагрузки, дублированию усилий, ошибкам интерпретации и, в конечном счёте, к провалу проекта.
Виды артефактов
Артефакты классифицируются по нескольким осям. Наиболее значимое деление — по типу содержания и стадии жизненного цикла:
- Аналитические проектные артефакты — фокусируются на понимании предметной области, выявлении и формулировании требований.
- Технические проектные артефакты — описывают архитектурные, конструктивные и реализационные решения.
- Исполняемые артефакты — исходный код, скрипты, бинарные файлы.
- Эксплуатационные артефакты — руководства, логи, мониторинги.
- Оценочные артефакты — тест-планы, протоколы, отчёты.
Далее рассматриваются первые две категории — аналитические и технические проектные артефакты — как наиболее значимые на этапах проектирования.
Аналитические проектные артефакты
Аналитические артефакты создаются в ходе системного и бизнес-анализа. Их цель — понять, что должно делать система, а не как она это будет делать.
Основные виды
1. Use Case (прецедент использования)
Use case — это описание последовательности действий, которые система выполняет в ответ на запрос актора (пользователя, внешней системы), чтобы достичь измеримой бизнес-цели.
Назначение:
- Фиксация функциональных требований в контексте взаимодействия;
- Выявление основных и альтернативных потоков;
- Основа для проектирования интерфейсов и тестирования.
Структура (по классической нотации):
- Название (глагол + объект: "Регистрация входящего документа");
- Акторы (основной и второстепенные);
- Предусловия;
- Основной поток (успешный сценарий);
- Альтернативные потоки (ошибки, исключения);
- Постусловия.
Use case особенно эффективен в системах с чётко выраженной ролевой моделью и предсказуемыми сценариями (корпоративные ИС, АСУ).
Use Case (вариант использования) — это структурированное описание последовательности действий, которые система и пользователь совершают вместе для достижения конкретной цели. Часто используется в традиционных (waterfall) и сложных системах.
Если сделать упрощённый шаблон, то формат у него был бы такой:
Название: [Название сценария]
Актор: [Кто инициирует?]
Цель: [Зачем это нужно?]
Основной сценарий (основной поток):
1. Пользователь нажимает "Добавить в корзину".
2. Система проверяет наличие товара.
3. Система добавляет товар в корзину.
4. Система обновляет сумму и отображает уведомление.
Альтернативные потоки:
- Если товара нет → показать сообщение "Нет в наличии". Исключения:
- Если сессия истекла → перенаправить на логин. Постусловия:
- Корзина содержит товар, сумма обновлена.
Use Case нужны, чтобы детально описать логику взаимодействия, увидеть все ветки и исключения, передать разработчикам и тестировщикам полную картину, построить диаграммы.
2. User Story (пользовательская история)
User Story — краткое описание функции с точки зрения конечного пользователя, сформулированное по шаблону:
"Как [роль], я хочу [действие], чтобы [бизнес-выгода]".
Пример:
"Как бухгалтер, я хочу формировать отчёт по НДС за квартал, чтобы сдать его в налоговую службу".
Назначение:
- Фокус на ценности для пользователя;
- Поддержка итеративной разработки;
- Гибкость в уточнении требований.
Структура:
- Заголовок;
- Тело (по шаблону выше);
- Критерии приёмки (acceptance criteria) — условия, при которых история считается завершённой;
- Оценка (story points);
- Приоритет.
User Story доминирует в гибких методологиях (Scrum, Kanban), но требует дисциплины: без чётких критериев приёмки она превращается в "воду".
User Story (пользовательская история) — это краткое, простое описание функции системы с точки зрения конечного пользователя, написанное в неформальном, разговорном стиле. Формат у неё, как правило, единый:
Как [роль], я хочу [действие], чтобы [цель / выгода].
Как покупатель, я хочу добавить товар в корзину, чтобы собрать заказ перед оплатой. Как администратор, я хочу видеть список заблокированных пользователей, чтобы управлять безопасностью.
User Story позволяет не забывать о пользователе, быстро передавать суть команде, приоритезировать по ценности и разбивать большие задачи на маленькие.
К User Story добавляются критерии приёмки, условия, при которых задача считается выполненной. К примеру:
- Товар появляется в корзине.
- Сумма корзины обновляется.
- Иконка корзины показывает +1.
- Можно добавить тот же товар повторно → количество увеличивается.
3. Job Story (история задачи)
Job Story — альтернатива User Story, основанная на концепции "Jobs to be Done" (JTBD). Фокус смещается с кто и что на контекст и мотивацию:
"Когда [ситуация], я хочу [мотивация], чтобы [ожидаемый результат]".
Пример:
"Когда я обрабатываю сотни документов в день, я хочу быстро находить дубликаты, чтобы не тратить время на повторную обработку".
Преимущества:
- Устраняет предвзятость по ролям;
- Лучше раскрывает причины поведения;
- Подходит для инновационных продуктов, где роли неочевидны.
Job Story особенно полезна на ранних этапах проектирования, когда модель пользователя ещё формируется.
Технические проектные артефакты
Технические артефакты отвечают на вопрос "как будет реализована система". Они создаются архитекторами, системными инженерами и senior-разработчиками.
Основные виды
1. Архитектурное описание (Architecture Description)
Назначение — определение высокоуровневой структуры системы — компонентов, их взаимодействия, платформы, принципов масштабирования и безопасности.
Структура (часто по 4+1 view model):
- Логическое представление (компоненты, классы);
- Процессное представление (потоки, параллелизм);
- Физическое размещение (серверы, сети, контейнеры);
- Сценарии использования (key use Кейсы);
- Технические ограничения и принятые компромиссы.
2. Техническая спецификация модуля
Назначение — детальное описание интерфейса, алгоритмов, структур данных и зависимостей конкретного модуля или сервиса.
Структура:
- Назначение модуля;
- Входные/выходные данные;
- API (методы, параметры, ошибки);
- Диаграммы последовательности или состояний;
- Требования к производительности и надёжности.
3. Спецификация API (OpenAPI, AsyncAPI)
Формализованное описание программного интерфейса в машиночитаемом формате. Используется для генерации клиентов, документации и автоматизированного тестирования.
4. Диаграммы (UML, BPMN, C4)
Общая теория, терминология и выбор нотации — основы диаграмм и моделирования. Ниже — виды артефактов:
Play ITЗагрузка интерактивного демо…
- UML — для описания структуры и поведения ПО (диаграммы классов, последовательности, состояний);
- BPMN — для моделирования бизнес-процессов;
- C4 Model — для многоуровневого описания архитектуры (Context, Containers, Components, Code).
5. Программа и методика испытаний (ПМИ)
Как рассмотрено ранее, ПМИ — технический артефакт, фиксирующий методы верификации. Он закрывает цикл: от требования → к реализации → к проверке.
Взаимосвязь артефактов
Артефакты не существуют изолированно. Между ними устанавливается сетевая связность:
- User Story → Use Case — при переходе от гибкой постановки к формальному описанию;
- Use Case → API-спецификация — при проектировании интерфейсов;
- API-спецификация → Тест-кейсы — при автоматизации проверок;
- Архитектурное описание → Техническая спецификация — при декомпозиции системы.
Эта связность обеспечивает целостность проекта и минимизацию расхождений между ожиданиями и реализацией.
Жизненный цикл артефакта и практики его сопровождения
Артефакт в инженерной практике не является статичным документом, созданным "один раз и навсегда". Напротив, он проходит жизненный цикл, сопоставимый с жизненным циклом программного обеспечения. Понимание этого цикла позволяет избежать как недостаточной актуальности документации, так и избыточной бюрократии.
Этапы жизненного цикла артефакта
-
Инициация
Артефакт создаётся в ответ на потребность — требование заказчика, архитектурное решение, необходимость тестирования. На этом этапе определяются:- тип артефакта (use case, спецификация, диаграмма и т.д.);
- владелец (аналитик, архитектор, техлид);
- целевая аудитория;
- уровень формальности.
-
Создание и согласование
Артефакт разрабатывается с учётом шаблонов, стандартов и контекста проекта. Затем проходит ревью с участием заинтересованных сторон:- заказчик проверяет соответствие бизнес-цели;
- разработчик — реализуемость;
- тестировщик — тестируемость.
Результат — утверждённая версия, зафиксированная в системе управления.
-
Использование
Артефакт становится основой для:- постановки задач (JIRA);
- написания кода;
- разработки тестов;
- обучения пользователей.
На этом этапе важно, чтобы артефакт был легко доступен и понятен целевой аудитории.
-
Поддержка и актуализация
При изменении требований, архитектуры или внешней среды артефакт обновляется. Процедура изменения включает:- фиксацию причины (например, "изменено требование п. 4.2 ТЗ");
- согласование изменений;
- обновление связанных артефактов (например, если меняется API — обновляются и use case, и тест-кейсы).
Хорошая практика — вести историю версий (например, через Git или Confluence history).
-
Архивация или утилизация
По завершении проекта или выводу системы из эксплуатации артефакты архивируются для:- аудита;
- передачи знаний;
- анализа ошибок в будущем.
В некоторых отраслях (медицина, авиация) срок хранения регламентирован законодательно (10–30 лет).
Инструменты управления артефактами
Современные команды используют комбинацию инструментов для хранения, версионирования и связывания артефактов:
| Тип артефакта | Типовой инструмент | Особенности |
|---|---|---|
| Требования (user story, use case) | JIRA, Azure DevOps | Связь с задачами, эпиками, спринтами |
| Текстовая документация | Confluence, Notion, Wiki | Гипертекст, совместное редактирование |
| Архитектурные диаграммы | Draw.io, Lucidchart, PlantUML | Встраивание в Confluence/Markdown |
| Спецификации API | Swagger Editor, Postman, Stoplight | Машиночитаемость, генерация клиентов |
| Технические спецификации | Markdown в Git-репозитории | Docs-as-code, CI-проверки |
| Тестовая документация | TestRail, Xray, Zephyr | Интеграция с JIRA и CI |
| Нормативные артефакты (ТЗ, ПМИ) | PDF/DOCX в системе ЭДО | Подпись, штампы, контроль подлинника |
Ключевой принцип: единое информационное пространство. Идеально, когда по ссылке из задачи в JIRA можно перейти к use case в Confluence, оттуда — к OpenAPI-спецификации в репозитории, а от неё — к автоматизированным тестам в GitLab CI.
Практики обеспечения качества артефактов
Качество артефакта оценивается по следующим критериям:
- Полнота — все аспекты требования раскрыты;
- Однозначность — отсутствие двусмысленностей;
- Согласованность — нет противоречий с другими артефактами;
- Тестируемость — возможно сформулировать критерии приёмки;
- Актуальность — соответствует текущему состоянию системы;
- Доступность — легко находим и понятен целевой аудитории.
Для поддержания качества применяются:
- Checklist’ы ревью (например: "Есть ли критерии приёмки?", "Указаны ли акторы?");
- Шаблоны и стили (например, корпоративный гайд по написанию user story);
- Автоматическая проверка (например, валидация OpenAPI-спецификации в CI);
- Регулярный аудит (раз в квартал — проверка устаревших страниц в Confluence).
Артефакты и культура команды
В конечном счёте, отношение к артефактам отражает инженерную культуру:
- В командах с низкой зрелостью артефакты воспринимаются как "бумажка для заказчика" — пишутся в последний момент, содержат общие фразы, не обновляются.
- В зрелых командах артефакты — рабочий инструмент: их пишут чтобы уменьшить неопределённость, ускорить разработку и избежать ошибок.
Ключевая установка:
"Если это не задокументировано — этого нет". это защита от хаоса в условиях роста сложности.
Как не утонуть в количестве артефактов
У начинающих команд часто возникает крайность: либо артефактов почти нет, либо документов слишком много и ими никто не пользуется. Практичный подход - заводить артефакт только под конкретный риск или задачу коммуникации.
Примеры:
- если спорят о границах поведения - нужен use case или сценарная спецификация;
- если непонятны границы сервиса - нужна архитектурная диаграмма;
- если есть риск провала приемки - нужна прозрачная связка требований и проверок.
Главный критерий: артефакт должен помогать принять решение или снизить неопределенность.
Карта связности "от идеи до проверки"
Полезно держать у каждого крупного требования цепочку:
проблема бизнеса -> user story/job story -> use case -> техническая спецификация -> тесты/ПМИ -> протокол результата
Эта цепочка особенно важна в проектах с несколькими командами, где контекст быстро теряется.
См. также:
- процессы ведения документации - Документация в процессах;
- моделирование и диаграммы - Моделирование бизнес-процессов;
- технический дизайн и реализация требований - Технический дизайн на основе требований.
Базовая теория (глава 2) для артефактов с API, интеграциями и NFR: OpenAPI и REST, интеграционные потоки, сеть и TLS, ИБ в требованиях.
Практическая проверка качества артефакта
Перед публикацией документа можно пройти простой тест:
- Читателю понятна цель артефакта за первые 30 секунд.
- Понятно, какие решения уже приняты, а что открыто.
- Видны связи с соседними документами и задачами.
- Есть критерий, по которому можно проверить корректность.
Если ответы "нет", стоит расширить пояснения и добавить примеры, а не только список пунктов.