Module Design Method

Overview

Единая методология проектирования: архитектурные принципы (SRP / Unix / Атомарность / Изоляция / Composability / Фрактальность / DRY) + инверсионная навигация (необходимые условия / вычитание / ограничение / kill criteria) + инфраструктурная триада (Config / Client / Storage) + шаблон модуля (свёрнутая или развёрнутая форма).

Центральный вопрос: «Без чего не получится?» Декомпозиция идёт от ЦКП к необходимым условиям, не от плана к шагам.

Базовая иерархия

Концептуальная (всегда трёхуровневая): Система → Модуль → Этап → Операция. Физическая (разворачивается по нагрузке): свёрнутая форма (этапы — файлы) или развёрнутая (этапы — папки).

Каждый уровень имеет собственный ЦКП — конкретный продукт, нужный следующему звену.

Workflow

Применяй по шагам. Не пропускай Step 2 — инверсия идёт до декомпозиции, не после.

Step 1 — Определи ЦКП системы

Одно предложение. Конкретный продукт, не процесс. «Ценный» здесь технический термин: ценность определяется потребностью следующего звена, не оценочно.

Тест: если убрать любое слово из формулировки — становится неоднозначно? Если нет, ЦКП размыт.

Step 2 — Инверсия (до декомпозиции)

Применяй три формы:

1. Целевая: «как гарантированно НЕ-получить ЦКП?»
2. Премортем: «проект провалился катастрофически. почему?» — записать причины как если уже случилось
3. Атрибутная: перевернуть ключевое свойство — что если поменять местами поток / роль / последовательность? (TRIZ 13)

Из инверсии выведи:

• Необходимые условия — то, без чего система мертва. Формат: метрика + порог + срок. Без метрики = пожелание, не условие
• Ограничение (bottleneck) — слабое звено, определяющее пропускную способность. Идентификация — гипотеза, верифицируй измерением (70-80% ошибаются с bottleneck)
• Kill criteria — «если [метрика] к [дата], то стоп». Формулируются ДО старта работы, пока мышление не искажено вложенными ресурсами

Полная модель — references/inversion.md.

Step 3 — Декомпозиция в модули

Для каждого модуля ответь:

1. Перед каким одним заказчиком он отвечает? Заказчик определяет границу
2. Контракт — формат входа, формат выхода, формат ошибки. Контракт — единственное, что связывает модули
3. ЦКП — что отдаёт следующему модулю или ЦКП системы

Если модуль меняется по двум причинам — это два модуля. Похожий код в разных модулях ≠ нарушение DRY, если представляет разные знания.

Step 4 — Декомпозиция модуля в этапы

Этап = ровно одна смена семантической природы данных. Этапы НЕ вкладываются — иерархия строго трёхуровневая.

Тест существительного (первичная эвристика):

• Назови вход одним существительным БЕЗ прилагательных
• Назови выход тем же способом
• Разные существительные → граница этапа (URL → HTML, HTML → структура, байты → image)
• То же существительное с прилагательным → НЕ граница (текст → чистый текст, массив → сортированный массив)
• Агрегация (одиночка → коллекция или наоборот) → граница (меняется кардинальность)

Расширение для пограничных случаев — если тест существительного дал «не граница», проверь ещё два:

1. Качественная трансформация: получает ли следующий потребитель новые возможности? (image (низкое разрешение) → image (высокое) — да, новые возможности для печати/AI-анализа → граница). Контрпример: text → text (с обрезанными пробелами) — никаких новых возможностей, НЕ граница
2. Stateful композиция: добавляется ли сопутствующее состояние с собственным lifecycle? (image → image + chat-session — композитная сущность → граница)

Если хотя бы один срабатывает — это граница этапа, даже если тест существительного сказал «не граница».

Step 5 — Декомпозиция этапа в операции

Операция = один семантический шаг с точки зрения этапа. Не «одна функция в коде».

Тест: могу ли я назвать вспомогательный вызов как самостоятельное действие, нужное этапу?

• Можно (parse_html нужен этапу как отдельный шаг) → отдельная операция
• Нельзя (clean_whitespace нужен только внутри extract_phone) → внутренняя реализация одной операции

Операция неделима — дальнейшее дробление сделает фрагменты неработоспособными.

Подъём операции:

• Нужна нескольким этапам одного модуля → на уровень модуля
• Нужна другим модулям → перерастает в отдельный модуль
• Только если знание одно и то же для разных заказчиков; разные знания → дублирование оправдано

Step 6 — Размещение триады Config / Client / Storage

Триада существует для границы модуля и внешнего мира. Один владелец на каждый Config/Client/Storage — не дублируется между уровнями.

• Все этапы используют общий внешний сервис → триада на уровне модуля
• Этап работает со своим внешним сервисом → триада на уровне этапа
• Нет внешних сервисов → триады нет
• Комбинации допустимы (модульная для общего + этапная для специфичного)

Триада НЕ привязывается к операции. Если операции нужна своя триада — это этап с одной операцией, разворачивай в этап.

Инициализация: Config → валидация (fail-fast) → инжекция в Client и Storage через конструктор.

Полная модель — references/conventions.md.

Step 7 — Развернуть или свернуть этап

Этап существует концептуально всегда. Физическое развёртывание — по семантической нагрузке.

Этап разворачивается в собственную папку, если выполнено хотя бы одно:

• собственная координационная логика (orchestrator с условиями, циклами, ветвлениями)
• собственная триада, отличная от модульной
• реализация делает модуль трудночитаемым в одном файле
• смысл этапа достаточно самостоятелен, чтобы иметь имя в навигации (harvesting/, refinement/)

Иначе — свёрнутая форма, этапы как файлы на уровне модуля.

Обе формы — references/template.md.

Step 8 — Валидация чек-листами

Прогоняй каждый уровень через свой чек-лист. Любой «нет» — единица собрана неверно, перепроектируй.

• Чек-лист модуля
• Чек-лист этапа
• Чек-лист операции

Все три — references/checklists.md.

Step 9 — Инверсионная отчётка перед финализацией

1. Каждый режим провала из Step 2 закрыт конкретной мерой (ресурс, ограничение, мониторинг, решение «не делать»)?
2. Необходимые условия мониторятся непрерывно, не только на старте?
3. Ограничение верифицировано измерением, а не мнением?
4. Kill criteria записаны до старта и привязаны к метрике + дате?
5. Решение прошло через прямое И обратное мышление?

Инверсия без действия = трата времени. Каждая выявленная угроза → конкретная мера в дизайне.

Ключевые правила

Развёртывание по нагрузке. Иерархия концептуальна; материализуй ровно столько, сколько требует семантика. Тривиальный модуль — один файл. Сложный — развёрнутый шаблон.

Контракт — единственная связь. Модули соединены контрактом, не кодом и не импортами. Внутренний контракт (внутри модуля) может меняться свободно; публичный контракт (между модулями) требует координации.

Вычитание раньше добавления. Прежде чем добавить, спроси: «можно решить, убрав что-то существующее?» Каждое добавление — источник хрупкости. НО перед удалением — Chesterton's Fence (зачем оно существует), замена, обратимость.

Фокус на ограничении. Улучшение НЕ-ограничения не улучшает систему. Найди bottleneck → используй на 100% → подчини всё его ритму → расширь → найди следующее (Goldratt, 5 Focusing Steps).

Negative knowledge устойчивее. Список «как провалится» конкретнее списка «как преуспеть». Режимов провала структурно меньше — обозримее (Taleb, Munger).

Фрактальность. Все принципы работают на любом уровне: операция, модуль, продукт, бизнес. Масштаб меняется — правила нет.

Common Mistakes

Output: design blueprint

Финальный артефакт — design blueprint в формате assets/blueprint.md. Заполняй по шагам workflow, не пропускай разделы. Пустой раздел = нерешённое архитектурное решение, не косметическая дыра.

References