АРТЕФАКТЫ · ОБЗОР

Как вести артефакты команды

Через полгода после релиза у команды есть либо файлы с ответами, либо мифы. Разница не в дисциплине людей - разница в том, есть ли место, куда решения обязаны ложиться. Эта статья о том, что такое артефакт в инженерной практике, как выглядит нормальный ритм работы с ними и почему большинство документации умирает ещё до первого пересмотра.

Что считается «артефактом»

В обычной речи «артефакт» - любой рабочий файл. В инженерной практике журналирования это слово означает конкретную вещь: запись с обязательной структурой, которая фиксирует одно решение, одно требование или одно доказательство.

Три свойства отличают артефакт от обычного документа.

Первое - обязательные поля. Артефакт без поля «условие пересмотра» - неполный артефакт, а не просто «неудобный документ». Структура не рекомендация, а контракт. Если поле пропущено, запись будет молча деградировать в устаревший памятник.

Второе - версионируется. Артефакт хранится рядом с кодом, в системе контроля версий. История изменений читается как git-лог: кто, когда и что именно переосмыслил. Это не «последняя версия в облаке», а полная хронология.

Третье - после активации не редактируется, а пересматривается. Вместо того чтобы тихо исправить старый файл, команда открывает новый пересмотр - с отдельной записью, датой и мотивировкой. Это фундаментальное отличие от вики: в вики правка незаметна, в артефакте - всегда видна.

Один файл, одна ответственность

Самый частый антипаттерн: «давайте соберём все решения за квартал в один большой документ». Или: «у нас есть мастер-спецификация, всё там». Логика понятна - меньше файлов, меньше переключений.

Проблема обнаруживается через четыре-шесть месяцев. Мастер-документ разрастается до 80 страниц. Поиск нужного решения занимает час. Никто не знает, что актуально, а что давно устарело. Условие пересмотра если и было, то утонуло где-то в середине. В итоге документ превращается в «архив, который мы не открываем».

Принцип «один файл - одно решение» решает эту проблему напрямую. Когда меняется контекст для одного выбора - открывается ровно тот файл, который к нему относится. Пересмотр не затрагивает соседние решения. Статус каждого решения («активно», «пересмотрено», «устарело») виден без чтения всего документа.

Практически это выглядит так: решение о выборе базы данных - отдельный файл. Решение о формате API - отдельный файл. Требование к производительности - отдельный файл. Доказательство того, что требование выполнено - ещё один отдельный файл, с явной ссылкой на требование.

Звучит как много файлов. На практике за год активная команда накапливает 40-80 артефактов - это нормально. Главное не количество, а то, что каждый из них отвечает на один вопрос, и его легко найти через поиск по ключевому слову.

Ритм работы с артефактами

Нет смысла изучать структуру артефактов отдельно от цикла работы с ними. Типичный цикл выглядит так - от первого черновика до момента, когда запись перестаёт быть актуальной.

1. Создать черновик

   Завести запись по шаблону, заполнить контекст и предварительную мотивировку. Черновик - не обязательство: это пространство для мышления вслух перед тем, как записать окончательный выбор.
2. Заполнить обязательные поля

   Контекст, варианты (минимум три), доказательства, выбранный вариант, причины отказа от других, условие пересмотра. Пока хотя бы одно поле пропущено - черновик не готов к активации.
3. Проверить на валидность

   Кто-то из команды читает запись и отвечает на один вопрос: «если я буду работать с этим через год, пойму ли, что именно решено и почему». Если нет - возвращается на доработку.
4. Активировать

   Запись переходит из черновика в активное состояние. С этого момента она не редактируется, только пересматривается. Команда может на неё ссылаться как на источник истины.
5. Следить за условием пересмотра

   Каждая активная запись несёт дату или событие, по которому нужно вернуться. Инструмент журналирования показывает «устаревшие» записи - те, у которых дата пересмотра прошла. Это не ошибка, это сигнал.
6. Пересмотреть или продлить

   Два исхода: решение всё ещё актуально - продлить с новой датой и краткой мотивировкой. Решение устарело - открыть новый черновик с обновлённым контекстом и начать цикл заново. Старая запись остаётся как история.

Что отличает живой артефакт от мёртвого

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

Автор - реальный человек, не «секретарь команды». Мёртвые документы часто написаны нейтральным корпоративным голосом без имени: «было решено», «команда постановила». Живой артефакт подписан конкретным человеком, который сделал конкретный выбор. Это не вопрос ответственности - это вопрос контекста. Через год читатель знает, кому задать уточняющий вопрос, если запись неполная.

Есть условие пересмотра, которое сработает само. Не «пересмотреть когда-нибудь», а конкретный триггер: «через 6 месяцев», «при росте нагрузки в три раза», «при выходе новой версии библиотеки». Что-то, что не требует, чтобы кто-то это вспомнил. Инструмент журналирования помечает устаревшие записи - и именно поэтому важно, чтобы каждая запись несла это условие.

Доказательства привязаны, а не упомянуты вскользь. «Мы проверяли - всё нормально» - это не доказательство. Живой артефакт ссылается на конкретный замер: «тест на реальных данных показал 230 мс при пиковой нагрузке, данные от 12 апреля, файл такой-то». Когда контекст меняется, видно, актуален ли замер или он сделан при других условиях.

Антипаттерны

Четыре ошибки, которые я видел чаще всего. Каждая выглядит разумно в моменте и разрушительна через полгода.

• АРХИВНАЯ СВАЛКА
  Команда создаёт артефакты, но никогда не пересматривает. Через год в репозитории 60 «активных» записей, половина из которых описывает реальность, которой больше нет. Никто не решается трогать «потому что вдруг что-то сломается».
• ТИХАЯ ПРАВКА
  Кто-то открывает активный артефакт и молча исправляет формулировку «чтобы актуализировать». Изменение не датировано, мотивировка не записана. Через три месяца никто не знает, когда именно поменялось решение и что было до.
• ШАБЛОН БЕЗ ЗАПОЛНЕНИЯ
  Файл создан по шаблону, но поля заполнены формально: «контекст - работаем над проектом X», «варианты - рассмотрели несколько», «условие пересмотра - по необходимости». Такая запись хуже пустой: она создаёт иллюзию того, что документация есть.
• МЕГАДОКУМЕНТ
  Все решения квартала - в одном файле. Каждый раз при изменении одного решения файл редактируется целиком. Git-история нечитаема. Никто не понимает, что изменилось и когда. Поиск нужного решения занимает 20 минут.
• АРТЕФАКТ БЕЗ ДОКАЗАТЕЛЬСТВ
  Решение выбрано, записано, активировано - но доказательства не привязаны. «Мы решили» без «потому что замер показал». Такой артефакт описывает выбор, но не даёт возможности проверить, актуален ли он при изменившихся данных.

Глубже

Две следующие статьи разбирают отдельные части практики детально: как устроен полный цикл принятия одного решения и что происходит с записью после активации.