Документирование: user story, use case, спецификация, критерии приёмки

Требование существует в трёх состояниях: в чьей-то голове, в разговоре и в артефакте. Первое не переживает отпуск, второе — неделю, и только третье можно передать, проверить и оспорить. Документирование — это не «оформить бумагу», а зафиксировать принятое решение в форме, по которой его можно воспроизвести без автора.

Отсюда весь дизайн работы аналитика с документами: форма выбирается под срок жизни знания и цену ошибки, а не под требования регламента. В предыдущей статье мы разложили требования по уровням — бизнес, пользовательские, функциональные, нефункциональные (виды требований). Теперь разберём, чем именно записывают каждый уровень, как выглядит хорошая история, когда её не хватает и почему большинство споров на приёмке — это споры о том, чего в документе не было.

1. Три работы, которые выполняет артефакт

Любой документ аналитика нанимают на одну из трёх работ. Спутать их — главный способ написать бесполезный текст.

Одна user story может делать все три работы, если у неё есть тело (договориться), место хранения со ссылками (вспомнить) и критерии приёмки (проверить). Спецификация на сорок страниц без критериев приёмки не делает третью работу вообще — по ней невозможно сказать «готово».

Стоимость документа считается не по времени написания. Полная формула такая:

Стоимость = написание + (чтение × N читателей) + (обновление × M изменений) + цена расхождения
Выгода    = предотвращённые переделки + сэкономленные вопросы + скорость входа нового человека

Из формулы следуют два неочевидных вывода. Первый: длинный документ дороже не в момент написания, а на каждом чтении — двадцать человек по двадцать минут это шесть с половиной часов на один документ. Второй: документ, который не обновляют, имеет отрицательную выгоду — по нему принимают решения, считая его актуальным, и получают расхождение. Отсюда практическое правило: документ живёт ровно столько, сколько влияет на решения; дальше его либо обновляют, либо честно помечают «устарело, источник истины — код и тесты».

Полезная метафора: документ — это кэш решения, а не само решение. Решение принимают люди в разговоре; документ хранит его копию. У кэша есть срок жизни, владелец и стратегия инвалидации, и если их нет — вы работаете с грязными данными.

2. Карта артефактов: чем что описывают

Базовый набор форм и их специализация:

Выбор артефакта — механическая процедура, а не вопрос вкуса:

Ключевое в этой схеме — последний шаг. Бизнес-правило почти всегда переиспользуется, и попытка записать его внутрь истории приводит к трём разъехавшимся копиям. Правило живёт в реестре с идентификатором (BR-07), а истории, спецификация и тесты на него ссылаются.

Сквозной пример статьи — смена тарифа в B2B SaaS с пересчётом оплаты. Домен выбран намеренно неудобный: тут есть деньги, внешний биллинг, права доступа, расчётные периоды и десяток исключений, которые невозможно вспомнить «на глаз».

3. User story: карточка, разговор, подтверждение

3.1. Что такое история на самом деле

User story — это не формат требования, а обещание разговора. Формулировка Рона Джеффриса про три C (Card, Conversation, Confirmation) объясняет всё устройство: карточка — напоминание, разговор — место, где рождается смысл, подтверждение — критерии приёмки.

Из этого следует практический вывод, который экономит недели: история не обязана содержать всё. Она обязана быть достаточной, чтобы команда поняла, о чём разговаривать, и содержать критерии, чтобы понять, когда закончили. Попытка втиснуть в историю полную спецификацию — самый распространённый способ получить документ, который никто не читает.

3.2. Шаблон и что в нём важно

Классический шаблон Connextra («как …, я хочу …, чтобы …») популяризировал Майк Кон в «User Stories Applied». Разберём рабочую историю из нашего примера:

US-311. Понижение тарифа с ближайшего расчётного периода

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

Ценность:    38% обращений в поддержку по биллингу — «как понизить тариф»;
             гипотеза: доля самостоятельных изменений тарифа 0% → 70% за квартал.
В скоупе:    выбор младшего тарифа, расчёт даты вступления, предупреждение о потере
             функций, письмо-подтверждение, отражение в счёте следующего периода.
Вне скоупа:  повышение тарифа (US-312), смена валюты (US-340), возврат средств
             за текущий период — запрещён BR-07.
Правила:     BR-07 (нет понижения внутри оплаченного периода), BR-12 (лимит мест),
             BR-15 (грейс-период на превышение лимита).
Открытые вопросы:
             Q-4. Что происходит с местами сверх лимита нового тарифа?
                  Владелец: продуктовый директор, срок: до 14.08.

Что здесь делает работу:

• Роль конкретная. Не «пользователь», а «администратор, урезающий расходы в конце квартала» — из этого сразу видно, что он придёт в последние дни месяца, то есть в пик нагрузки на биллинг.
• Ценность — проверяемая гипотеза с числом. Она нужна не для красоты: когда бюджет кончится, именно по ней решают, резать историю или нет.
• «Вне скоупа» — самая дешёвая строка в документе и самая экономная. Одна строка про границы стоит секунды, час спора на приёмке — денег.
• Ссылки на правила по идентификаторам. Текст правила в историю не копируется никогда.
• Открытый вопрос с владельцем и сроком. Единственный честный способ показать, что решение ещё не принято, и не дать неизвестности тихо просочиться в код.

Чек-лист INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable) разобран в обзоре трека; здесь важнее то, что INVEST не проверяет: он ничего не говорит про полноту исключений — за это отвечают критерии приёмки.

3.3. Когда шаблон мешает

Шаблон Connextra не универсален. Три случая, где он вредит:

1. Роль всегда одна и та же. В админке внутренней системы «как оператор» в каждой из двухсот историй — шум. Пишите повелительное наклонение: «Показывать в списке заявок колонку срока SLA с подсветкой просроченных». Смысл не теряется, читать быстрее.
2. Ценность не пользовательская, а системная. Замена библиотеки шифрования не имеет «как пользователь, я хочу». Для этого есть enabler-истории: формулируйте через риск и последствие: «Перейти на поддерживаемую версию OpenSSL до 30.09, иначе не проходим PCI-аудит и теряем эквайринг».
3. Контекст важнее роли. Формат job story Алана Клемента (Replacing the User Story with the Job Story) переносит акцент на ситуацию: «Когда я получил счёт больше ожидаемого, я хочу увидеть расшифровку изменений тарифа, чтобы понять, за что списали, и не идти в поддержку». Для биллинга это часто точнее — ситуация объясняет поведение лучше, чем должность.

3.4. Антипаттерны историй

Про декомпозицию — как резать историю, чтобы каждый кусок оставался ценным, — подробно в аналитике в Agile. Про то, как истории складываются в карту продукта, — у Джеффа Паттона (User Story Mapping) и в треке продуктового менеджмента.

4. Критерии приёмки: место, где текст становится проверяемым

4.1. Два формата и когда какой

Чек-лист — список утверждений, каждое из которых можно проверить «да/нет». Годится, когда проверок много и они простые.

Сценарии Given/When/Then (Gherkin, разбор формата у Мартина Фаулера) — когда важен контекст и последовательность, когда результат зависит от состояния или когда критерий сразу превращается в автотест.

Практика: основной поток и типовые ветки — сценариями, а мелкие ограничения — чек-листом. Всё сценариями — многословно; всё чек-листом — теряется состояние.

Функция: Понижение тарифа администратором

  Предыстория:
    Дано рабочее пространство "Акме" на тарифе "Business", 25 мест
    И расчётный период оплачен до 2026-08-31
    И текущая дата 2026-08-14

  Сценарий: Понижение вступает в силу со следующего периода
    Когда администратор выбирает тариф "Team" и подтверждает переход
    Тогда создаётся запланированное изменение с датой 2026-09-01
    И до 2026-08-31 функции тарифа "Business" остаются доступны
    И в счёте за сентябрь указана цена тарифа "Team"
    И администратору уходит письмо с датой вступления и списком теряемых функций

  Сценарий: Мест больше, чем разрешает новый тариф
    Дано в пространстве 25 активных участников, лимит тарифа "Team" — 10
    Когда администратор выбирает тариф "Team"
    Тогда система показывает, что нужно освободить 15 мест до 2026-09-01
    И переход можно запланировать
    И при наступлении 2026-09-01 с непогашенным превышением действует грейс BR-15

  Сценарий: Повторное подтверждение не создаёт второе изменение
    Дано запланировано изменение тарифа на "Team" с 2026-09-01
    Когда администратор повторно подтверждает тот же переход
    Тогда запланированное изменение остаётся одно
    И ответ содержит идентификатор существующего изменения

  Сценарий: Отказ внешнего биллинга
    Дано провайдер биллинга недоступен
    Когда администратор подтверждает переход
    Тогда изменение сохраняется в статусе "Ожидает подтверждения"
    И администратор видит сообщение, что переход принят и подтвердится в течение часа
    И повторная отправка в биллинг выполняется автоматически

  Сценарий: Права
    Дано пользователь имеет роль "Участник"
    Когда он открывает страницу тарифа
    Тогда кнопка смены тарифа недоступна
    И попытка вызвать API возвращает 403 без утечки текущей цены

Проверка качества критериев одной фразой: можно ли написать по ним автотест, не задав ни одного вопроса? Нельзя — это пожелание, а не критерий. Дальнейшая судьба этих сценариев — в тестировании: при живом BDD текст становится исполняемым и падает, когда поведение разъезжается с документом.

4.2. Как добиться полноты: думать состояниями, а не экранами

Критерии, написанные «по экрану», всегда неполны: экран показывает счастливый путь. Полнота берётся из модели состояний объекта, который меняет история.

Схема мгновенно порождает вопросы, которых не было ни в одном интервью: можно ли планировать понижение, когда подписка просрочена? Что происходит с запланированным изменением при приостановке? Отменяется ли изменение при отмене подписки? Каждый вопрос — это либо строка критериев, либо строка в разделе открытых вопросов. Подробнее про диаграммы состояний как инструмент поиска дыр — в UML для аналитика.

Рабочий чек-лист покрытия критериев — шесть осей, по которым проверяют каждую историю:

Пять из шести осей — не про функциональность, а про ситуации. Именно там живут дефекты с пометкой «требование не учтено».

4.3. Антипаттерны критериев

• Пересказ описания. «Администратор может понизить тариф» — это заголовок, а не проверка.
• Критерий без наблюдаемого результата. «Система корректно обрабатывает переход» — опишите, что видно снаружи: статус, письмо, строка в счёте, запись в логе.
• «Или» в результате. «Тогда показывается сообщение или письмо» — неопределённость переехала в тест. Разделите на два сценария.
• Критерий-реализация. «Тогда в таблице subscription_changes появляется строка» — привязывает приёмку к внутреннему устройству; тест сломается при рефакторинге.
• UI-микроменеджмент. «Кнопка серая, 14 пикселей» — это дизайн-система, не требование.
• Критерии, написанные после разработки. Тогда они описывают то, что получилось, а не то, что было нужно. Пишите их до старта, вместе с QA и разработчиком — практика three amigos.

Формальную часть проверки удобно автоматизировать. Ниже линтер, который читает Gherkin и ловит структурные дефекты (проверка размытых формулировок в тексте требований разобрана в видах требований — здесь дополняющие правила):

"""Линтер критериев приёмки в формате Gherkin: структура сценария, а не смысл."""
import re
from dataclasses import dataclass, field

GIVEN = re.compile(r"^\s*(Дано|Given)\b", re.IGNORECASE)
WHEN = re.compile(r"^\s*(Когда|When)\b", re.IGNORECASE)
THEN = re.compile(r"^\s*(Тогда|Then)\b", re.IGNORECASE)
AND = re.compile(r"^\s*(И|And)\b", re.IGNORECASE)
SCENARIO = re.compile(r"^\s*(Сценарий|Scenario)\b", re.IGNORECASE)
VAGUE = re.compile(r"\b(корректно|правильно|как ожидается|успешно|нормально)\b", re.IGNORECASE)


@dataclass
class Scenario:
    line: int
    title: str
    steps: list[tuple[str, str]] = field(default_factory=list)  # (тип шага, текст)


def parse(text: str) -> list[Scenario]:
    """Разбор один проход по строкам: O(n) по времени, O(s) по памяти (s — число сценариев)."""
    scenarios: list[Scenario] = []
    current: Scenario | None = None
    last_kind = ""
    for i, raw in enumerate(text.splitlines(), start=1):
        line = raw.strip()
        if SCENARIO.match(line):
            current = Scenario(i, line)
            scenarios.append(current)
            last_kind = ""
        elif current is not None:
            for kind, pattern in (("given", GIVEN), ("when", WHEN), ("then", THEN)):
                if pattern.match(line):
                    current.steps.append((kind, line))
                    last_kind = kind
                    break
            else:
                if AND.match(line) and last_kind:
                    current.steps.append((last_kind, line))
    return scenarios


def lint(text: str) -> list[str]:
    problems: list[str] = []
    for sc in parse(text):
        kinds = [k for k, _ in sc.steps]
        if "given" not in kinds:
            problems.append(f"{sc.line}: нет предусловия — сценарий зависит от неизвестного состояния")
        if kinds.count("when") == 0:
            problems.append(f"{sc.line}: нет действия — это описание состояния, а не проверка")
        if kinds.count("when") > 1:
            problems.append(f"{sc.line}: два действия в одном сценарии — непонятно, что именно проверяем")
        if "then" not in kinds:
            problems.append(f"{sc.line}: нет ожидаемого результата — нечего проверять")
        for kind, step in sc.steps:
            if kind == "then" and " или " in step.lower():
                problems.append(f"{sc.line}: «или» в результате — недетерминированная проверка")
            if VAGUE.search(step):
                problems.append(f"{sc.line}: размытая формулировка в шаге: {step[:60]}")
    return problems

Сложность разбора — O(n) по времени и O(s) по памяти, где n — число строк, s — число сценариев; на файле в тысячу строк это миллисекунды. Линтер не понимает домена и не должен: его работа — вернуть текст автору до того, как на него потратят время трое рецензентов.

5. Use case: когда истории перестаёт хватать

История намеренно коротка. Когда сценарий длинный, ветвистый и регламентированный, нужна форма, где явно перечислены основной поток, альтернативы, исключения и гарантии. Канон — Алистер Кокбёрн, «Writing Effective Use Cases».

UC-14. Плановая смена тарифа рабочего пространства

Уровень:             пользовательская задача (sea level)
Основной актор:      Администратор рабочего пространства
Заинтересованные:    Финансовый контролёр (предсказуемый счёт),
                     Поддержка (меньше обращений),
                     Провайдер биллинга (корректные подписки)
Предусловия:         администратор аутентифицирован; подписка в статусе «Активная»;
                     текущий период оплачен
Гарантия минимума:   изменение либо запланировано целиком, либо не создано;
                     деньги не списываются и не возвращаются в момент планирования
Гарантия успеха:     изменение зафиксировано с датой вступления, биллинг синхронизирован,
                     администратор уведомлён, счёт следующего периода пересчитан

Основной поток:
  1. Администратор открывает раздел «Тариф и оплата».
  2. Система показывает текущий тариф, дату конца оплаченного периода и доступные тарифы.
  3. Администратор выбирает целевой тариф.
  4. Система проверяет BR-07 (нет понижения внутри периода), BR-12 (лимит мест)
     и показывает дату вступления и список теряемых функций.
  5. Администратор подтверждает.
  6. Система создаёт запланированное изменение и передаёт его в биллинг.
  7. Система отправляет письмо с датой вступления и составом изменений.

Альтернативные потоки:
  3a. Выбран старший тариф        → повышение вступает немедленно, UC-15 (пропорциональный
      расчёт), текущий поток завершается.
  4a. Мест больше лимита BR-12    → система показывает, сколько мест освободить и до какой
      даты; планирование остаётся доступным, применяется грейс BR-15.
  6a. Биллинг не ответил за 5 с   → изменение сохраняется как «Ожидает подтверждения»,
      повтор по экспоненциальной задержке до 1 часа, затем эскалация в поддержку.

Исключения:
  E1. Подписка просрочена         → планирование запрещено, показывается требование оплаты.
  E2. Изменение уже запланировано → показывается существующее, предлагается заменить.
  E3. Биллинг отклонил операцию   → изменение снимается, уведомление администратору
      и в канал поддержки, запись в аудит-лог.

Частота:                ~400 в месяц, пик в последние 3 дня месяца (х5)
Нефункциональные:       NFR-9 (страница тарифов p95 ≤ 800 мс),
                        NFR-12 (письмо в течение 2 мин)
Открытые вопросы:       Q-4 — судьба мест сверх лимита; владелец: продуктовый директор

5.1. Тот же сценарий как последовательность взаимодействий

Текстовый use case плохо показывает, кто с кем разговаривает и где проходят границы ответственности. Для этого есть sequence-диаграмма — и это второй, а не альтернативный взгляд на тот же сценарий:

Диаграмма ловит то, что текст прячет: где генерируется ключ идемпотентности, кто хранит статус при отказе биллинга, что видит пользователь, пока подтверждения нет. Разбор нотации — в UML для аналитика, а детали контрактов и кодов ошибок — в анализе интеграций.

5.2. Story или use case: таблица выбора

Гибрид работает лучше обоих: use case как долгоживущее описание сценария в базе знаний + истории как порции работы, ссылающиеся на его шаги. Тогда история остаётся короткой, а полнота сценария не теряется.

6. Спецификация: когда нужен документ целиком

6.1. Структура рабочей спецификации

Классические стандарты — ISO/IEC/IEEE 29148 (наследник IEEE 830) и шаблон Volere — дают исчерпывающую структуру. Целиком её применяют редко; практичнее держать в голове скелет и включать разделы по надобности.

Раздел «Служебное» кажется бюрократией ровно до первого случая, когда по спецификации двухлетней давности принимают решение и потом выясняют, что она была черновиком. Минимальный паспорт документа помещается в семь строк:

# Шапка спецификации: хранится вместе с текстом, а не в отдельной табличке
id: SRS-BILLING-04
title: Смена тарифа рабочего пространства
status: approved          # draft | review | approved | deprecated
version: 3.2
owner: a.petrova          # кто отвечает за актуальность, а не кто написал
approvers: [finance-lead, security, platform-arch]
last_review: 2026-07-02   # дата последней сверки с реальностью, а не правки текста
supersedes: SRS-BILLING-02
related: [BR-07, BR-12, BR-15, UC-14, US-311, OpenAPI: subscriptions.yaml]

6.2. Бизнес-правила и таблицы решений

Правила — самая долгоживущая часть требований и самая часто дублируемая. Формат записи в реестре: идентификатор, формулировка, владелец, источник (закон, договор, решение), дата вступления, где реализовано.

Когда правило зависит от нескольких условий, проза перестаёт работать: три условия дают восемь комбинаций, и в тексте гарантированно потеряются две. Тогда нужна таблица решений (нотация DMN формализует то же самое):

Таблица заодно служит планом тестирования: пять строк — пять сценариев, и видно, что комбинация «повышение + места сверх лимита» невозможна по построению (у старшего тарифа лимит больше) — это тоже требование, и его стоит записать явно.

6.3. Что в спецификацию не кладут

• UI до пикселя — живёт в макетах и дизайн-системе, см. прототипирование и UX-трек.
• Схему таблиц в терминах СУБД — в спецификации концептуальная модель и словарь данных, физическая схема живёт с кодом миграций; см. моделирование данных.
• Полный JSON-контракт — источник истины OpenAPI-файл в репозитории, в спецификации — ссылка и сценарии обмена (анализ интеграций).
• Решения по архитектуре — им место в ADR рядом с кодом (шаблоны ADR).
• Всё, что уже есть в тестах — дублировать поведение в прозе значит гарантированно разойтись с ним.

7. Трассировка и жизненный цикл артефакта

7.1. Как связаны артефакты

Трассировка — не отчётность, а два практических действия: оценить последствия изменения («если правило BR-07 меняется, что переписываем?») и осмысленно урезать скоуп («что теряем, если выкинем US-311?»). Модель связей:

В реальном инструменте это выглядит скромнее: идентификатор правила в тексте критерия, ссылка на use case в истории, номер истории в названии теста и в сообщении коммита. Матрица трассировки в отдельной таблице оправдана только там, где её требует регулятор: поддерживать её руками дорого, а ссылки поддерживаются сами, потому что ими пользуются.

7.2. Жизненный цикл документа

Состояние «Требует обновления» — самое важное и почти всегда отсутствующее. Без него документ переходит из «утверждён» сразу в «врёт», и никто этого не замечает. Дешёвая практика: поле last_review в шапке и правило «раз в квартал владелец подтверждает актуальность или переводит в Deprecated». Второе дешёвое правило: пометка «устарело» с указанием нового источника истины лучше молчаливого устаревания — она экономит часы тому, кто найдёт документ через поиск.

8. Что ломается чаще всего

Четыре типовых провала документирования и то, чем именно они лечатся на уровне артефакта. Природа этих ошибок разобрана в видах требований; здесь — что конкретно писать, чтобы они не проходили дальше.

8.1. Неявные требования

Самая дорогая категория: никто не соврал, просто «это же очевидно». Очевидно оно только тому, кто десять лет в домене. Лечится не внимательностью, а фиксированным списком вопросов к каждой истории — тем самым, что в разделе 4.2, плюс доменные:

Практика, которая ловит больше всего: читать историю вслух с позиции того, кто хочет её сломать. «Я админ, я нажал кнопку дважды с разницей в 200 мс, потом сменил тариф обратно, потом мой платёж не прошёл» — три предложения, и в критериях появляются три недостающие строки.

8.2. Противоречия между стейкхолдерами

Финансы говорят «понижение только со следующего периода», продажи — «клиенту при уходе нужно дать понизиться немедленно». Обе позиции попадают в документ в разных разделах, и противоречие всплывает на приёмке.

Что делает документ, а не переговоры (сами переговоры — в работе со стейкхолдерами):

1. Противоречие фиксируется как объект, а не сглаживается формулировкой. Плохо: «понижение применяется в соответствии с политикой компании». Хорошо: строка в журнале открытых вопросов с обеими позициями и именами.
2. Решение записывается по шаблону, включая проигравшую альтернативу. Через полгода вернутся именно к ней:

D-19. Момент вступления понижения тарифа
Вопрос:      применять понижение немедленно с возвратом части оплаты или со следующего периода?
Варианты:    (A) немедленно с пропорциональным возвратом — позиция продаж;
             (B) со следующего периода без возврата — позиция финансов, оферта п. 5.4.
Решение:     B. Возврат средств потребует изменения оферты и учётной политики;
             стоимость оценена в 6 недель юридической работы.
Кто решил:   финансовый директор, 2026-07-14. Присутствовали: продажи, продукт, бухгалтерия.
Пересмотр:   вернуться при выходе на рынок ЕС (планово Q2 2027).
Последствия: BR-07 остаётся в силе; US-311 планирует изменение, не выполняет его немедленно.

3. У каждого правила один владелец. Если владельца нет, противоречие структурное: два человека считают себя источником истины. Это чинится не документом, а решением руководителя — но документ делает проблему видимой.

8.3. «Хотелки» без задачи

Признак — требование сформулировано как решение, а на вопрос «что сломается, если не сделать» ответа нет. На уровне артефакта работает обязательное поле «Ценность»: история без заполненной ценности не проходит Definition of Ready и не берётся в спринт. Это не бюрократия, а фильтр: заполнить поле честно можно только через задачу пользователя или бизнес-метрику.

Пример из жизни: «нужен экспорт истории тарифов в PDF». Три вопроса — «какую задачу решает», «как решаете сейчас», «что будет, если не сделаем в этом квартале» — дают ответ: финконтролёр раз в квартал сверяет расходы и делает это скриншотами. Настоящее требование — не PDF, а строка расхождений в существующем отчёте, и стоит она в десять раз дешевле. В документе это выглядит как переписанная история плюс запись в журнале решений о том, почему PDF не делаем — иначе запрос вернётся через месяц.

8.4. Требования, которые невозможно проверить

Тест грубый и безотказный: опишите ситуацию, в которой требование нарушено. Не можете — требования нет. «Смена тарифа должна работать надёжно» не опровергается ничем. «При недоступности биллинга изменение сохраняется в статусе Pending, повтор выполняется не позже чем через 60 минут, пользователю показано сообщение о принятии» — опровергается прогоном.

На уровне артефакта помогает жёсткое правило: у истории нет статуса Ready, пока каждый критерий не отвечает на три вопроса — при каком состоянии, после какого действия, что именно наблюдаем. Всё, что не отвечает, переезжает либо в НФТ с числом (нефункциональные), либо в открытые вопросы.

8.5. Бонусные грабли

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

9. Документ или схема на доске

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

1. Кто прочитает это, кроме тех, кто сейчас в комнате? Никто — доски достаточно.
2. Понадобится ли это через полгода? Нет — доски достаточно.
3. Что стоит ошибка? Час работы — доски достаточно. Деньги, данные, регуляторика, внешний контрагент — нужен документ, и его цена уже оправдана.

Три «нет» — фотографируйте доску, кладите фото в задачу с датой и подписью решения. Это абсолютно легитимный артефакт. Хотя бы одно «да» — пишите текст.

Минимум, который фиксируют письменно всегда, даже в самой быстрой команде: решение с автором и датой, критерии приёмки, изменившееся бизнес-правило и числовое НФТ. Всё остальное обсуждается по обстоятельствам.

И обратное правило, которое чаще нарушают: не пишите документ, у которого нет читателя. Если вы не можете назвать по имени человека, который его откроет, и повод, по которому он его откроет, — вы пишете в архив. Лучше потратить это время на разговор, схему и три строки критериев.

10. Как это выглядит в неделю аналитика

Последняя строка — та, которую пропускают чаще всего, и именно она отличает базу знаний от кладбища тикетов. История после релиза умирает; правило, сценарий и словарь терминов должны пережить её. Процессная сторона этого цикла — в аналитике в Agile, проверка результата — в приёмке, а инструменты, в которых всё это хранят, — в инструментах и карьере.

Чек-лист ревью артефакта (десять пунктов, проходится за пять минут):

1. Есть роль/актор и понятно, кто заметит результат.
2. Ценность сформулирована через задачу или метрику, а не через «удобнее».
3. Явно записано, что вне скоупа.
4. Все правила даны ссылками на идентификаторы, а не скопированным текстом.
5. Критерии покрывают норму, границы, ошибки, права, данные и повтор.
6. Каждый критерий отвечает: при каком состоянии, после какого действия, что наблюдаем.
7. Ни в одном критерии нет «или», «корректно», «удобно».
8. Открытые вопросы перечислены, у каждого владелец и срок.
9. Указаны владелец документа, версия и дата последней сверки.
10. По тексту можно написать тест, не задав ни одного вопроса.

Мини-итог

• Документ — кэш решения: у него есть владелец, срок жизни и стратегия инвалидации. Неподдерживаемый документ хуже отсутствующего.
• Форма выбирается по цене ошибки и сроку жизни знания, а не по регламенту: разговор → история → use case → спецификация.
• User story — обещание разговора: карточка, разговор, подтверждение. Критичные строки, которые пропускают: ценность как гипотеза, «вне скоупа», ссылки на правила, открытые вопросы с владельцем.
• Критерии приёмки — единственное место, где текст становится проверяемым. Полнота берётся из модели состояний и шести осей: норма, границы, ошибки, права, данные, повтор.
• Use case нужен там, где ветки и исключения составляют суть сценария; гибрид «use case в базе знаний + истории на его шаги» работает лучше любой из форм по отдельности.
• Бизнес-правила живут в реестре с идентификаторами; сложные условия — таблицей решений, которая заодно является планом тестирования.
• У каждого факта один дом, остальные ссылаются. Скопированный текст правила гарантированно разъедется.
• Неявные требования ловятся списком вопросов, противоречия — журналом решений с проигравшей альтернативой, «хотелки» — обязательным полем ценности, непроверяемое — правилом «опишите ситуацию, в которой это нарушено».

Источники

• Mike Cohn. User Stories Applied — базовая книга по историям и их декомпозиции: https://www.mountaingoatsoftware.com/books/user-stories-applied
• Ron Jeffries. Card, Conversation, Confirmation — первоисточник модели 3C: https://ronjeffries.com/xprog/articles/expcardconversationconfirmation/
• Alistair Cockburn. Writing Effective Use Cases — уровни целей, гарантии, структура потоков: https://alistair.cockburn.us/writing-effective-use-cases/
• Karl Wiegers, Joy Beatty. Software Requirements, 3rd ed. — глава про спецификацию и её качество: https://www.karlwiegers.com/books.html
• ISO/IEC/IEEE 29148:2018 — стандарт по требованиям и структуре SRS: https://www.iso.org/standard/72089.html
• Volere Requirements Specification Template — подробный шаблон с чек-листами: https://www.volere.org/templates/volere-requirements-specification-template/
• Gojko Adzic. Specification by Example и Fifty Quick Ideas to Improve Your User Stories: https://gojko.net/books/specification-by-example/, https://gojko.net/books/fifty-quick-ideas-to-improve-your-user-stories/
• Jeff Patton. User Story Mapping — истории как карта, а не список: https://www.jpattonassociates.com/user-story-mapping/
• Alan Klement. Replacing the User Story with the Job Story: https://jtbd.info/replacing-the-user-story-with-the-job-story-af7cdee10c27
• Gherkin Reference, Cucumber — синтаксис Given/When/Then: https://cucumber.io/docs/gherkin/reference/
• Martin Fowler. GivenWhenThen — когда формат помогает и когда мешает: https://martinfowler.com/bliki/GivenWhenThen.html
• Architecture Decision Records — шаблоны записи решений: https://adr.github.io/
• DMN Specification, OMG — формализация таблиц решений: https://www.omg.org/spec/DMN/
• BABOK Guide v3, IIBA — техники документирования в общей системе анализа: https://www.iiba.org/career-resources/a-business-analysis-professionals-foundation-for-success/babok/

Что дальше

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

UML для аналитика: какие диаграммы полезны и как их читают разработчики