Шаблони — порівняння Lean (мої) vs Corporate (твої)
Швидке порівняння для рішення, який набір використовуємо як canonical.
| Розділ / характеристика | Lean (мій) | Corporate (твій) |
|---|---|---|
| Розмір template-файлу | ~250 рядків | ~370 рядків |
| BA Input section | відсутній | є (для команд з окремим BA) |
| Scope (in/out) | є | є |
| Glossary | окремий розділ | в кінці документа |
| Domain Model + ERD | об’єднано в одному розділі (Mermaid ERD inline) | ERD як [[Diagram — ...]] embed (PlantUML/окремий файл) |
| Data Dictionary | в Appendix B | окремий повний розділ з прикладами |
| Functional Requirements | user stories з AC у форматі Given/When/Then; ID FR-MODULE-NN | atomic FRs у EARS-синтаксисі; ID FR-PREFIX-XXXX; обов’язковий ELSE для кожного IF |
| Business Rules → Validation Rules маппінг | відсутній (правила вмонтовані в AC) | є — окрема таблиця BR ID → BA Rule → Тех. реалізація → VR ID |
| Validation Rules table | відсутня (контракт у Data Dictionary + AC) | є — окрема таблиця з error codes |
| Error Handling | error codes у AC | окрема таблиця Code / HTTP / Cause / Behavior / FR-link |
| Security | NFR-SEC підрозділ | окремий розділ з підрозділами (Auth, PII, MAG/Keycloak) |
| NFRs | один розділ з підгрупами Performance/Reliability/Security/Observability/Maintainability | один розділ з Performance/Load/Availability/Scalability/Reliability |
| Logging & Monitoring | в NFR-OBS | окремий розділ |
| Test Data & Postman | відсутній | окремий розділ |
| Document Checklist (DoD) | відсутній | є |
| Traceability | через ID-and (FR ↔ AC ↔ ADR) | окремий розділ + Jira link |
| Roadmap | окремий розділ | відсутній |
| Risks / Open Questions | Appendix C | в окремому розділі вище |
| Діаграми | inline Mermaid + опціональний PlantUML embed | завжди embed [[Diagram — ...]] (через plantuml-master skill) |
| Changelog | Appendix D | на початку (одразу після frontmatter) |
Кому підходить що
Section titled “Кому підходить що”- Lean — оптимальний для personal / OSS / portfolio-проектів соло. Швидко писати, читати без контексту корпоративного процесу. Мінімум обов’язкових полів — менше спокуси залишити «TBD» в ритуальних розділах.
- Corporate — оптимальний для enterprise-команд з окремими BA / SA / DEV / QA ролями, Jira-traceability, Compliance/MAG-задачами, Postman-колекціями. Виглядає дуже сильно як портфоліо-артефакт — демонструє корпоративний досвід «як у корпоративному продукті».
Гібридні варіанти
Section titled “Гібридні варіанти”- Lean у MVP-1 → Corporate для v1 — починаємо швидко, переписуємо до повного Corporate-формату коли проект стабілізується.
- Corporate-структура + Lean-наповнення — використовуємо твій шаблон, але без обов’язкового заповнення BA Input / MAG / Postman (бо їх просто немає в personal-проекті). Залишаємо ці секції пустими з міткою “N/A — solo project” або видаляємо.
- Lean + запозичення — мій шаблон, але додаємо з твого: явну таблицю Error Handling (її в моєму нема, але корисна), DoD checklist, BR→VR маппінг.
| Розділ | Lean (мій) | Corporate (твій) |
|---|---|---|
| Розмір | ~70 рядків | ~55 рядків |
| Frontmatter | id, status, date, deciders, supersedes/superseded_by, related, tags | tags, decision_status, domain, epic, project, jira_ticket, target_release, supersedes/superseded_by, stakeholders |
| Status section explicit | окремий розділ з датою | в frontmatter |
| Considered alternatives | таблиця з Pros/Cons/Outcome | таблиця Опис/Чому відхилено |
| Decision | active voice “We will…” + implementation-shaping deets | ”Обрано Варіант X тому що…” |
| Consequences | Positive / Negative / Neutral follow-ups (з actionable [ ] checkbox) | Позитивні / Trade-offs / Дії |
| References | окремий розділ | відсутній |
Висновок: ADR-шаблони майже ідентичні за духом. Різниця стилістична: мій трохи акуратніший про status lifecycle і References, твій акуратніший про корпоративний контекст (epic/jira/stakeholders у frontmatter). Можна злити в гібрид без втрат.
Діаграми
Section titled “Діаграми”| Тип | Моя пропозиція | Твоя поточна практика |
|---|---|---|
| ERD | Mermaid inline (рендериться на GitHub readme + Obsidian) | PlantUML як окрема нотатка [[Diagram — ... — ERD]] (твій plantuml-master skill) |
| Sequence | Mermaid inline | PlantUML embed |
| State machine | Mermaid inline | PlantUML embed |
| C4 (Context / Container) | PlantUML (точніше за Mermaid для C4) | PlantUML embed |
| BPMN (бізнес-флоу) | окремий BPMN XML → PNG | bpmn-analyst skill (BPMN 2.0 XML → PNG) |
Trade-off:
- Mermaid inline — рендериться скрізь без додаткових інструментів (GitHub web, Obsidian, статичні сайти). Це плюс для портфоліо-сайту.
- PlantUML embed — точніше для C4/BPMN, виглядає більш «professional», але вимагає рендер-pipeline (твій skill це автоматизує).
Гібрид: Mermaid для всього inline, PlantUML тільки для C4 і де Mermaid недостатньо точний (наприклад, BPMN).
Що обираємо
Section titled “Що обираємо”Вибір між:
- (А) Lean canonical — твій Corporate-набір залишається для роботи в Corporate банку, для personal-проекту використовуємо мій Lean.
- (B) Corporate canonical, з опущеними N/A-секціями — використовуємо твій навіть для personal, секції без сенсу для solo-проекту просто прибираємо. Максимальна portfolio-цінність.
- (C) Гібрид — Lean як базова структура, з конкретними додаваннями з Corporate (Error Handling table, DoD checklist, BR→VR — на твій вибір що додати).
Дай знати, який варіант обираєш — і я пишу design.md з урахуванням цього вибору.