Acceptance Criteria

---
name: acceptance-criteria
description: "Критерии приёмки (AC) к задаче Jira на русском: таблица с основным сценарием и пограничными случаями, регресс, доказательства для backend, Given/When/Then. Собирает контекст из задачи, Confluence и diff PR, публикует в Jira после подтверждения. Используй всегда, когда просят «составь AC», «напиши критерии приёмки», «что проверять по задаче», «definition of done», даже без номера задачи. English: acceptance criteria, AC for Jira ticket, definition of done."
license: MIT
compatibility: "python3 (только стандартная библиотека); для скриптов — Jira Server/Data Center с персональным токеном (PAT), опционально Confluence и Bitbucket Server. Без доступа к Jira скилл работает по тексту задачи, вставленному в чат."
metadata:
  author: KonstantinVCH
  version: "1.0.0"
  language: ru
---

# Критерии приёмки (Acceptance Criteria)

AC отвечают на вопрос «какие проверки нужны, чтобы понять, что задача готова к проду».
Это контракт: разработчик знает, что реализовать, QA — что проверить, ревьюер — как принять.
Каждая строка AC должна давать однозначный ответ «выполнено / не выполнено» и указывать, чем
это доказывается.

Режим работы: кратко. В Jira ничего не публиковать без явного «да» человека.

## Настройка под проект

Всё, что зависит от компании (URL Jira, Confluence, Bitbucket, ключ проекта, id кастомного поля
«Как проверить», архитектура сервисов, своя матрица рисков, ссылка на конвенцию тестовой
документации), собрано в `references/project-config.md`. Заполни его один раз. Если файл не
заполнен — спроси у пользователя минимум: URL Jira и номер задачи.

---

## Шаг 0 — Память команды (если она есть)

Если у проекта есть база знаний (Obsidian, Confluence-раздел QA, wiki, заметки прошлых сессий),
сначала поищи в ней по сервису из задачи, по номеру задачи и по ключевой фиче (русское название,
английское, аббревиатура). Это дешевле, чем заново открывать уже известные грабли.

Что ищем:
- известные **расхождения документации и кода** (DOC_GAP) → по каждому обязателен EC;
- **уроки** прошлых задач → сразу закладываем в AC;
- известные **особенности** сервисов, партнёров, событий очередей → уточняем правила в AC;
- **существующие тест-кейсы** (Allure TestOps, TestRail и т.п.) → не дублировать в AC то, что уже
  автоматизировано.

Базы знаний нет или она недоступна — скажи об этом одной строкой и продолжай.

---

## Шаг 1 — Собрать контекст задачи (скрипт)

Сбор контекста — детерминированная рутина: четыре-пять REST-запросов, разбор ссылок, усечение
диффа. Скрипт `scripts/fetch_context.py` делает её одинаково каждый раз; внимание нужно на
составление AC, а не на дёрганье REST.

Скрипт достаёт описание, комментарии, поле «Как проверить» (если задано), метки, тип задачи,
**страницы Confluence из описания и комментариев** (и `pageId=`, и `/display/SPACE/Title`), а также
**git diff всех PR задачи** (Jira dev-status → Bitbucket Server, с фильтром шума: тесты, lock-файлы,
картинки).

```bash
export JIRA_URL=https://jira.example.com        # обязателен
export JIRA_TOKEN=...                           # обязателен: PAT Jira (Профиль → Personal Access Tokens)
export CONFLUENCE_URL=https://wiki.example.com  # опционален
export CONFLUENCE_TOKEN=...                     # опционален: без него страницы пропускаются
export BITBUCKET_URL=https://git.example.com    # опционален
export BITBUCKET_TOKEN=...                      # опционален: без него diff пропускается
export JIRA_HOWTO_FIELD=customfield_10006       # опционален: id поля «Как проверить»

python3 scripts/fetch_context.py PROJ-123            # человекочитаемый контекст
python3 scripts/fetch_context.py PROJ-123 --json     # JSON для программной обработки
python3 scripts/fetch_context.py PROJ-123 --no-diff  # без diff (быстрее)
```

Токены не хардкодить и не вставлять в чат — только переменные окружения.

Если подключён MCP-сервер Atlassian (например, `mcp-atlassian`), описание и комментарии можно
читать через него; diff PR и разбор ссылок на Confluence скрипт всё равно делает надёжнее.
Доступа к API нет совсем — попроси пользователя вставить текст задачи и ссылки в чат.

Что даёт вывод:
- **описание, комментарии, «Как проверить»** — требования, бизнес-логика, пограничные случаи от
  аналитика;
- **метки** — для матрицы рисков (`references/risk-signals.md`);
- **Confluence** — контракты, sequence-диаграммы, статусные модели, схемы БД, события очередей;
- **git diff и список PR/страниц со ссылками** — что меняется на самом деле (сервис, метод,
  событие, feature-флаг). Секция «Ссылки для блока Новое» — готовые рабочие URL, других не
  выдумывать;
- **тип задачи**: баг-фикс → сразу к Шагу 3; новая фича или доработка → Шаги 2.1–2.3.

---

## Шаг 2.1 — Прочитать контекст (фичи и доработки)

Для backend-задач источник требований — спеки и диаграммы, а не макеты. Читай собранное так:

1. **Confluence**: sequence-диаграммы, статусная модель, схема БД, контракт API, описание событий.
   Проверь: описаны ли ошибочные ответы? Обязательные поля? Граничные условия? Расхождение спеки
   с diff → кандидат в EC.
2. **Git diff**: что именно меняется — сервис, метод, событие очереди, feature-флаг. От этого
   зависят артефакты (Шаг 3) и блок «Новое».
3. **Слои сервиса**: если в архитектуре есть фасад (BFF, gateway, `*-api`) над ядром
   (`*-service`), читай оба. Обогащение данных часто живёт в фасаде, а не в ядре: проверка только
   ядра пропускает потерю поля при сохранении.

---

## Шаг 2.2 — Вопросы аналитику

Формулируй вопросы, только если есть реальная неопределённость:

- непонятно ожидаемое поведение в конкретном сценарии;
- спека противоречит коду или Confluence;
- не описан путь ошибки (ошибка API партнёра, таймаут, повтор);
- непонятно, на каком тестовом пользователе/партнёре воспроизводить;
- не описано событие очереди: какие поля обязательны, кто вычисляет статус.

Аналитику пиши бизнес-языком, без кода и трейсов; один вопрос — одна-две строки, варианты
ответа списком. **Покажи вопросы → дождись ответов → только потом Шаг 3.**

---

## Шаг 2.3 — Сигналы рисков

Прочитай `references/risk-signals.md` — стартовая матрица рисков backend-систем (очереди,
feature-флаги, статусные машины, кэши, идентификаторы, интеграции). Добавь к ней проектную
матрицу из `references/project-config.md`, если она заполнена.

По уровню риска калибруй AC:
- **Критический / Высокий** → строка AC обязательна, кандидат на ⭐;
- **Средний** → EC, если задача затрагивает эту область;
- **Низкий** → можно опустить, ⭐ не ставить.

---

## Шаг 3 — Артефакты под тип изменений

Прочитай `references/artifacts.md` — какое доказательство подходит к какому изменению.

| Тип изменений | Артефакты |
|---|---|
| Новый флоу через очередь / событие | payload отправки в очередь + traceId (успех) + traceId (ошибка) |
| Изменение API-контракта | HTTP-ответ success + error + SQL до/после |
| Изменение состояния сущности в БД | SQL до/после + traceId |
| Feature-флаг | скриншот консоли флагов + SQL/API-проверка состояния флага |
| Новый сервис / модуль | зелёный CI-пайплайн + smoke-ответ API |
| Инфраструктура (k8s-манифесты, Ansible, Helm) | зелёный CI-пайплайн + health-check |

---

## Шаг 4 — Составить таблицу AC

Цель: зафиксировать проверки, подтверждающие готовность задачи к проду, — разработчик собирает
по ним доказательства, ревьюер однозначно отвечает «готово / не готово».

### Формат (Jira wiki markup)

```
h2. ✅ Критерии приёмки: {короткое название функционала из задачи}

|| № || Тип || AC || Артефакты ||
| 1 ⭐ | HP | ... | traceId |
| 2 ⭐ | HP | ... | SQL до/после |
| 3 | HP | ... | HTTP-ответ |
| 4 | EC | ... | traceId (ошибка в трейсе) |
| 5 | EC | ... | — |

h3. 🆕 Новое в доработке (спецификация)
* [Точный пункт спеки/контракта, добавленный этой доработкой|РАБОЧИЙ_URL] — что именно добавилось

h3. 🔁 Регресс (проверить рядом с изменением)
* [Смежное существующее поведение, которое могло затронуть изменение] — что перепроверить
```

Если Jira не используется — та же структура в Markdown (`| № | Тип | AC | Артефакты |`).
Подробности, примеры «плохо/хорошо» и правила минимизации — в `references/table-format.md`.

- **Заголовок** — с названием функционала, а не безликое «Acceptance Criteria».
- **🆕 Новое** — конкретные пункты спеки/контракта, которые ДОБАВИЛА задача (метод, поле, статус,
  событие, флаг), каждый со ссылкой. Ссылки бери только из секции «Ссылки для блока Новое» вывода
  `fetch_context.py` или из текста задачи. URL не выдумывать.
- **🔁 Регресс** — существующее поведение рядом с изменением (обратная совместимость, смежные
  ветки флоу, общие методы). Для баг-фикса — только реально затронутое.
- **Стенд не указывать.** На каком стенде прогонять, решается при раскатке задачи, а не из
  постановки. Выдуманный дефолт («стенд 1») вводит в заблуждение, если релиз оказался на другом.
  Если для воспроизведения важен конкретный партнёр или тип пользователя — это предусловие
  соответствующей строки AC.

### Given / When / Then

Когда аналитик или команда принимают AC в стиле BDD, строку можно писать так:
«**Дано** заказ в статусе `PAID`; **когда** приходит событие `OrderCancelledEvent`; **тогда**
`orders.status = CANCELLED`, в трейсе есть consume-спан без ошибок». Таблица и колонка
«Артефакты» сохраняются — меняется только формулировка ячейки AC.

### Типы сценариев

- **HP** (happy path) — всё ЯВНО описанное в задаче, спеке, комментариях. Разработчик ОБЯЗАН это
  реализовать.
- **EC** (edge case) — не описано, но может сломаться: ошибка API партнёра, таймаут, повтор,
  граничный payload, неверный тип поля, флаг выключен, пустой кэш.

**Порядок:** HP со ⭐ → HP без ⭐ → EC со ⭐ → EC без ⭐. Нумерация сквозная, номера присваивать
после сортировки.

**⭐ (прод-смок):** 1–3 звёздочки на задачу — основной happy path и критичный регресс рядом с
изменением. Что такое прод-смок и чего не отмечать — в `references/artifacts.md`.

### Чеклист перед первым показом

1. **Тестируемость.** Каждый AC — проверяемое утверждение с конкретикой: код ошибки, поле,
   значение, порог. «Быстро», «корректно», «нормально работает» без измеримого критерия — не AC.
2. **Одно поведение — одна строка.** «Валидирует И сохраняет И шлёт событие» — это три строки.
   Объединять можно только строки с одним и тем же доказательством (один трейс или один SQL).
3. **Количество — по размеру изменения.** Мелкая правка — 2–4 строки, крупная доработка — сколько
   реально нужно. Не добивать количество ради планки и не дробить одно поведение.
4. **Сигналы из памяти команды.** Все DOC_GAP и уроки из Шага 0 отражены в EC.
5. **Порядок ⭐.** HP со ⭐ первыми, потом HP без, потом EC.
6. **Матрица партнёров/вариантов.** Если изменение в общей логике, которую используют несколько
   партнёров, клиентов или типов продукта, — EC на вариант, отличный от дефолтного.
7. **Очереди.** Если в AC есть отправка сообщения в очередь — указаны exchange, routing key и
   payload с правильными типами полей (int и string различаются: несовпадение типа роняет
   консьюмер).
8. **NOT NULL в БД.** Если в AC есть «запись в БД» — сверь DDL миграции (`not null`, уникальность)
   до того, как писать EC про пустое значение.
9. **Feature-флаг.** Если задача за флагом — есть проверка поведения при выключенном флаге.
10. **Баг-фикс.** Не добавлять EC про смежные флоу, которые изменение не затрагивает.

---

## Шаг 5 — Согласовать и опубликовать

### Согласование

Покажи таблицу в чате. Получи явное «да» или правки. **Без одобрения не публиковать** —
публикация меняет общую задачу, которую читает вся команда.

### Публикация через Jira REST (скрипт)

Некоторые MCP-обёртки Jira при обновлении описания портят wiki markup: `1.` превращается в `#`,
`{*}` — в `{_}`, теряются параметры картинок. Скрипт `scripts/publish_ac.py` пишет через прямой
REST, разметка сохраняется, а существующий блок AC в описании заменяется без дублей.

```bash
# 1. Сохрани согласованную таблицу в файл (например ac.txt), начиная с заголовка h2./h3.
# 2. Опубликуй:
python3 scripts/publish_ac.py PROJ-123 --file ac.txt             # в ОПИСАНИЕ (заменить/добавить блок)
python3 scripts/publish_ac.py PROJ-123 --comment --file ac.txt   # КОММЕНТАРИЕМ (черновик на ревью)
python3 scripts/publish_ac.py PROJ-123 --file ac.txt --dry-run   # превью без отправки
```

Скрипт печатает превью и спрашивает подтверждение. Флаг `--yes` пропускает вопрос — используй его
только после явного согласия человека в чате.

---

## Справка

- `scripts/fetch_context.py` — сбор контекста (Шаг 1)
- `scripts/publish_ac.py` — публикация (Шаг 5)
- `references/table-format.md` — формат таблицы, минимизация, примеры
- `references/artifacts.md` — артефакты-доказательства для backend, правила ⭐
- `references/risk-signals.md` — стартовая матрица рисков
- `references/project-config.md` — настройки проекта (заполнить под себя)

Связанные скиллы: `qa-task-testing` (полный QA-протокол задачи, где AC — один из шагов),
`bug-report` (оформление найденного дефекта), `test-session-report` (итог прогона).