Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,7 @@ service setup-команды проекта; он намеренно не пер

### Методические источники

- Dan North, [*Introducing BDD*](https://dannorth.net/blog/introducing-bdd/) — первичный источник Behaviour-Driven Development: уточнение требований через business value, concrete examples и executable acceptance scenarios в форме `Given / When / Then`;
- Philippe Kruchten, [*Architectural Blueprints — The “4+1” View Model of Software Architecture*](https://arxiv.org/abs/2006.04975) — первичный источник stakeholder-oriented проверки Logical, Process, Development и Physical views через driving scenarios; [краткий обзор](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model);
- Nenad Medvidovic, Richard N. Taylor, [*A Classification and Comparison Framework for Software Architecture Description Languages*](https://ics.uci.edu/~taylor/documents/2000-ADLs-TSE.pdf) — источник архитектурной модели components, connectors и configurations.

Expand Down
2 changes: 1 addition & 1 deletion template/memory-bank/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ audience: humans_and_agents
Читать, когда нужно: проверить SSoT rules, frontmatter contract и governance-правила документации.

- [`flows/README.md`](flows/README.md)
Читать, когда нужно: создать use case, epic/feature package, провести артефакт по lifecycle gates или использовать шаблон.
Читать, когда нужно: создать use case, epic/feature package, применить BDD-практику, провести артефакт по lifecycle gates или использовать шаблон.

- [`adr/README.md`](adr/README.md)
Читать, когда нужно: найти или завести Architecture Decision Record.
Expand Down
23 changes: 23 additions & 0 deletions template/memory-bank/engineering/testing-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ doc_function: canonical
purpose: "Описывает testing policy репозитория: обязательность test case design, требования к automated regression coverage и допустимые manual-only gaps."
derived_from:
- ../dna/governance.md
- ../flows/behavior-specification.md
- ../flows/feature.md
- validation-profiles.md
status: active
Expand All @@ -16,6 +17,7 @@ canonical_for:
- manual_only_verification_exceptions
- simplify_review_discipline
- verification_context_separation
- bdd_automation_policy
must_not_define:
- feature_acceptance_criteria
- feature_scope
Expand Down Expand Up @@ -50,6 +52,25 @@ audience: humans_and_agents
- Required automated tests считаются закрывающими риск только если они проходят локально и в CI.
- Manual-only verify допустим только как явное исключение и не заменяет automated coverage там, где automation реалистична.

## BDD Automation Policy

[`Behavior Specification Practice`](../flows/behavior-specification.md)
определяет Discovery и Formulation; этот policy определяет automation boundary.

- BDD не требует Gherkin, Cucumber, browser automation или E2E-only tests.
- Для каждого required `SC-*` / `NEG-*` выбирай самый низкий надёжный unit,
component, contract, integration или E2E surface, который доказывает
observable outcome.
- Один behavior example может проверяться несколькими техническими тестами;
каждый test surface должен быть виден в `implementation-plan.md#test-strategy`.
- Имя, tag или metadata теста должны сохранять ссылку на `SC-*` / `NEG-*`, если
project framework это допускает без brittle coupling.
- Test code не владеет requirement или expected behavior. При изменении
expected verdict сначала обнови canonical `UC/domain/brief` owner, затем
examples, `CHK-*`, plan и code.
- Gherkin, если выбран downstream-проектом, является executable projection
canonical `SC-*` / `NEG-*`, а не параллельным source of truth.

## Ownership Split

- Canonical validation profile decision живёт только в owner-е, назначенном [`validation-profiles.md`](validation-profiles.md); testing policy и execution artifacts не выбирают profile повторно.
Expand All @@ -72,6 +93,8 @@ Canonical lifecycle gates живут в [../flows/feature.md](../flows/feature.m
- Покрыты новые или измененные contracts, события, schema или integration boundaries.
- Покрыты критичные failure modes из `FM-*` в required `design.md`, bug history или acceptance risks.
- Покрыты feature-specific negative/edge scenarios, если они меняют verdict.
- Required `SC-*` / `NEG-*` прослеживаются через `CHK-*` к automated test либо
явно approved manual-only gap и concrete `EVID-*`.
- Процент line coverage сам по себе недостаточен: нужен scenario- и contract-level coverage.

## Когда Manual-Only Допустим
Expand Down
1 change: 1 addition & 0 deletions template/memory-bank/features/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ audience: humans_and_agents
- Если работа требует roadmap, risk register и нескольких delivery subissues, сначала создай или обнови epic package в [`../epics/README.md`](../epics/README.md).
- По умолчанию feature ссылается на общий product context из [`../product/context.md`](../product/context.md), а при изменении предметных правил также на соответствующие документы из [`../domain/README.md`](../domain/README.md).
- Если feature реализует или существенно меняет устойчивый сценарий проекта, она должна ссылаться на соответствующий `UC-*` из [`../use-cases/README.md`](../use-cases/README.md).
- Для observable behavior применяй [`Behavior Specification Practice`](../flows/behavior-specification.md): canonical examples остаются `SC-*` / `NEG-*` в `brief.md`, automation связывается через `CHK-*` / `EVID-*`, а BDD не создаёт отдельный route или owner.
- В шаблонном репозитории этот каталог может быть пустым. Это нормально.

## Naming
Expand Down
2 changes: 2 additions & 0 deletions template/memory-bank/flows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ derived_from:
- small-change.md
- refactoring.md
- epic.md
- behavior-specification.md
- use-case.md
- feature.md
- feature-artifact-catalog.md
Expand All @@ -33,6 +34,7 @@ audience: humans_and_agents
- [Small Change Flow](small-change.md) — direct delivery без feature package, design и execution plan, но с обязательным routing record.
- [Refactoring Flow](refactoring.md) — behavior-preserving restructuring, characterization coverage, checkpoints и closure gates.
- [Epic Flow](epic.md) — Epic Intake/Proposal, lifecycle крупных инициатив, roadmap, decision log, risks и handoff в feature packages.
- [Behavior Specification Practice](behavior-specification.md) — BDD-цикл Discovery → Formulation → Automation, качество concrete examples и traceability `UC/REQ → SC/NEG → CHK → test evidence`; это практика внутри выбранного flow, а не отдельный route.
- [Use Case Flow](use-case.md) — критерии, lifecycle и ownership для project-level `UC-*`, включая operational / agentic сценарии.
- [Feature Flow](feature.md) — lifecycle `brief.md -> optional design.md -> implementation-plan.md`, gates и стабильные ID (`REQ-*`, `SOL-*`, `STEP-*`).
- [Feature Artifact Catalog](feature-artifact-catalog.md) — optional problem/solution/execution artifacts, selection triggers, ownership, default forms и template availability.
Expand Down
205 changes: 205 additions & 0 deletions template/memory-bank/flows/behavior-specification.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,205 @@
---
title: Behavior Specification Practice
doc_kind: governance
doc_function: canonical
purpose: "Определяет BDD-практику Discovery → Formulation → Automation, качество concrete examples и traceability без создания отдельного delivery route или второго owner требований."
derived_from:
- ../dna/governance.md
- ../dna/principles.md
canonical_for:
- behavior_discovery_practice
- behavior_example_formulation_rules
- behavior_automation_handoff
- bdd_ownership_boundaries
- bdd_traceability_contract
status: active
audience: humans_and_agents
---

# Behavior Specification Practice

Behavior-Driven Development (BDD) в Memory Bank — это сквозная практика
совместного уточнения, формулирования и проверки наблюдаемого поведения. Она
дополняет выбранный delivery flow, но не является отдельным route в
[`Task Routing`](routing.md) и не создаёт каталог `memory-bank/bdd/`.

BDD выполняется короткими итерациями:

```text
Discovery: что система могла бы делать
→ Formulation: что она должна делать в конкретном примере
→ Automation: что реализация фактически делает
```

## Method Sources

- Dan North, [Introducing BDD](https://dannorth.net/blog/introducing-bdd/) —
первичный источник подхода, business-value framing и формы
`Given / When / Then`.
- [Cucumber BDD Guide](https://cucumber.io/docs/bdd/) — современное описание
цикла Discovery, Formulation и Automation. Cucumber является одним из
возможных инструментов, а не обязательной частью практики.

## Ownership Model

BDD не вводит `BDD-*` identifiers. Он уточняет существующую цепочку owners:

| Fact | Canonical owner |
| --- | --- |
| Устойчивый project-level scenario | `UC-*` |
| Shared domain rule / invariant | `memory-bank/domain/` |
| Обязательное поведение delivery-единицы | `REQ-*` в feature `brief.md` |
| Положительный concrete example | `SC-*` в feature `brief.md` |
| Negative / edge concrete example | `NEG-*` в feature `brief.md` |
| Способ проверки и expected verdict | `CHK-*` в feature `brief.md` |
| Test surface, framework и execution sequencing | `implementation-plan.md` |
| Исполняемая проверка | test code |
| Наблюдаемый результат проверки | `EVID-*` |

Canonical traceability:

```text
UC → BR / REQ → SC / NEG → CHK → automated test → EVID
```

Один `UC-*` может иметь много downstream examples. Один `SC-*` или `NEG-*`
может проверяться несколькими техническими тестами. Test code не становится
owner-ом requirement или acceptance semantics.

## When To Apply Structured BDD

Concrete examples полезны для любого изменения observable behavior. Явная
структура `Given / When / Then` обязательна, когда prose оставляет material
неоднозначность, в том числе при одном из условий:

- несколько business rules, roles, branches или state transitions;
- outcome зависит от комбинации входных условий;
- есть significant negative, edge, retry, duplicate или recovery behavior;
- меняется user-visible, API, event или operational contract;
- один scenario должны одинаково понимать product, engineering и test roles.

Для compact change допустим однострочный `SC-*`, если context, event и
observable outcome всё равно однозначны. Gherkin и Cucumber не обязательны.

## Discovery

Discovery проводится до фиксации feature problem space как ready. Это может
быть conversation, асинхронный review или agent-assisted analysis, но должны
быть представлены product/domain, implementation и verification perspectives.

Обсуди малый delivery slice через конкретные examples и маршрутизируй findings
сразу к существующим owners:

| Discovery finding | Destination |
| --- | --- |
| Stable project flow | создать или обновить `UC-*` |
| Shared domain rule | соответствующий owner в `domain/` |
| Feature-specific rule | `REQ-*` |
| Positive example | `SC-*` |
| Negative / edge example | `NEG-*` |
| Unanswered verdict-changing question | `DEC-*` |
| Deferred behavior | `NS-*`, upstream backlog или отдельная delivery-unit |

Не создавай отдельный discovery transcript как canonical artifact. Optional
feature-local use-case companion может показывать derived example map, но не
принимать новые requirements, acceptance criteria или checks.

## Formulation

Каждый structured example содержит:

- **Name** — краткое описание различающего поведения;
- **Rule refs** — применимые `UC/BR/REQ` references;
- **Given** — только существенное начальное состояние;
- **When** — одно значимое событие или действие;
- **Then** — observable outcome для пользователя, оператора или external
system;
- **Check refs** — применимые `CHK-*` либо planned mapping до `Problem Ready`.

Пример:

```markdown
#### SC-01: Успешная оплата при достаточном балансе

- Rule refs: `UC-004/BR-01`, `REQ-02`
- Given: баланс клиента не меньше суммы заказа
- When: клиент подтверждает оплату
- Then: заказ получает статус «оплачен»
- And: публикуется подтверждение платежа
- Checks: `CHK-01`
```

Scenario quality rules:

1. Используй domain language, а не selectors, endpoints, tables или class names.
2. Проверяй observable result, а не скрытое внутреннее состояние, если оно не
является явно опубликованным contract.
3. Один example иллюстрирует одно главное правило или одну различающую branch.
4. Используй concrete values, когда они снимают неоднозначность boundary.
5. Не копируй общий `UC-*` flow или shared domain rule в каждый example.
6. Не превращай scenario в implementation procedure или длинный UI click path.

## Automation

Automation связывает accepted example с системой как проверку и направляет
реализацию, но не требует конкретного framework или test level.

- Выбирай самый низкий надёжный test surface, который доказывает observable
behavior: unit, component, contract, integration или E2E.
- Gherkin scenario не означает обязательный browser/UI test.
- Имя, tag или metadata automated test должны сохранять ссылку на `SC-*` или
`NEG-*`, если conventions выбранного проекта это допускают.
- Manual-only gap требует причины, процедуры и approvals из выбранного
validation profile.
- Изменение expected behavior сначала обновляет canonical owner, затем examples,
checks, plan и test code.

## Lifecycle Integration

### Problem Ready

- verdict-changing discovery questions разрешены либо зафиксированы как
blocking `DEC-*`;
- каждый `REQ-*` покрыт минимум одним `SC-*` или `NEG-*`;
- required examples формулируют context, event и observable outcome;
- `CHK-*` и `EVID-*` образуют проверяемый acceptance contract.

### Solution Ready

Если design required, driving `SC-*` участвуют в cross-view correspondence, а
существенные `NEG-*` / edge examples связываются с применимыми `FM-*`,
`CTR-*`, `INV-*` или получают обоснованный `N/A`.

### Plan Ready

Test Strategy показывает для каждого required `SC-*` / `NEG-*` planned test
surface, automation, required suites, evidence и допустимые manual-only gaps.

### Done

- required examples имеют pass/fail evidence через `CHK-*` / `EVID-*`;
- required automated coverage добавлено и зелёное локально и в CI;
- manual-only gaps явно approved;
- `UC`, `brief`, derived views и executable checks не противоречат друг другу.

## Change Propagation

При material change стабильного scenario сначала обнови `UC-*` или shared
domain owner, затем feature `REQ/SC/NEG/CHK`, derived views, plan и test code.
Не оставляй одновременно два противоречащих active descriptions одного
behavior.

## Anti-Patterns

- отдельный BDD-каталог как второй owner acceptance;
- Gherkin, написанный после реализации только ради отчёта;
- все examples автоматизированы через медленные E2E tests;
- `Then` проверяет private database или internal method вместо outcome;
- feature-local example переписывает весь `UC-*`;
- derived `FUC-*` или `TC-*` вводит новый verdict, отсутствующий в `brief.md`.

## Outcome / Exit Contract

BDD применён корректно, когда команда имеет shared understanding через
concrete examples, canonical facts остаются у существующих owners, а required
behavior прослеживается от `UC/REQ` через `SC/NEG` и `CHK` до test evidence.
Loading
Loading