Skip to content
Merged
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
14 changes: 11 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,11 +100,19 @@ service setup-команды проекта; он намеренно не пер

## Развитие шаблона

Источники полезных практик:
### Методические источники

- 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.

### Downstream-репозитории и практические полигоны

Эти репозитории используют и адаптируют Memory Bank под конкретные проекты.
Опыт их эксплуатации может становиться источником обобщаемых правил для
шаблона, но их project-specific факты остаются в downstream-копиях.

- [`dapi/zelma`](https://github.com/dapi/zelma);
- [`brandymint/merchantly`](https://github.com/brandymint/merchantly);
- [`alfagen/mercury`](https://github.com/alfagen/mercury);
- 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.
- [`alfagen/mercury`](https://github.com/alfagen/mercury).

Добавляйте в шаблон только обобщаемые правила. Названия продуктов, инфраструктурные детали и другие project-specific факты должны оставаться в downstream-копии `memory-bank/`.
1 change: 1 addition & 0 deletions template/memory-bank/flows/feature-artifact-catalog.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ audience: humans_and_agents

| Artifact | Question answered | Trigger | Default form / suggested path | Ownership | Template |
| --- | --- | --- | --- | --- | --- |
| 4+1 viewpoint coverage and correspondence | Достаточно ли одно решение описано для Logical, Process, Development, Physical concerns и driving Scenarios, и согласованы ли эти projections? | Любой required `design.md` | Sections in `design.md`; отдельный artifact не создаётся | Только cross-references между canonical owners; views не вводят новые facts | [Design](templates/feature/design.md) |
| `design.md` | Какое решение выбрано и почему? | `Design required: yes` | `features/FT-XXX/design.md` | `root`: manifest, selected design и default owner неделегированных feature-local solution facts | [Design](templates/feature/design.md) |
| C4 view | Какие system, container, component или critical code boundaries и bindings затронуты? | Срабатывает C4 trigger из feature flow | Embedded Mermaid/table; при росте `diagrams/<name>-c4.md` | `derived-view` для feature-local projection или `external-dependency` для canonical shared model; не заменяет Architecture Coverage Decision | pattern in Design |
| Component responsibility map | Как распределена ответственность между modules/services? | Новая decomposition, orchestration или ownership transfer | Table or C3 view in `design.md` | Selected responsibilities остаются `SOL-*` / `SD-*` | pattern only |
Expand Down
62 changes: 60 additions & 2 deletions template/memory-bank/flows/feature.md
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,59 @@ C4 можно не создавать, если изменение одновр
3. C4 artifact не должен содержать execution steps, file-level TODO или test commands.
4. Если C4 level required, `Solution Ready` недостижим без artifact-а или ссылки на уже существующий canonical C4/design artifact, который покрывает affected boundary.

## 4+1 Viewpoint Coverage Requirements

Каждый required `design.md` до `Solution Ready` обязан проверить решение через
модель 4+1: Logical, Process, Development, Physical и driving Scenarios. Это
stakeholder/concern coverage поверх canonical facts, а не пять новых владельцев
архитектуры и не обязательство создать пять документов или диаграмм.

- **Logical View** показывает предоставляемое поведение, domain meaning и
requirements. Он ссылается на canonical `brief.md`, `UC-*`, PRD и domain
owners и обязателен для любой designed feature.
- **Process View** показывает runtime behavior: взаимодействия, ordering,
state transitions, concurrency, failure и recovery. Не путай его с Feature
Flow: Feature Flow управляет delivery lifecycle, а Process View описывает
исполняемую систему.
- **Development View** показывает устойчивую организацию code modules,
components, interfaces и ownership с точки зрения разработчика.
`implementation-plan.md` не является Development View: он владеет порядком
работы, а не архитектурой реализации.
- **Physical View** показывает runtime/deployment topology: deployable nodes,
queues, stores, environment/config bindings и operational boundaries.
- **Scenarios (+1)** связывают остальные views через `SC-*`, применимые
project-level `UC-*` и negative/error paths. Scenario используется как input
design analysis и затем как основа проверки, а не только как финальный test.

### View Applicability Predicates

| View | `covered` обязателен, когда | `N/A` допустим, когда |
| --- | --- | --- |
| Logical | Всегда: designed feature реализует или изменяет capability, rule или observable engineering/operations outcome из `brief.md` | Никогда |
| Process | Selected solution меняет runtime interactions, state transitions, ordering, sync/async boundary, concurrency, failure propagation или recovery behavior | Все runtime semantics остаются у существующих canonical owners без изменений, а scenario не вводит новый temporal/failure path |
| Development | Selected solution меняет module/component/interface responsibilities, code ownership, dependency direction или внутреннюю decomposition | Решение полностью использует существующую implementation structure и не перераспределяет ответственность или dependencies |
| Physical | Selected solution меняет deployable/runtime nodes, queue/store boundary, environment/config binding, network/trust placement или deployment topology | Решение выполняется в существующей topology и не меняет runtime placement или bindings |
| Scenarios (+1) | Всегда: каждый `SC-*` участвует в Cross-View Correspondence | Никогда |

Если evidence недостаточно, чтобы доказать `N/A`, view остается `covered` и
анализ продолжается либо unresolved applicability проходит Human Gate.

Logical View и Scenarios всегда получают `covered`. Process, Development и
Physical получают `covered` по predicates выше либо обоснованный `N/A`.
Каждая строка называет stakeholder/concern, canonical owner/refs и optional
supporting projection. Supporting views ссылаются на canonical IDs и не вводят
новые requirements, decisions, contracts или topology facts.

До `Solution Ready` каждый `SC-*` из `brief.md` должен присутствовать в
Cross-View Correspondence: scenario/requirement → применимые runtime semantics
→ code/component ownership → deployment topology → `CHK-*`/`EVID-*`. Для
неприменимого view фиксируется `N/A`, а не выдумывается искусственная связь.

4+1 дополняет, но не заменяет C4 и Architecture Coverage Decision: 4+1
проверяет stakeholder concerns, C4 выбирает структурный zoom level, а
Architecture Coverage проверяет components, connectors, configuration,
behavioral semantics и quality/evolution concerns.

## Architecture Coverage Requirements

Каждый required `design.md` до `Solution Ready` обязан явно проверить достаточность архитектурного описания по пяти аспектам: components, connectors, configuration, behavioral semantics и quality/evolution concerns. Это обязательный analysis decision, а не требование создать пять разделов, отдельные файлы или diagrams: компактные факты остаются в `design.md`, а неприменимый аспект получает обоснованный `N/A`.
Expand Down Expand Up @@ -217,6 +270,9 @@ Feature-local `ui-reference/README.md` ссылается на `engineering/ui-d
## Migration Strategy

- Новые feature packages обязаны сразу следовать структуре `brief.md -> optional design.md -> implementation-plan.md`.
- Новый `design.md` обязан сразу содержать 4+1 Viewpoint Coverage Decision и Cross-View Correspondence.
- Existing active/archived `design.md`, который уже прошёл `Solution Ready` до принятия 4+1 rules, сохраняет прежний gate state, пока его canonical solution facts не меняются; documented prior review или pinned template revision служит evidence grandfathering.
- При material change существующего design pack grandfathering прекращается: перед повторным `Solution Ready` добавь 4+1 coverage и correspondence по текущему contract. Одна только execution continuation без изменения canonical solution facts не требует retroactive backfill.
- При миграции старого package layout сначала назначь canonical owners: problem-space content переносится в `brief.md`, required solution-space content — в root `design.md` или явно проиндексированный constituent.
- После миграции package не должен сохранять duplicate active owners для problem space или solution space.
- Миграция может происходить постепенно, package-by-package.
Expand Down Expand Up @@ -274,6 +330,8 @@ flowchart LR
- [ ] `design.md` содержит ≥ 1 `SOL-*`
- [ ] `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`
- [ ] 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` имеет причину
Expand Down Expand Up @@ -459,7 +517,7 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng
1. Любой canonical `brief.md` использует как минимум `REQ-*`, `NS-*`, `SC-*`, `CHK-*`, `EVID-*`.
2. Любой `brief.md` со `status: active` задает хотя бы один explicit test case через `SC-*`.
3. `brief.md` может использовать только минимальный problem-space набор для compact feature package или расширенный набор feature IDs по необходимости; отдельные problem-space templates не используются.
4. Любой required `design.md` использует как минимум один `SOL-*`, один `C4-*` decision, Architecture Coverage Decision и Design Verification selection и связывает solution refs минимум с одним `REQ-*` из sibling `brief.md`.
4. Любой новый required `design.md` и существующий design pack, повторно входящий в `Solution Ready` после material solution change, использует как минимум один `SOL-*`, один `C4-*` decision, 4+1 Viewpoint Coverage Decision, Cross-View Correspondence, Architecture Coverage Decision и Design Verification selection и связывает solution refs минимум с одним `REQ-*` из sibling `brief.md`; grandfathered packages следуют Migration Strategy.
5. Любой `design.md` фиксирует selection rationale для C4 applicability; выбранные C4 views используют `C4-*` и связываются с `SOL-*`, `SD-*`, `CTR-*`, `INV-*` или ADR refs.
6. Любой `design.md`, где есть принятые feature-local решения, использует `SD-*`; `ALT-*`, `TRD-*`, `CTR-*`, `INV-*`, `FM-*` и `RB-*` применяются только когда соответствующая solution-semantics действительно нужна.
7. Любой optional support doc использует только local support IDs и traceability к canonical refs; он не вводит новые canonical `REQ-*`, `SC-*`, `CHK-*` или `EVID-*`.
Expand All @@ -469,7 +527,7 @@ Canonical testing policy живёт в [../engineering/testing-policy.md](../eng

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`, если есть, связывает `REQ-*` из `brief.md` с `SOL-*`, `ALT-*`, `TRD-*`, `C4-*`, `SD-*`, `CTR-*`, `INV-*`, `FM-*`, `RB-*` и accepted ADR refs.
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.
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-*`.
Expand Down
Loading
Loading