Skip to content

Лендинг продукта. Как описать платформу из N сервисов по JTBD

«Технической информации присуще качество, когда ею легко пользоваться, её легко понять и легко найти.»

— Gretchen Hargis, Michelle Carey и др., Developing Quality Technical Information (IBM Press)

В статье «README — это продукт» мы сделали так, чтобы каждый файл в репозитории сервиса знал своего потребителя. У README — четыре потребителя, и каждый нанимает его на свою работу.

В статье «Композиция корректности» мы показали, что корректность системы из N сервисов выводится из корректности каждого сервиса и совместимости их контрактов. Один сервис никому не нужен — нужна система.

И вот тут вылезает дыра. Сервис описан хорошо. А продукт — платформа из десяти, двадцати, ста сервисов — не описан нигде. У системы нет входной двери. Менеджер не понимает, что это за зверь. Новый потребитель не понимает, из каких кусков он состоит. ИИ-агент, которого позвали делать фичу на три сервиса, не понимает, с чего начать и куда писать план.

В этой статье вводим лендинг продукта — витрину платформы. Разберём: кто его нанимает, что в него писать (и чего не писать), как это делают в индустрии, и как кросс-сервисная фича стартует именно здесь. Плюс скиллы для слабой модели и мат-часть.

Сквозной живой пример — concept-репозиторий codemonstersteam/pinout: экосистема инструментов для проверки совместимости сервисов по их OpenAPI/AsyncAPI-спецификациям. Платформа из четырёх модулей, у которой есть та самая входная дверь. Удобно, что pinout построен по той же методологии рациональной разработки, что мы разбираем в серии (его модули стоят на service-template и компонентных тестах) — так что лендинг тут не выдуман под статью, а живёт в проде.

GL HF DD!

Что нужно заранее

  • Прочитанная «README — это продукт» — четыре JTBD-потребителя одного сервиса
  • Прочитанная «Композиция корректности» — продукт как система из N сервисов
  • Распределённый продукт: несколько репозиториев-сервисов под одной платформой (полирепо)

В этой главе:

Продукт — это не сервис

Сделаем различение, без которого дальше каша.

  • Сервис — один репозиторий, один деплой, один контракт (OpenAPI/AsyncAPI). У него есть README.md, docs/architecture.md, компонентные тесты. Его потребители описаны в статье про JTBD-README.
  • Продукт — платформа из N сервисов, которые ходят друг к другу через сеть и вместе решают задачу пользователя. У продукта нет одного README, потому что у него нет одного репозитория.

Возьмите pinout: валидатор синхронных контрактов pinout-openapi, валидатор асинхронных pinout-asyncapi, координатор графа зависимостей pinout-netlist, единый фронт pinout-cli. По отдельности каждый описан своей спекой и README. А что это вместе? Из каких кусков состоит система? Что с чем разговаривает? Где входная дверь?

В индустрии эту дверь ставят в отдельный репозиторий-концепт (он же meta-repo, он же coordination-root). Это не код — это описание системы целиком. Для pinout это codemonstersteam/pinout: зонтичный репозиторий, где живут модель контракта, обоснование и верхнеуровневый бэклог всей экосистемы.

И у его главной страницы — лендинга — свой потребитель, свой JTBD. Не такой, как у README сервиса.

Пятый потребитель: кто читает лендинг

У README сервиса четыре потребителя. У лендинга продукта — пятый, и он другой.

Сегмент: потребитель concept-уровня (менеджер, CTO, новый потребитель, ИИ-агент-оркестратор).

Job: за 60 секунд решить «годится ли мне эта платформа», затем сделать первый шаг.

Боль:

  • Менеджер / CTO не лезет в технические детали — ему нужна картина целого за минуту, чтобы принять управленческое решение. Он редкий гость в своём хозяйстве. А зря: разве CTO не может взглянуть на репозитории своего хозяйства и оценить масштаб великолепия? Или бардака?
  • Инженер-потребитель оценивает: эта платформа решает мою проблему или нет? Из чего она состоит? С чего начать?
  • ИИ-агент-оркестратор, которому поручили фичу на три сервиса, должен понять структуру системы и найти, куда писать общий план.

Что нужно в лендинге этому потребителю:

  • что это за платформа — одно предложение, не абзац;
  • из каких кусков состоит — список сервисов/нод со статусом готовности, картина целого;
  • стек платформы и схема верхнего уровня;
  • границы — что платформа сознательно НЕ делает (отсекает ложные ожидания за минуту);
  • позиционирование — чем отличается от известных альтернатив (потребитель сравнивает не в вакууме);
  • первый шаг — ссылка на пошаговое подключение и на сервисы-примеры.

Чего не нужно: API конкретного сервиса, его модель данных, команды запуска, детали реализации. Это утопит картину целого в деталях одного куска. Лендинг описывает систему, не сервис.

Это уточняет четвёртый сегмент из прошлой статьи. Там «менеджер» читал README сервиса и тонул. Теперь у него своя дверь — лендинг продукта в concept-репо. README сервиса в первых строках ставит ссылку наверх: «Часть экосистемы pinout. Модель контракта и концепция — там».

Как это делают в индустрии

Прежде чем изобретать — посмотрим на лучшие открытые продукты. Все они платформы из N сервисов, и у всех есть «дверь», описывающая систему целиком.

Supabase — open-source бэкенд-платформа. README и страница архитектуры прямо перечисляют куски: Kong (gateway) → GoTrue (auth), PostgREST (REST поверх Postgres), Realtime (websockets), Storage. Это образцовый ответ на «из чего состоит система» — не реализация одного сервиса, а карта платформы.

Dapr — CNCF-проект, распределённый рантайм. Его Overview построен вокруг building blocks (pub/sub, state, secrets, workflow, actors): концепт описывает возможности системы как набор кубиков, а не как один бинарь.

Backstage (Spotify) — каталог ПО и портал разработчика. Его System Model — это готовая онтология для описания продукта из N сервисов: Domain → System → Component → API. Ровно тот язык, на котором лендинг продукта говорит про целое: какие домены, какие системы, какие компоненты, какие API между ними.

GitHub Spec Kit и AWS Kiro — инструменты spec-driven development. Они показывают, где в 2025–2026 живёт план фичи: спецификация (spec.md), план (plan.md), задачи (tasks/). Не в голове, не в чате — в версионируемом артефакте рядом с кодом. Мы используем тот же скелет для кросс-сервисной фичи (ниже).

monorepo.tools и стандарт AGENTS.md — про координацию. Для полирепо консенсус такой: завести solution-root репозиторий как слой координации для агентов, с одним каноническим набором правил. Это и есть роль concept-репо.

Вывод из всех референсов один: у зрелого распределённого продукта есть отдельное место, которое описывает систему, а не сервис. Витрина + каталог + координация. Мы собираем это в concept-репо — и ниже разбираем на живом pinout, как каждый из этих элементов ложится в один README.

Что пишем в лендинг и чего НЕ пишем

Лендинг — это README.md concept-репо плюс парная страница docs/get-started.md (пошаговое подключение). Главная ошибка — натащить туда деталей сервиса. Поэтому начинаем с анти-контента.

Анти-контент: чего в лендинге быть НЕ должно

Если в лендинге есть… …куда вынести
API-эндпоинты, pipe-описания README сервиса
Архитектура конкретного сервиса docs/architecture.md сервиса
Модель данных, команды запуска, структура проекта README сервиса
Детали реализации любого уровня репозиторий сервиса
Длинный quickstart, troubleshooting docs/get-started.md концепта
Манифест / архитектура платформы / roadmap (развёрнуто) docs/manifesto.md / docs/architecture.md / docs/roadmap.md концепта

Правило одно: concept описывает систему, не сервис. Concept ссылается, не копирует.

Что писать: шесть проходов

Лендинг собирается за проходы, каждый с жёстким лимитом (это важно для слабой модели — см. скиллы ниже):

  1. Hero. Что за платформа — одно предложение ≤ 25 слов. Затем: для кого.
  2. Из чего состоит. Список нод/сервисов/форматов, каждый — одна строка ≤ 12 слов, со статусом готовности (✅ работает / 📋 проектируется / 🚧 концепт). Картина целого, без деталей куска.
  3. Анти-контент чистка. Прогон по таблице выше: всё, что про один сервис, — вынести.
  4. Стек и схема. Таблица компонент платформы → технология + одна диаграмма верхнего уровня (ноды и связи, не внутренности сервиса). ASCII годится, но mermaid/C4-Context в GitHub рендерится как картинка и читается лучше — предпочтителен.
  5. Границы и позиционирование. Короткая таблица «что платформа НЕ делает → чем закрывается» и таблица «альтернатива → чем мы отличаемся». Оба режут ложные ожидания за минуту.
  6. Первый шаг. Ссылка на docs/get-started.md и на модуль-пример, который уже работает (у pinout это pinout-asyncapi ✅). Текст ссылки описателен, не «здесь».

Лимит-ориентир — одна–две прокрутки. Строгий порог «≤ 60 строк» держим для витринной части (проходы 1–4, 6). Обоснование, границы и позиционирование могут добавить объёма — и это нормально для раннего концепта, где инвариант, границы и сравнение с альтернативами ещё не заслужили отдельных docs/-страниц (см. оговорку ниже). Правило-детектор остаётся прежним: если объём растёт из-за деталей одного сервиса — возврат к проходу 3.

Разбор живого лендинга: README pinout

Посмотрим, как эти проходы ложатся на реальный README pinout — концепт-репозиторий экосистемы валидаторов контрактов:

Проход Где в README pinout
Hero Первая строка: «Экосистема инструментов, которая проверяет совместимость сервисов по их машиночитаемым спецификациям (OpenAPI, AsyncAPI) на pre-merge стадии в CI» — ~20 слов, ровно одна работа
Из чего состоит Таблица «Состав экосистемы»: pinout-asyncapi ✅, pinout-openapi 📋, pinout-netlist 📋, pinout-cli 📋 — каждый модуль со статусом и ссылкой на репо
Стек и схема Диаграмма mermaid C4-Context «Экосистема pinout»: ноды-валидаторы, внешние consumer/provider, стрелки связей — картина целого, без внутренностей модуля
Границы Таблица «Границы (что pinout сознательно не делает)»: пять строк «граница → как закрывается» — отсекает ожидание «это заменит мне компонентные тесты»
Позиционирование Таблица vs Pact / Microcks / oasdiff — «что делает → чем отличается pinout»
Первый шаг Ссылки на модули-репозитории; рабочий вход — pinout-asyncapi (✅ работает)

Обратите внимание на приём аналогии в hero-блоке: pinout объясняет себя через распиновку микросхемы (какие сигналы на какие пины). Одна точная метафора экономит потребителю concept-уровня абзац объяснений — это чистая clarity из мат-части ниже.

Оговорка: где pinout стоит подрезать

Живой пример честнее идеала. README pinout длиннее витринного порога: он держит инлайн развёрнутое «Обоснование» (несущий инвариант, семь преимуществ перед генерацией клиентских либ) и «Принципы». По анти-контент-правилу это кандидаты на вынос в docs/manifesto.md / docs/architecture.md концепта.

Почему это пока допустимо: pinout — ранний концепт (🚧), где обоснование ещё активно обсуждается и является главным содержанием репо, а не сервиса. Пока читатель — это в основном тот, кто решает «а стоит ли вообще так делать», обоснование рядом с витриной оправдано. Как только модулей станет больше и появятся внешние потребители, «Обоснование» и «Принципы» переезжают в docs/, а лендинг сжимается к витрине. Это и есть работающее правило: не «никогда инлайн», а «инлайн, пока обоснование — главный продукт репо; выносим, когда главным становится сама платформа».

Кросс-сервисная фича стартует в лендинге

Теперь главное, ради чего concept-репо — это не только витрина, но и coordination-root.

Фича затрагивает один сервис → её проектируют и реализуют в его репозитории (скиллы program-design и program-implementation из прошлых статей).

Фича затрагивает больше одного сервиса → проектирование стартует в лендинге, как кросс-сервисная фича. Где живёт артефакт — по практике spec-driven development:

codemonstersteam/pinout/docs/features/<slug>/
  spec.md   — что и зачем (SDD spec)
  plan.md   — кросс-сервисная декомпозиция + ссылки на бэклоги сервисов + статусы

spec.md → plan.md — это тот же скелет spec → plan, что у Spec Kit и Kiro, только на уровне продукта. Полный жизненный цикл:

  1. Specify (spec.md): проблема и outcome, затронутые сервисы (≥ 2), границы scope, constraints, прежние решения (ссылки на ADR/concept), критерии приёмки — кросс-сервисный сценарий.
  2. Дизайн: какие контракты между сервисами появляются или меняются (OpenAPI/AsyncAPI), кто кого вызывает, последовательность. Контракт проектируется spec-first.
  3. Plan (plan.md): таблица — на каждый затронутый сервис строка со ссылкой на задачу в его backlog.md, в порядке зависимости. Пример для реальной фичи pinout «структурированный JSON-отчёт валидаторов → приём в netlist»:
| # | Сервис (репо)     | Что делает                   | Backlog-задача                  | Зависит от | Статус |
|---|-------------------|------------------------------|---------------------------------|------------|--------|
| 1 | pinout-netlist    | схема отчёта + endpoint приёма| pinout-netlist/backlog.md#...   | —          | todo   |
| 2 | pinout-asyncapi   | эмит отчёта в формате схемы   | pinout-asyncapi/backlog.md#...  | 1          | todo   |
| 3 | pinout-openapi    | эмит отчёта в формате схемы   | pinout-openapi/backlog.md#...   | 1          | todo   |
  1. Связывание: в каждом сервисе заводим задачу со ссылкой обратно на фичу; дальше сервис идёт своим флоу. Единое имя ветки во всех репо feat/<slug>; PR в порядке зависимости, в теле — Depends on <repo>#<PR>. Это прямые polyrepo-практики координации: backend → shared → frontend.
  2. Синхронизация статусов: plan.md — единственный источник правды о прогрессе фичи. Обновляется при каждом merge в сервисе.
  3. Закрытие: все строки done И кросс-сервисный сценарий из критериев приёмки проходит (контрактные/компонентные тесты зелёные).

Заметьте симметрию с композицией корректности: как корректность системы собирается из корректности сервисов плюс совместимости контрактов, так и разработка кросс-фичи собирается из локальных бэклогов сервисов плюс согласованного плана в лендинге. Лендинг — точка композиции на уровне процесса.

Вот скиллы

Документация и оркестрация — не разовый акт вдохновения, а детерминированная процедура. Мы вынесли её в три скилла формата SKILL.md — они живут в открытом харнесе rationaldev-ai-sdlc-skills (папка skills/lib/). Все три рассчитаны на слабую модель (уровня Qwen 37B): пошаговые проходы, таблицы-роутеры вместо суждений, жёсткие числовые лимиты, STOP-правила, финальные чеклисты. Сильная модель (Opus) проектирует скилл — слабая исполняет.

Скилл Зона Что делает
documentation один сервис Роутер «контент → файл», проходы сборки README и docs/architecture.md, триггеры обновления
doc-quality-review любой документ Рубрика ревью качества по ядру характеристик из книги (см. мат-часть)
platform-landing concept-репо PART I — витрина (шесть проходов), PART II — жизненный цикл кросс-сервисной фичи

У platform-landing есть и готовые шаблоны: landing-README.md.tmpl, get-started.md.tmpl, component-row.md.tmpl — скелет лендинга и пошагового подключения под проходы из этой статьи.

Ключевой приём для слабой модели — роутер вместо суждения. Не «реши, куда положить текст» (это требует вывода, на котором маленькая модель плывёт), а «найди строку в таблице — положи туда». То же с лимитами: не «пиши кратко», а «одно предложение ≤ 25 слов». И STOP-правила: не понял сегмент, нет контракта, правка удаляет факт → остановись и спроси оператора, не угадывай.

Вот мат-часть

Под скиллами — две теоретические опоры.

JTBD: документация как продукт

Documentation «для всех» — а значит ни для кого. Каждый документ нанимается на конкретную работу конкретного потребителя. Лендинг продукта — это просто ещё один продукт с ещё одним потребителем (concept-уровень), который мы спроектировали по JTBD, как и README сервиса.

Цена вопроса не абстрактна. Качественная документация повышает производительность команды на 25% (DORA 2023); команды с качественной докой в 2.4 раза чаще показывают высокую производительность доставки. У распределённого продукта без лендинга самый дорогой потерянный человек — тот, кто неделю собирает картину системы по десяти разрозненным README.

Девять характеристик качества: IBM «Developing Quality Technical Information»

Чтобы ревью доки не было «нравится/не нравится», нужна рубрика. Берём её из классической книги Gretchen Hargis, Michelle Carey и др. (IBM Press). Она задаёт девять характеристик качества в трёх группах:

Группа Характеристики
Easy to use (легко пользоваться) Task orientation · Accuracy · Completeness
Easy to understand (легко понять) Clarity · Concreteness · Style
Easy to find (легко найти) Organization · Retrievability · Visual effectiveness

Для dev-доков мы взяли ядро из шести (task orientation, accuracy, completeness, clarity, organization, retrievability) и переформулировали каждую проверку под markdown-репозиторий. Примеры того, во что они превращаются в doc-quality-review:

  • Task orientation → «документ написан под конкретный JTBD-сегмент, а не для всех»; «заголовки раскрывают задачу, а не абстрактны».
  • Accuracy → «таблица API и pipe соответствуют api-specification/»; «команды запуска реально работают».
  • Completeness → «покрыто всё, что нужно сегменту, и только это»; «один источник правды, без дублей».
  • Clarity → «овервью ≤ 20 слов»; «каждый новый термин определён».
  • Organization → «каждый кусок в своём файле по роутеру»; «видно, как части складываются».
  • Retrievability → «все ссылки резолвятся и описательны»; «есть указатель на concept».

Книга даёт и готовую рейтинговую шкалу (Appendix A: каждую характеристику оцениваешь 1–5). В скилле для слабой модели мы свели её к ✓/✗ и правилу «если ✗ → действие», чтобы убрать субъективность.

Зачем характеристики Style / Concreteness / Visual оставили за бортом ядра? Они про типографику, иллюстрации и художественный стиль — для лендинга и dev-доки вторичны. Лендинг проверяется на «легко найти суть и решить за минуту», а не на красоту шрифтов.

Замыкание

Серия про рациональную разработку прошла путь снизу вверх: модуль → сервис → спецификация → система. Документация шла тем же путём:

  • README сервиса знает четырёх потребителей (статья 02).
  • Корректность системы собирается из сервисов и контрактов (статья 08).
  • Лендинг продукта даёт системе входную дверь и точку старта для кросс-фич (эта статья).

Распределённый продукт без лендинга — это дом без входной двери: внутри всё на месте, но войти можно только зная, где сломан забор. Лендинг ставит дверь: потребитель concept-уровня за минуту решает, годится ли платформа, а кросс-сервисная фича получает один артефакт, из которого видно весь план.

Живой пример этой двери — codemonstersteam/pinout: hero в одну строку, состав со статусами, C4-схема, границы и позиционирование в одном README. Не идеальный (обоснование ещё инлайн — и мы честно разобрали, когда его выносить), но рабочий.

И всё это — не вдохновение, а процедура: три скилла, две теоретические опоры, проверяемые лимиты. Дорогая модель проектирует процедуру. Дешёвая — исполняет. Человек — решает.

GG!