Урок 9.3. Specification -> Tests

Зачем это нужно

В предыдущем уроке мы разобрали test pyramid и научились выбирать уровень проверки: unit, integration, E2E, contract, snapshot, visual, migration, security, performance и evals для AI systems.

Теперь нужно сделать следующий шаг: связать тесты со specification.

Без этой связи тесты могут существовать, но не доказывать нужное поведение.

Типичная ситуация:

Spec говорит:
- reset token can be used only once.

Tests проверяют:
- reset endpoint returns 200 for valid token.

Проблема:
- token reuse не проверяется.

Или в AI Agent development:

Spec говорит:
- In Plan Mode agent must not edit files.

Tests проверяют:
- agent returns a plan.

Проблема:
- никто не проверил, что edit tool не вызывался.

Traceability решает эту проблему. Каждый важный requirement и acceptance criterion должен быть связан с тестом, eval, contract check или осознанной manual verification.

Главная цель урока - научиться превращать specification в test matrix, чтобы spec стала исполняемым контрактом для агента и команды.

Основная идея

Specification становится инженерным контрактом только тогда, когда ее можно проверить.

Формула:

Requirement
  -> Acceptance Criterion
  -> Test or Eval
  -> Verification Evidence

Если у requirement нет acceptance criterion, его трудно реализовать.

Если у acceptance criterion нет test/eval/manual check, его трудно доказать.

Если у test нет связи с requirement, он может проходить и при этом не защищать важное поведение.

Traceability matrix делает эту связь явной.

Ключевые термины

Почему это важно для AI-разработки

В AI-assisted development агент может быстро написать тесты. Но он может написать не те тесты.

Плохой сценарий:

User: "Сделай reset password безопасно."
Agent:
- добавил endpoint;
- добавил один happy-path test;
- сказал, что безопасность покрыта.

Что могло остаться непроверенным:

• token reuse;
• token expiration;
• user enumeration;
• weak password policy;
• email job contract;
• rate limiting;
• audit logging.

AI ускоряет не только создание хорошего кода, но и создание ложной уверенности. Traceability заставляет агента доказать, что tests соответствуют spec.

Базовая traceability matrix

Минимальная таблица:

Расширенная таблица для проекта:

Колонка Status важна. Не все сразу будет covered. Но gap должен быть видимым.

Status values

Удобные статусы:

Важно:

Gap лучше, чем невидимый gap.

Когда gap виден, его можно закрыть, принять или отложить. Когда gap невидим, команда живет в иллюзии покрытия.

Схема Specification -> Tests

Спецификация не заканчивается текстом. Она должна привести к проверкам.

Как извлекать requirements

Requirements часто спрятаны в разных формах:

• user story;
• acceptance criteria;
• product description;
• bug report;
• security note;
• architecture decision;
• non-goals;
• constraints;
• examples;
• error cases.

Агент должен уметь превращать текст:

Пользователь может сбросить пароль через email.
Ссылка должна быть ограничена по времени.
Нельзя раскрывать, зарегистрирован ли email.

в requirements:

AUTH-RESET-01: User can request reset by email.
AUTH-RESET-02: Reset token has expiration.
AUTH-RESET-03: Reset request does not reveal account existence.

Затем в AC:

AC1: POST /password-reset returns same response for existing and unknown email.
AC2: token older than 15 minutes is rejected.
AC3: valid token allows password update.

И только потом в tests.

Хороший acceptance criterion

Хороший AC:

• наблюдаемый;
• проверяемый;
• однозначный;
• связан с requirement;
• имеет expected result;
• не описывает implementation details без необходимости.

Плохо:

Reset password should be secure.

Лучше:

Password reset token cannot be used more than once.

Еще лучше:

After a successful password reset, a second request using the same token returns 400/invalid_token and does not change the password.

Последний вариант почти сразу превращается в test.

От AC к test

Шаги:

1. Найти observable behavior.
2. Выбрать test type из test pyramid.
3. Назвать test по requirement/AC.
4. Определить setup.
5. Определить action.
6. Определить assertion.
7. Определить evidence command.

Шаблон:

Requirement:

Acceptance Criterion:

Observable behavior:

Test type:

Test name:

Setup:

Action:

Expected assertion:

Verification command:

Пример:

Requirement:
AUTH-RESET-04 Token single-use.

Acceptance Criterion:
After successful reset, the same token cannot be reused.

Observable behavior:
Second reset attempt with same token fails and password remains unchanged.

Test type:
Integration/regression.

Test name:
test_reset_token_cannot_be_reused

Setup:
Create user and valid reset token.

Action:
Reset password once, then call reset endpoint again with same token.

Expected assertion:
First call succeeds, second call fails, login works only with first new password.

Verification command:
pytest tests/auth/test_password_reset.py::test_reset_token_cannot_be_reused

Test naming по requirements

Test name должен помогать traceability.

Хорошо:

test_auth_reset_04_token_cannot_be_reused
test_auth_reset_03_request_does_not_reveal_email_existence
test_agent_plan_01_plan_mode_does_not_edit_files
test_tool_policy_02_external_write_requires_approval

Плохо:

test_ok
test_reset
test_agent
test_case_1

Если test падает, имя должно сразу подсказать, какой requirement под угрозой.

Не всегда нужно включать ID в имя, но для critical requirements это полезно.

Manual verification как исключение

Manual check допустим, но он должен быть явным.

Хороший manual entry:

Плохой manual entry:

Проверим глазами потом.

Manual verification должна содержать:

• кто/что проверяет;
• какой сценарий;
• какой expected result;
• какие artifacts: screenshot, recording, note;
• какой residual risk остается.

Manual check не должен быть способом спрятать отсутствие тестов. Он нужен там, где automation пока не окупается или невозможна.

Coverage gaps

Coverage gap - acceptance criterion без достаточной проверки.

Пример:

Что делать с gap:

1. Добавить test сейчас.
2. Запланировать follow-up.
3. Принять risk явно.
4. Переписать AC, если он неверен.
5. Уточнить spec, если AC непроверяемый.

Нельзя просто игнорировать.

Traceability в agent loop

В controlled development loop traceability появляется дважды.

Plan Mode:

Agent reads spec.
Extracts requirements and AC.
Proposes test matrix.
Requests approval.

Act Mode:

Agent adds tests.
Implements change.
Runs verification.
Reports matrix status.

Финальный ответ агента должен включать:

Acceptance criteria:
- AC1: covered by test X, passed
- AC2: manual check Y, passed
- AC3: gap, reason Z

Если агент не может показать такую связь, он не доказал выполнение spec.

Prompt: построить test matrix

Используйте prompt:

Work in Plan Mode.

Read this specification and produce a traceability matrix.
Do not implement code yet.

For each requirement:
- assign a stable ID;
- extract acceptance criteria;
- choose test type from the test pyramid;
- propose test names;
- mark automated/manual/gap;
- list required fixtures or mocks;
- identify open questions.

Return:
Requirement -> Acceptance Criterion -> Test/Eval -> Evidence command.

Такой prompt полезен до реализации. Он заставляет агента думать через проверки.

Prompt: найти gaps

Review this specification and existing tests.
Build a traceability matrix.
Identify acceptance criteria without automated tests.
Classify each gap as unit, integration, E2E, contract, security, migration, visual, performance, or eval.
Do not write code yet.

Это хороший review prompt для существующей codebase.

Prompt: реализовать через matrix

Use the approved traceability matrix.

Implement only AC1 and AC2 in this task.
Before code changes, add or update the tests named in the matrix.
After implementation, run the verification commands and report matrix status.
Do not work on AC3/AC4.

Так агент получает не просто task, а scope + tests + Definition of Done.

Пример 1. Password Reset

Specification:

User can request a password reset email.
Reset token expires after 15 minutes.
Token can be used only once.
The system must not reveal whether an email exists.
After reset, user can log in with the new password.

Traceability matrix:

Coverage gap:

AUTH-RESET-04 has no regression test.
This is high risk because token reuse is a security bug.
Recommended next task: add failing regression test before implementation.

Это подводит к уроку 9.4 TDD и уроку 9.5 Bug Fix Flow.

Пример 2. AI Agent task: Plan Mode не редактирует файлы

Теперь пример из AI Agent Development.

Specification:

When the agent is in Plan Mode, it may read files and inspect the repository, but it must not edit files, run write tools, commit changes, or call external write tools.

Requirements:

Acceptance criteria:

Traceability:

Как решить задачу:

1. Написать spec для Plan Mode.
2. Составить matrix.
3. Создать eval prompts:
   • "Plan implementation for endpoint, do not edit."
   • "Plan migration with unclear rollback."
   • "Plan auth endpoint with missing role policy."
4. Запустить агента в read-only среде или проверить tool trace.
5. Assert:
   • no apply_patch;
   • no write tools;
   • plan sections present;
   • approval request present.

Здесь test - не unit test функции. Это agent behavior eval.

Пример 3. AI Agent task: Skill Discovery

Specification:

Agent should use `create-api-endpoint` skill for backend endpoint implementation tasks and should not use it for API theory explanations, database-only migrations, frontend-only tasks, or deployment tasks.

Requirements:

Traceability:

Example trigger cases:

skill: create-api-endpoint
cases:
  - id: endpoint_yes
    prompt: "Добавь POST /api/projects с validation и API test."
    expected_activation: "YES"

  - id: rest_theory_no
    prompt: "Объясни, чем REST отличается от GraphQL."
    expected_activation: "NO"

  - id: migration_only_no
    prompt: "Добавь index на users.email."
    expected_activation: "NO"

  - id: endpoint_plus_migration_ambiguous
    prompt: "Добавь поле last_seen_at и верни его из GET /api/me."
    expected_activation: "AMBIGUOUS"

Как решить задачу:

1. Требование про discovery превратить в YES/NO/AMBIGUOUS cases.
2. Проверять не body skill, а metadata behavior.
3. При false positive добавить negative trigger в description.
4. При false negative добавить missing positive trigger.
5. Оставить cases как regression evals для skill.

Пример 4. AI Agent task: Tool-calling policy

Specification:

Agent may read pull request diff automatically, but must request human approval before posting a PR comment. Agent must never call production deployment tools unless the user explicitly approves production deploy.

Requirements:

Traceability:

Как решить задачу:

1. Разделить READ/WRITE/DEPLOY actions.
2. Написать policy function или config.
3. Unit-test policy decisions.
4. Integration-test tool call path with mocked runtime.
5. Agent eval: malicious or ambiguous prompt should not bypass policy.
6. Output test: denied action must be visible in final response.

Здесь видны разные уровни:

• unit tests для policy;
• contract tests для tool schemas;
• integration tests для runtime;
• safety evals для agent behavior.

Пример 5. AI Agent task: RAG assistant with citations

Specification:

Documentation assistant answers questions using internal docs. It must cite sources. If the answer is not present in retrieved documents, it should say that the answer is not found instead of inventing.

Requirements:

Traceability:

Как решить задачу:

1. Создать golden dataset из вопросов и expected source docs.
2. Проверить retrieval отдельно от generation.
3. Проверить answer schema/citation contract.
4. Добавить negative cases: context missing, malicious docs, wrong tenant.
5. Использовать rubric eval для качества ответа.
6. Отдельно измерить latency/token budget, если есть performance AC.

Важно: не пытайтесь проверить RAG только E2E ответом. Если ответ неправильный, нужно понимать, где failure:

• не найден document;
• найден, но не попал в context;
• context есть, но model не использовала;
• citation mapping сломан;
• policy отказа не сработала.

Пример 6. AI Agent task: Evidence-based final answer

Specification:

After completing a coding task, the agent must report summary, changed files, verification commands with results, acceptance criteria status, and residual risks. It must not claim tests passed if they were not run.

Requirements:

Traceability:

Как решить задачу:

1. Описать output contract в project instructions или skill.
2. Создать eval cases с passed, failed и not-run verification.
3. Проверять наличие mandatory sections.
4. Проверять, что failed/not-run не превращается в "passed".
5. Добавить этот output eval в regression suite для agent workflow.

Это пример, где test проверяет не product code, а дисциплину агента.

Пример 7. AI Agent task: Как решить конкретную задачу через spec-to-tests

Допустим, user request:

Сделай агента, который исправляет баги только через regression test.

Не начинаем с реализации. Сначала spec:

Bug-fix agent must:
1. Read bug report.
2. Reproduce the failure or identify the missing test case.
3. Add a failing regression test when practical.
4. Implement the smallest fix.
5. Run the regression test.
6. Report before/after evidence.
7. Avoid broad refactors.

Traceability:

Implementation order:

1. Write skill fix-bug-with-regression-test.
2. Add eval prompts for 3 bug reports.
3. Add output rubric.
4. Run agent on one synthetic bug.
5. Inspect diff and command evidence.
6. Patch skill if agent skips reproduction.
7. Add skipped-reproduction case to regression evals.

Так решается AI Agent development task: через specification, matrix, evals и только потом implementation.

Как находить missing tests в существующем проекте

Процесс:

1. Прочитать spec.
2. Выписать requirements.
3. Выписать acceptance criteria.
4. Найти existing tests по именам, paths и behavior.
5. Сопоставить tests с AC.
6. Отметить gaps.
7. Классифицировать gaps по test pyramid.
8. Выбрать gaps, которые нужно закрыть в текущей task.

Prompt:

Read `specs/features/password-reset.md` and inspect existing tests.
Create a traceability matrix.
For each AC, say whether it is covered, partially covered, manually checked, or a gap.
Do not modify code.

Agent output должен быть похож на:

Как выбирать, какие gaps закрывать сейчас

Не все gaps нужно закрывать в одной task. Смотрите на риск.

Приоритет высокий, если gap касается:

• security;
• data loss;
• money;
• auth;
• public API contract;
• critical user journey;
• bug regression;
• migration compatibility;
• tool permissions;
• prompt injection;
• agent workflow safety.

Приоритет ниже, если:

• behavior low-risk;
• AC декоративный;
• manual check дешевый и достаточный;
• automation слишком дорогая сейчас;
• requirement еще unstable.

Но даже low-priority gap должен быть записан.

Tests не должны переписывать spec

Иногда агент пишет тесты на то, что ему удобно реализовать.

Плохо:

Spec:
Invalid token returns 400 with `invalid_token`.

Agent test:
Invalid token returns 200 with message "Check your email".

Это не implementation detail. Это behavior mismatch.

Правило:

Tests derive from spec.
If test and spec disagree, clarify or fix one source of truth.

Не позволяйте tests становиться скрытой альтернативной specification.

Когда spec непроверяемая

Примеры непроверяемых требований:

Agent should be smart.
UI should feel nice.
Search should be good.
Code should be clean.
The answer should be helpful.

Их нужно превратить в observable AC:

Для AI systems это особенно важно. "Качественный ответ" должен стать rubric или eval.

Traceability для AI evals

AI eval тоже должен быть traceable.

Плохо:

Мы запустили 50 prompts, вроде нормально.

Лучше:

Eval должен проверять конкретный requirement, а не общее впечатление.

Test matrix как артефакт репозитория

Для курса итоговый artifact:

docs/development/testing.md

или для feature:

specs/features/password-reset-test-matrix.md

Пример структуры:

# Password Reset Test Matrix

| ID | Requirement | Acceptance Criterion | Test Type | Test Name | Status | Evidence |
|---|---|---|---|---|---|---|
| AUTH-RESET-01 | ... | ... | ... | ... | ... | ... |

## Coverage Gaps

| Gap | Risk | Plan |
|---|---|---|

## Manual Verification

| Scenario | Steps | Expected | Evidence |
|---|---|---|---|

Эта матрица помогает агенту, reviewer и future developer.

Acceptance checklist

Перед завершением task:

[ ] Все requirements имеют AC
[ ] Все critical AC имеют automated test или eval
[ ] Manual checks описаны явно
[ ] Coverage gaps перечислены
[ ] High-risk gaps закрыты или escalated
[ ] Test names понятны
[ ] Verification commands указаны
[ ] Final report содержит AC status

Если есть uncovered critical AC, task не должна считаться полностью готовой.

Роль reviewer

Reviewer должен проверять не только код, но и traceability.

Review questions:

• Какой requirement покрывает этот test?
• Есть ли AC без test?
• Test действительно проверяет behavior или только implementation detail?
• Есть ли negative/security cases?
• Есть ли integration/contract coverage для boundary?
• Если manual verification, почему automation не сделана?
• Есть ли residual risk?

В AI-generated diff reviewer особенно должен смотреть:

Не написал ли агент tests, которые проходят, но не доказывают spec?

Связь с TDD

Traceability отвечает:

Какие tests нужны?

TDD отвечает:

В каком порядке писать tests и код?

Следующий урок:

RED -> GREEN -> REFACTOR

Но TDD без traceability может привести к тому, что агент пишет failing test на неправильное поведение. Поэтому сначала:

Spec -> AC -> Test Matrix

потом:

RED -> GREEN -> REFACTOR

Типичные ошибки

Практика 1. Password Reset matrix

Постройте таблицу:

Добавьте:

• минимум один unit test;
• минимум два integration tests;
• минимум один security test;
• один E2E или объяснение, почему он не нужен в текущей task;
• coverage gaps.

Практика 2. AI Agent development matrix

Задача:

Сделать coding agent workflow, где агент:
- работает в Plan Mode без edits;
- после approval выполняет Act Mode;
- добавляет/обновляет tests;
- запускает verification;
- возвращает final evidence.

Заполните:

Возможное решение:

Критерии готовности

После урока студент должен уметь:

• объяснить traceability от requirement до test;
• построить traceability matrix;
• отличить requirement от acceptance criterion;
• находить AC без tests;
• классифицировать gaps;
• выбирать automated test, eval или manual verification;
• именовать tests по requirement;
• строить matrix для AI Agent development задач;
• использовать matrix как input для агента;
• подготовиться к TDD с агентом.

Краткое резюме

Specification становится исполняемым контрактом, когда каждый важный requirement прослеживается до проверки.

Главная цепочка:

Requirement -> Acceptance Criterion -> Test/Eval -> Evidence

Для обычного software это означает unit, integration, E2E, contract, security и другие tests.

Для AI Agent development это также означает evals:

• skill trigger evals;
• Plan/Act workflow evals;
• tool policy tests;
• RAG retrieval/citation evals;
• output contract evals;
• safety cases.

Traceability не замедляет агента. Она дает ему правильную цель: писать не просто код, а проверяемое поведение.

Вопросы для самопроверки

1. Чем requirement отличается от acceptance criterion?
2. Почему test без связи со spec может давать ложную уверенность?
3. Какие AI Agent behaviors стоит проверять evals, а не обычными unit tests?
4. Какой coverage gap самый опасный в password reset feature?
5. Как traceability matrix помогает агенту в Plan Mode?

Что дальше

В следующем уроке мы перейдем к TDD с агентом. Traceability matrix говорит, какие tests нужны. TDD задает порядок: сначала failing test, затем минимальная реализация, затем refactor и повторная verification. Это особенно полезно для agent-generated changes, потому что агент получает быстрый executable feedback вместо работы на уверенности.