Спецификация поведения

В первой задаче ALGI нужно принимать оценку боли и заметку пациента. Формулировка кажется достаточной, пока не доходишь до деталей: разрешён ли балл 7.5, что делать с пустой заметкой, можно ли показывать её врачу без изменений? Если это не решить до запуска, ответы окажутся в сгенерированном коде и тестах. Причём код и тесты могут согласованно реализовать неверное решение.

Спецификация, или spec, фиксирует ожидаемое поведение. Для небольшой функции хватит нескольких примеров и ограничений в Markdown рядом с кодом.

Разберём спецификацию дневника

Откройте examples/algi-lite/specs/pain-diary.bdd.md. В ней три сценария: допустимая запись, недопустимый балл и сводка для врача. Первый можно записать так:

# language: ru
Функция: Запись в дневник боли
  Сценарий: Нормализация заметки
    Допустим пациент указал балл 7
    И написал заметку "  боль   после прогулки  "
    Когда запись проходит проверку
    Тогда балл остаётся равным 7
    И заметка сохраняется как "боль после прогулки"

Здесь есть входные данные и ожидаемый результат. По ним можно написать тест, не зная, будет ли реализация использовать класс, словарь или отдельный сервис. Gherkin удобен для такого описания, но сам по себе ничего не запускает. В нашем стенде сценарии читают люди, а проверки написаны отдельно на unittest.

Для ошибки тоже нужен наблюдаемый результат. В исходной спецификации балл 13 должен приводить к отказу с сообщением о диапазоне от 0 до 10. Этому соответствует существующий тест:

def test_invalid_score_is_rejected(self):
    with self.assertRaisesRegex(ValidationError, "between 0 and 10"):
        validate_pain_entry(13)

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

Где спецификация пока недоговорена

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

Сводка должна скрывать email, телефон и полное имя. При этом она включает фрагменты заметок, куда пациент может написать все три. До реализации нужно выбрать, какие данные разрешено переносить в отчёт и как это проверять. Наличие поля disclaimer этот вопрос не решает.

Вторая задача добавляет clinician_report, псевдоним и поле trend, но ссылается на ту же спецификацию дневника. Отдельного сценария для вычисления trend в ней нет. Сравнивать первую и последнюю запись или оценивать всю последовательность - пока решение реализации. В учебном коде используется первый вариант; он не описывает медицинскую динамику состояния.

Как довести документ до запуска

Сначала выпишите открытые вопросы рядом со сценарием, который они затрагивают. Затем согласуйте ответы с тем, кто отвечает за поведение продукта. Для исправления опечатки это может быть сам разработчик; для состава отчёта нужен владелец соответствующей функции.

После решения добавьте примеры. Вместо «не раскрывать личные данные» полезно иметь, например, заметку напишите на patient@example.com и точное ожидание для отчёта. Это проверка одного формата адреса, а не всех способов идентификации человека. Полные имена и произвольный текст потребуют отдельного решения.

Далее сопоставьте требования с тестами:

Требование	Проверка в текущем стенде	Чего ещё не хватает
Балл от 0 до 10	test_invalid_score_is_rejected отклоняет 13.	Границ 0 и 10, отрицательного числа и типов входа.
Нормализация пробелов	test_valid_entry_is_normalized проверяет заметку и активность.	Согласованного поведения при превышении длины.
Отсутствие контактов в отчёте	Во втором этапе есть test_report_redacts_direct_identifiers.	Полных имён и других форматов контактов.
Расчёт trend	test_report_contains_aggregate_values_and_trend проверяет рост.	Пустого списка, одной записи и правила порядка записей в спецификации.

Попробуйте на одном требовании

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

Если ответы совпали, требование можно переносить в задачу для агента. Если нет, уточните пример до запуска. Шаблон спецификации и чеклист ревью помогут проверить остальные требования.