🙏Собрал развернутое саммари сессии митапа

🔌 pinout: спроектировали валидатор OpenAPI-контрактов и попутно прокачали свои скиллы разработки

На этой сессии проектировали инструмент, который на pre-merge стадии в CI проверяет, что потребитель REST-сервиса совместим с
прод-контрактом поставщика — сравнением их OpenAPI-спек. Без генерации клиентских либ, без подъёма заглушек: чистая функция
«спека vs спека».

🔗 Экосистема: https://github.com/codemonstersteam/pinout
🔗 Сам валидатор: https://github.com/codemonstersteam/pinout-openapi
Что зацепило больше всего

📐 Системные use case по Коберну.
Оказалось, что fully-dressed use case (акторы, предусловия, основной сценарий, extensions =
режимы отказа, гарантии/exit) — это не «бумажка для галочки», а рабочая спецификация. Структура use case изоморфна Gherkin: Main
Success → happy-тест, каждый Extension → один сценарий отказа. Формула сошлась сама собой: N сценариев = 1 + число extensions.

🗺 C4 как уровни дизайна. Разложили проект по уровням C4 на Mermaid (рендерится прямо в GitHub):
• C1 (контекст экосистемы) — в концепт-репо
• C2 + C3 (контейнер + дерево модулей) — в компоненте
• C4 = тот самый системный use case «как работает программа»

📄 Живой пример: https://github.com/codemonstersteam/pinout-openapi/blob/main/docs/design/contract-validate/c4.md

Главный инсайт — это всё прошивается в систему

Получилась сквозная трассировка:
use case (Cockburn)
→ вертикальный слайс
→ компонентный тест
→ узлы графа контрактов.

1 слайс = 1 внешний вход = 1 use case.

Ничего не выдумывается из кода — каждый компонентный тест выводится из соответствующего extension use case, с двусторонней сверкой (нет extension без теста и нет теста без extension).

Как мы доработали скиллы разработки

По следам сессии внесли правки прямо в процедуры скиллов (не в «когда-нибудь потом»):

✅ documentation — обязательные C4-диаграммы по уровням, системный use case как C4-уровень, таблица сбоев в README, gate:
документация только по скиллу (никакой свободной прозы мимо процедур)

✅ program-design — C4 по уровням, модель ошибок (коды → exit, «деградация видна, не маскируется под успех»), трассировка
UC→слайс→тест, conformance-gate (STOP перед хендоффом)

✅ component-tests — режимы отказа берутся из extensions use case

✅ роль plan-reviewer — асимметричная проверка соответствия дизайна скиллу

Плюс зашили несколько жёстких правил в скилл проектирования:
• Один внешний вход = один Request. Все параметры (включая флаги CLI) собираются в единый Request; флаг — это поле Request, а не
отдельный аргумент или «прокинутый сбоку» io.Writer. Внешний ввод парсится только в адаптере.

• Развилки по флагам — это юниты, а не компонентные тесты. Выбор «куда писать» (--out) и «в каком формате» (--format)
оформляется чистой функцией (resolveDestination, renderReport) и покрывается юнит-тестами. В компонентные сценарии идёт только
режим отказа записи — иначе матрица stdout/файл × json/md раздувает число сценариев.

• Запрет «тестового» второго метода I/O (WriteTo(io.Writer) рядом с боевым Write) — решение выносится в логику, лишний шов не
заводится.

Вывод сессии: use case по Коберну + C4 + вертикальные слайсы — это один связный конвейер, а не три отдельные практики. Когда они
сшиты, дизайн перестаёт расходиться с тестами и кодом by design.

#codemonstersvlog #разработка #архитектура #C4 #UseCase #OpenAPI