From 110fbc7ec0db62cfdad67749db5a7ed20696d3fa Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Thu, 6 Aug 2026 16:34:36 +0500 Subject: [PATCH] docs: integrate BDD lifecycle practice --- README.md | 1 + template/memory-bank/README.md | 2 +- .../memory-bank/engineering/testing-policy.md | 23 ++ template/memory-bank/features/README.md | 1 + template/memory-bank/flows/README.md | 2 + .../flows/behavior-specification.md | 205 ++++++++++++++++++ .../flows/feature-artifact-catalog.md | 7 +- template/memory-bank/flows/feature.md | 37 ++-- .../memory-bank/flows/priming/feature.yaml | 2 + .../memory-bank/flows/priming/use-case.yaml | 1 + .../memory-bank/flows/templates/README.md | 2 +- .../flows/templates/feature/README.md | 2 +- .../flows/templates/feature/brief.md | 39 +++- .../flows/templates/feature/design.md | 7 +- .../templates/feature/implementation-plan.md | 5 + .../templates/feature/support/use-cases.md | 37 +++- .../flows/templates/use-case/UC-XXX.md | 14 ++ template/memory-bank/flows/use-case.md | 34 ++- template/memory-bank/use-cases/README.md | 6 + 19 files changed, 387 insertions(+), 40 deletions(-) create mode 100644 template/memory-bank/flows/behavior-specification.md diff --git a/README.md b/README.md index 660f737..79c4e6a 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/template/memory-bank/README.md b/template/memory-bank/README.md index 008eb77..85d90b3 100644 --- a/template/memory-bank/README.md +++ b/template/memory-bank/README.md @@ -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. diff --git a/template/memory-bank/engineering/testing-policy.md b/template/memory-bank/engineering/testing-policy.md index dde3907..256d2a1 100644 --- a/template/memory-bank/engineering/testing-policy.md +++ b/template/memory-bank/engineering/testing-policy.md @@ -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 @@ -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 @@ -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 повторно. @@ -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 Допустим diff --git a/template/memory-bank/features/README.md b/template/memory-bank/features/README.md index b1aee59..e0b0412 100644 --- a/template/memory-bank/features/README.md +++ b/template/memory-bank/features/README.md @@ -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 diff --git a/template/memory-bank/flows/README.md b/template/memory-bank/flows/README.md index 1b41539..c312bbe 100644 --- a/template/memory-bank/flows/README.md +++ b/template/memory-bank/flows/README.md @@ -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 @@ -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. diff --git a/template/memory-bank/flows/behavior-specification.md b/template/memory-bank/flows/behavior-specification.md new file mode 100644 index 0000000..37f51dc --- /dev/null +++ b/template/memory-bank/flows/behavior-specification.md @@ -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. diff --git a/template/memory-bank/flows/feature-artifact-catalog.md b/template/memory-bank/flows/feature-artifact-catalog.md index c63715a..46f6d30 100644 --- a/template/memory-bank/flows/feature-artifact-catalog.md +++ b/template/memory-bank/flows/feature-artifact-catalog.md @@ -14,6 +14,11 @@ audience: humans_and_agents Этот каталог — меню, а не checklist. Он перечисляет распространенные программно-инженерные артефакты и помогает выбрать только те, которые снимают реальную неоднозначность конкретной feature. +Для observable behavior сначала примени +[`Behavior Specification Practice`](behavior-specification.md). Discovery, +Formulation и Automation используют существующие owners и сами по себе не +требуют отдельного artifact. + При bootstrap feature package обязательны только `README.md` и `brief.md`. Все остальные документы, таблицы и diagrams условны. `implementation-plan.md` появляется только перед реальным execution, а отдельный `design.md` — только когда `brief.md` фиксирует `Design required: yes`. ## Selection Rules @@ -36,7 +41,7 @@ audience: humans_and_agents | Epic package | Как координируются roadmap, risks и несколько delivery units? | Работа крупнее одной vertical feature | `memory-bank/epics/EP-XXX/` | Initiative coordination, не feature execution | [Epic](templates/epic/README.md) | | `README.md` | Какие artifacts реально входят в feature package и в каком порядке их читать? | Любой feature package | `features/FT-XXX/README.md` | Routing only | [Feature README](templates/feature/README.md) | | `brief.md` | Какую проблему решаем, что входит в scope и как принимаем результат? | Любой feature package | `features/FT-XXX/brief.md` | Canonical problem, requirements, acceptance and evidence contract | [Brief](templates/feature/brief.md) | -| Feature-local use cases | Какие happy, edge и error journeys удобнее review отдельно? | Много scenarios/roles или нужен `FUC -> REQ -> CHK` mapping | `use-cases/README.md` | Derived scenario projection; canonical acceptance остается в `brief.md` | [Feature Use Cases](templates/feature/support/use-cases.md) | +| Feature-local use cases / behavior example map | Какие happy, edge и error journeys и их `Given / When / Then` projections удобнее review отдельно? | Много scenarios/roles или нужен `FUC → SC/NEG → REQ → CHK` mapping | `use-cases/README.md` | Derived scenario/example projection; canonical acceptance остается в `brief.md`, новый verdict здесь запрещён | [Feature Use Cases](templates/feature/support/use-cases.md) | | Runtime surface inventory | Где behavior существует сейчас и какой context доступен? | Несколько entrypoints, mappings, fallbacks или context variants | `runtime-surfaces.md` | Current-state reference | [Runtime Surfaces](templates/feature/support/runtime-surfaces.md) | | UI flow / mockups | Что видит пользователь и какие interface states проходит? | Меняется UI, navigation, editor/preview или interaction model | `ui-reference/README.md`, `ui-reference/mockups/*`; ссылка на `engineering/ui-design-guide/README.md` или нужный surface document | Interface reference; requirements и selected solution остаются у canonical owners; shared UI catalog не копируется в feature | [UI Reference](templates/feature/support/ui-reference.md) | | Glossary | Что означают неоднозначные business и technical terms? | Терминология materially влияет на scope, contract или review | Compact table in owner; при росте `glossary.md` | Reference term registry with source refs | pattern only | diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index b822be2..e9ee157 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -8,6 +8,7 @@ derived_from: - ../dna/frontmatter.md - routing.md - priming/context-priming.md + - behavior-specification.md - ../engineering/validation-profiles.md canonical_for: - feature_directory_structure @@ -35,6 +36,7 @@ canonical_for: - feature_design_pack_relation_rules - feature_design_pack_readiness_rules - feature_solution_ownership_rules + - feature_behavior_specification_gates status: active audience: humans_and_agents --- @@ -67,13 +69,14 @@ immutable revision и `GRND-*` evidence. 9. Для canonical `brief.md`, canonical `design.md`, feature-level `README.md` и `implementation-plan.md` используй wrapper-шаблоны из `memory-bank/flows/templates/feature/`: сам template-файл имеет `doc_function: template`, а frontmatter/body инстанцируемого документа живут внутри embedded template contract. 10. Смысл стабильных идентификаторов (`REQ-*`, `SOL-*`, `SD-*`, `STEP-*` и т.д.) задается в секции «Stable Identifiers» ниже. 11. Acceptance scenarios (`SC-*`) покрывают delivery-unit end-to-end: для пользовательского slice — от входного события до наблюдаемого результата через все затронутые слои; для infrastructure/engineering/operations change — от system, operator или pipeline trigger до observable operational outcome. Тестирование отдельного слоя в изоляции допустимо как implementation detail плана, но не заменяет end-to-end acceptance. -12. **Связь с task tracker.** При создании feature package агент обязан добавить в исходную задачу или ticket ссылку на `brief.md`, а после появления downstream-документов — ссылки на существующие `design.md` и `implementation-plan.md`. -13. До Bootstrap / Brief агент обязан прочитать весь текущий `memory-bank/prd/*.md` corpus. Это обязательный context baseline независимо от того, зависит ли feature от конкретного PRD; PRD не заменяет сам feature package. -14. Если фича создает новый устойчивый сценарий проекта или materially changes существующий, соответствующий `UC-*` в `memory-bank/use-cases/` должен быть создан или обновлен до closure. -15. Optional feature-support docs (`runtime-surfaces.md`, `diagrams/-sequence.md`, `ui-reference/README.md`, `use-cases/README.md`) допустимы для сложных фич как grounding / review / traceability aids. Они не становятся canonical owner problem space, solution space, acceptance inventory или execution sequencing. -16. Полное чтение PRD corpus не создаёт semantic dependency от каждого PRD. `brief.md: derived_from` импортирует только фактические upstream-owner references и не копирует весь upstream scope. -17. Если работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units, не расширяй feature package: повтори [`Task Routing`](routing.md), выбери [`Epic Flow`](epic.md) и после epic handoff веди каждую утвержденную delivery-единицу как отдельный feature package. -18. Validation profile выбирается в `brief.md` по [`validation-profiles.md`](../engineering/validation-profiles.md). `design.md` может уточнить risk facts, а `implementation-plan.md` разворачивает minimum contract в команды, suites и checkpoints, но ни один из них не дублирует profile decision. +12. Для observable behavior применяй [`Behavior Specification Practice`](behavior-specification.md): discovery findings маршрутизируются в существующие owners, concrete examples формулируются через `SC-*` / `NEG-*`, а automation связывается через `CHK-*` и `EVID-*`. BDD не вводит отдельный route или `BDD-*` identifiers. +13. **Связь с task tracker.** При создании feature package агент обязан добавить в исходную задачу или ticket ссылку на `brief.md`, а после появления downstream-документов — ссылки на существующие `design.md` и `implementation-plan.md`. +14. До Bootstrap / Brief агент обязан прочитать весь текущий `memory-bank/prd/*.md` corpus. Это обязательный context baseline независимо от того, зависит ли feature от конкретного PRD; PRD не заменяет сам feature package. +15. Если фича создает новый устойчивый сценарий проекта или materially changes существующий, соответствующий `UC-*` в `memory-bank/use-cases/` должен быть создан или обновлен до closure. +16. Optional feature-support docs (`runtime-surfaces.md`, `diagrams/-sequence.md`, `ui-reference/README.md`, `use-cases/README.md`) допустимы для сложных фич как grounding / review / traceability aids. Они не становятся canonical owner problem space, solution space, acceptance inventory или execution sequencing. +17. Полное чтение PRD corpus не создаёт semantic dependency от каждого PRD. `brief.md: derived_from` импортирует только фактические upstream-owner references и не копирует весь upstream scope. +18. Если работа крупнее одной delivery-feature и требует общего roadmap, cross-feature risk register или нескольких delivery units, не расширяй feature package: повтори [`Task Routing`](routing.md), выбери [`Epic Flow`](epic.md) и после epic handoff веди каждую утвержденную delivery-единицу как отдельный feature package. +19. Validation profile выбирается в `brief.md` по [`validation-profiles.md`](../engineering/validation-profiles.md). `design.md` может уточнить risk facts, а `implementation-plan.md` разворачивает minimum contract в команды, suites и checkpoints, но ни один из них не дублирует profile decision. ## Feature Package Anatomy @@ -309,7 +312,9 @@ flowchart LR - [ ] `brief.md` → `status: active` - [ ] секция `What` содержит ≥ 1 `REQ-*` и ≥ 1 `NS-*` - [ ] секция `Verify` содержит ≥ 1 `SC-*` -- [ ] каждый `REQ-*` прослеживается к ≥ 1 `SC-*` через traceability matrix +- [ ] каждый `REQ-*` прослеживается к ≥ 1 `SC-*` или `NEG-*` через traceability matrix; основной changed behavior всегда имеет positive `SC-*` +- [ ] verdict-changing вопросы из behavior discovery разрешены либо зафиксированы как blocking `DEC-*`; найденные stable flows, shared rules и deferred work переданы соответствующим `UC-*`, domain owner и `NS-*` / отдельной delivery-unit +- [ ] каждый required `SC-*` / `NEG-*` однозначно задаёт существенный context, одно событие и observable outcome; при structured BDD triggers из [`Behavior Specification Practice`](behavior-specification.md) используется `Given / When / Then` или эквивалентная структура - [ ] секция `Verify` содержит ≥ 1 `CHK-*` и ≥ 1 `EVID-*` - [ ] если deliverable нельзя принять без negative/edge coverage → ≥ 1 `NEG-*` - [ ] `brief.md` содержит Design Requirement Decision: `Design required: yes/no` и причину @@ -331,7 +336,7 @@ flowchart LR - [ ] `design.md` ссылается минимум на один canonical `REQ-*` из sibling `brief.md` - [ ] `design.md` фиксирует C4 applicability decision; если C4 level required, C4 artifact или ссылка на canonical C4/design artifact присутствует в design-pack - [ ] 4+1 Viewpoint Coverage Decision применяет View Applicability Predicates и фиксирует `covered` для Logical View и Scenarios, а для Process, Development и Physical — `covered` или evidence-backed `N/A`, stakeholder/concern, canonical refs и optional supporting projection -- [ ] Cross-View Correspondence содержит каждый `SC-*` из `brief.md` и связывает его с requirement, применимыми Process/Development/Physical refs и `CHK-*`/`EVID-*`; неприменимые связи отмечены `N/A` +- [ ] Cross-View Correspondence содержит каждый `SC-*` из `brief.md` и связывает его с requirement, применимыми Process/Development/Physical refs и `CHK-*`/`EVID-*`; существенные `NEG-*` / edge examples связаны с применимыми `FM-*`, `CTR-*`, `INV-*` или обоснованным `N/A` - [ ] Architecture Coverage Decision фиксирует `covered` или обоснованный `N/A` для components, connectors, configuration, behavioral semantics и quality/evolution concerns - [ ] при cross-component interaction явно показаны bindings/topology, direction, connector kind и значимые interaction semantics; один перечень components недостаточен - [ ] Design Verification выбирает каждый analysis class по риску через `required: yes/no`; required analyses имеют method и result/evidence, а `no` имеет причину @@ -356,7 +361,7 @@ Plan Ready artifact-review convergence допускает не более пят - [ ] минимум один `GRND-*` подтверждает существующий implementation pattern или current change surface, а минимум один — существующую test surface либо evidence-backed отсутствие подходящего покрытия - [ ] шаги и workstreams в `implementation-plan.md` ссылаются на canonical IDs из `brief.md` и, если design layer существует, solution refs из их непосредственных design-pack owners / external dependencies - [ ] для designed feature план содержит явное refinement применимых `SOL-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs через `realization target -> STEP/CHK/EVID`; каждый применимый ref встречается минимум в одной mapping-строке, а найденный solution gap сначала обновляет canonical owner -- [ ] `Test Strategy`, approvals и checkpoints покрывают применимые obligations validation profile из `brief.md`, не дублируя решение +- [ ] `Test Strategy`, approvals и checkpoints покрывают применимые obligations validation profile из `brief.md`, не дублируя решение; каждый required `SC-*` / `NEG-*` имеет planned test surface, automation status, required local/CI suites и evidence - [ ] candidate revisions `brief.md`, полного optional design pack, всех referenced external dependencies, `implementation-plan.md` и grounded immutable commit SHA repository revision заморожены для Plan Ready artifact review - [ ] Plan Ready artifact review проверил достаточность grounding, consistency с upstream owners, ownership boundaries, traceability, executability, test strategy, approvals и stop/fallback conditions - [ ] все critical/important artifact findings исправлены; остальные findings явно disposition как допустимые non-blocking/deferred с owner; после последнего исправления получен clean re-review текущих candidate revisions @@ -377,6 +382,7 @@ Plan Ready artifact-review convergence допускает не более пят - [ ] все `CHK-*` из `brief.md` имеют результат pass/fail в evidence - [ ] все `EVID-*` из `brief.md` заполнены конкретными carriers (путь к файлу, CI run, screenshot) +- [ ] каждый required `SC-*` / `NEG-*` прослеживается через `CHK-*` к automated test или явно approved manual-only gap; test name, tag или metadata сохраняет scenario ref, если это допускают project conventions - [ ] delivered behavior не противоречит accepted `SOL-*` / `SD-*` / ADR refs, если design layer существует - [ ] automated tests для change surface добавлены или обновлены - [ ] required test suites зелёные локально и в CI @@ -426,7 +432,7 @@ Plan Ready artifact-review convergence допускает не более пят 5. Если design layer нужен, design pack aggregate-владеет feature-local solution space. Root `design.md` владеет manifest, selected design и всеми неделегированными solution facts; constituent владеет только явно делегированными canonical facts; derived view не владеет canonical facts; external dependency сохраняет собственного canonical owner. 6. `delivery_status` остается только на `brief.md`; `design.md` и `implementation-plan.md` не дублируют lifecycle state delivery-единицы. 7. `design.md` не должен переопределять business requirements, scope, acceptance criteria, canonical checks, evidence contract, detailed current-system inventory или execution sequencing. -8. Feature-support docs не должны переопределять canonical facts. Они могут давать surface inventory, UI reference, mockups, derived use cases и review mappings только как support context. +8. Feature-support docs не должны переопределять canonical facts. Они могут давать surface inventory, UI reference, mockups, derived use cases, behavior example maps и review mappings только как support context; derived example не может вводить новый verdict, отсутствующий в `brief.md`. 9. Если feature зависит от ADR, ADR остаётся canonical owner решения, а `design.md` индексирует его как `external-dependency`; только `status: active` + `decision_status: accepted` считается finalized design. 10. Если feature зависит от канонического use case, `brief.md` ссылается на соответствующий файл в `memory-bank/use-cases/`. Use case остается owner-ом trigger/preconditions/main flow/postconditions на уровне проекта, а `brief.md` фиксирует только slice-specific проблему и verify. 11. `implementation-plan.md` остается derived execution-документом: он ссылается на canonical IDs из `brief.md` и, если есть, применимые `SOL-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs, показывает их realization в `STEP/CHK/EVID`, фиксирует discovery context и test strategy для исполнения и не переопределяет scope, selected design, C4 architecture model, blockers, acceptance criteria или evidence contract. @@ -450,8 +456,9 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng 4. **Sufficient coverage** = покрыт основной changed behavior, новые или измененные contracts из их design-pack owner / external dependency, критичные failure modes из `FM-*` и feature-specific negative/edge scenarios, если они меняют verdict. Процент line coverage сам по себе недостаточен. 5. **Manual-only допустим** только как явное исключение (live infra, hardware, недетерминированная среда). Для каждого gap — причина, ручная процедура или `EVID-*`, owner follow-up и approval ref через `AG-*`. 6. **К Problem Ready** `brief.md` уже фиксирует test case inventory: минимум один `SC-*`, traceability к `REQ-*` и Design Requirement Decision. **К Solution Ready** весь required design pack готов и согласован по gate выше. **К Done** — automated tests добавлены, обязательные suites зелёные локально и в CI. -7. **Simplify review** — отдельный проход после функциональных тестов, до closure. Цель: убедиться, что код минимально сложен. Три похожие строки лучше premature abstraction. Complexity оправдана только со ссылкой на `CON-*`, `INV-*`, `FM-*`, `SD-*` или accepted ADR. -8. **Verification context separation** — функциональная верификация, simplify review и acceptance test — три логически отдельных прохода. Между проходами агент формулирует выводы до начала следующего. Для compact feature packages допустимо в одной сессии, но simplify review не пропускается. +7. **BDD automation не означает E2E-only.** Для `SC-*` / `NEG-*` выбирай самый низкий надёжный unit, component, contract, integration или E2E surface, который доказывает observable outcome; Gherkin и Cucumber не обязательны. +8. **Simplify review** — отдельный проход после функциональных тестов, до closure. Цель: убедиться, что код минимально сложен. Три похожие строки лучше premature abstraction. Complexity оправдана только со ссылкой на `CON-*`, `INV-*`, `FM-*`, `SD-*` или accepted ADR. +9. **Verification context separation** — функциональная верификация, simplify review и acceptance test — три логически отдельных прохода. Между проходами агент формулирует выводы до начала следующего. Для compact feature packages допустимо в одной сессии, но simplify review не пропускается. ## Stable Identifiers @@ -526,8 +533,8 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng ### Traceability Contract 1. Scope в `brief.md` фиксируется через `REQ-*`, non-scope через `NS-*`. -2. Verify в `brief.md` связывает `REQ-*` с test cases через `Acceptance Scenarios`, feature-specific `NEG-*`, `Traceability matrix`, `Test matrix` и `Evidence contract`. -3. `design.md`, если есть, связывает каждый `SC-*` и применимые `REQ-*` из `brief.md` с Logical, Process, Development и Physical refs через Cross-View Correspondence; canonical solution traceability отдельно связывает `REQ-*` с `SOL-*`, `ALT-*`, `TRD-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs. +2. Verify в `brief.md` связывает `REQ-*` с concrete examples через `Acceptance Scenarios`, feature-specific `NEG-*`, `Traceability matrix`, `Test matrix` и `Evidence contract`; structured examples сохраняют rule refs, context, event, observable outcome и `CHK-*` mapping. +3. `design.md`, если есть, связывает каждый `SC-*` и применимые `REQ-*` из `brief.md` с Logical, Process, Development и Physical refs через Cross-View Correspondence; существенные `NEG-*` / edge examples связываются с применимыми `FM-*`, `CTR-*`, `INV-*` или `N/A`; canonical solution traceability отдельно связывает `REQ-*` с `SOL-*`, `ALT-*`, `TRD-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs. 4. `implementation-plan.md` ссылается на canonical IDs из `brief.md` и, если есть, применимые `SOL-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs в Design Realization Mapping и `Implements`; `Verifies` содержит связанные `CHK-*`, а `Evidence IDs` — подтверждающие `EVID-*`, образуя trace chain от canonical ref до evidence. 5. Если sequencing блокируется неизвестностью, план фиксирует её как `OQ-*`, а не прячет в prose. 6. Если выполнение требует человеческого подтверждения для рискованных действий, план фиксирует это через `AG-*`. diff --git a/template/memory-bank/flows/priming/feature.yaml b/template/memory-bank/flows/priming/feature.yaml index c51d445..b067f26 100644 --- a/template/memory-bank/flows/priming/feature.yaml +++ b/template/memory-bank/flows/priming/feature.yaml @@ -2,6 +2,7 @@ version: 1 process: feature stages: bootstrap_brief: + - memory-bank/flows/behavior-specification.md - memory-bank/flows/feature-artifact-catalog.md - memory-bank/features/README.md - memory-bank/prd/*.md @@ -28,6 +29,7 @@ stages: - memory-bank/flows/templates/feature/support/runtime-surfaces.md - memory-bank/flows/templates/feature/support/sequence-diagram.md scenario_design: + - memory-bank/flows/behavior-specification.md - memory-bank/flows/templates/feature/support/use-cases.md plan_ready: - memory-bank/flows/templates/feature/implementation-plan.md diff --git a/template/memory-bank/flows/priming/use-case.yaml b/template/memory-bank/flows/priming/use-case.yaml index fbcb7b6..0046993 100644 --- a/template/memory-bank/flows/priming/use-case.yaml +++ b/template/memory-bank/flows/priming/use-case.yaml @@ -2,6 +2,7 @@ version: 1 process: use_case stages: create_update: + - memory-bank/flows/behavior-specification.md - memory-bank/use-cases/*.md - memory-bank/product/*.md - memory-bank/domain/*.md diff --git a/template/memory-bank/flows/templates/README.md b/template/memory-bank/flows/templates/README.md index 83e0860..662df8d 100644 --- a/template/memory-bank/flows/templates/README.md +++ b/template/memory-bank/flows/templates/README.md @@ -69,7 +69,7 @@ audience: humans_and_agents - [FT-XXX: Runtime Surfaces Template](feature/support/runtime-surfaces.md) — optional support template для current runtime inventory, semantic mapping, context matrix и resolution tables. - [FT-XXX: Sequence Diagram Template](feature/support/sequence-diagram.md) — optional reference template для temporal / async interactions, retries, timeouts и failure branches. - [FT-XXX: UI Reference Template](feature/support/ui-reference.md) — optional support template для interface changes, screen map, interaction states и mockups. -- [FT-XXX: Feature Use Cases Template](feature/support/use-cases.md) — optional support template для derived use cases, test case candidates и `FUC -> REQ -> CHK` review mapping. +- [FT-XXX: Feature Use Cases Template](feature/support/use-cases.md) — optional support template для derived use cases, BDD example map, test candidates и `FUC → SC/NEG → REQ → CHK` review mapping без нового acceptance owner. - [ADR-XXX: Short Decision Name](adr/ADR-XXX.md) — шаблон ADR. Отвечает на вопрос: как зафиксировать архитектурное решение. - [PROMPT-XXX: Reusable Prompt Name](prompt/PROMPT-XXX.md) — шаблон reusable prompt-документа. Отвечает на вопрос: как сохранить исходную формулировку в frontmatter и улучшенный prompt в copyable body-блоке. - [PROC-XXX: Process Documentation Index](process/README.md) — шаблон индекса процесс-документов. Отвечает на вопрос: как собрать routing-layer для reusable process cards, session handoff и lifecycle protocol. diff --git a/template/memory-bank/flows/templates/feature/README.md b/template/memory-bank/flows/templates/feature/README.md index c86571f..bb35380 100644 --- a/template/memory-bank/flows/templates/feature/README.md +++ b/template/memory-bank/flows/templates/feature/README.md @@ -39,7 +39,7 @@ Downstream routes для living feature package добавляются по ме - `use-cases/README.md` Читать, когда нужно: если scenario set требует отдельного review-friendly представления happy/edge/error journeys. - Отвечает на вопрос: какие derived feature-local use cases и test candidates проецируются из canonical brief. + Отвечает на вопрос: какие derived feature-local use cases, BDD examples и test candidates проецируются из canonical brief без нового acceptance owner. - `contracts/.md` Читать, когда нужно: если API/event/queue/callback/file/store/cache/auth/locking/runtime-config interaction contract вынесен из `design.md` из-за объема или самостоятельной review boundary. diff --git a/template/memory-bank/flows/templates/feature/brief.md b/template/memory-bank/flows/templates/feature/brief.md index 5d94804..1716af8 100644 --- a/template/memory-bank/flows/templates/feature/brief.md +++ b/template/memory-bank/flows/templates/feature/brief.md @@ -5,6 +5,7 @@ doc_function: template purpose: Governed wrapper-шаблон для canonical `brief.md` в AI-driven development. Фиксирует, как инстанцировать problem-space intent, scope и machine-checkable verify без смешения wrapper и целевого frontmatter. derived_from: - ../../feature.md + - ../../behavior-specification.md - ../../feature-artifact-catalog.md - ../../../dna/frontmatter.md - ../../../engineering/testing-policy.md @@ -28,6 +29,8 @@ canonical_for: Optional companions выбирай по [Feature Artifact Catalog](../../feature-artifact-catalog.md). Не копируй весь каталог в feature и не создавай placeholders: Artifact Routing Decision перечисляет только выбранные artifacts и material omissions, которые важно объяснить reviewers. +Для observable behavior применяй [Behavior Specification Practice](../../behavior-specification.md). Compact feature может оставить однострочный `SC-*`, если context, event и outcome однозначны. При нескольких rules/branches, significant edge/error behavior или изменении user/API/event/operational contract используй structured `Given / When / Then` examples. + Используй стабильные идентификаторы по taxonomy из [../../feature.md#stable-identifiers](../../feature.md#stable-identifiers). ### Frontmatter Quick Ref @@ -149,12 +152,38 @@ failure modes или rollout/backout в `brief.md`. | Requirement ID | Problem refs | Acceptance refs | Checks | Evidence IDs | | --- | --- | --- | --- | --- | | `REQ-01` | `ASM-01`, `CON-01`, `DEC-01` | `EC-01`, `SC-01` | `CHK-01` | `EVID-01` | -| `REQ-02` | `ASM-01`, `CON-01` | `EC-02`, `SC-02` | `CHK-01` | `EVID-01` | +| `REQ-02` | `ASM-01`, `CON-01` | `EC-02`, `SC-02`, `NEG-01` | `CHK-01`, `CHK-02` | `EVID-01`, `EVID-02` | ### Acceptance Scenarios -- `SC-01` Основной happy path. -- `SC-02` Обязательный real-world или edge scenario. +Для compact feature допустима однострочная форма, если она однозначно задаёт +существенный context, event и observable outcome: + +- `SC-01` Основной happy path: при , когда , система публикует или показывает . + +Для structured BDD используй форму ниже. Rule refs ссылаются на canonical +`UC/BR/REQ`, но не копируют их semantics. + +#### SC-02: Название различающего поведения + +- Rule refs: `UC-XXX/BR-01`, `REQ-02` +- Given: существенное начальное состояние +- When: одно значимое событие или действие +- Then: observable outcome для пользователя, оператора или external system +- And: дополнительный observable outcome, только если нужен verdict +- Checks: `CHK-01` + +### Negative / Edge Scenarios + +Добавляй `NEG-*`, когда negative или boundary behavior меняет acceptance verdict. + +#### NEG-01: Название error или edge behavior + +- Rule refs: `UC-XXX/EX-01`, `REQ-02` +- Given: существенное boundary-состояние +- When: событие или действие +- Then: наблюдаемый отказ, fallback или preserved state +- Checks: `CHK-02` ### Checks @@ -163,20 +192,24 @@ Verify должен быть исполнимым. | Check ID | Covers | How to check | Expected result | Evidence path | | --- | --- | --- | --- | --- | | `CHK-01` | `EC-01`, `SC-01` | Команда или процедура | Что считаем успехом | Где лежит артефакт | +| `CHK-02` | `NEG-01` | Команда или процедура | Какой negative / edge verdict ожидается | Где лежит артефакт | ### Test matrix | Check ID | Evidence IDs | Evidence path | | --- | --- | --- | | `CHK-01` | `EVID-01` | `artifacts/ft-xxx/verify/chk-01/` | +| `CHK-02` | `EVID-02` | `artifacts/ft-xxx/verify/chk-02/` | ### Evidence - `EVID-01` Какой артефакт обязан появиться после проверки. +- `EVID-02` Evidence negative / edge verdict или approved manual-only gap. ### Evidence contract | Evidence ID | Artifact | Producer | Path contract | Reused by checks | | --- | --- | --- | --- | --- | | `EVID-01` | Лог, отчет, скриншот или sample output | verify-runner / human | `artifacts/ft-xxx/verify/chk-01/` | `CHK-01` | +| `EVID-02` | Лог, отчет или sample output для negative/edge behavior | verify-runner / human | `artifacts/ft-xxx/verify/chk-02/` | `CHK-02` | ``` diff --git a/template/memory-bank/flows/templates/feature/design.md b/template/memory-bank/flows/templates/feature/design.md index 07f08bd..3e82730 100644 --- a/template/memory-bank/flows/templates/feature/design.md +++ b/template/memory-bank/flows/templates/feature/design.md @@ -118,12 +118,15 @@ execution sequence, а не устойчивую структуру code modules ### Cross-View Correspondence -Добавь по строке для каждого `SC-*` из `brief.md`. Используй только ссылки на -canonical facts; для неприменимого view укажи `N/A`. +Добавь по строке для каждого `SC-*` из `brief.md` и каждого существенного +`NEG-*` / edge example, который влияет на failure, contract или invariant +design. Используй только ссылки на canonical facts; для неприменимого view +укажи `N/A`. | Scenario / requirement | Logical refs | Process refs | Development refs | Physical refs | Verification refs | | --- | --- | --- | --- | --- | --- | | `SC-01` / `REQ-01` | `REQ-01`, применимый `UC-*` | `CTR-01`, `INV-01`, `FM-01` / `N/A` | `SOL-01`, `C4-L3-*`, `SD-01` / `N/A` | `C4-L2-*`, `RB-01`, ops ref / `N/A` | `CHK-01`, `EVID-01` | +| `NEG-01` / `REQ-01` | `REQ-01`, применимый `UC-*/EX-*` | `FM-01`, `CTR-01`, `INV-01` / `N/A` | `SOL-01`, `SD-01` / `N/A` | `RB-01`, ops ref / `N/A` | `CHK-02`, `EVID-02` | ## Architecture Coverage Decision diff --git a/template/memory-bank/flows/templates/feature/implementation-plan.md b/template/memory-bank/flows/templates/feature/implementation-plan.md index 4a66028..58b6b56 100644 --- a/template/memory-bank/flows/templates/feature/implementation-plan.md +++ b/template/memory-bank/flows/templates/feature/implementation-plan.md @@ -134,6 +134,11 @@ revision. Если revision расходится или один из переч Какие test surfaces должны быть обновлены по мере реализации. Сошлись на validation profile из `brief.md` и покажи, как каждая применимая обязанность его minimum contract закрывается tests, suites, evidence, approvals и rollout/backout checkpoints. Этот раздел не переопределяет profile decision или canonical test cases из `brief.md`. +Для каждого required `SC-*` / `NEG-*` выбери самый низкий надёжный test level, +который доказывает observable outcome. BDD не требует Gherkin, Cucumber или +E2E-only tests. Если project conventions позволяют, planned test name, tag или +metadata сохраняет scenario ref для traceability. + | Test surface | Canonical refs | Existing coverage | Planned automated coverage | Required local suites / commands | Required CI suites / jobs | Manual-only gap / justification | Manual-only approval ref | | --- | --- | --- | --- | --- | --- | --- | --- | | `path/or/behavior` | `REQ-01`, `SC-01`, `NEG-01`, `CHK-01`, `SOL-01 если design существует` | Что покрыто сейчас | Какой suite, test type или deterministic check обязаны добавить или обновить | Какие команды или suites обязаны быть зелёными локально | Какие jobs или suites обязаны быть зелёными в CI | Что пока остается manual-only и почему | `AG-01` / review link / `none` | diff --git a/template/memory-bank/flows/templates/feature/support/use-cases.md b/template/memory-bank/flows/templates/feature/support/use-cases.md index 03b3911..3481b5a 100644 --- a/template/memory-bank/flows/templates/feature/support/use-cases.md +++ b/template/memory-bank/flows/templates/feature/support/use-cases.md @@ -2,9 +2,10 @@ title: "FT-XXX: Feature Use Cases Template" doc_kind: feature-support doc_function: template -purpose: Governed wrapper-шаблон optional feature-local `use-cases/README.md`. Читать, когда feature needs review-friendly scenarios and derived test case candidates without moving canonical acceptance out of `brief.md`. +purpose: Governed wrapper-шаблон optional feature-local `use-cases/README.md`. Читать, когда feature needs review-friendly use cases, BDD example mapping и derived test candidates без переноса canonical acceptance из `brief.md`. derived_from: - ../../../feature.md + - ../../../behavior-specification.md - ../../../feature-artifact-catalog.md - ../../../../dna/frontmatter.md status: active @@ -21,9 +22,11 @@ canonical_for: ## Wrapper Notes -Создавай feature-local `use-cases/README.md`, если scenario set становится сложным для review: много happy/edge/error cases, несколько user roles или нужен удобный `FUC -> REQ -> CHK` mapping. +Создавай feature-local `use-cases/README.md`, если scenario set становится сложным для review: много happy/edge/error cases, несколько user roles или нужен удобный `FUC → SC/NEG → REQ → CHK` mapping. Этот документ не подменяет canonical `SC-*`, `NEG-*`, `CHK-*` и `EVID-*` из `brief.md`. +BDD examples здесь являются derived projection: они не могут вводить новый +context, event, outcome или verdict, отсутствующий в canonical `brief.md`. ## Instantiated Frontmatter @@ -31,7 +34,7 @@ canonical_for: title: "FT-XXX: Feature Use Cases" doc_kind: feature-support doc_function: reference -purpose: "Derived use-case companion для FT-XXX. Упаковывает сценарии и test case candidates для review без переопределения canonical acceptance inventory." +purpose: "Derived use-case companion для FT-XXX. Упаковывает use cases, BDD example mapping и test candidates для review без переопределения canonical acceptance inventory." derived_from: - ../brief.md # Required only when design.md exists: @@ -56,23 +59,32 @@ must_not_define: Canonical acceptance / test inventory остается в `brief.md` через `SC-*`, `NEG-*`, `CHK-*` и `EVID-*`. -## Happy Path +## Rule And Example Map -| ID | Use case | Description | Primary refs | +Проецируй только существующие canonical refs. Verdict-changing question должен +быть записан как `DEC-*` в `brief.md`, а не решён в этом companion. + +| Rule refs | Positive examples | Negative / edge examples | Open question refs | | --- | --- | --- | --- | -| `FUC-H01` | Название сценария | Что делает пользователь и какой результат ожидается | `REQ-01`, `SC-01` | +| `UC-XXX/BR-01`, `REQ-01` | `SC-01` | `NEG-01` | `DEC-01` / `none` | + +## Happy Path + +| ID | Use case | Given | When | Then | Primary refs | +| --- | --- | --- | --- | --- | --- | +| `FUC-H01` | Название сценария | Существенный context из `SC-01` | Событие из `SC-01` | Observable outcome из `SC-01` | `REQ-01`, `SC-01`, `CHK-01` | ## Edge Cases -| ID | Use case | Description | Primary refs | -| --- | --- | --- | --- | -| `FUC-E01` | Название edge case | Какой допустимый крайний случай должен работать | `REQ-01`, `SC-01` | +| ID | Use case | Given | When | Then | Primary refs | +| --- | --- | --- | --- | --- | --- | +| `FUC-E01` | Название edge case | Boundary context | Событие | Observable boundary outcome | `REQ-01`, `SC-01`, `CHK-01` | ## Error Cases -| ID | Use case | Description | Primary refs | -| --- | --- | --- | --- | -| `FUC-ER01` | Название error case | Как система ведет себя при ошибке | `NEG-01`, `FM-01` | +| ID | Use case | Given | When | Then | Primary refs | +| --- | --- | --- | --- | --- | --- | +| `FUC-ER01` | Название error case | Failure context | Событие | Observable rejection, fallback или preserved state | `NEG-01`, `CHK-02`, `FM-01` / `none` | ## Interface Use Cases @@ -85,6 +97,7 @@ Canonical acceptance / test inventory остается в `brief.md` через ## Derived Test Case Candidates `TC-*` здесь являются candidates для planning/review и должны ссылаться на canonical `CHK-*`, а не создавать новые checks. +Они не считаются automation plan или test implementation owner. | Test Case ID | Covers | Preconditions | Steps | Expected result | Automation candidate | | --- | --- | --- | --- | --- | --- | diff --git a/template/memory-bank/flows/templates/use-case/UC-XXX.md b/template/memory-bank/flows/templates/use-case/UC-XXX.md index 41b7a3d..d4e5774 100644 --- a/template/memory-bank/flows/templates/use-case/UC-XXX.md +++ b/template/memory-bank/flows/templates/use-case/UC-XXX.md @@ -8,6 +8,7 @@ derived_from: - ../../../dna/frontmatter.md - ../../../product/context.md - ../../use-case.md + - ../../behavior-specification.md status: active audience: humans_and_agents template_for: use_case @@ -24,6 +25,8 @@ canonical_for: Use case фиксирует устойчивый проектный сценарий. Он описывает trigger, preconditions, основной flow, альтернативы и postconditions, но не уходит в implementation sequence, архитектуру или feature-level verify. +BDD concrete examples живут downstream как `SC-*` / `NEG-*`. Use case дает им стабильные точки traceability через `BR-*`, `ALT-*` и `EX-*`, но не копирует example bodies, checks или test matrix. + Критерии выбора, lifecycle и границы между `UC-*`, `SC-*` и `FUC-*` определяет [`Use Case Flow`](../../use-case.md). Если сценарий слишком локален и живет только внутри одной delivery-единицы, не поднимай его в `UC-*`: оставь его в `SC-*` у соответствующей feature. @@ -50,6 +53,7 @@ must_not_define: - implementation_sequence - architecture_decision - feature_level_test_matrix + - bdd_example_inventory ``` ## Instantiated Body @@ -127,6 +131,16 @@ must_not_define: | ADR | `ADR-XXX` / `none` | | Runbooks / Ops | `../ops/...` / `none` | +## Downstream Behavior Coverage + +Заполняй после появления downstream feature examples. Таблица является +навигацией; canonical acceptance и checks остаются в feature `brief.md`. + +| UC element | Downstream examples | Coverage note | +| --- | --- | --- | +| `BR-01` | `FT-XXX/SC-01`, `FT-XXX/NEG-01` | Какие различающие positive/negative examples проверяют rule | +| `ALT-01` | `FT-YYY/SC-02` | Какая feature реализует alternative branch | + ## Lifecycle Note (Required When Archived) - Почему сценарий больше не является active behavior. diff --git a/template/memory-bank/flows/use-case.md b/template/memory-bank/flows/use-case.md index 60ed760..ca16918 100644 --- a/template/memory-bank/flows/use-case.md +++ b/template/memory-bank/flows/use-case.md @@ -6,6 +6,7 @@ purpose: Lifecycle создания, активации и обновления derived_from: - ../dna/governance.md - priming/context-priming.md + - behavior-specification.md - feature.md canonical_for: - use_case_selection @@ -14,6 +15,7 @@ canonical_for: - use_case_lifecycle - operational_agentic_use_case_rules - use_case_registry_contract + - use_case_behavior_coverage_contract status: active audience: humans_and_agents --- @@ -38,7 +40,10 @@ actor-а: trigger, preconditions, основной flow, ожидаемые ал `UC-*` является canonical owner сценария уровня проекта. Feature-level `SC-*` остается owner-ом acceptance конкретной delivery-единицы, а feature-local -`FUC-*` — derived представлением сценариев для review. +`FUC-*` — derived представлением сценариев для review. BDD concrete examples +не заменяют `UC-*`: они уточняют отдельные rules и branches в downstream +feature через `SC-*` / `NEG-*` по +[`Behavior Specification Practice`](behavior-specification.md). ## Selection Gate @@ -55,6 +60,17 @@ features, runbooks, prompts или ops docs. Не создавай `UC-*` для acceptance case, локального edge case или implementation detail: оставь это в `SC-*`, `NEG-*` или optional feature-local `FUC-*`. +## Behavior Coverage + +`UC-*` владеет stable goal, actor, trigger, preconditions, main flow, +alternatives/exceptions, postconditions и business rules. Он не хранит полную +матрицу BDD examples, feature checks или test implementation. + +Используй стабильные `BR-*`, `ALT-*` и `EX-*` как точки traceability. Когда +downstream examples уже существуют, связывай элементы use case с concrete +`FT-XXX/SC-*` и `FT-XXX/NEG-*`. Такая coverage table навигационная: acceptance +semantics и checks остаются в соответствующем feature `brief.md`. + ## Operational / Agentic Use Cases Operational и agentic use cases описывают повторяемую работу, где человек, @@ -80,11 +96,13 @@ candidate scenario → selection gate → stable UC ID → draft from template [`use-cases/README.md`](../use-cases/README.md). 3. Создай файл по [`UC-XXX` template](templates/use-case/UC-XXX.md). 4. Заполни общий scenario contract: goal, actor, trigger, preconditions, main - flow, alternatives/exceptions, postconditions и business rules. + flow, alternatives/exceptions, postconditions и стабильные `BR-*` business + rules. 5. Для operational / agentic сценария добавь только применимые optional contracts: observable status, handoff, diagnostics и recovery. -6. Добавь upstream/downstream traceability без копирования требований или - implementation details из owner-документов. +6. Добавь upstream/downstream traceability и доступную behavior coverage без + копирования requirements, BDD example bodies или implementation details из + owner-документов. 7. Зарегистрируй use case в аннотированном реестре и переведи его в `active` после прохождения Activation Gate. @@ -104,6 +122,8 @@ candidate scenario → selection gate → stable UC ID → draft from template - [ ] main flow описывает observable behavior, а не implementation sequence - [ ] ожидаемые alternatives/exceptions и успешные/неуспешные postconditions зафиксированы +- [ ] применимые business rules имеют стабильные `BR-*`, а существующие + downstream `SC-*` / `NEG-*` связаны через behavior coverage - [ ] operational contracts добавлены, только если они являются частью наблюдаемого project-level behavior - [ ] traceability содержит актуальные upstream и downstream refs @@ -118,6 +138,10 @@ candidate scenario → selection gate → stable UC ID → draft from template compatibility boundary; не оставляй одновременно два противоречащих active описания одного сценария. +Material change требует impact analysis по связанным `BR/ALT/EX → SC/NEG`: +обнови feature `brief.md`, `CHK-*`, derived views, execution plan и test code +после изменения их canonical upstream owner. + ### Active → Archived - [ ] сценарий больше не является поддерживаемым project-level behavior @@ -130,6 +154,8 @@ compatibility boundary; не оставляй одновременно два п - `use-cases/README.md` владеет навигацией, ID и короткими аннотациями. - `UC-*` владеет project-level scenario contract. - `flows/templates/use-case/UC-XXX.md` владеет структурой нового документа. +- `flows/behavior-specification.md` владеет BDD practice и правилами + formulation/automation, но не scenario semantics. - `brief.md` владеет feature scope, acceptance и evidence contract. - `design.md`, ADR и delegated contracts владеют solution и architecture facts. - runbooks владеют executable operational procedures и конкретными recovery diff --git a/template/memory-bank/use-cases/README.md b/template/memory-bank/use-cases/README.md index 7c35a88..1a41041 100644 --- a/template/memory-bank/use-cases/README.md +++ b/template/memory-bank/use-cases/README.md @@ -17,6 +17,12 @@ audience: humans_and_agents Use case нужен для сценария, который живет на уровне продукта, повторяется во времени и может быть upstream для нескольких feature packages. Это не замена `SC-*` внутри `brief.md`: `SC-*` описывают acceptance сценарии delivery-единицы, а `UC-*` описывают устойчивое поведение системы на уровне проекта. +Один `UC-*` может иметь много downstream BDD examples. `BR-*`, `ALT-*` и +`EX-*` дают точки traceability к feature `SC-*` / `NEG-*`, но example bodies, +`CHK-*` и test implementation не копируются в project-level use case. Правила +Discovery, Formulation и Automation определяет +[`Behavior Specification Practice`](../flows/behavior-specification.md). + Обычно use case наследует общий product context из [`../product/context.md`](../product/context.md). Если сценарий зависит от предметных правил, states или events, он также должен ссылаться на соответствующие документы из [`../domain/README.md`](../domain/README.md). ## Когда Заводить Use Case