Синхронизация документации

Документация живёт в git рядом с кодом (docs-as-code): репозиторий Fluttrium/docs, сайт собирается из Markdown при каждом изменении. Правило одно — если изменение кода меняет то, что видит продавец или разработчик витрины, документация обновляется в том же цикле, а не «потом».

Из чего состоит

Файл в `Fluttrium/docs`	Что делает
`STYLE.md`	Как писать: две аудитории, типы страниц, язык, надписи интерфейса, пример MOSHNA
`sync-map.yml`	Карта «какой код → какие страницы» для всех репозиториев
`.claude/skills/docs-sync/SKILL.md`	Скилл Claude Code, который по диффу кода правит документацию и открывает PR
`astro.config.mjs`	Меню сайта. Страница без записи в меню на сайт не попадёт

Карта `sync-map.yml`

Каждое правило связывает файлы кода (glob с префиксом репозитория) со страницами документации (slug из меню):

repos:
  platform:
    github: Fluttrium/platform
    branch: main

rules:
  - name: Доставка СДЭК
    code:
      - platform:src/cdek/**
      - platform:shop-sdk/operations/cdek.graphql
    pages:
      - seller/settings/cdek
      - seller/sales/orders
      - dev/cdek

Репозитории в карте: platform (платформа и SDK), moshna (витрина — пример во всём руководстве), instance (сборка админки: версия и перевод), core (брендинг админки). Новый модуль платформы или новая витрина — новое правило в карте.

Скилл `docs-sync`

Скилл выполняет весь цикл сам:

Берёт дифф изменения: текущая ветка, PR или диапазон коммитов.
Находит затронутые страницы по sync-map.yml. Файлы, которых нет в карте, оценивает по смыслу и при необходимости дописывает правило.
Читает страницы и текущий код, правит только то, что стало неправдой: шаги, надписи, сроки, лимиты, примеры запросов. Надписи админки сверяет с переводом установленной версии.
Новую возможность без страницы оформляет новой страницей и пунктом меню.
Собирает сайт: npm run build проверяет разметку и битые ссылки.
Открывает PR в Fluttrium/docs с таблицей «страница → что изменено → на чём проверено». Если PR кода ещё не смержен — черновиком.

Запуск

В репозитории платформы или витрины, в Claude Code:

/docs-sync            изменения текущей ветки относительно основной
/docs-sync 42         изменения PR №42 этого репозитория
/docs-sync a1b2..c3d4 изменения между коммитами
/docs-sync --check    только отчёт: какие страницы затронуты

Скилл ищет репозиторий документации в DOCS_REPO_PATH, затем в соседней папке ../docs, иначе клонирует Fluttrium/docs во временную папку.

Установка

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

mkdir -p ~/.claude/skills
ln -s "$(pwd)/.claude/skills/docs-sync" ~/.claude/skills/docs-sync   # из корня Fluttrium/docs

Ссылка, а не копия: правки скилла в репозитории сразу действуют.

Порядок работы

Когда	Что делать
Готовите PR, который меняет поведение для продавца или Shop API	`/docs-sync --check` — понять, какие страницы задеты
PR кода на ревью	`/docs-sync <номер PR>` — черновик PR документации, ссылку на него в описание PR кода
PR кода смержен	Перевести PR документации из черновика, проверить и смержить
Обновили платформу на сервере	`/docs-sync` по диапазону релиза в репозитории платформы

Автоматической проверки в CI репозиториев платформы и витрины пока нет: сверку запускают скиллом по этой таблице.

Что скилл не пишет

Название движка, на котором построена платформа, — нигде в тексте. Технические идентификаторы (заголовок vendure-token, переменные окружения, пути файлов) допустимы только в коде и таблицах вкладки «Для разработчиков».
Секреты и личные данные: токены, пароли, ключи, внутренние адреса серверов, почты и телефоны покупателей и сотрудников.
Догадки. Непроверенное остаётся пометкой TODO в тексте и выносится в описание PR.